include/ode/threading_impl.h

   1 /*************************************************************************
   2  *                                                                       *
   3  * Open Dynamics Engine, Copyright (C) 2001,2002 Russell L. Smith.       *
   4  * All rights reserved.  Email: russ@q12.org   Web: www.q12.org          *
   5  *                                                                       *
   6  * Builtin ODE threading implementation header.                          *
   7  * Copyright (C) 2011-2024 Oleh Derevenko. All rights reserved.          *
   8  * e-mail: odar@eleks.com (change all "a" to "e")                        *
   9  *                                                                       *
  10  * This library is free software; you can redistribute it and/or         *
  11  * modify it under the terms of EITHER:                                  *
  12  *   (1) The GNU Lesser General Public License as published by the Free  *
  13  *       Software Foundation; either version 2.1 of the License, or (at  *
  14  *       your option) any later version. The text of the GNU Lesser      *
  15  *       General Public License is included with this library in the     *
  16  *       file LICENSE.TXT.                                               *
  17  *   (2) The BSD-style license that is included with this library in     *
  18  *       the file LICENSE-BSD.TXT.                                       *
  19  *                                                                       *
  20  * This library is distributed in the hope that it will be useful,       *
  21  * but WITHOUT ANY WARRANTY; without even the implied warranty of        *
  22  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the files    *
  23  * LICENSE.TXT and LICENSE-BSD.TXT for more details.                     *
  24  *                                                                       *
  25  *************************************************************************/
  26
  27 /*
  28  *  A threading implementation built into ODE for those who does not care to
  29  *  or can't implement an own one.
  30  */
  31
  32 #ifndef _ODE_THREADING_IMPL_H_
  33 #define _ODE_THREADING_IMPL_H_
  34
  35
  36 #include <ode/odeconfig.h>
  37 #include <ode/threading.h>
  38
  39
  40 #ifdef __cplusplus
  41 extern "C" {
  42 #endif
  43
  44
  45 struct dxThreadingThreadPool;
  46 typedef struct dxThreadingThreadPool *dThreadingThreadPoolID;
  47
  48
  49 /**
  50  * @brief Allocates built-in self-threaded threading implementation object.
  51  *
  52  * A self-threaded implementation is a type of implementation that performs
  53  * processing of posted calls by means of caller thread itself. This type of
  54  * implementation does not need thread pool to serve it.
  55  *
  56  * Note that since May 9th, 2017 (rev. #2066) the Self-Threaded implementation
  57  * returns 0 rather than 1 as available thread count to distinguish from
  58  * thread pools with just one thread in them.
  59  *
  60  * The processing is arranged in a way to prevent call stack depth growth
  61  * as more and more nested calls are posted.
  62  *
  63  * Note that it is not necessary to create and assign a self-threaded
  64  * implementation to a world, as there is a global one used by default
  65  * if no implementation is explicitly assigned. You should only assign
  66  * each world an individual threading implementation instance if simulations
  67  * need to be run in parallel in multiple threads for the worlds.
  68  *
  69  * @returns ID of object allocated or NULL on failure
  70  *
  71  * @ingroup threading
  72  * @see dThreadingAllocateMultiThreadedImplementation
  73  * @see dThreadingFreeImplementation
  74  */
  75 ODE_API dThreadingImplementationID dThreadingAllocateSelfThreadedImplementation();
  76
  77 /**
  78  * @brief Allocates built-in multi-threaded threading implementation object.
  79  *
  80  * A multi-threaded implementation is a type of implementation that has to be
  81  * served with a thread pool. The thread pool can be either the built-in ODE object
  82  * or set of external threads that dedicate themselves to this purpose and stay
  83  * in ODE until implementation releases them.
  84  *
  85  * @returns ID of object allocated or NULL on failure
  86  *
  87  * @ingroup threading
  88  * @see dThreadingThreadPoolServeMultiThreadedImplementation
  89  * @see dExternalThreadingServeMultiThreadedImplementation
  90  * @see dThreadingFreeImplementation
  91  */
  92 ODE_API dThreadingImplementationID dThreadingAllocateMultiThreadedImplementation();
  93
  94 /**
  95  * @brief Retrieves the functions record of a built-in threading implementation.
  96  *
  97  * The implementation can be the one allocated by ODE (from @c dThreadingAllocateMultiThreadedImplementation).
  98  * Do not use this function with self-made custom implementations -
  99  * they should be bundled with their own set of functions.
 100  *
 101  * @param impl Threading implementation ID
 102  * @returns Pointer to associated functions structure
 103  *
 104  * @ingroup threading
 105  * @see dThreadingAllocateMultiThreadedImplementation
 106  */
 107 ODE_API const dThreadingFunctionsInfo *dThreadingImplementationGetFunctions(dThreadingImplementationID impl);
 108
 109 /**
 110  * @brief Requests a built-in implementation to release threads serving it.
 111  *
 112  * The function unblocks threads employed in implementation serving and lets them
 113  * return to from where they originate. It's the responsibility of external code
 114  * to make sure all the calls to ODE that might be dependent on given threading
 115  * implementation object had already returned before this call is made. If threading
 116  * implementation is still processing some posted calls while this function is
 117  * invoked the behavior is implementation dependent.
 118  *
 119  * This call is to be used to request the threads to be released before waiting
 120  * for them in host pool or before waiting for them to exit. Implementation object
 121  * must not be destroyed before it is known that all the serving threads have already
 122  * returned from it. If implementation needs to be reused after this function is called
 123  * and all the threads have exited from it a call to @c dThreadingImplementationCleanupForRestart
 124  * must be made to restore internal state of the object.
 125  *
 126  * If this function is called for self-threaded built-in threading implementation
 127  * the call has no effect.
 128  *
 129  * @param impl Threading implementation ID
 130  *
 131  * @ingroup threading
 132  * @see dThreadingAllocateMultiThreadedImplementation
 133  * @see dThreadingImplementationCleanupForRestart
 134  */
 135 ODE_API void dThreadingImplementationShutdownProcessing(dThreadingImplementationID impl);
 136
 137 /**
 138  * @brief Restores built-in implementation's state to let it be reused after shutdown.
 139  *
 140  * If a multi-threaded built-in implementation needs to be reused after a call
 141  * to @c dThreadingImplementationShutdownProcessing this call is to be made to
 142  * restore object's internal state. After that the implementation can be served again.
 143  *
 144  * If this function is called for self-threaded built-in threading implementation
 145  * the call has no effect.
 146  *
 147  * @param impl Threading implementation ID
 148  *
 149  * @ingroup threading
 150  * @see dThreadingAllocateMultiThreadedImplementation
 151  * @see dThreadingImplementationShutdownProcessing
 152  */
 153 ODE_API void dThreadingImplementationCleanupForRestart(dThreadingImplementationID impl);
 154
 155 /**
 156  * @brief Deletes an instance of built-in threading implementation.
 157  *
 158  * @warning A care must be taken to make sure the implementation is unassigned
 159  * from all the objects it was assigned to and that there are no more threads
 160  * serving it before attempting to call this function.
 161  *
 162  * @param impl Threading implementation ID
 163  *
 164  * @ingroup threading
 165  * @see dThreadingAllocateMultiThreadedImplementation
 166  */
 167 ODE_API void dThreadingFreeImplementation(dThreadingImplementationID impl);
 168
 169
 170 typedef void (dThreadReadyToServeCallback)(void *callback_context);
 171
 172 /**
 173  * @brief An entry point for external threads that would like to serve a built-in
 174  * threading implementation object.
 175  *
 176  * A thread that calls this function remains blocked in ODE and serves implementation
 177  * object @p impl until being released with @c dThreadingImplementationShutdownProcessing call.
 178  * This function can be used to provide external threads instead of ODE's built-in
 179  * thread pools.
 180  *
 181  * The optional callback @readiness_callback is called after the thread has reached
 182  * and has registered within the implementation. The implementation should not
 183  * be used until all dedicated threads register within it as otherwise it will not
 184  * have accurate view of the execution resources available.
 185  *
 186  * @param impl Threading implementation ID
 187  * @param readiness_callback Optional readiness callback to be called after thread enters the implementation
 188  * @param callback_context A value to be passed as parameter to readiness callback
 189  *
 190  * @ingroup threading
 191  * @see dThreadingAllocateMultiThreadedImplementation
 192  * @see dThreadingImplementationShutdownProcessing
 193  */
 194 ODE_API void dExternalThreadingServeMultiThreadedImplementation(dThreadingImplementationID impl,
 195   dThreadReadyToServeCallback *readiness_callback/*=NULL*/, void *callback_context/*=NULL*/);
 196
 197
 198 /**
 199  * @brief Creates an instance of built-in thread pool object that can be used to serve
 200  * multi-threaded threading implementations.
 201  *
 202  * The threads allocated inherit priority of caller thread. Their affinity is not
 203  * explicitly adjusted and gets the value the system assigns by default. Threads
 204  * have their stack memory fully committed immediately on start. On POSIX platforms
 205  * threads are started with all the possible signals blocked. Threads execute
 206  * calls to @c dAllocateODEDataForThread with @p ode_data_allocate_flags
 207  * on initialization.
 208  *
 209  * On POSIX platforms this function must be called with signals masked
 210  * or other measures must be taken to prevent reception of signals by calling thread
 211  * for the duration of the call.
 212  *
 213  * @param thread_count Number of threads to start in pool
 214  * @param stack_size Size of stack to be used for every thread or 0 for system default value
 215  * @param ode_data_allocate_flags Flags to be passed to @c dAllocateODEDataForThread on behalf of each thread
 216  * @returns ID of object allocated or NULL on failure
 217  *
 218  * @ingroup threading
 219  * @see dThreadingAllocateMultiThreadedImplementation
 220  * @see dThreadingImplementationShutdownProcessing
 221  * @see dThreadingFreeThreadPool
 222  */
 223 ODE_API dThreadingThreadPoolID dThreadingAllocateThreadPool(unsigned thread_count,
 224   dsizeint stack_size, unsigned int ode_data_allocate_flags, void *reserved/*=NULL*/);
 225
 226 /**
 227  * @brief Commands an instance of built-in thread pool to serve a built-in multi-threaded
 228  * threading implementation.
 229  *
 230  * A pool can only serve one threading implementation at a time.
 231  * Call @c dThreadingImplementationShutdownProcessing to release pool threads
 232  * from implementation serving and make them idle. Pool threads must be released
 233  * from any implementations before pool is attempted to be deleted.
 234  *
 235  * This function waits for threads to register within implementation before returning.
 236  * So, after the function call exits the implementation can be used immediately.
 237  *
 238  * @param pool Thread pool ID to serve the implementation
 239  * @param impl Implementation ID of implementation to be served
 240  *
 241  * @ingroup threading
 242  * @see dThreadingAllocateThreadPool
 243  * @see dThreadingAllocateMultiThreadedImplementation
 244  * @see dThreadingImplementationShutdownProcessing
 245  */
 246 ODE_API void dThreadingThreadPoolServeMultiThreadedImplementation(dThreadingThreadPoolID pool, dThreadingImplementationID impl);
 247
 248 /**
 249  * @brief Waits until all pool threads are released from threading implementation
 250  * they might be serving.
 251  *
 252  * The function can be used after a call to @c dThreadingImplementationShutdownProcessing
 253  * to make sure all the threads have already been released by threading implementation
 254  * and it can be deleted or it can be cleaned up for restart and served by another pool
 255  * or this pool's threads can be used to serve another threading implementation.
 256  *
 257  * Note that is it not necessary to call this function before pool destruction
 258  * since @c dThreadingFreeThreadPool performs similar wait operation implicitly on its own.
 259  *
 260  * It is OK to call this function even if pool was not serving any threading implementation
 261  * in which case the call exits immediately with minimal delay.
 262  *
 263  * @param pool Thread pool ID to wait for
 264  *
 265  * @ingroup threading
 266  * @see dThreadingAllocateThreadPool
 267  * @see dThreadingImplementationShutdownProcessing
 268  * @see dThreadingFreeThreadPool
 269  */
 270 ODE_API void dThreadingThreadPoolWaitIdleState(dThreadingThreadPoolID pool);
 271
 272 /**
 273  * @brief Deletes a built-in thread pool instance.
 274  *
 275  * The pool threads must be released from any implementations they might be serving
 276  * before this function is called. Otherwise the call is going to block
 277  * and wait until pool's threads return.
 278  *
 279  * @param pool Thread pool ID to delete
 280  *
 281  * @ingroup threading
 282  * @see dThreadingAllocateThreadPool
 283  * @see dThreadingImplementationShutdownProcessing
 284  */
 285 ODE_API void dThreadingFreeThreadPool(dThreadingThreadPoolID pool);
 286
 287
 288 #ifdef __cplusplus
 289 }
 290 #endif
 291
 292 #endif /* #ifndef _ODE_THREADING_IMPL_H_ */