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