Return to thread.h CVS log

Up to [ELWIX - Embedded LightWeight unIX -] / embedaddon / strongswan / src / libstrongswan / threading

Strongswan

    1: /*
    2:  * Copyright (C) 2009 Tobias Brunner
    3:  * HSR Hochschule fuer Technik Rapperswil
    4:  *
    5:  * This program is free software; you can redistribute it and/or modify it
    6:  * under the terms of the GNU General Public License as published by the
    7:  * Free Software Foundation; either version 2 of the License, or (at your
    8:  * option) any later version.  See <http://www.fsf.org/copyleft/gpl.txt>.
    9:  *
   10:  * This program is distributed in the hope that it will be useful, but
   11:  * WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
   12:  * or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
   13:  * for more details.
   14:  */
   15: 
   16: /**
   17:  * @defgroup thread thread
   18:  * @{ @ingroup threading
   19:  */
   20: 
   21: #ifndef THREADING_THREAD_H_
   22: #define THREADING_THREAD_H_
   23: 
   24: #include <utils/utils.h>
   25: 
   26: typedef struct thread_t thread_t;
   27: 
   28: /**
   29:  * Main function of a thread.
   30:  *
   31:  * @param arg			argument provided to constructor
   32:  * @return				value provided to threads joining the terminating thread
   33:  */
   34: typedef void *(*thread_main_t)(void *arg);
   35: 
   36: /**
   37:  * Cleanup callback function for a thread.
   38:  *
   39:  * @param arg			argument provided to thread_cleanup_push
   40:  */
   41: typedef void (*thread_cleanup_t)(void *arg);
   42: 
   43: /**
   44:  * Thread wrapper implements simple, portable and advanced thread functions.
   45:  *
   46:  * @note All threads other than the main thread need either to be joined or
   47:  * detached by calling the corresponding method.
   48:  */
   49: struct thread_t {
   50: 
   51: 	/**
   52: 	 * Cancel this thread.
   53: 	 */
   54: 	void (*cancel)(thread_t *this);
   55: 
   56: 	/**
   57: 	 * Send a signal to this thread.
   58: 	 *
   59: 	 * @param sig		the signal to be sent to this thread
   60: 	 */
   61: 	void (*kill)(thread_t *this, int sig);
   62: 
   63: 	/**
   64: 	 * Detach this thread, this automatically destroys the thread object after
   65: 	 * the thread returned from its main function.
   66: 	 *
   67: 	 * @note Calling detach is like calling destroy on other objects.
   68: 	 */
   69: 	void (*detach)(thread_t *this);
   70: 
   71: 	/**
   72: 	 * Join this thread, this automatically destroys the thread object
   73: 	 * afterwards.
   74: 	 *
   75: 	 * @note Calling join is like calling destroy on other objects.
   76: 	 *
   77: 	 * @return			the value returned from the thread's main function or
   78: 	 *					a call to exit.
   79: 	 */
   80: 	void *(*join)(thread_t *this);
   81: };
   82: 
   83: /**
   84:  * Create a new thread instance.
   85:  *
   86:  * @param main			thread main function
   87:  * @param arg			argument provided to the main function
   88:  * @return				thread instance
   89:  */
   90: thread_t *thread_create(thread_main_t main, void *arg);
   91: 
   92: /**
   93:  * Get a thread object for the current thread.
   94:  *
   95:  * @return				thread instance
   96:  */
   97: thread_t *thread_current();
   98: 
   99: /**
  100:  * Get the ID of the current thread.
  101:  *
  102:  * Depending on the build configuration thread IDs are either assigned
  103:  * incrementally starting from 1, or equal the value returned by an appropriate
  104:  * syscall (like gettid() or GetCurrentThreadId()), if available.
  105:  *
  106:  * @return				ID of the current thread
  107:  */
  108: u_int thread_current_id();
  109: 
  110: /**
  111:  * Push a function onto the current thread's cleanup handler stack.
  112:  * The callback function is called whenever the thread is cancelled, exits or
  113:  * thread_cleanup_pop is called with TRUE as execute argument.
  114:  *
  115:  * @param cleanup		function called on thread exit
  116:  * @param arg			argument provided to the callback
  117:  */
  118: void thread_cleanup_push(thread_cleanup_t cleanup, void *arg);
  119: 
  120: /**
  121:  * Remove the top function from the current thread's cleanup handler stack
  122:  * and optionally execute it.
  123:  *
  124:  * @param execute		TRUE to execute the function
  125:  */
  126: void thread_cleanup_pop(bool execute);
  127: 
  128: /**
  129:  * Pop and execute all cleanup handlers in reverse order of registration.
  130:  *
  131:  * This function is for very special purposes only, where the caller exactly
  132:  * knows which cleanup handlers have been pushed. For regular use, a caller
  133:  * should thread_cleanup_pop() exactly the number of handlers it pushed
  134:  * using thread_cleanup_push().
  135:  */
  136: void thread_cleanup_popall();
  137: 
  138: /**
  139:  * Enable or disable the cancelability of the current thread. The current
  140:  * value is returned.
  141:  *
  142:  * @param enable		TRUE to enable cancelability
  143:  * @return				the current state of the cancelability
  144:  */
  145: bool thread_cancelability(bool enable);
  146: 
  147: /**
  148:  * Force creation of a cancellation point in the calling thread.
  149:  *
  150:  * This temporarily enables thread cancelability, tests for a pending
  151:  * cancellation request and then disables cancelability again if it was
  152:  * disabled before the call to thread_cancellation_point().
  153:  */
  154: void thread_cancellation_point();
  155: 
  156: /**
  157:  * Exit the current thread.
  158:  *
  159:  * @param val			value provided to threads joining the current thread
  160:  */
  161: void thread_exit(void *val);
  162: 
  163: /**
  164:  * Called by the main thread to initialize the thread management.
  165:  */
  166: void threads_init();
  167: 
  168: /**
  169:  * Called by the main thread to deinitialize the thread management.
  170:  */
  171: void threads_deinit();
  172: 
  173: #endif /** THREADING_THREAD_H_ @} */