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