=== modified file 'src/vortex_handlers.h' --- src/vortex_handlers.h 2009-08-03 13:40:43 +0000 +++ src/vortex_handlers.h 2009-08-05 06:03:50 +0000 @@ -1039,6 +1039,46 @@ int position, axlPointer user_data); +/** + * @brief Handler used by Vortex library to create a new thread. A custom handler + * can be specified using \ref vortex_thread_set_create + * + * @param thread_def A reference to the thread identifier created by + * the function. This parameter is not optional. + * + * @param func The function to execute. + * + * @param user_data User defined data to be passed to the function to + * be executed by the newly created thread. + * + * @return The function returns axl_true if the thread was created + * properly and the variable thread_def is defined with the particular + * thread reference created. + * + * @see vortex_thread_create + */ +typedef axl_bool (* VortexThreadCreateFunc) (VortexThread * thread_def, + VortexThreadFunc func, + axlPointer user_data, + va_list args); + +/** + * @brief Handler used by Vortex Library to release a thread's resources. + * A custom handler can be specified using \ref vortex_thread_set_destroy + * + * @param thread_def A reference to the thread that must be destroyed. + * + * @param free_data Boolean that set whether the thread pointer should + * be released or not. + * + * @return axl_true if the destroy operation was ok, otherwise axl_false is + * returned. + * + * @see vortex_thread_destroy + */ +typedef axl_bool (* VortexThreadDestroyFunc) (VortexThread * thread_def, + axl_bool free_data); + #endif /* @} */ === modified file 'src/vortex_thread.c' --- src/vortex_thread.c 2009-08-03 13:40:43 +0000 +++ src/vortex_thread.c 2009-08-05 05:56:19 +0000 @@ -89,7 +89,7 @@ #endif /** - * @brief Creates a new thread, executing the function provided, + * @internal Creates a new thread, executing the function provided, * passing the referece received to the function (user_data). * * For complete examples on how to create threads, see \ref VortexThreadConf documentation. @@ -108,12 +108,11 @@ * * @see vortex_thread_destroy */ -axl_bool vortex_thread_create (VortexThread * thread_def, +axl_bool vortex_thread_create_internal (VortexThread * thread_def, VortexThreadFunc func, axlPointer user_data, - ...) + va_list args) { - va_list args; VortexThreadConf conf; /* default configuration for joinable state, axl_true */ axl_bool joinable = axl_true; @@ -129,7 +128,6 @@ v_return_val_if_fail (func, axl_false); /* open arguments to get the thread configuration */ - va_start (args, user_data); do { /* get next configuration */ conf = va_arg (args, axl_bool); @@ -149,8 +147,6 @@ } while (1); - /* close the std args */ - va_end (args); #if defined(AXL_OS_WIN32) @@ -212,18 +208,18 @@ } /** - * @brief Wait for the provided thread to finish, destroy its + * @internal Wait for the provided thread to finish, destroy its * resources and optionally release its pointer. * * @param thread_def A reference to the thread that must be destroyed. * * @param free_data Boolean that set whether the thread pointer should - * be released ot not. + * be released or not. * * @return axl_true if the destroy operation was ok, otherwise axl_false is * returned. */ -axl_bool vortex_thread_destroy (VortexThread * thread_def, axl_bool free_data) +axl_bool vortex_thread_destroy_internal (VortexThread * thread_def, axl_bool free_data) { #if defined(AXL_OS_WIN32) @@ -280,6 +276,120 @@ #endif } +/** + * @internal Variables to hold the active thread management function pointers. + * They are initialised to use the default Vortex functions. If the user are not interested + * in using external threading functions he doesn't need to do anything, or even know about this + * functionality. + */ +VortexThreadCreateFunc __vortex_thread_create = vortex_thread_create_internal; +VortexThreadDestroyFunc __vortex_thread_destroy = vortex_thread_destroy_internal; + +/** + * @brief Creates a new thread, executing the function provided, + * passing the referece received to the function (user_data). + * + * For complete examples on how to create threads, see \ref VortexThreadConf documentation. + * + * @param thread_def A reference to the thread identifier created by + * the function. This parameter is not optional. + * + * @param func The function to execute. + * + * @param user_data User defined data to be passed to the function to + * be executed by the newly created thread. + * + * @return The function returns axl_true if the thread was created + * properly and the variable thread_def is defined with the particular + * thread reference created. + * + * @see vortex_thread_destroy + */ +axl_bool vortex_thread_create (VortexThread * thread_def, + VortexThreadFunc func, + axlPointer user_data, + ...) +{ + axl_bool result; + va_list args; + + /* initialize the args value */ + va_start (args, user_data); + + /* create the thread */ + result = __vortex_thread_create(thread_def, func, user_data, args); + + /* end args values */ + va_end (args); + + return result; +} + +/** + * @brief Wait for the provided thread to finish, destroy its + * resources and optionally release its pointer. + * + * @param thread_def A reference to the thread that must be destroyed. + * + * @param free_data Boolean that set whether the thread pointer should + * be released or not. + * + * @return axl_true if the destroy operation was ok, otherwise axl_false is + * returned. + */ +axl_bool vortex_thread_destroy (VortexThread * thread_def, axl_bool free_data) +{ + return __vortex_thread_destroy(thread_def, free_data); +} + +/** + * @brief Allows to specify the function Vortex library will call to create a + * new thread. + * + * If the user does not have reason to change the default thread + * creation mechanism this function can be ignored. + * + * NOTE: The thread mechanism functions (\ref vortex_thread_set_create and + * \ref vortex_thread_set_destroy) must be set before any other Vortex API + * calls are made. Changing the thread mechanism functions while Vortex is + * running will most likely lead to memory corruption or program crashes. + * + * @param create_fn The function to be executed to create a new thread + * + * @see vortex_thread_set_destroy + */ +void vortex_thread_set_create(VortexThreadCreateFunc create_fn) +{ + if (NULL != create_fn) + { + __vortex_thread_create = create_fn; + } +} + +/** + * @brief Allows to specify the function Vortex library will call to destroy a + * thread's resources. + * + * If the user does not have reason to change the default thread + * cleanup mechanism this function can be ignored. + * + * NOTE: The thread mechanism functions (\ref vortex_thread_set_create and + * \ref vortex_thread_set_destroy) must be set before any other Vortex API + * calls are made. Changing the thread mechanism functions while Vortex is + * running will most likely lead to memory corruption or program crashes. + * + * @param destroy_fn The function to be executed to clean up a thread + * + * @see vortex_thread_set_create + */ +void vortex_thread_set_destroy(VortexThreadDestroyFunc destroy_fn) +{ + if (NULL != destroy_fn) + { + __vortex_thread_destroy = destroy_fn; + } +} + /** * @brief Allows to create a new mutex to protect critical sections to * be executed by several threads at the same time. === modified file 'src/vortex_thread.h' --- src/vortex_thread.h 2009-08-03 13:40:43 +0000 +++ src/vortex_thread.h 2009-08-04 10:38:18 +0000 @@ -55,6 +55,10 @@ axl_bool vortex_thread_destroy (VortexThread * thread_def, axl_bool free_data); +void vortex_thread_set_create (VortexThreadCreateFunc create_fn); + +void vortex_thread_set_destroy(VortexThreadDestroyFunc destroy_fn); + axl_bool vortex_mutex_create (VortexMutex * mutex_def); axl_bool vortex_mutex_destroy (VortexMutex * mutex_def);