cppu/inc/uno/threadpool.h

   1 /*************************************************************************
   2  *
   3  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
   4  *
   5  * Copyright 2008 by Sun Microsystems, Inc.
   6  *
   7  * OpenOffice.org - a multi-platform office productivity suite
   8  *
   9  * $RCSfile: threadpool.h,v $
  10  * $Revision: 1.8 $
  11  *
  12  * This file is part of OpenOffice.org.
  13  *
  14  * OpenOffice.org is free software: you can redistribute it and/or modify
  15  * it under the terms of the GNU Lesser General Public License version 3
  16  * only, as published by the Free Software Foundation.
  17  *
  18  * OpenOffice.org is distributed in the hope that it will be useful,
  19  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  20  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  21  * GNU Lesser General Public License version 3 for more details
  22  * (a copy is included in the LICENSE file that accompanied this code).
  23  *
  24  * You should have received a copy of the GNU Lesser General Public License
  25  * version 3 along with OpenOffice.org.  If not, see
  26  * <http://www.openoffice.org/license.html>
  27  * for a copy of the LGPLv3 License.
  28  *
  29  ************************************************************************/
  30
  31 #include <sal/types.h>
  32 #include <rtl/byteseq.h>
  33
  34 #ifdef __cplusplus
  35 extern "C" {
  36 #endif
  37
  38 /***
  39  * Thread identifier administration.
  40  ***/
  41 /**
  42   Establishs an association between the current thread and the given thread identifier.
  43   There can be only one association at a time. The association must be broken by
  44   uno_releaseIdFromCurrentThread().
  45   This method is in general called by a bridge, that wants to bind a remote threadId
  46   to a new thread.
  47
  48   @param pThreadId a byte sequence, that contains the identifier of the current thread.
  49   @return true, when the identifier was registered.
  50           false, when the thread has already an identifier. The identifier was not
  51           altered. ( This is in general a bug ).
  52
  53   @see uno_releaseIdFromCurrentThread()
  54  */
  55 sal_Bool SAL_CALL uno_bindIdToCurrentThread( sal_Sequence *pThreadId )
  56     SAL_THROW_EXTERN_C();
  57
  58
  59 /**
  60   Get the identifier of the current thread.
  61   If no id has been bound for the thread before, a new one is generated and bound
  62   to the thread.
  63   For each call to uno_getIdOfCurrentThread(), a call to uno_releaseIdFromCurrentThread()
  64   must be done.
  65
  66   @param ppThreadId [out] Contains the (acquired) ThreadId.
  67   @see uno_releaseIdFromCurrentThread()
  68  */
  69 void SAL_CALL uno_getIdOfCurrentThread( sal_Sequence **ppThreadId )
  70     SAL_THROW_EXTERN_C();
  71
  72
  73 /**
  74   If the internal refcount drops to zero, the association betwen threadId and
  75   thread is broken.
  76  */
  77 void SAL_CALL uno_releaseIdFromCurrentThread()
  78     SAL_THROW_EXTERN_C();
  79
  80
  81 struct _uno_ThreadPool;
  82 typedef struct _uno_ThreadPool * uno_ThreadPool;
  83
  84 /**
  85   Creates a threadpool handle. Typically each remote bridge instances creates one
  86   handle.
  87  */
  88 uno_ThreadPool SAL_CALL
  89 uno_threadpool_create() SAL_THROW_EXTERN_C();
  90
  91
  92 /**
  93   Makes the current thread known to the threadpool. This function must be
  94   called, BEFORE uno_threadpool_enter() is called and BEFORE a job for this
  95   thread is put into the threadpool (avoid a race between this thread and
  96   an incoming request/reply).
  97   For every call to uno_threadpool_attach, a corrosponding call to
  98   uno_threadpool_detach must be done.
  99
 100   @param hPool The bridge threadpool handle previously created by uno_threadpool_create.
 101
 102 */
 103 void SAL_CALL
 104 uno_threadpool_attach( uno_ThreadPool hPool ) SAL_THROW_EXTERN_C();
 105
 106 /**
 107   This method is called to wait for a reply of a previously sent request. This is a
 108   blocking method. uno_threadpool_attach() must have been called before.
 109
 110   @param hPool the handle that was previously created by uno_threadpool_create().
 111   @param ppJob [out] the pointer, that was given by uno_threadpool_putJob
 112   0, when uno_threadpool_dispose() was the reason to fall off from threadpool.
 113   @see uno_threadpool_dispose()
 114  **/
 115 void SAL_CALL
 116 uno_threadpool_enter( uno_ThreadPool hPool , void **ppJob )
 117     SAL_THROW_EXTERN_C();
 118
 119 /**
 120    Detaches the current thread from the threadpool. Must be called for
 121    every call to uno_threadpool_attach.
 122 */
 123 void SAL_CALL
 124 uno_threadpool_detach( uno_ThreadPool hPool ) SAL_THROW_EXTERN_C();
 125
 126 /**
 127   Puts a job into the pool. A job may eiter be a request or a reply
 128   (replies have a 0 in the doRequest parameter). This function is non-blocking.
 129
 130   A request may either be synchronous or asynchronous.
 131   If the request is synchronous, it is first looked up,
 132   if there exists a handle with the given
 133   identifier. If this is the case, the thread is woken up and the doRequest
 134   function is called with the given pJob. If no handle exists,
 135   a new thread is created and the given threadId is bound to the new thread.
 136
 137   If the request is asynchronous, it is put into the queue of asynchronous
 138   requests for the current threadid. The requests are always executed in a new
 139   thread, even if the thread with the given id is waiting in the pool. No id is bound
 140   to the newly created thread. The responsibilty is left to the bridge ( if it
 141   wishes to bind a name).
 142
 143   If pJob is a reply, there MUST be a thread with the given threadId waiting
 144   for this reply.
 145
 146   @param pThreadId The Id of the thread, that initialized this request. (In general a
 147                    remote threadid).
 148   @param pJob The argument, that doRequest will get or that will be returned by
 149                    uno_threadpool_enter().
 150   @param doRequest The function, that shall be called to execute the request.
 151                    0 if pJob is a reply.
 152   @param bIsOneway True, if the request is asynchrons. False, if it is synchronous.
 153                    Set to sal_False, if pJob is a reply.
 154  */
 155 void SAL_CALL
 156 uno_threadpool_putJob(
 157     uno_ThreadPool hPool,
 158     sal_Sequence *pThreadId,
 159     void *pJob,
 160     void ( SAL_CALL * doRequest ) ( void *pThreadSpecificData ),
 161     sal_Bool bIsOneway ) SAL_THROW_EXTERN_C();
 162
 163 /**
 164   All threads, that are waiting on the hPool handle, are forced out of the pool.
 165   The threads waiting with uno_threadpool_enter() will return with *ppJob == 0
 166
 167   Later calls to uno_threadpool_enter() using the hPool handle will also
 168   return immeadiatly with *ppJob == 0.
 169
 170   @param hPool The handle to be disposed.
 171   In case, hPool is 0, this function joins on all threads created
 172   by the threadpool administration. This may e.g. used to ensure, that
 173   no threads are inside the cppu library anymore, in case it needs to get
 174   unloaded.
 175
 176   This function is called i.e. by a bridge, that is forced to dispose itself.
 177  */
 178 void SAL_CALL
 179 uno_threadpool_dispose( uno_ThreadPool hPool ) SAL_THROW_EXTERN_C();
 180
 181
 182 /** Releases the previously with uno_threadpool_create() created handle.
 183     The handle thus becomes invalid. It is an error to use the handle after
 184     uno_threadpool_destroy().
 185     @see uno_threadpool_create()
 186  */
 187 void SAL_CALL
 188 uno_threadpool_destroy( uno_ThreadPool hPool ) SAL_THROW_EXTERN_C();
 189
 190 #ifdef __cplusplus
 191 }
 192 #endif