LibreOffice: uno/threadpool.h File Reference

LibreOffice LibreOffice 24.2 SDK C/C++ API Reference

Loading...
Searching...
No Matches
Typedefs | Functions
threadpool.h File Reference
`#include "cppu/cppudllapi.h"`
`#include "sal/types.h"`

Go to the source code of this file.

## Typedefs
typedef struct _uno_ThreadPool * | uno_ThreadPool

## Functions
CPPU_DLLPUBLIC sal_Bool | uno_bindIdToCurrentThread (sal_Sequence *pThreadId) SAL_THROW_EXTERN_C()
| Establishes an association between the current thread and the given thread identifier.
CPPU_DLLPUBLIC void | uno_getIdOfCurrentThread (sal_Sequence **ppThreadId) SAL_THROW_EXTERN_C()
| Get the identifier of the current thread.
CPPU_DLLPUBLIC void | uno_releaseIdFromCurrentThread () SAL_THROW_EXTERN_C()
| If the internal refcount drops to zero, the association between threadId and thread is broken.
CPPU_DLLPUBLIC uno_ThreadPool | uno_threadpool_create () SAL_THROW_EXTERN_C()
| Creates a threadpool handle.
CPPU_DLLPUBLIC void | uno_threadpool_attach (uno_ThreadPool hPool) SAL_THROW_EXTERN_C()
| Makes the current thread known to the threadpool.
CPPU_DLLPUBLIC void | uno_threadpool_enter (uno_ThreadPool hPool, void **ppJob) SAL_THROW_EXTERN_C()
| This method is called to wait for a reply of a previously sent request.
CPPU_DLLPUBLIC void | uno_threadpool_detach (uno_ThreadPool hPool) SAL_THROW_EXTERN_C()
| Detaches the current thread from the threadpool.
CPPU_DLLPUBLIC void | uno_threadpool_putJob (uno_ThreadPool hPool, sal_Sequence *pThreadId, void *pJob, void(*doRequest)(void *pThreadSpecificData), sal_Bool bIsOneway) SAL_THROW_EXTERN_C()
| Puts a job into the pool.
CPPU_DLLPUBLIC void | uno_threadpool_dispose (uno_ThreadPool hPool) SAL_THROW_EXTERN_C()
| All threads, that are waiting on the hPool handle, are forced out of the pool.
CPPU_DLLPUBLIC void | uno_threadpool_destroy (uno_ThreadPool hPool) SAL_THROW_EXTERN_C()
| Releases the previously with uno_threadpool_create() created handle.

## Typedef Documentation

## ◆ uno_ThreadPool

typedef struct _uno_ThreadPool* uno_ThreadPool

## Function Documentation

## ◆ uno_bindIdToCurrentThread()

CPPU_DLLPUBLIC sal_Bool uno_bindIdToCurrentThread | ( | sal_Sequence * | pThreadId | ) |

Establishes an association between the current thread and the given thread identifier.

There can be only one association at a time. The association must be broken by uno_releaseIdFromCurrentThread(). This method is in general called by a bridge, that wants to bind a remote threadId to a new thread.

Parameters

  pThreadId | a byte sequence, that contains the identifier of the current thread.

Returns
  true, when the identifier was registered. false, when the thread has already an identifier. The identifier was not altered. ( This is in general a bug ).

See also
  uno_releaseIdFromCurrentThread()

## ◆ uno_getIdOfCurrentThread()

CPPU_DLLPUBLIC void uno_getIdOfCurrentThread | ( | sal_Sequence ** | ppThreadId | ) |

Get the identifier of the current thread.

If no id has been bound for the thread before, a new one is generated and bound to the thread. For each call to uno_getIdOfCurrentThread(), a call to uno_releaseIdFromCurrentThread() must be done.

Parameters

  ppThreadId | [out] Contains the (acquired) ThreadId.

See also
  uno_releaseIdFromCurrentThread()

## ◆ uno_releaseIdFromCurrentThread()

CPPU_DLLPUBLIC void uno_releaseIdFromCurrentThread | ( |  | ) |

If the internal refcount drops to zero, the association between threadId and thread is broken.

## ◆ uno_threadpool_attach()

CPPU_DLLPUBLIC void uno_threadpool_attach | ( | uno_ThreadPool | hPool | ) |

Makes the current thread known to the threadpool.

This function must be called, BEFORE uno_threadpool_enter() is called and BEFORE a job for this thread is put into the threadpool (avoid a race between this thread and an incoming request/reply). For every call to uno_threadpool_attach, a corresponding call to uno_threadpool_detach must be done.

Parameters

  hPool | The bridge threadpool handle previously created by uno_threadpool_create.

## ◆ uno_threadpool_create()

CPPU_DLLPUBLIC uno_ThreadPool uno_threadpool_create | ( |  | ) |

Creates a threadpool handle.

Typically each remote bridge instances creates one handle.

## ◆ uno_threadpool_destroy()

CPPU_DLLPUBLIC void uno_threadpool_destroy | ( | uno_ThreadPool | hPool | ) |

Releases the previously with uno_threadpool_create() created handle.

The handle thus becomes invalid. It is an error to use the handle after uno_threadpool_destroy().

A call to uno_threadpool_destroy can synchronously join on spawned worker threads, so this function must never be called from such a worker thread.

See also
  uno_threadpool_create()

## ◆ uno_threadpool_detach()

CPPU_DLLPUBLIC void uno_threadpool_detach | ( | uno_ThreadPool | hPool | ) |

Detaches the current thread from the threadpool.

Must be called for every call to uno_threadpool_attach.

Parameters

  hPool | the handle that was previously created by uno_threadpool_create().

## ◆ uno_threadpool_dispose()

CPPU_DLLPUBLIC void uno_threadpool_dispose | ( | uno_ThreadPool | hPool | ) |

All threads, that are waiting on the hPool handle, are forced out of the pool.

The threads waiting with uno_threadpool_enter() will return with *ppJob == 0

Later calls to uno_threadpool_enter() using the hPool handle will also return immediately with *ppJob == 0.

Parameters

  hPool | The handle to be disposed.

This function is called i.e. by a bridge, that is forced to dispose itself.

## ◆ uno_threadpool_enter()

CPPU_DLLPUBLIC void uno_threadpool_enter | ( | uno_ThreadPool | hPool,
|  | void ** | ppJob )

This method is called to wait for a reply of a previously sent request.

This is a blocking method. uno_threadpool_attach() must have been called before.

Parameters

  hPool | the handle that was previously created by uno_threadpool_create().
  ppJob | [out] the pointer, that was given by uno_threadpool_putJob 0, when uno_threadpool_dispose() was the reason to fall off from threadpool.

See also
  uno_threadpool_dispose()

## ◆ uno_threadpool_putJob()

CPPU_DLLPUBLIC void uno_threadpool_putJob | ( | uno_ThreadPool | hPool,
|  | sal_Sequence * | pThreadId,
|  | void * | pJob,
|  | void(*)(void *pThreadSpecificData) | doRequest,
|  | sal_Bool | bIsOneway )

Puts a job into the pool.

A job may either be a request or a reply (replies have a 0 in the doRequest parameter). This function is non-blocking.

A request may either be synchronous or asynchronous. If the request is synchronous, it is first looked up, if there exists a handle with the given identifier. If this is the case, the thread is woken up and the doRequest function is called with the given pJob. If no handle exists, a new thread is created and the given threadId is bound to the new thread.

If the request is asynchronous, it is put into the queue of asynchronous requests for the current threadid. The requests are always executed in a new thread, even if the thread with the given id is waiting in the pool. No id is bound to the newly created thread. The responsibility is left to the bridge (if it wishes to bind a name).

If pJob is a reply, there MUST be a thread with the given threadId waiting for this reply.

Parameters

  hPool | the handle that was previously created by uno_threadpool_create().
  pThreadId | The Id of the thread, that initialized this request. (In general a remote threadid).
  pJob | The argument, that doRequest will get or that will be returned by uno_threadpool_enter().
  doRequest | The function, that shall be called to execute the request. 0 if pJob is a reply.
  bIsOneway | True, if the request is asynchronous. False, if it is synchronous. Set to sal_False, if pJob is a reply.