--- /dev/null
+/*************************************************************************
+ * *
+ * 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-2019 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 <time.h> since time_t is used and it is not available by default in some OSes
+#include <time.h>
+
+
+#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_ */
projects / xonotic / xonotic.git / blobdiff