Sat Aug 6 00:40:05 2011

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_DEL_SPINLOCK(sched, id, lock)
#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.
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_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 180 of file sched.h.

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

Definition at line 100 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_semi_ack(), ack_trans(), ast_closestream(), ast_rtcp_write_rr(), ast_rtcp_write_sr(), ast_rtp_destroy(), ast_rtp_stop(), auth_fail(), build_gateway(), build_peer(), destroy_packet(), destroy_packets(), destroy_peer(), dnsmgr_start_refresh(), do_reload(), filestream_destructor(), handle_command_response(), handle_request_cancel(), handle_response_invite(), handle_response_peerpoke(), handle_response_register(), iax2_ack_registry(), iax2_destroy_helper(), iax2_do_register(), iax2_dprequest(), iax2_frame_free(), iax2_provision(), make_trunk(), mgcpsock_read(), misdn_tasks_remove(), parse_register_contact(), qualify_peer(), receive_digit(), reg_source_db(), remove_provisional_keepalive_sched(), schedule_delivery(), sip_call(), sip_do_reload(), sip_hangup(), sip_poke_all_peers(), sip_poke_noanswer(), sip_poke_peer(), sip_registry_destroy(), sip_scheddestroy(), sip_send_all_registers(), sipsock_read(), socket_process(), submit_unscheduled_batch(), transmit_register(), and update_jbsched().

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

Convenience macro for objects and reference (del).

Definition at line 186 of file sched.h.

#define AST_SCHED_DEL_SPINLOCK ( sched,
id,
lock   ) 

Definition at line 63 of file sched.h.

Referenced by __sip_ack(), and iax2_destroy().

#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 99 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 245 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(), do_register(), do_reload(), dundi_discover(), dundi_query(), dundi_send(), handle_command_response(), handle_response_invite(), handle_response_peerpoke(), handle_response_register(), iax2_sched_add(), mgcp_postrequest(), parse_register_contact(), populate_addr(), precache_trans(), qualify_peer(), queue_request(), receive_digit(), reg_source_db(), sip_call(), sip_poke_all_peers(), sip_poke_noanswer(), sip_poke_peer(), sip_scheddestroy(), sip_send_all_registers(), submit_scheduled_batch(), submit_unscheduled_batch(), transmit_register(), and update_provisional_keepalive().

00246 {
00247    return ast_sched_add_variable(con, when, callback, data, 0);
00248 }

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 213 of file sched.c.

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

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

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

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.

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 257 of file sched.c.

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

Referenced by delete_users(), iax2_poke_peer(), reg_source_db(), sip_cancel_destroy(), socket_process(), unlink_peer(), and update_registry().

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

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 299 of file sched.c.

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

Referenced by ast_sched_add_variable(), and ast_sched_del().

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

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 329 of file sched.c.

References AST_LIST_EMPTY, AST_LIST_FIRST, AST_LIST_REMOVE_HEAD, ast_log(), ast_mutex_lock(), ast_mutex_unlock(), ast_tv(), ast_tvadd(), ast_tvcmp(), ast_tvnow(), sched::callback, sched::data, DEBUG, sched::list, sched_context::lock, LOG_DEBUG, 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(), misdn_tasks_thread_func(), network_thread(), reload_config(), sched_thread(), speech_background(), wait_for_winner(), and waitstream_core().

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

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 148 of file sched.c.

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

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

00149 {
00150    int ms;
00151 
00152    DEBUG(ast_log(LOG_DEBUG, "ast_sched_wait()\n"));
00153 
00154    ast_mutex_lock(&con->lock);
00155    if (AST_LIST_EMPTY(&con->schedq)) {
00156       ms = -1;
00157    } else {
00158       ms = ast_tvdiff_ms(AST_LIST_FIRST(&con->schedq)->when, ast_tvnow());
00159       if (ms < 0)
00160          ms = 0;
00161    }
00162    ast_mutex_unlock(&con->lock);
00163 
00164    return ms;
00165 }

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 386 of file sched.c.

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

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

00387 {
00388    struct sched *s;
00389    long secs = -1;
00390    DEBUG(ast_log(LOG_DEBUG, "ast_sched_when()\n"));
00391 
00392    ast_mutex_lock(&con->lock);
00393    AST_LIST_TRAVERSE(&con->schedq, s, list) {
00394       if (s->id == id)
00395          break;
00396    }
00397    if (s) {
00398       struct timeval now = ast_tvnow();
00399       secs = s->when.tv_sec - now.tv_sec;
00400    }
00401    ast_mutex_unlock(&con->lock);
00402    
00403    return secs;
00404 }

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 75 of file sched.c.

References ast_calloc, and ast_mutex_init().

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

00076 {
00077    struct sched_context *tmp;
00078 
00079    if (!(tmp = ast_calloc(1, sizeof(*tmp))))
00080       return NULL;
00081 
00082    ast_mutex_init(&tmp->lock);
00083    tmp->eventcnt = 1;
00084    
00085    return tmp;
00086 }

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 88 of file sched.c.

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

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

00089 {
00090    struct sched *s;
00091 
00092    ast_mutex_lock(&con->lock);
00093 
00094 #ifdef SCHED_MAX_CACHE
00095    /* Eliminate the cache */
00096    while ((s = AST_LIST_REMOVE_HEAD(&con->schedc, list)))
00097       free(s);
00098 #endif
00099 
00100    /* And the queue */
00101    while ((s = AST_LIST_REMOVE_HEAD(&con->schedq, list)))
00102       free(s);
00103    
00104    /* And the context */
00105    ast_mutex_unlock(&con->lock);
00106    ast_mutex_destroy(&con->lock);
00107    free(con);
00108 }


Generated on Sat Aug 6 00:40:05 2011 for Asterisk - the Open Source PBX by  doxygen 1.4.7