Asterisk.org: Developer Documentation (28 Oct 2009)

Wed Oct 28 15:47:56 2009

## Asterisk developer's documentation

# sched.h

Go to the documentation of this file.

    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 */