/************************************************************************* * * * Open Dynamics Engine, Copyright (C) 2001,2002 Russell L. Smith. * * All rights reserved. Email: russ@q12.org Web: www.q12.org * * * * Threading support header file. * * Copyright (C) 2011-2020 Oleh Derevenko. All rights reserved. * * e-mail: odar@eleks.com (change all "a" to "e") * * * * This library is free software; you can redistribute it and/or * * modify it under the terms of EITHER: * * (1) The GNU Lesser General Public License as published by the Free * * Software Foundation; either version 2.1 of the License, or (at * * your option) any later version. The text of the GNU Lesser * * General Public License is included with this library in the * * file LICENSE.TXT. * * (2) The BSD-style license that is included with this library in * * the file LICENSE-BSD.TXT. * * * * 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 files * * LICENSE.TXT and LICENSE-BSD.TXT for more details. * * * *************************************************************************/ /* * ODE threading support interfaces */ #ifndef _ODE_THREADING_H_ #define _ODE_THREADING_H_ #include "ode/odeconfig.h" // Include since time_t is used and it is not available by default in some OSes #include #ifdef __cplusplus extern "C" { #endif struct dxThreadingImplementation; typedef struct dxThreadingImplementation *dThreadingImplementationID; typedef unsigned dmutexindex_t; struct dxMutexGroup; typedef struct dxMutexGroup *dMutexGroupID; #define dTHREADING_THREAD_COUNT_UNLIMITED 0U /** * @brief Allocates a group of muteces. * * The Mutex allocated do not need to support recursive locking. * * The Mutex names are provided to aid in debugging and thread state tracking. * * @param impl Threading implementation ID * @param Mutex_count Number of Mutex to create * @Mutex_names_ptr Pointer to optional Mutex names array to be associated with individual Mutex * @returns MutexGroup ID or NULL if error occurred. * * @ingroup threading * @see dMutexGroupFreeFunction * @see dMutexGroupMutexLockFunction * @see dMutexGroupMutexUnlockFunction */ typedef dMutexGroupID dMutexGroupAllocFunction (dThreadingImplementationID impl, dmutexindex_t Mutex_count, const char *const *Mutex_names_ptr/*=NULL*/); /** * @brief Deletes a group of muteces. * * @param impl Threading implementation ID * @param mutex_group Mutex group to deallocate * * @ingroup threading * @see dMutexGroupAllocFunction * @see dMutexGroupMutexLockFunction * @see dMutexGroupMutexUnlockFunction */ typedef void dMutexGroupFreeFunction (dThreadingImplementationID impl, dMutexGroupID mutex_group); /** * @brief Locks a mutex in a group of muteces. * * The function is to block execution until requested mutex can be locked. * * Note: Mutex provided may not support recursive locking. Calling this function * while mutex is already locked by current thread will result in unpredictable behavior. * * @param impl Threading implementation ID * @param mutex_group Mutex group to use for locking * @param mutex_index The index of mutex to be locked (0..Mutex_count - 1) * * @ingroup threading * @see dMutexGroupAllocFunction * @see dMutexGroupFreeFunction * @see dMutexGroupMutexUnlockFunction */ typedef void dMutexGroupMutexLockFunction (dThreadingImplementationID impl, dMutexGroupID mutex_group, dmutexindex_t mutex_index); /** * @brief Attempts to lock a mutex in a group of muteces. * * The function is to lock the requested mutex if it is unoccupied or * immediately return failure if mutex is already locked by other thread. * * Note: Mutex provided may not support recursive locking. Calling this function * while mutex is already locked by current thread will result in unpredictable behavior. * * @param impl Threading implementation ID * @param mutex_group Mutex group to use for locking * @param mutex_index The index of mutex to be locked (0..Mutex_count - 1) * @returns 1 for success (mutex is locked) and 0 for failure (mutex is not locked) * * @ingroup threading * @see dMutexGroupAllocFunction * @see dMutexGroupFreeFunction * @see dMutexGroupMutexLockFunction * @see dMutexGroupMutexUnlockFunction */ /* typedef int dMutexGroupMutexTryLockFunction (dThreadingImplementationID impl, dMutexGroupID mutex_group, dmutexindex_t mutex_index);*/ /** * @brief Unlocks a mutex in a group of muteces. * * The function is to unlock the given mutex provided it had been locked before. * * @param impl Threading implementation ID * @param mutex_group Mutex group to use for unlocking * @param mutex_index The index of mutex to be unlocked (0..Mutex_count - 1) * * @ingroup threading * @see dMutexGroupAllocFunction * @see dMutexGroupFreeFunction * @see dMutexGroupMutexLockFunction */ typedef void dMutexGroupMutexUnlockFunction (dThreadingImplementationID impl, dMutexGroupID mutex_group, dmutexindex_t mutex_index); struct dxCallReleasee; typedef struct dxCallReleasee *dCallReleaseeID; struct dxCallWait; typedef struct dxCallWait *dCallWaitID; typedef dsizeint ddependencycount_t; typedef ddiffint ddependencychange_t; typedef dsizeint dcallindex_t; typedef int dThreadedCallFunction(void *call_context, dcallindex_t instance_index, dCallReleaseeID this_releasee); typedef struct dxThreadedWaitTime { time_t wait_sec; unsigned long wait_nsec; } dThreadedWaitTime; /** * @brief Allocates a Wait ID that can be used to wait for a call. * * @param impl Threading implementation ID * @returns Wait ID or NULL if error occurred * * @ingroup threading * @see dThreadedCallWaitResetFunction * @see dThreadedCallWaitFreeFunction * @see dThreadedCallPostFunction * @see dThreadedCallWaitFunction */ typedef dCallWaitID dThreadedCallWaitAllocFunction(dThreadingImplementationID impl); /** * @brief Resets a Wait ID so that it could be used to wait for another call. * * @param impl Threading implementation ID * @param call_wait Wait ID to reset * * @ingroup threading * @see dThreadedCallWaitAllocFunction * @see dThreadedCallWaitFreeFunction * @see dThreadedCallPostFunction * @see dThreadedCallWaitFunction */ typedef void dThreadedCallWaitResetFunction(dThreadingImplementationID impl, dCallWaitID call_wait); /** * @brief Frees a Wait ID. * * @param impl Threading implementation ID * @param call_wait Wait ID to delete * * @ingroup threading * @see dThreadedCallWaitAllocFunction * @see dThreadedCallPostFunction * @see dThreadedCallWaitFunction */ typedef void dThreadedCallWaitFreeFunction(dThreadingImplementationID impl, dCallWaitID call_wait); /** * @brief Post a function to be called in another thread. * * A call is scheduled to be executed asynchronously. * * A @a out_summary_fault variable can be provided for call to accumulate any * possible faults from its execution and execution of any possible sub-calls. * This variable gets result that @a call_func returns. Also, if dependent calls * are executed after the call already exits, the variable is also going to be * updated with results of all those calls before control is released to master. * * @a out_post_releasee parameter receives a value of @c dCallReleaseeID that can * later be used for @a dependent_releasee while scheduling sub-calls to make * current call depend on them. The value is only returned if @a dependencies_count * is not zero (i.e. if any dependencies are expected at all). The call is not going * to start until all its dependencies complete. * * In case if number of dependencies is unknown in advance 1 can be passed on call * scheduling. Then @c dThreadedCallDependenciesCountAlterFunction can be used to * add one more extra dependencies before scheduling each subcall. And then, after * all sub-calls had been scheduled, @c dThreadedCallDependenciesCountAlterFunction * can be used again to subtract initial extra dependency from total number. * Adding one dependency in advance is necessary to obtain releasee ID and to make * sure the call will not start and will not terminate before all sub-calls are scheduled. * * Extra dependencies can also be added from the call itself after it has already * been started (with parameter received in @c dThreadedCallFunction). * In that case those dependencies will start immediately or after call returns * but the call's master will not be released/notified until all additional * dependencies complete. This can be used to schedule sub-calls from a call and * then pass own job to another sub-call dependent on those initial sub-calls. * * By using @ call_wait it is possible to assign a Wait ID that can later * be passed into @c dThreadedCallWaitFunction to wait for call completion. * * If @a call_name is available (and it should!) the string must remain valid until * after call completion. In most cases this should be a static string literal. * * Since the function is an analogue of normal method call it is not supposed to fail. * Any complications with resource allocation on call scheduling should be * anticipated, avoided and worked around by implementation. * * @param impl Threading implementation ID * @param out_summary_fault Optional pointer to variable to be set to 1 if function * call (or any sub-call) fails internally, or 0 if all calls return success * @param out_post_releasee Optional pointer to variable to receive releasee ID * associated with the call * @param dependencies_count Number of dependencies that are going to reference * this call as dependent releasee * @param dependent_releasee Optional releasee ID to reference with this call * @param call_wait Optional Wait ID that can later be used to wait for the call * @param call_func Pointer to function to be called * @param call_context Context parameter to be passed into the call * @param instance_index Index parameter to be passed into the call * @param call_name Optional name to be associated with the call (for debugging and state tracking) * * @ingroup threading * @see dThreadedCallWaitFunction * @see dThreadedCallDependenciesCountAlterFunction * @see dThreadingImplResourcesForCallsPreallocateFunction */ typedef void dThreadedCallPostFunction(dThreadingImplementationID impl, int *out_summary_fault/*=NULL*/, dCallReleaseeID *out_post_releasee/*=NULL*/, ddependencycount_t dependencies_count, dCallReleaseeID dependent_releasee/*=NULL*/, dCallWaitID call_wait/*=NULL*/, dThreadedCallFunction *call_func, void *call_context, dcallindex_t instance_index, const char *call_name/*=NULL*/); /** * @brief Add or remove extra dependencies from call that has been scheduled * or is in process of execution. * * Extra dependencies can be added to a call if exact number of sub-calls is * not known in advance at the moment the call is scheduled. Also, some dependencies * can be removed if sub-calls were planned but then dropped. * * In case if total dependency count of a call reaches zero by result of invoking * this function, the call is free to start executing immediately. * * After the call execution had been started, any additional dependencies can only * be added from the call function itself! * * @param impl Threading implementation ID * @param target_releasee ID of releasee to apply dependencies count change to * @param dependencies_count_change Number of dependencies to add or remove * * @ingroup threading * @see dThreadedCallPostFunction */ typedef void dThreadedCallDependenciesCountAlterFunction(dThreadingImplementationID impl, dCallReleaseeID target_releasee, ddependencychange_t dependencies_count_change); /** * @brief Wait for a posted call to complete. * * Function blocks until a call identified by @a call_wait completes or * timeout elapses. * * IT IS ILLEGAL TO INVOKE THIS FUNCTION FROM WITHIN A THREADED CALL! * This is because doing so will block a physical thread and will require * increasing worker thread count to avoid starvation. Use call dependencies * if it is necessary make sure sub-calls have been completed instead! * * If @a timeout_time_ptr is NULL, the function waits without time limit. If @a timeout_time_ptr * points to zero value, the function only checks status and does not block. * * If @a wait_name is available (and it should!) the string must remain valid for * the duration of wait. In most cases this should be a static string literal. * * Function is not expected to return failures caused by system call faults as * those are hardly ever possible to be handled in this case anyway. In event of * system call fault the function is supposed to terminate application. * * @param impl Threading implementation ID * @param out_wait_status Optional pointer to variable to receive 1 if waiting succeeded * or 0 in case of timeout * @param call_wait Wait ID that had been passed to scheduling a call that needs to be waited for * @param timeout_time_ptr Optional pointer to time specification the wait must not * last longer than (pass NULL for infinite timeout) * @param wait_name Optional name to be associated with the wait (for debugging and state tracking) * * @ingroup threading * @see dThreadedCallPostFunction */ typedef void dThreadedCallWaitFunction(dThreadingImplementationID impl, int *out_wait_status/*=NULL*/, dCallWaitID call_wait, const dThreadedWaitTime *timeout_time_ptr/*=NULL*/, const char *wait_name/*=NULL*/); /** * @brief Retrieve number of active threads that serve the implementation. * * @param impl Threading implementation ID * @returns Number of active threads * * @ingroup threading */ typedef unsigned dThreadingImplThreadCountRetrieveFunction(dThreadingImplementationID impl); /** * @brief Preallocate resources to handle posted calls. * * The function is intended to make sure enough resources is preallocated for the * implementation to be able to handle posted calls. Then @c max_simultaneous_calls_estimate * is an estimate of how many posted calls can potentially be active or scheduled * at the same time. The value is usually derived from the way the calls are posted * in library code and dependencies between them. * * @warning While working on an implementation be prepared that the estimate provided * yet rarely but theoretically can be exceeded due to unpredictability of thread execution. * * This function is normally going to be invoked by library each time it is entered * from outside to do the job but before any threaded calls are going to be posted. * * @param impl Threading implementation ID * @param max_simultaneous_calls_estimate An estimated number of calls that can be posted simultaneously * @returns 1 or 0 to indicate success or failure * * @ingroup threading * @see dThreadedCallPostFunction */ typedef int dThreadingImplResourcesForCallsPreallocateFunction(dThreadingImplementationID impl, ddependencycount_t max_simultaneous_calls_estimate); /** * @brief An interface structure with function pointers to be provided by threading implementation. */ typedef struct dxThreadingFunctionsInfo { unsigned struct_size; dMutexGroupAllocFunction *alloc_mutex_group; dMutexGroupFreeFunction *free_mutex_group; dMutexGroupMutexLockFunction *lock_group_mutex; dMutexGroupMutexUnlockFunction *unlock_group_mutex; dThreadedCallWaitAllocFunction *alloc_call_wait; dThreadedCallWaitResetFunction *reset_call_wait; dThreadedCallWaitFreeFunction *free_call_wait; dThreadedCallPostFunction *post_call; dThreadedCallDependenciesCountAlterFunction *alter_call_dependencies_count; dThreadedCallWaitFunction *wait_call; dThreadingImplThreadCountRetrieveFunction *retrieve_thread_count; dThreadingImplResourcesForCallsPreallocateFunction *preallocate_resources_for_calls; /* * Beware of Jon Watte's anger if you dare to uncomment this! * May cryptic text below be you a warning! * Стародавні легенди розказують, що кожного сміливця, хто наважиться порушити табу * і відкрити заборонений код, спіткає страшне прокляття і він відразу почне робити * одні лиш помилки. * * dMutexGroupMutexTryLockFunction *trylock_group_mutex; */ } dThreadingFunctionsInfo; #ifdef __cplusplus } #endif #endif /* #ifndef _ODE_THREADING_H_ */