include/uno/threadpool.h

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