include/asterisk/sched.h

   1 /*
   2  * Asterisk
   3  *
   4  * Mark Spencer <markster@marko.net>
   5  *
   6  * Copyright(C) Mark Spencer
   7  *
   8  * Distributed under the terms of the GNU General Public License (GPL) Version 2
   9  *
  10  * Scheduler Routines (derived from cheops)
  11  *
  12  */
  13
  14 #ifndef _ASTERISK_SCHED_H
  15 #define _ASTERISK_SCHED_H
  16
  17 #if defined(__cplusplus) || defined(c_plusplus)
  18 extern "C" {
  19 #endif
  20
  21 /*! Max num of schedule structs */
  22 /*!
  23  * The max number of schedule structs to keep around
  24  * for use.  Undefine to disable schedule structure
  25  * caching. (Only disable this on very low memory
  26  * machines)
  27  */
  28 #define SCHED_MAX_CACHE 128
  29
  30 struct sched_context;
  31
  32 /*! New schedule context */
  33 /* !
  34  * Create a scheduling context
  35  * Returns a malloc'd sched_context structure, NULL on failure
  36  */
  37 extern struct sched_context *sched_context_create(void);
  38
  39 /*! destroys a schedule context */
  40 /*!
  41  * \param c Context to free
  42  * Destroys (free's) the given sched_context structure
  43  * Returns 0 on success, -1 on failure
  44  */
  45 void sched_context_destroy(struct sched_context *c);
  46
  47 /*! callback for a cheops scheduler */
  48 /*!
  49  * A cheops scheduler callback takes a pointer with callback data and
  50  * returns a 0 if it should not be run again, or non-zero if it should be
  51  * rescheduled to run again
  52  */
  53 typedef int (*ast_sched_cb)(void *data);
  54 #define AST_SCHED_CB(a) ((ast_sched_cb)(a))
  55
  56 /*!Adds a scheduled event */
  57 /*!
  58  * \param con Schduler context to add
  59  * \param when how many milliseconds to wait for event to occur
  60  * \param callback function to call when the amount of time expires
  61  * \param data data to pass to the callback
  62  * Schedule an event to take place at some point in the future.  callback
  63  * will be called with data as the argument, when milliseconds into the
  64  * future (approximately)
  65  * Returns 0 on success, -1 on failure
  66  */
  67 extern int ast_sched_add(struct sched_context *con, int when, ast_sched_cb callback, void *data);
  68
  69 /*! Deletes a scheduled event */
  70 /*!
  71  * \param con scheduling context to delete item from
  72  * \param id ID of the scheduled item to delete
  73  * Remove this event from being run.  A procedure should not remove its
  74  * own event, but return 0 instead.
  75  * Returns 0 on success, -1 on failure
  76  */
  77 extern int ast_sched_del(struct sched_context *con, int id);
  78
  79 /*! Determines number of seconds until the next outstanding event to take place */
  80 /*!
  81  * \param con context to act upon
  82  * Determine the number of seconds until the next outstanding event
  83  * should take place, and return the number of milliseconds until
  84  * it needs to be run.  This value is perfect for passing to the poll
  85  * call.  Returns "-1" if there is nothing there are no scheduled events
  86  * (and thus the poll should not timeout)
  87  */
  88 extern int ast_sched_wait(struct sched_context *con);
  89
  90 /*! Runs the queue */
  91 /*!
  92  * \param con Scheduling context to run
  93  * Run the queue, executing all callbacks which need to be performed
  94  * at this time.  Returns the number of events processed.
  95  */
  96 extern int ast_sched_runq(struct sched_context *con);
  97
  98 /*!Dumps the scheduler contents */
  99 /*!
 100  * \param con Context to dump
 101  * Debugging: Dump the contents of the scheduler to stderr
 102  */
 103 extern void ast_sched_dump(struct sched_context *con);
 104
 105 /*
 106  *! Convenience macro for objects and reference (add)
 107  *
 108  */
 109 #define ast_sched_add_object(obj,con,when,callback) ast_sched_add((con),(when),(callback), ASTOBJ_REF((obj)))
 110
 111 /*
 112  *! Convenience macro for objects and reference (del)
 113  *
 114  */
 115 #define ast_sched_del_object(obj,destructor,con,id) do { \
 116         if ((id) > -1) { \
 117                 ast_sched_del((con),(id)); \
 118                 (id) = -1; \
 119                 ASTOBJ_UNREF((obj),(destructor)); \
 120         } \
 121 } while(0)
 122
 123 #if defined(__cplusplus) || defined(c_plusplus)
 124 }
 125 #endif
 126
 127
 128
 129 #endif