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