/************************************************************************* * * $RCSfile: threadpool.h,v $ * * $Revision: 1.3 $ * * last change: $Author: dbo $ $Date: 2001-03-09 12:10:56 $ * * The Contents of this file are made available subject to the terms of * either of the following licenses * * - GNU Lesser General Public License Version 2.1 * - Sun Industry Standards Source License Version 1.1 * * Sun Microsystems Inc., October, 2000 * * GNU Lesser General Public License Version 2.1 * ============================================= * Copyright 2000 by Sun Microsystems, Inc. * 901 San Antonio Road, Palo Alto, CA 94303, USA * * This library is free software; you can redistribute it and/or * modify it under the terms of the GNU Lesser General Public * License version 2.1, as published by the Free Software Foundation. * * This library is distributed in the hope that it will be useful, * but WITHOUT ANY WARRANTY; without even the implied warranty of * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU * Lesser General Public License for more details. * * You should have received a copy of the GNU Lesser General Public * License along with this library; if not, write to the Free Software * Foundation, Inc., 59 Temple Place, Suite 330, Boston, * MA 02111-1307 USA * * * Sun Industry Standards Source License Version 1.1 * ================================================= * The contents of this file are subject to the Sun Industry Standards * Source License Version 1.1 (the "License"); You may not use this file * except in compliance with the License. You may obtain a copy of the * License at http://www.openoffice.org/license.html. * * Software provided under this License is provided on an "AS IS" basis, * WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, * WITHOUT LIMITATION, WARRANTIES THAT THE SOFTWARE IS FREE OF DEFECTS, * MERCHANTABLE, FIT FOR A PARTICULAR PURPOSE, OR NON-INFRINGING. * See the License for the specific provisions governing your rights and * obligations concerning the Software. * * The Initial Developer of the Original Code is: Sun Microsystems, Inc. * * Copyright: 2000 by Sun Microsystems, Inc. * * All Rights Reserved. * * Contributor(s): _______________________________________ * * ************************************************************************/ #include #include #ifdef __cplusplus extern "C" { #endif /*** * Thread identifier administration. ***/ /** * Establishs an association between the current thread an the given thread identifier. * There can be only one association at a time. The association must be broken by * uno_releaseIdFromCurrentThread. * This method is in general called by a bridge, that wants to bind a remote threadId * to a new thread. * * @param pThreadId a byte sequence, that contains the identifier of the current thread. * @return true, when the identifier was registered.
* false, when the thread has already an identifier. The identifier was not * altered. ( This is in general a bug ).
**/ SAL_DLLEXPORT sal_Bool SAL_CALL uno_bindIdToCurrentThread( sal_Sequence *pThreadId ) SAL_THROW_EXTERN_C(); /** * Get the identifier of the current thread. * If no id has been bound for the thread before, a new one is generated and bound * to the thread. * For each call to uno_getIdOfCurrentThread, a call to uno_releaseIdFromCurrentThread * must be done. * * @param ppThreadId [out] Contains the (acquired) ThreadId. **/ SAL_DLLEXPORT void SAL_CALL uno_getIdOfCurrentThread( sal_Sequence **ppThreadId ) SAL_THROW_EXTERN_C(); /** * If the internal refcount drops to zero, the association betwen threadId and * thread is broken. **/ SAL_DLLEXPORT void SAL_CALL uno_releaseIdFromCurrentThread() SAL_THROW_EXTERN_C(); /** * The threadpool **/ struct uno_threadpool_Handle; /** * Create a handle for the current thread before entering waiting pool. This method must be * called, BEFORE the request is sent (to avoid a race between this thread and an incoming * reply). * This method shall only be called for synchronous requests. * * @param nDisposeId An ID, that uniquely identifies a bridge within the * local process. The pointer to the bridge object should be used. * @see uno_threadpool_disposeThreads ***/ SAL_DLLEXPORT struct uno_threadpool_Handle * SAL_CALL uno_threadpool_createHandle( sal_Int64 nDisposeId ) SAL_THROW_EXTERN_C(); /** * This method is called to wait for a reply of a previously sent request. This is a * blocking method. * * @param pHandle the handle that was previously created by uno_threadpool_createHandle. * @param ppThreadSpecificData [out] the pointer, that was given by uno_threadpool_reply. * If the threads for this bridge were disposed, * *ppThreadSpecificData is null. **/ SAL_DLLEXPORT void SAL_CALL uno_threadpool_enter( struct uno_threadpool_Handle * pHandle , void **ppThreadSpecificData ) SAL_THROW_EXTERN_C(); /** * A request is put into a queue of waiting requests. This method is non-blocking. * * If the request is synchronous, it is first looked up, * if there exists a handle with the given * identifier. If this is the case, the thread is woken up and the doRequest * function is called with the given pThreadSpecificData. If no handle exists, * a new thread is created and the given threadId is bound to the new thread. * * If the request is asynchronous, it is put into the queue of asynchronous * requests for the current threadid. The requests are always executed in a new * thread, even if the thread with the given Id waiting in the pool. No Id is bound * to the newly created thread. The responsibilty is left to the bridge ( if it * wishes to bind a name). * * @param pThreadId The Id of thread, that initialized this request. (In general a * remote threadid). * @param pThreadSpecificData The argument, that doRequest will get. * @param doRequest The function, that shall be called to execute the request. * @param bIsOneway True, if the request is asynchrons. False, if it is synchronous * **/ SAL_DLLEXPORT void SAL_CALL uno_threadpool_putRequest( sal_Sequence *pThreadId, void *pThreadSpecificData, void ( SAL_CALL * doRequest ) ( void *pThreadSpecificData ), sal_Bool bIsOneway ) SAL_THROW_EXTERN_C(); /** * A reply is put into the threadpool. There MUST be a thread with the given threadId waiting * for this reply. This method is non-blocking. * * @param pThreadSpecificData The pointer, that is returned by uno_threadpool_enter. **/ SAL_DLLEXPORT void SAL_CALL uno_threadpool_putReply( sal_Sequence *pThreadId, void *pThreadSpecificData ) SAL_THROW_EXTERN_C(); /** * All threads, that are waiting on handles, that were created with * nDisposeId, are forced out of the pool. * (@see uno_threadpool_createTicket) These threads will return from * uno_threadpool_enter with 0 == *ppThreadSpecificData. * Later calls to uno_threadpool_enter with the given disposeId also * return immeadiatly. * * @param nDisposeId Identfies the caller of uno_threadpool_createTicket * * This function is called i.e. by a bridge, that is forced to dispose itself. * When disposing of the bridge has finished, the bridge MUST call * uno_threadpool_stopDisposeThreads. **/ SAL_DLLEXPORT void SAL_CALL uno_threadpool_disposeThreads( sal_Int64 nDisposeId ) SAL_THROW_EXTERN_C(); /** * Informs the threadpool, that no special treatment is needed for the given nDisposeId. * This allows the threadpool to release internal resources * and must be called after all threads originated from this bridge have returned. * (This can in general be done in the bridge destructor). * * @param nDisposeId Identifies the caller of uno_threadpool_createTicket * @see uno_threadpool_disposeThreads **/ SAL_DLLEXPORT void SAL_CALL uno_threadpool_stopDisposeThreads( sal_Int64 nDisposeId ) SAL_THROW_EXTERN_C(); #ifdef __cplusplus } #endif