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