include/uno/threadpool.h

   1 /* -*- Mode: C++; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 4 -*- */
   2 /*
   3  * This file is part of the LibreOffice project.
   4  *
   5  * This Source Code Form is subject to the terms of the Mozilla Public
   6  * License, v. 2.0. If a copy of the MPL was not distributed with this
   7  * file, You can obtain one at http://mozilla.org/MPL/2.0/.
   8  *
   9  * This file incorporates work covered by the following license notice:
  10  *
  11  *   Licensed to the Apache Software Foundation (ASF) under one or more
  12  *   contributor license agreements. See the NOTICE file distributed
  13  *   with this work for additional information regarding copyright
  14  *   ownership. The ASF licenses this file to you under the Apache
  15  *   License, Version 2.0 (the "License"); you may not use this file
  16  *   except in compliance with the License. You may obtain a copy of
  17  *   the License at http://www.apache.org/licenses/LICENSE-2.0 .
  18  */
  19
  20 /*
  21  * This file is part of LibreOffice published API.
  22  */
  23
  24 #ifndef INCLUDED_UNO_THREADPOOL_H
  25 #define INCLUDED_UNO_THREADPOOL_H
  26
  27 #include "cppu/cppudllapi.h"
  28 #include "sal/types.h"
  29
  30 #ifdef __cplusplus
  31 extern "C" {
  32 #endif
  33
  34 /***
  35  * Thread identifier administration.
  36  ***/
  37 /**
  38   Establishes an association between the current thread and the given thread identifier.
  39   There can be only one association at a time. The association must be broken by
  40   uno_releaseIdFromCurrentThread().
  41   This method is in general called by a bridge, that wants to bind a remote threadId
  42   to a new thread.
  43
  44   @param pThreadId a byte sequence, that contains the identifier of the current thread.
  45   @return true, when the identifier was registered.
  46           false, when the thread has already an identifier. The identifier was not
  47           altered. ( This is in general a bug ).
  48
  49   @see uno_releaseIdFromCurrentThread()
  50  */
  51 CPPU_DLLPUBLIC sal_Bool SAL_CALL uno_bindIdToCurrentThread( sal_Sequence *pThreadId )
  52     SAL_THROW_EXTERN_C();
  53
  54
  55 /**
  56   Get the identifier of the current thread.
  57   If no id has been bound for the thread before, a new one is generated and bound
  58   to the thread.
  59   For each call to uno_getIdOfCurrentThread(), a call to uno_releaseIdFromCurrentThread()
  60   must be done.
  61
  62   @param ppThreadId [out] Contains the (acquired) ThreadId.
  63   @see uno_releaseIdFromCurrentThread()
  64  */
  65 CPPU_DLLPUBLIC void SAL_CALL uno_getIdOfCurrentThread( sal_Sequence **ppThreadId )
  66     SAL_THROW_EXTERN_C();
  67
  68
  69 /**
  70   If the internal refcount drops to zero, the association between threadId and
  71   thread is broken.
  72  */
  73 CPPU_DLLPUBLIC void SAL_CALL uno_releaseIdFromCurrentThread()
  74     SAL_THROW_EXTERN_C();
  75
  76
  77 struct _uno_ThreadPool;
  78 typedef struct _uno_ThreadPool * uno_ThreadPool;
  79
  80 /**
  81   Creates a threadpool handle. Typically each remote bridge instances creates one
  82   handle.
  83  */
  84 CPPU_DLLPUBLIC uno_ThreadPool SAL_CALL
  85 uno_threadpool_create() SAL_THROW_EXTERN_C();
  86
  87
  88 /**
  89   Makes the current thread known to the threadpool. This function must be
  90   called, BEFORE uno_threadpool_enter() is called and BEFORE a job for this
  91   thread is put into the threadpool (avoid a race between this thread and
  92   an incoming request/reply).
  93   For every call to uno_threadpool_attach, a corresponding call to
  94   uno_threadpool_detach must be done.
  95
  96   @param hPool The bridge threadpool handle previously created by uno_threadpool_create.
  97
  98 */
  99 CPPU_DLLPUBLIC void SAL_CALL
 100 uno_threadpool_attach( uno_ThreadPool hPool ) SAL_THROW_EXTERN_C();
 101
 102 /**
 103   This method is called to wait for a reply of a previously sent request. This is a
 104   blocking method. uno_threadpool_attach() must have been called before.
 105
 106   @param hPool the handle that was previously created by uno_threadpool_create().
 107   @param ppJob [out] the pointer, that was given by uno_threadpool_putJob
 108   0, when uno_threadpool_dispose() was the reason to fall off from threadpool.
 109   @see uno_threadpool_dispose()
 110  **/
 111 CPPU_DLLPUBLIC void SAL_CALL
 112 uno_threadpool_enter( uno_ThreadPool hPool , void **ppJob )
 113     SAL_THROW_EXTERN_C();
 114
 115 /**
 116    Detaches the current thread from the threadpool. Must be called for
 117    every call to uno_threadpool_attach.
 118   @param hPool the handle that was previously created by uno_threadpool_create().
 119 */
 120 CPPU_DLLPUBLIC void SAL_CALL
 121 uno_threadpool_detach( uno_ThreadPool hPool ) SAL_THROW_EXTERN_C();
 122
 123 /**
 124   Puts a job into the pool. A job may either be a request or a reply
 125   (replies have a 0 in the doRequest parameter). This function is non-blocking.
 126
 127   A request may either be synchronous or asynchronous.
 128   If the request is synchronous, it is first looked up,
 129   if there exists a handle with the given
 130   identifier. If this is the case, the thread is woken up and the doRequest
 131   function is called with the given pJob. If no handle exists,
 132   a new thread is created and the given threadId is bound to the new thread.
 133
 134   If the request is asynchronous, it is put into the queue of asynchronous
 135   requests for the current threadid. The requests are always executed in a new
 136   thread, even if the thread with the given id is waiting in the pool. No id is bound
 137   to the newly created thread. The responsibility is left to the bridge (if it
 138   wishes to bind a name).
 139
 140   If pJob is a reply, there MUST be a thread with the given threadId waiting
 141   for this reply.
 142
 143   @param hPool the handle that was previously created by uno_threadpool_create().
 144   @param pThreadId The Id of the thread, that initialized this request. (In general a
 145                    remote threadid).
 146   @param pJob The argument, that doRequest will get or that will be returned by
 147                    uno_threadpool_enter().
 148   @param doRequest The function, that shall be called to execute the request.
 149                    0 if pJob is a reply.
 150   @param bIsOneway True, if the request is asynchronous. False, if it is synchronous.
 151                    Set to sal_False, if pJob is a reply.
 152  */
 153 CPPU_DLLPUBLIC void SAL_CALL
 154 uno_threadpool_putJob(
 155     uno_ThreadPool hPool,
 156     sal_Sequence *pThreadId,
 157     void *pJob,
 158     void ( SAL_CALL * doRequest ) ( void *pThreadSpecificData ),
 159     sal_Bool bIsOneway ) SAL_THROW_EXTERN_C();
 160
 161 /**
 162   All threads, that are waiting on the hPool handle, are forced out of the pool.
 163   The threads waiting with uno_threadpool_enter() will return with *ppJob == 0
 164
 165   Later calls to uno_threadpool_enter() using the hPool handle will also
 166   return immediately with *ppJob == 0.
 167
 168   @param hPool The handle to be disposed.
 169
 170   This function is called i.e. by a bridge, that is forced to dispose itself.
 171  */
 172 CPPU_DLLPUBLIC void SAL_CALL
 173 uno_threadpool_dispose( uno_ThreadPool hPool ) SAL_THROW_EXTERN_C();
 174
 175
 176 /** Releases the previously with uno_threadpool_create() created handle.
 177     The handle thus becomes invalid. It is an error to use the handle after
 178     uno_threadpool_destroy().
 179
 180     A call to uno_threadpool_destroy can synchronously join on spawned worker
 181     threads, so this function must never be called from such a worker thread.
 182
 183     @see uno_threadpool_create()
 184  */
 185 CPPU_DLLPUBLIC void SAL_CALL
 186 uno_threadpool_destroy( uno_ThreadPool hPool ) SAL_THROW_EXTERN_C();
 187
 188 #ifdef __cplusplus
 189 }
 190 #endif
 191
 192 #endif // INCLUDED_UNO_THREADPOOL_H
 193
 194 /* vim:set shiftwidth=4 softtabstop=4 expandtab: */