00001 /* 00002 * Asterisk -- An open source telephony toolkit. 00003 * 00004 * Copyright (C) 1999 - 2005, Digium, Inc. 00005 * 00006 * Mark Spencer <markster@digium.com> 00007 * 00008 * See http://www.asterisk.org for more information about 00009 * the Asterisk project. Please do not directly contact 00010 * any of the maintainers of this project for assistance; 00011 * the project provides a web site, mailing lists and IRC 00012 * channels for your use. 00013 * 00014 * This program is free software, distributed under the terms of 00015 * the GNU General Public License Version 2. See the LICENSE file 00016 * at the top of the source tree. 00017 */ 00018 00019 /*! \file 00020 * \brief Scheduler Routines (derived from cheops) 00021 */ 00022 00023 #ifndef _ASTERISK_SCHED_H 00024 #define _ASTERISK_SCHED_H 00025 00026 #if defined(__cplusplus) || defined(c_plusplus) 00027 extern "C" { 00028 #endif 00029 00030 /*! Max num of schedule structs */ 00031 /*! 00032 * The max number of schedule structs to keep around 00033 * for use. Undefine to disable schedule structure 00034 * caching. (Only disable this on very low memory 00035 * machines) 00036 */ 00037 #define SCHED_MAX_CACHE 128 00038 00039 struct sched_context; 00040 00041 /*! New schedule context */ 00042 /* ! 00043 * Create a scheduling context 00044 * Returns a malloc'd sched_context structure, NULL on failure 00045 */ 00046 extern struct sched_context *sched_context_create(void); 00047 00048 /*! destroys a schedule context */ 00049 /*! 00050 * \param c Context to free 00051 * Destroys (free's) the given sched_context structure 00052 * Returns 0 on success, -1 on failure 00053 */ 00054 void sched_context_destroy(struct sched_context *c); 00055 00056 /*! callback for a cheops scheduler */ 00057 /*! 00058 * A cheops scheduler callback takes a pointer with callback data and 00059 * returns a 0 if it should not be run again, or non-zero if it should be 00060 * rescheduled to run again 00061 */ 00062 typedef int (*ast_sched_cb)(void *data); 00063 #define AST_SCHED_CB(a) ((ast_sched_cb)(a)) 00064 00065 /*!Adds a scheduled event */ 00066 /*! 00067 * \param con Scheduler context to add 00068 * \param when how many milliseconds to wait for event to occur 00069 * \param callback function to call when the amount of time expires 00070 * \param data data to pass to the callback 00071 * Schedule an event to take place at some point in the future. callback 00072 * will be called with data as the argument, when milliseconds into the 00073 * future (approximately) 00074 * If callback returns 0, no further events will be re-scheduled 00075 * Returns a schedule item ID on success, -1 on failure 00076 */ 00077 extern int ast_sched_add(struct sched_context *con, int when, ast_sched_cb callback, void *data); 00078 00079 /*!Adds a scheduled event */ 00080 /*! 00081 * \param con Scheduler context to add 00082 * \param when how many milliseconds to wait for event to occur 00083 * \param callback function to call when the amount of time expires 00084 * \param data data to pass to the callback 00085 * \param variable If true, the result value of callback function will be 00086 * used for rescheduling 00087 * Schedule an event to take place at some point in the future. callback 00088 * will be called with data as the argument, when milliseconds into the 00089 * future (approximately) 00090 * If callback returns 0, no further events will be re-scheduled 00091 * Returns a schedule item ID on success, -1 on failure 00092 */ 00093 extern int ast_sched_add_variable(struct sched_context *con, int when, ast_sched_cb callback, void *data, int variable); 00094 00095 /*! Deletes a scheduled event */ 00096 /*! 00097 * \param con scheduling context to delete item from 00098 * \param id ID of the scheduled item to delete 00099 * Remove this event from being run. A procedure should not remove its 00100 * own event, but return 0 instead. 00101 * Returns 0 on success, -1 on failure 00102 */ 00103 extern int ast_sched_del(struct sched_context *con, int id); 00104 00105 /*! Determines number of seconds until the next outstanding event to take place */ 00106 /*! 00107 * \param con context to act upon 00108 * Determine the number of seconds until the next outstanding event 00109 * should take place, and return the number of milliseconds until 00110 * it needs to be run. This value is perfect for passing to the poll 00111 * call. Returns "-1" if there is nothing there are no scheduled events 00112 * (and thus the poll should not timeout) 00113 */ 00114 extern int ast_sched_wait(struct sched_context *con); 00115 00116 /*! Runs the queue */ 00117 /*! 00118 * \param con Scheduling context to run 00119 * Run the queue, executing all callbacks which need to be performed 00120 * at this time. Returns the number of events processed. 00121 */ 00122 extern int ast_sched_runq(struct sched_context *con); 00123 00124 /*!Dumps the scheduler contents */ 00125 /*! 00126 * \param con Context to dump 00127 * Debugging: Dump the contents of the scheduler to stderr 00128 */ 00129 extern void ast_sched_dump(const struct sched_context *con); 00130 00131 /*!Returns the number of seconds before an event takes place */ 00132 /*! 00133 * \param con Context to use 00134 * \param id Id to dump 00135 */ 00136 extern long ast_sched_when(struct sched_context *con,int id); 00137 00138 /* 00139 *! Convenience macro for objects and reference (add) 00140 * 00141 */ 00142 #define ast_sched_add_object(obj,con,when,callback) ast_sched_add((con),(when),(callback), ASTOBJ_REF((obj))) 00143 00144 /* 00145 *! Convenience macro for objects and reference (del) 00146 * 00147 */ 00148 #define ast_sched_del_object(obj,destructor,con,id) do { \ 00149 if ((id) > -1) { \ 00150 ast_sched_del((con),(id)); \ 00151 (id) = -1; \ 00152 ASTOBJ_UNREF((obj),(destructor)); \ 00153 } \ 00154 } while(0) 00155 00156 #if defined(__cplusplus) || defined(c_plusplus) 00157 } 00158 #endif 00159 00160 #endif /* _ASTERISK_SCHED_H */