@ -1,9 +1,10 @@
/*
/*
* Asterisk - - An open source telephony toolkit .
* Asterisk - - An open source telephony toolkit .
*
*
* Copyright ( C ) 1999 - 20 05 , Digium , Inc .
* Copyright ( C ) 1999 - 20 1 0, Digium , Inc .
*
*
* Mark Spencer < markster @ digium . com >
* Mark Spencer < markster @ digium . com >
* Russell Bryant < russell @ digium . com >
*
*
* See http : //www.asterisk.org for more information about
* See http : //www.asterisk.org for more information about
* the Asterisk project . Please do not directly contact
* the Asterisk project . Please do not directly contact
@ -27,16 +28,10 @@
extern " C " { extern " C " {
# endif # endif
/*!
/*! \brief Max num of schedule structs
* \ brief Remove a scheduler entry
* \ note The max number of schedule structs to keep around
*
* for use . Undefine to disable schedule structure
* This is a loop construct to ensure that
* caching . ( Only disable this on very low memory
* machines )
*/
# define SCHED_MAX_CACHE 128
/*! \brief a loop construct to ensure that
* the scheduled task get deleted . The idea is that
* the scheduled task get deleted . The idea is that
* if we loop attempting to remove the scheduled task ,
* if we loop attempting to remove the scheduled task ,
* then whatever callback had been running will complete
* then whatever callback had been running will complete
@ -137,25 +132,27 @@ extern "C" {
# define AST_SCHED_REPLACE_UNREF(id, sched, when, callback, data, unrefcall, addfailcall, refcall) \ # define AST_SCHED_REPLACE_UNREF(id, sched, when, callback, data, unrefcall, addfailcall, refcall) \
AST_SCHED_REPLACE_VARIABLE_UNREF ( id , sched , when , callback , data , 0 , unrefcall , addfailcall , refcall )
AST_SCHED_REPLACE_VARIABLE_UNREF ( id , sched , when , callback , data , 0 , unrefcall , addfailcall , refcall )
struct sched_context ; /*!
* \ brief Create a scheduler context
/*! \brief New schedule context
*
* \ note Create a scheduling context
* \ return Returns a malloc ' d sched_context structure , NULL on failure
* \ return Returns a malloc ' d sched_context structure , NULL on failure
*/
*/
struct * ( void ) ; struct ast_ sched_context * ast_ sched_context_create( void ) ;
/*! \brief destroys a schedule context
/*!
* Destroys ( free ' s ) the given sched_context structure
* \ brief destroys a schedule context
*
* \ param c Context to free
* \ param c Context to free
* \ return Returns 0 on success , - 1 on failure
*/
*/
void ( struct * c ) ; void ast_ sched_context_destroy( struct ast_ sched_context * c ) ;
/*! \brief callback for a cheops scheduler
/*!
* A cheops scheduler callback takes a pointer with callback data and
* \ brief scheduler callback
* \ return returns a 0 if it should not be run again , or non - zero if it should be
*
* rescheduled to run again
* A scheduler callback takes a pointer with callback data and
*
* \ retval 0 if the callback should not be rescheduled
* \ retval non - zero if the callback should be scheduled agai
*/
*/
typedef int ( * ast_sched_cb ) ( const void * data ) ; typedef int ( * ast_sched_cb ) ( const void * data ) ;
# define AST_SCHED_CB(a) ((ast_sched_cb)(a)) # define AST_SCHED_CB(a) ((ast_sched_cb)(a))
@ -173,20 +170,25 @@ struct ast_cb_names {
* \ param cbnames to check against
* \ param cbnames to check against
* \ since 1.6 .1
* \ since 1.6 .1
*/
*/
void ast_sched_report ( struct * con , struct ast_str * * buf , struct ast_cb_names * cbnames ) ; void ast_sched_report ( struct ast_ sched_context * con , struct ast_str * * buf , struct ast_cb_names * cbnames ) ;
/*! \brief Adds a scheduled event
/*!
* \ brief Adds a scheduled event
*
* Schedule an event to take place at some point in the future . callback
* Schedule an event to take place at some point in the future . callback
* will be called with data as the argument , when milliseconds into the
* will be called with data as the argument , when milliseconds into the
* future ( approximately )
* future ( approximately )
*
* If callback returns 0 , no further events will be re - scheduled
* If callback returns 0 , no further events will be re - scheduled
*
* \ param con Scheduler context to add
* \ param con Scheduler context to add
* \ param when how many milliseconds to wait for event to occur
* \ param when how many milliseconds to wait for event to occur
* \ param callback function to call when the amount of time expires
* \ param callback function to call when the amount of time expires
* \ param data data to pass to the callback
* \ param data data to pass to the callback
*
* \ return Returns a schedule item ID on success , - 1 on failure
* \ return Returns a schedule item ID on success , - 1 on failure
*/
*/
int ast_sched_add ( struct * con , int when , ast_sched_cb callback , const void * data ) attribute_warn_unused_result ; int ast_sched_add ( struct ast_ sched_context * con , int when , ast_sched_cb callback , const void * data ) attribute_warn_unused_result ;
/*!
/*!
* \ brief replace a scheduler entry
* \ brief replace a scheduler entry
@ -199,22 +201,27 @@ int ast_sched_add(struct sched_context *con, int when, ast_sched_cb callback, co
* \ retval - 1 failure
* \ retval - 1 failure
* \ retval otherwise , returns scheduled item ID
* \ retval otherwise , returns scheduled item ID
*/
*/
int ast_sched_replace ( int old_id , struct * con , int when , ast_sched_cb callback , const void * data ) attribute_warn_unused_result ; int ast_sched_replace ( int old_id , struct ast_ sched_context * con , int when , ast_sched_cb callback , const void * data ) attribute_warn_unused_result ;
/*!Adds a scheduled event with rescheduling support
/*!
* \ brief Adds a scheduled event with rescheduling support
*
* \ param con Scheduler context to add
* \ param con Scheduler context to add
* \ param when how many milliseconds to wait for event to occur
* \ param when how many milliseconds to wait for event to occur
* \ param callback function to call when the amount of time expires
* \ param callback function to call when the amount of time expires
* \ param data data to pass to the callback
* \ param data data to pass to the callback
* \ param variable If true , the result value of callback function will be
* \ param variable If true , the result value of callback function will be
* used for rescheduling
* used for rescheduling
*
* Schedule an event to take place at some point in the future . Callback
* Schedule an event to take place at some point in the future . Callback
* will be called with data as the argument , when milliseconds into the
* will be called with data as the argument , when milliseconds into the
* future ( approximately )
* future ( approximately )
*
* If callback returns 0 , no further events will be re - scheduled
* If callback returns 0 , no further events will be re - scheduled
*
* \ return Returns a schedule item ID on success , - 1 on failure
* \ return Returns a schedule item ID on success , - 1 on failure
*/
*/
int ast_sched_add_variable ( struct * con , int when , ast_sched_cb callback , const void * data , int variable ) attribute_warn_unused_result ; int ast_sched_add_variable ( struct ast_ sched_context * con , int when , ast_sched_cb callback , const void * data , int variable ) attribute_warn_unused_result ;
/*!
/*!
* \ brief replace a scheduler entry
* \ brief replace a scheduler entry
@ -227,66 +234,83 @@ int ast_sched_add_variable(struct sched_context *con, int when, ast_sched_cb cal
* \ retval - 1 failure
* \ retval - 1 failure
* \ retval otherwise , returns scheduled item ID
* \ retval otherwise , returns scheduled item ID
*/
*/
int ast_sched_replace_variable ( int old_id , struct sched_context * con , int when , ast_sched_cb callback , const void * data , int variable ) attribute_warn_unused_result ; int ast_sched_replace_variable ( int old_id , struct ast_sched_context * con , int when , ast_sched_cb callback , const void * data , int variable ) attribute_warn_unused_result ;
/*!
/*!
* \ brief Find a sched structure and return the data field associated with it .
* \ brief Find a sched structure and return the data field associated with it .
*
* \ param con scheduling context in which to search fro the matching id
* \ param con scheduling context in which to search fro the matching id
* \ param id ID of the scheduled item to find
* \ param id ID of the scheduled item to find
* \ return the data field from the matching sched struct if found ; else return NULL if not found .
* \ return the data field from the matching sched struct if found ; else return NULL if not found .
*
* \ since 1.6 .1
* \ since 1.6 .1
*/
*/
const void * ast_sched_find_data ( struct ast_sched_context * con , int id ) ;
const void * ast_sched_find_data ( struct sched_context * con , int id ) ; /*!
* \ brief Deletes a scheduled event
/*! \brief Deletes a scheduled event
*
* Remove this event from being run . A procedure should not remove its own
* Remove this event from being run . A procedure should not remove its own
* event , but return 0 instead . In most cases , you should not call this
* event , but return 0 instead . In most cases , you should not call this
* routine directly , but use the AST_SCHED_DEL ( ) macro instead ( especially if
* routine directly , but use the AST_SCHED_DEL ( ) macro instead ( especially if
* you don ' t intend to do something different when it returns failure ) .
* you don ' t intend to do something different when it returns failure ) .
*
* \ param con scheduling context to delete item from
* \ param con scheduling context to delete item from
* \ param id ID of the scheduled item to delete
* \ param id ID of the scheduled item to delete
*
* \ return Returns 0 on success , - 1 on failure
* \ return Returns 0 on success , - 1 on failure
*/
*/
# ifndef AST_DEVMODE # ifndef AST_DEVMODE
int ast_sched_del ( struct * con , int id ) attribute_warn_unused_result ; int ast_sched_del ( struct ast_ sched_context * con , int id ) attribute_warn_unused_result ;
# else # else
int _ast_sched_del ( struct * con , int id , const char * file , int line , const char * function ) attribute_warn_unused_result ; int _ast_sched_del ( struct ast_ sched_context * con , int id , const char * file , int line , const char * function ) attribute_warn_unused_result ;
# define ast_sched_del(a, b) _ast_sched_del(a, b, __FILE__, __LINE__, __PRETTY_FUNCTION__) # define ast_sched_del(a, b) _ast_sched_del(a, b, __FILE__, __LINE__, __PRETTY_FUNCTION__)
# endif # endif
/*! \brief Determines number of seconds until the next outstanding event to take place
/*!
* \ brief Determines number of seconds until the next outstanding event to take place
*
* Determine the number of seconds until the next outstanding event
* Determine the number of seconds until the next outstanding event
* should take place , and return the number of milliseconds until
* should take place , and return the number of milliseconds until
* it needs to be run . This value is perfect for passing to the poll
* it needs to be run . This value is perfect for passing to the poll
* call .
* call .
*
* \ param con context to act upon
* \ param con context to act upon
*
* \ return Returns " -1 " if there is nothing there are no scheduled events
* \ return Returns " -1 " if there is nothing there are no scheduled events
* ( and thus the poll should not timeout )
* ( and thus the poll should not timeout )
*/
*/
int ast_sched_wait ( struct * con ) attribute_warn_unused_result ; int ast_sched_wait ( struct ast_ sched_context * con ) attribute_warn_unused_result ;
/*! \brief Runs the queue
/*!
* \ param con Scheduling context to run
* \ brief Runs the queue
*
* Run the queue , executing all callbacks which need to be performed
* Run the queue , executing all callbacks which need to be performed
* at this time .
* at this time .
*
* \ param con Scheduling context to run
* \ param con context to act upon
* \ param con context to act upon
*
* \ return Returns the number of events processed .
* \ return Returns the number of events processed .
*/
*/
int ast_sched_runq ( struct * con ) ; int ast_sched_runq ( struct ast_ sched_context * con ) ;
/*! \brief Dumps the scheduler contents
/*!
* \ brief Dumps the scheduler contents
*
* Debugging : Dump the contents of the scheduler to stderr
* Debugging : Dump the contents of the scheduler to stderr
*
* \ param con Context to dump
* \ param con Context to dump
*/
*/
void ast_sched_dump ( struct * con ) ; void ast_sched_dump ( struct ast_ sched_context * con ) ;
/*! \brief Returns the number of seconds before an event takes place
/*!
* \ brief Returns the number of seconds before an event takes place
*
* \ param con Context to use
* \ param con Context to use
* \ param id Id to dump
* \ param id Id to dump
*/
*/
long ast_sched_when ( struct * con , int id ) ; long ast_sched_when ( struct ast_ sched_context * con , int id ) ;
/*!
/*!
* \ brief Convenience macro for objects and reference ( add )
* \ brief Convenience macro for objects and reference ( add )
@ -307,112 +331,14 @@ long ast_sched_when(struct sched_context *con,int id);
} while ( 0 ) } while ( 0 )
/*!
/*!
* \ brief An opaque type representing a scheduler thread
* \ brief Start a thread for processing scheduler entries
*
*
* The purpose of the ast_sched_thread API is to provide a common implementation
* \ param con the scheduler context this thread will manage
* of the case where a module wants to have a dedicated thread for handling the
* scheduler .
*/
struct ast_sched_thread ;
/*!
* \ brief Create a scheduler with a dedicated thread
*
* This function should be used to allocate a scheduler context and a dedicated
* thread for processing scheduler entries . The thread is started immediately .
*
* \ retval NULL error
* \ retval non - NULL a handle to the scheduler and its dedicated thread .
*/
struct ast_sched_thread * ast_sched_thread_create ( void ) ;
/*!
* \ brief Destroy a scheduler and its thread
*
* This function is used to destroy a scheduler context and the dedicated thread
* that was created for handling scheduler entries . Any entries in the scheduler
* that have not yet been processed will be thrown away . Once this function is
* called , the handle must not be used again .
*
* \ param st the handle to the scheduler and thread
*
* \ return NULL for convenience
*/
struct ast_sched_thread * ast_sched_thread_destroy ( struct ast_sched_thread * st ) ;
/*!
* \ brief Add a scheduler entry
*
* \ param st the handle to the scheduler and thread
* \ param when the number of ms in the future to run the task . A value < = 0
* is treated as " run now " .
* \ param cb the function to call when the scheduled time arrives
* \ param data the parameter to pass to the scheduler callback
*
* \ retval - 1 Failure
* \ retval > = 0 Sched ID of added task
*/
int ast_sched_thread_add ( struct ast_sched_thread * st , int when , ast_sched_cb cb ,
const void * data ) ;
/*!
* \ brief Add a variable reschedule time scheduler entry
*
* \ param st the handle to the scheduler and thread
* \ param when the number of ms in the future to run the task . A value < = 0
* is treated as " run now " .
* \ param cb the function to call when the scheduled time arrives
* \ param data the parameter to pass to the scheduler callback
* \ param variable If this value is non - zero , then the scheduler will use the return
* value of the scheduler as the amount of time in the future to run the
* task again . Normally , a return value of 0 means do not re - schedule , and
* non - zero means re - schedule using the time provided when the scheduler
* entry was first created .
*
* \ retval - 1 Failure
* \ retval > = 0 Sched ID of added task
*/
int ast_sched_thread_add_variable ( struct ast_sched_thread * st , int when , ast_sched_cb cb ,
const void * data , int variable ) ;
/*!
* \ brief Get the scheduler context for a given ast_sched_thread
*
* This function should be used only when direct access to the scheduler context
* is required . Its use is discouraged unless necessary . The cases where
* this is currently required is when you want to take advantage of one of the
* AST_SCHED macros .
*
* \ param st the handle to the scheduler and thread
*
* \ return the sched_context associated with an ast_sched_thread
*/
struct sched_context * ast_sched_thread_get_context ( struct ast_sched_thread * st ) ;
/*!
* \ brief Delete a scheduler entry
*
* This uses the AST_SCHED_DEL macro internally .
*
* \ param st the handle to the scheduler and thread
* \ param id scheduler entry id to delete
*
*
* \ retval 0 success
* \ retval 0 success
* \ retval non - zero failure
* \ retval non - zero failure
*/
*/
# define ast_sched_thread_del(st, id) ({ \ int ast_sched_start_thread ( struct ast_sched_context * con ) ;
struct sched_context * __tmp_context = ast_sched_thread_get_context ( st ) ; \
AST_SCHED_DEL ( __tmp_context , id ) ; \
} )
/*!
* \ brief Force re - processing of the scheduler context
*
* \ param st the handle to the scheduler and thread
*
* \ return nothing
*/
void ast_sched_thread_poke ( struct ast_sched_thread * st ) ;
# if defined(__cplusplus) || defined(c_plusplus) # if defined(__cplusplus) || defined(c_plusplus)
} }
Russell Bryant
15 years ago