Thu Jul 9 13:41:33 2009

Asterisk developer's documentation


sched.h File Reference

Scheduler Routines (derived from cheops). More...

Go to the source code of this file.

Defines

#define ast_sched_add_object(obj, con, when, callback)   ast_sched_add((con),(when),(callback), ASTOBJ_REF((obj)))
 Convenience macro for objects and reference (add).
#define AST_SCHED_CB(a)   ((ast_sched_cb)(a))
#define AST_SCHED_DEL(sched, id)
 a loop construct to ensure that the scheduled task get deleted. The idea is that if we loop attempting to remove the scheduled task, then whatever callback had been running will complete and reinsert the task into the scheduler.
#define ast_sched_del_object(obj, destructor, con, id)
 Convenience macro for objects and reference (del).
#define AST_SCHED_REPLACE(id, sched, when, callback, data)   AST_SCHED_REPLACE_VARIABLE(id, sched, when, callback, data, 0)
#define AST_SCHED_REPLACE_VARIABLE(id, sched, when, callback, data, variable)
#define SCHED_MAX_CACHE   128
 Max num of schedule structs.

Typedefs

typedef int(*) ast_sched_cb (const void *data)
 callback for a cheops scheduler A cheops scheduler callback takes a pointer with callback data and

Functions

int ast_sched_add (struct sched_context *con, int when, ast_sched_cb callback, const void *data)
 Adds a scheduled event 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 future (approximately) If callback returns 0, no further events will be re-scheduled.
int ast_sched_add_variable (struct sched_context *con, int when, ast_sched_cb callback, const void *data, int variable)
 Schedule callback(data) to happen when ms into the future.
int ast_sched_del (struct sched_context *con, int id)
 Deletes a scheduled event 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 routine directly, but use the AST_SCHED_DEL() macro instead (especially if you don't intend to do something different when it returns failure).
void ast_sched_dump (const struct sched_context *con)
 Dumps the scheduler contents Debugging: Dump the contents of the scheduler to stderr.
int ast_sched_replace (int old_id, struct sched_context *con, int when, ast_sched_cb callback, const void *data)
 replace a scheduler entry
int ast_sched_replace_variable (int old_id, struct sched_context *con, int when, ast_sched_cb callback, const void *data, int variable)
 replace a scheduler entry
int ast_sched_runq (struct sched_context *con)
 Runs the queue.
int ast_sched_wait (struct sched_context *con)
 Determines number of seconds until the next outstanding event to take place Determine the number of seconds until the next outstanding event should take place, and return the number of milliseconds until it needs to be run. This value is perfect for passing to the poll call.
long ast_sched_when (struct sched_context *con, int id)
 Returns the number of seconds before an event takes place.
sched_contextsched_context_create (void)
 New schedule context.
void sched_context_destroy (struct sched_context *c)
 destroys a schedule context Destroys (free's) the given sched_context structure


Detailed Description

Scheduler Routines (derived from cheops).

Definition in file sched.h.


Define Documentation

#define ast_sched_add_object ( obj,
con,
when,
callback   )     ast_sched_add((con),(when),(callback), ASTOBJ_REF((obj)))

Convenience macro for objects and reference (add).

Definition at line 204 of file sched.h.

#define AST_SCHED_CB (  )     ((ast_sched_cb)(a))

Definition at line 96 of file sched.h.

#define AST_SCHED_DEL ( sched,
id   ) 

a loop construct to ensure that the scheduled task get deleted. The idea is that if we loop attempting to remove the scheduled task, then whatever callback had been running will complete and reinsert the task into the scheduler.

Since macro expansion essentially works like pass-by-name parameter passing, this macro will still work correctly even if the id of the task to delete changes. This holds as long as the name of the id which could change is passed to the macro and not a copy of the value of the id.

Definition at line 50 of file sched.h.

Referenced by __oh323_destroy(), __oh323_update_info(), __sip_destroy(), __sip_reliable_xmit(), __sip_semi_ack(), ack_trans(), ast_rtcp_write_rr(), ast_rtcp_write_sr(), ast_rtp_destroy(), ast_rtp_stop(), build_gateway(), build_peer(), delete_users(), destroy_packet(), destroy_packets(), destroy_peer(), dnsmgr_start_refresh(), do_reload(), filestream_destructor(), handle_command_response(), handle_request_cancel(), handle_request_do(), handle_response_invite(), handle_response_register(), iax2_destroy_helper(), iax2_frame_free(), make_trunk(), mgcpsock_read(), misdn_tasks_remove(), parse_register_contact(), qualify_peer(), receive_digit(), schedule_delivery(), sip_destroy_peer(), sip_hangup(), sip_indicate(), sip_poke_peer(), sip_registry_destroy(), sip_unregister(), socket_process(), and submit_unscheduled_batch().

#define ast_sched_del_object ( obj,
destructor,
con,
id   ) 

Convenience macro for objects and reference (del).

Definition at line 210 of file sched.h.

#define AST_SCHED_REPLACE ( id,
sched,
when,
callback,
data   )     AST_SCHED_REPLACE_VARIABLE(id, sched, when, callback, data, 0)

Definition at line 72 of file sched.h.

Referenced by handle_response_peerpoke(), handle_response_register(), iax2_sched_replace(), reg_source_db(), sip_call(), sip_poke_all_peers(), sip_poke_noanswer(), sip_poke_peer(), sip_send_all_registers(), and transmit_register().

#define AST_SCHED_REPLACE_VARIABLE ( id,
sched,
when,
callback,
data,
variable   ) 

Definition at line 61 of file sched.h.

Referenced by __sip_reliable_xmit().

#define SCHED_MAX_CACHE   128

Max num of schedule structs.

Note:
The max number of schedule structs to keep around for use. Undefine to disable schedule structure caching. (Only disable this on very low memory machines)

Definition at line 36 of file sched.h.

Referenced by sched_release().


Typedef Documentation

typedef int(*) ast_sched_cb(const void *data)

callback for a cheops scheduler A cheops scheduler callback takes a pointer with callback data and

Returns:
returns a 0 if it should not be run again, or non-zero if it should be rescheduled to run again

Definition at line 95 of file sched.h.


Function Documentation

int ast_sched_add ( struct sched_context con,
int  when,
ast_sched_cb  callback,
const void *  data 
)

Adds a scheduled event 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 future (approximately) If callback returns 0, no further events will be re-scheduled.

Parameters:
con Scheduler context to add
when how many milliseconds to wait for event to occur
callback function to call when the amount of time expires
data data to pass to the callback
Returns:
Returns a schedule item ID on success, -1 on failure

Definition at line 253 of file sched.c.

References ast_sched_add_variable().

Referenced by __oh323_update_info(), ast_readaudio_callback(), ast_readvideo_callback(), ast_rtp_raw_write(), ast_rtp_read(), ast_sched_replace(), do_register(), do_reload(), dundi_discover(), dundi_query(), dundi_send(), handle_command_response(), handle_request_invite(), handle_response_invite(), iax2_hangup(), iax2_sched_add(), mgcp_postrequest(), parse_register_contact(), populate_addr(), precache_trans(), qualify_peer(), queue_request(), receive_digit(), sip_scheddestroy(), start_session_timer(), submit_scheduled_batch(), submit_unscheduled_batch(), and transmit_register().

00254 {
00255    return ast_sched_add_variable(con, when, callback, data, 0);
00256 }

int ast_sched_add_variable ( struct sched_context con,
int  when,
ast_sched_cb  callback,
const void *  data,
int  variable 
)

Schedule callback(data) to happen when ms into the future.

Adds a scheduled event with rescheduling support

Parameters:
con Scheduler context to add
when how many milliseconds to wait for event to occur
callback function to call when the amount of time expires
data data to pass to the callback
variable If true, the result value of callback function will be used for rescheduling 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 future (approximately) If callback returns 0, no further events will be re-scheduled
Returns:
Returns a schedule item ID on success, -1 on failure

Definition at line 214 of file sched.c.

References ast_debug, ast_mutex_lock(), ast_mutex_unlock(), ast_sched_dump(), ast_tv(), sched::callback, sched::data, DEBUG, sched_context::eventcnt, sched::id, sched_context::lock, option_debug, sched::resched, sched_alloc(), sched_release(), sched_settime(), schedule(), sched::variable, and sched::when.

Referenced by _misdn_tasks_add_variable(), ast_sched_add(), ast_sched_replace_variable(), dnsmgr_start_refresh(), and do_reload().

00215 {
00216    struct sched *tmp;
00217    int res = -1;
00218 
00219    DEBUG(ast_debug(1, "ast_sched_add()\n"));
00220 
00221    ast_mutex_lock(&con->lock);
00222    if ((tmp = sched_alloc(con))) {
00223       tmp->id = con->eventcnt++;
00224       tmp->callback = callback;
00225       tmp->data = data;
00226       tmp->resched = when;
00227       tmp->variable = variable;
00228       tmp->when = ast_tv(0, 0);
00229       if (sched_settime(&tmp->when, when)) {
00230          sched_release(con, tmp);
00231       } else {
00232          schedule(con, tmp);
00233          res = tmp->id;
00234       }
00235    }
00236 #ifdef DUMP_SCHEDULER
00237    /* Dump contents of the context while we have the lock so nothing gets screwed up by accident. */
00238    if (option_debug)
00239       ast_sched_dump(con);
00240 #endif
00241    ast_mutex_unlock(&con->lock);
00242 
00243    return res;
00244 }

int ast_sched_del ( struct sched_context con,
int  id 
)

Deletes a scheduled event 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 routine directly, but use the AST_SCHED_DEL() macro instead (especially if you don't intend to do something different when it returns failure).

Parameters:
con scheduling context to delete item from
id ID of the scheduled item to delete
Returns:
Returns 0 on success, -1 on failure

Definition at line 265 of file sched.c.

References ast_assert, ast_debug, AST_LIST_REMOVE_CURRENT, AST_LIST_TRAVERSE_SAFE_BEGIN, AST_LIST_TRAVERSE_SAFE_END, ast_mutex_lock(), ast_mutex_unlock(), ast_sched_dump(), DEBUG, sched::list, option_debug, s, and sched_release().

Referenced by __sip_ack(), __sip_destroy(), ast_sched_replace(), ast_sched_replace_variable(), handle_response_register(), iax2_poke_peer(), reg_source_db(), restart_session_timer(), sip_cancel_destroy(), socket_process(), stop_session_timer(), unlink_peer(), and update_registry().

00269 {
00270    struct sched *s;
00271 
00272    DEBUG(ast_debug(1, "ast_sched_del()\n"));
00273    
00274    ast_mutex_lock(&con->lock);
00275    AST_LIST_TRAVERSE_SAFE_BEGIN(&con->schedq, s, list) {
00276       if (s->id == id) {
00277          AST_LIST_REMOVE_CURRENT(list);
00278          con->schedcnt--;
00279          sched_release(con, s);
00280          break;
00281       }
00282    }
00283    AST_LIST_TRAVERSE_SAFE_END;
00284 
00285 #ifdef DUMP_SCHEDULER
00286    /* Dump contents of the context while we have the lock so nothing gets screwed up by accident. */
00287    if (option_debug)
00288       ast_sched_dump(con);
00289 #endif
00290    ast_mutex_unlock(&con->lock);
00291 
00292    if (!s) {
00293       ast_debug(1, "Attempted to delete nonexistent schedule entry %d!\n", id);
00294 #ifndef AST_DEVMODE
00295       ast_assert(s != NULL);
00296 #else
00297       _ast_assert(0, "s != NULL", file, line, function);
00298 #endif
00299       return -1;
00300    }
00301    
00302    return 0;
00303 }

void ast_sched_dump ( const struct sched_context con  ) 

Dumps the scheduler contents Debugging: Dump the contents of the scheduler to stderr.

Parameters:
con Context to dump

Definition at line 306 of file sched.c.

References ast_debug, AST_LIST_TRAVERSE, ast_tvnow(), ast_tvsub(), sched::callback, sched::data, sched_context::eventcnt, sched::id, sched::list, sched_context::schedccnt, sched_context::schedcnt, sched_context::schedq, and sched::when.

Referenced by ast_sched_add_variable(), and ast_sched_del().

00307 {
00308    struct sched *q;
00309    struct timeval tv = ast_tvnow();
00310 #ifdef SCHED_MAX_CACHE
00311    ast_debug(1, "Asterisk Schedule Dump (%d in Q, %d Total, %d Cache)\n", con->schedcnt, con->eventcnt - 1, con->schedccnt);
00312 #else
00313    ast_debug(1, "Asterisk Schedule Dump (%d in Q, %d Total)\n", con->schedcnt, con->eventcnt - 1);
00314 #endif
00315 
00316    ast_debug(1, "=============================================================\n");
00317    ast_debug(1, "|ID    Callback          Data              Time  (sec:ms)   |\n");
00318    ast_debug(1, "+-----+-----------------+-----------------+-----------------+\n");
00319    AST_LIST_TRAVERSE(&con->schedq, q, list) {
00320       struct timeval delta = ast_tvsub(q->when, tv);
00321 
00322       ast_debug(1, "|%.4d | %-15p | %-15p | %.6ld : %.6ld |\n", 
00323          q->id,
00324          q->callback,
00325          q->data,
00326          delta.tv_sec,
00327          (long int)delta.tv_usec);
00328    }
00329    ast_debug(1, "=============================================================\n");
00330 }

int ast_sched_replace ( int  old_id,
struct sched_context con,
int  when,
ast_sched_cb  callback,
const void *  data 
)

replace a scheduler entry

Deprecated:
You should use the AST_SCHED_REPLACE() macro instead.
This deletes the scheduler entry for old_id if it exists, and then calls ast_sched_add to create a new entry. A negative old_id will be ignored.

Return values:
-1 failure
otherwise,returns scheduled item ID

Definition at line 246 of file sched.c.

References ast_sched_add(), and ast_sched_del().

00247 {
00248    if (old_id > -1)
00249       ast_sched_del(con, old_id);
00250    return ast_sched_add(con, when, callback, data);
00251 }

int ast_sched_replace_variable ( int  old_id,
struct sched_context con,
int  when,
ast_sched_cb  callback,
const void *  data,
int  variable 
)

replace a scheduler entry

Deprecated:
You should use the AST_SCHED_REPLACE_VARIABLE() macro instead.
This deletes the scheduler entry for old_id if it exists, and then calls ast_sched_add to create a new entry. A negative old_id will be ignored.

Return values:
-1 failure
otherwise,returns scheduled item ID

Definition at line 203 of file sched.c.

References ast_sched_add_variable(), and ast_sched_del().

00204 {
00205    /* 0 means the schedule item is new; do not delete */
00206    if (old_id > 0)
00207       ast_sched_del(con, old_id);
00208    return ast_sched_add_variable(con, when, callback, data, variable);
00209 }

int ast_sched_runq ( struct sched_context con  ) 

Runs the queue.

Parameters:
con Scheduling context to run Run the queue, executing all callbacks which need to be performed at this time.
con context to act upon
Returns:
Returns the number of events processed.

Definition at line 335 of file sched.c.

References ast_debug, AST_LIST_EMPTY, AST_LIST_FIRST, AST_LIST_REMOVE_HEAD, ast_mutex_lock(), ast_mutex_unlock(), ast_tv(), ast_tvadd(), ast_tvcmp(), ast_tvnow(), sched::callback, sched::data, DEBUG, sched::list, sched_context::lock, sched::resched, sched_release(), sched_settime(), sched_context::schedcnt, sched_context::schedq, schedule(), sched::variable, and sched::when.

Referenced by background_detect_exec(), do_cdr(), do_monitor(), do_refresh(), handle_speechrecognize(), misdn_tasks_thread_func(), network_thread(), reload_config(), sched_thread(), speech_background(), wait_for_winner(), and waitstream_core().

00336 {
00337    struct sched *current;
00338    struct timeval tv;
00339    int numevents;
00340    int res;
00341 
00342    DEBUG(ast_debug(1, "ast_sched_runq()\n"));
00343       
00344    ast_mutex_lock(&con->lock);
00345 
00346    for (numevents = 0; !AST_LIST_EMPTY(&con->schedq); numevents++) {
00347       /* schedule all events which are going to expire within 1ms.
00348        * We only care about millisecond accuracy anyway, so this will
00349        * help us get more than one event at one time if they are very
00350        * close together.
00351        */
00352       tv = ast_tvadd(ast_tvnow(), ast_tv(0, 1000));
00353       if (ast_tvcmp(AST_LIST_FIRST(&con->schedq)->when, tv) != -1)
00354          break;
00355       
00356       current = AST_LIST_REMOVE_HEAD(&con->schedq, list);
00357       con->schedcnt--;
00358 
00359       /*
00360        * At this point, the schedule queue is still intact.  We
00361        * have removed the first event and the rest is still there,
00362        * so it's permissible for the callback to add new events, but
00363        * trying to delete itself won't work because it isn't in
00364        * the schedule queue.  If that's what it wants to do, it 
00365        * should return 0.
00366        */
00367          
00368       ast_mutex_unlock(&con->lock);
00369       res = current->callback(current->data);
00370       ast_mutex_lock(&con->lock);
00371          
00372       if (res) {
00373          /*
00374           * If they return non-zero, we should schedule them to be
00375           * run again.
00376           */
00377          if (sched_settime(&current->when, current->variable? res : current->resched)) {
00378             sched_release(con, current);
00379          } else
00380             schedule(con, current);
00381       } else {
00382          /* No longer needed, so release it */
00383          sched_release(con, current);
00384       }
00385    }
00386 
00387    ast_mutex_unlock(&con->lock);
00388    
00389    return numevents;
00390 }

int ast_sched_wait ( struct sched_context con  ) 

Determines number of seconds until the next outstanding event to take place Determine the number of seconds until the next outstanding event should take place, and return the number of milliseconds until it needs to be run. This value is perfect for passing to the poll call.

Parameters:
con context to act upon
Returns:
Returns "-1" if there is nothing there are no scheduled events (and thus the poll should not timeout)

Definition at line 142 of file sched.c.

References ast_debug, AST_LIST_EMPTY, AST_LIST_FIRST, ast_mutex_lock(), ast_mutex_unlock(), ast_tvdiff_ms(), ast_tvnow(), DEBUG, sched_context::lock, and sched_context::schedq.

Referenced by background_detect_exec(), do_cdr(), do_monitor(), do_refresh(), handle_speechrecognize(), misdn_tasks_thread_func(), network_thread(), sched_thread(), speech_background(), wait_for_winner(), and waitstream_core().

00143 {
00144    int ms;
00145 
00146    DEBUG(ast_debug(1, "ast_sched_wait()\n"));
00147 
00148    ast_mutex_lock(&con->lock);
00149    if (AST_LIST_EMPTY(&con->schedq)) {
00150       ms = -1;
00151    } else {
00152       ms = ast_tvdiff_ms(AST_LIST_FIRST(&con->schedq)->when, ast_tvnow());
00153       if (ms < 0)
00154          ms = 0;
00155    }
00156    ast_mutex_unlock(&con->lock);
00157 
00158    return ms;
00159 }

long ast_sched_when ( struct sched_context con,
int  id 
)

Returns the number of seconds before an event takes place.

Parameters:
con Context to use
id Id to dump

Definition at line 392 of file sched.c.

References ast_debug, AST_LIST_TRAVERSE, ast_mutex_lock(), ast_mutex_unlock(), ast_tvnow(), DEBUG, sched::list, sched_context::lock, s, and sched_context::schedq.

Referenced by _sip_show_peer(), handle_cli_status(), and parse_register_contact().

00393 {
00394    struct sched *s;
00395    long secs = -1;
00396    DEBUG(ast_debug(1, "ast_sched_when()\n"));
00397 
00398    ast_mutex_lock(&con->lock);
00399    AST_LIST_TRAVERSE(&con->schedq, s, list) {
00400       if (s->id == id)
00401          break;
00402    }
00403    if (s) {
00404       struct timeval now = ast_tvnow();
00405       secs = s->when.tv_sec - now.tv_sec;
00406    }
00407    ast_mutex_unlock(&con->lock);
00408    
00409    return secs;
00410 }

struct sched_context* sched_context_create ( void   ) 

New schedule context.

Note:
Create a scheduling context
Returns:
Returns a malloc'd sched_context structure, NULL on failure

Definition at line 69 of file sched.c.

References ast_calloc, and ast_mutex_init().

Referenced by __ast_channel_alloc_ap(), ast_cdr_engine_init(), dnsmgr_init(), load_module(), and misdn_tasks_init().

00070 {
00071    struct sched_context *tmp;
00072 
00073    if (!(tmp = ast_calloc(1, sizeof(*tmp))))
00074       return NULL;
00075 
00076    ast_mutex_init(&tmp->lock);
00077    tmp->eventcnt = 1;
00078    
00079    return tmp;
00080 }

void sched_context_destroy ( struct sched_context c  ) 

destroys a schedule context Destroys (free's) the given sched_context structure

Parameters:
c Context to free
Returns:
Returns 0 on success, -1 on failure

Definition at line 82 of file sched.c.

References ast_free, AST_LIST_REMOVE_HEAD, ast_mutex_destroy(), ast_mutex_lock(), ast_mutex_unlock(), sched::list, sched_context::lock, s, sched_context::schedc, and sched_context::schedq.

Referenced by __ast_channel_alloc_ap(), __unload_module(), ast_channel_free(), ast_hangup(), load_module(), misdn_tasks_destroy(), and unload_module().

00083 {
00084    struct sched *s;
00085 
00086    ast_mutex_lock(&con->lock);
00087 
00088 #ifdef SCHED_MAX_CACHE
00089    /* Eliminate the cache */
00090    while ((s = AST_LIST_REMOVE_HEAD(&con->schedc, list)))
00091       ast_free(s);
00092 #endif
00093 
00094    /* And the queue */
00095    while ((s = AST_LIST_REMOVE_HEAD(&con->schedq, list)))
00096       ast_free(s);
00097    
00098    /* And the context */
00099    ast_mutex_unlock(&con->lock);
00100    ast_mutex_destroy(&con->lock);
00101    ast_free(con);
00102 }


Generated on Thu Jul 9 13:41:33 2009 for Asterisk - the Open Source PBX by  doxygen 1.4.7