/* * Copyright (c) 2014, Siemens AG. All rights reserved. * * Redistribution and use in source and binary forms, with or without * modification, are permitted provided that the following conditions are met: * * 1. Redistributions of source code must retain the above copyright notice, * this list of conditions and the following disclaimer. * * 2. Redistributions in binary form must reproduce the above copyright notice, * this list of conditions and the following disclaimer in the documentation * and/or other materials provided with the distribution. * * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE * POSSIBILITY OF SUCH DAMAGE. */ #ifndef EMBB_BASE_C_THREAD_H_ #define EMBB_BASE_C_THREAD_H_ /** * \defgroup C_BASE_THREADS Thread * * Threads supporting thread-to-core affinities. * * Provides an abstraction from platform-specific threading implementations to * create, manage, and join threads of execution. Support for thread-to-core * affinities is given on thread creation by using the core set functionality. * * \ingroup C_BASE * \{ */ #ifdef __cplusplus extern "C" { #endif #include #include #include #include #ifdef DOXYGEN /** * Opaque type representing a thread of execution. */ typedef opaque_type embb_thread_t; #endif /* DOXYGEN */ /** * Thread start function pointer type. * * The return value can be used to return a user-defined exit code when the * thread is joined. */ typedef int(*embb_thread_start_t)(void*); /** * Returns the maximum number of threads handled by EMB2. * * The maximum thread number concerns all threads in a program using * EMB2 functionalities or data structures, regardless of whether * a thread is started by EMB2 or other threading libraries. * Each thread that makes use of EMB2 at least once consumes one * entry in the internal tables. The entry is permanently consumed during a * program run, even if the thread does not exist any longer. If more threads * than the maximum thread count access EMB2, undefined behavior or * abortion of program execution can occur. * * \return Maximum number of threads * * \lockfree * * \see embb_thread_set_max_count() */ unsigned int embb_thread_get_max_count(); /** * Sets maximum number of threads handled by EMBB. * * It needs to be set before any EMB2 functionalities are used or * data structures are defined, unless the default value is sufficient. * * \notthreadsafe * \see embb_thread_get_max_count() */ void embb_thread_set_max_count( unsigned int max /**< [IN] Maximum number of threads */ ); /** * Returns the calling thread (that is, this thread). * * The returned handle is only valid for the thread calling the function. * * \return Calling thread * * \threadsafe */ embb_thread_t embb_thread_current(); /** * Reschedule the current thread for later execution. * * This is only a request, the realization depends on the implementation and the * scheduler employed by the operating system. * * \threadsafe */ void embb_thread_yield(); /** * Creates and runs a thread. * * \pre The given thread is not running and has not yet been successfully joined. * \post On success, the given thread has started to run. * \return EMBB_SUCCESS if the thread could be created. \n * EMBB_NOMEM if there was insufficient amount of memory \n * EMBB_ERROR otherwise. * \memory Dynamically allocates a small constant amount of memory to store the * function and argument pointers. This memory is freed when the thread * is joined. * \notthreadsafe * \see embb_thread_join() */ int embb_thread_create( embb_thread_t* thread, /**< [OUT] Thread to be run */ const embb_core_set_t* core_set, /**< [IN] Set of cores on which the thread shall be executed. Can be NULL to indicate automatic thread scheduling by the OS. */ embb_thread_start_t function, /**< [IN] Function which is executed by the thread when started. Has to be of type embb_thread_start_t. */ void* arg /**< [IN/OUT] Argument to thread start function. Can be NULL. */ ); /** * Waits until the given thread has finished execution. * * \pre The given thread has been successfully created using embb_thread_create(). * \post If successful, the thread has finished execution and all memory * associated to the thread has been freed. * \return EMBB_SUCCESS if thread was joined \n * EMBB_ERROR otherwise * \notthreadsafe * \see embb_thread_create() */ int embb_thread_join( embb_thread_t* thread, /**< [IN/OUT] Thread to be joined */ int* result_code /**< [OUT] Memory location (or NULL) for thread result code */ ); /** * Compares two threads represented by their handles for equality. * * \return Non-zero, if equal \n * 0, otherwise * \notthreadsafe */ int embb_thread_equal( const embb_thread_t* lhs, /**< [IN] First thread (left-hand side of equality sign) */ const embb_thread_t* rhs /**< [IN] Second thread (right-hand side of equality sign) */ ); #ifdef __cplusplus } /* Close extern "C" { */ #endif /** * \} */ #endif /* EMBB_BASE_C_THREAD_H_ */