Annotation of embedaddon/strongswan/src/libstrongswan/threading/thread.h, revision 1.1
1.1 ! misho 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_ @} */
FreeBSD-CVSweb <freebsd-cvsweb@FreeBSD.org>