Thu Sep 7 01:03:40 2017

Asterisk developer's documentation


timing.h File Reference

Timing source management. More...

Go to the source code of this file.

Data Structures

struct  ast_timing_interface
 Timing module interface. More...

Defines

#define ast_register_timing_interface(i)   _ast_register_timing_interface(i, ast_module_info->self)
 Register a set of timing functions.

Enumerations

enum  ast_timer_event { AST_TIMING_EVENT_EXPIRED = 1, AST_TIMING_EVENT_CONTINUOUS = 2 }

Functions

void * _ast_register_timing_interface (struct ast_timing_interface *funcs, struct ast_module *mod)
int ast_timer_ack (const struct ast_timer *handle, unsigned int quantity)
 Acknowledge a timer event.
void ast_timer_close (struct ast_timer *handle)
 Close an opened timing handle.
int ast_timer_disable_continuous (const struct ast_timer *handle)
 Disable continuous mode.
int ast_timer_enable_continuous (const struct ast_timer *handle)
 Enable continuous mode.
int ast_timer_fd (const struct ast_timer *handle)
 Get a poll()-able file descriptor for a timer.
enum ast_timer_event ast_timer_get_event (const struct ast_timer *handle)
 Retrieve timing event.
unsigned int ast_timer_get_max_rate (const struct ast_timer *handle)
 Get maximum rate supported for a timer.
const char * ast_timer_get_name (const struct ast_timer *handle)
 Get name of timer in use.
struct ast_timerast_timer_open (void)
 Open a timer.
int ast_timer_set_rate (const struct ast_timer *handle, unsigned int rate)
 Set the timing tick rate.
int ast_unregister_timing_interface (void *handle)
 Unregister a previously registered timing interface.

Detailed Description

Timing source management.

Author:
Kevin P. Fleming <kpfleming@digium.com>
Russell Bryant <russell@digium.com>

Portions of Asterisk require a timing source, a periodic trigger for media handling activities. The functions in this file allow a loadable module to provide a timing source for Asterisk and its modules, so that those modules can request a 'timing handle' when they require one. These handles are file descriptors, which can be used with select() or poll().

The timing source used by Asterisk must provide the following features:

1) Periodic triggers, with a configurable interval (specified as number of triggers per second).

2) Multiple outstanding triggers, each of which must be 'acked' to clear it. Triggers must also be 'ackable' in quantity.

3) Continuous trigger mode, which when enabled causes every call to poll() on the timer handle to immediately return.

4) Multiple 'event types', so that the code using the timer can know whether the wakeup it received was due to a periodic trigger or a continuous trigger.

Definition in file timing.h.


Define Documentation

#define ast_register_timing_interface (  )     _ast_register_timing_interface(i, ast_module_info->self)

Register a set of timing functions.

Parameters:
i An instance of the ast_timing_interfaces structure with pointers to the functions provided by the timing implementation.
Return values:
NULL failure
non-Null handle to be passed to ast_unregister_timing_interface() on success
Since:
1.6.1

Definition at line 94 of file timing.h.

Referenced by load_module().


Enumeration Type Documentation

Enumerator:
AST_TIMING_EVENT_EXPIRED 
AST_TIMING_EVENT_CONTINUOUS 

Definition at line 57 of file timing.h.

00057                      {
00058    AST_TIMING_EVENT_EXPIRED = 1,
00059    AST_TIMING_EVENT_CONTINUOUS = 2,
00060 };


Function Documentation

void* _ast_register_timing_interface ( struct ast_timing_interface funcs,
struct ast_module mod 
)

Definition at line 75 of file timing.c.

References ast_calloc, ast_heap_push(), ast_heap_unlock, ast_heap_wrlock, timing_holder::iface, timing_holder::mod, ast_timing_interface::timer_ack, ast_timing_interface::timer_close, ast_timing_interface::timer_disable_continuous, ast_timing_interface::timer_enable_continuous, ast_timing_interface::timer_get_event, ast_timing_interface::timer_get_max_rate, ast_timing_interface::timer_open, and ast_timing_interface::timer_set_rate.

00077 {
00078    struct timing_holder *h;
00079 
00080    if (!funcs->timer_open ||
00081        !funcs->timer_close ||
00082        !funcs->timer_set_rate ||
00083        !funcs->timer_ack ||
00084        !funcs->timer_get_event ||
00085        !funcs->timer_get_max_rate ||
00086        !funcs->timer_enable_continuous ||
00087        !funcs->timer_disable_continuous) {
00088       return NULL;
00089    }
00090 
00091    if (!(h = ast_calloc(1, sizeof(*h)))) {
00092       return NULL;
00093    }
00094 
00095    h->iface = funcs;
00096    h->mod = mod;
00097 
00098    ast_heap_wrlock(timing_interfaces);
00099    ast_heap_push(timing_interfaces, h);
00100    ast_heap_unlock(timing_interfaces);
00101 
00102    return h;
00103 }

int ast_timer_ack ( const struct ast_timer handle,
unsigned int  quantity 
)

Acknowledge a timer event.

Parameters:
handle timer handle returned from timer_open()
quantity number of timer events to acknowledge
Note:
This function should only be called if timer_get_event() returned AST_TIMING_EVENT_EXPIRED.
Return values:
-1 failure, with errno set
0 success
Since:
10.5.2

Definition at line 172 of file timing.c.

References ast_timer::fd, ast_timer::holder, timing_holder::iface, and ast_timing_interface::timer_ack.

Referenced by __ast_read(), monmp3thread(), softmix_bridge_thread(), spandsp_fax_read(), timing_read(), and timing_test().

00173 {
00174    int res = -1;
00175 
00176    res = handle->holder->iface->timer_ack(handle->fd, quantity);
00177 
00178    return res;
00179 }

void ast_timer_close ( struct ast_timer handle  ) 

Close an opened timing handle.

Parameters:
handle timer handle returned from timer_open()
Returns:
nothing
Since:
1.6.1

Definition at line 150 of file timing.c.

References ast_free, ast_module_unref(), ast_timer::fd, ast_timer::holder, timing_holder::iface, timing_holder::mod, and ast_timing_interface::timer_close.

Referenced by __unload_module(), ast_channel_destructor(), init_app_class(), load_module(), local_ast_moh_start(), moh_class_destructor(), session_destroy(), softmix_bridge_destroy(), and timing_test().

00151 {
00152    handle->holder->iface->timer_close(handle->fd);
00153    handle->fd = -1;
00154    ast_module_unref(handle->holder->mod);
00155    ast_free(handle);
00156 }

int ast_timer_disable_continuous ( const struct ast_timer handle  ) 

Disable continuous mode.

Parameters:
handle timer handle returned from timer_close()
Return values:
-1 failure, with errno set
0 success
Since:
1.6.1

Definition at line 190 of file timing.c.

References ast_timer::fd, ast_timer::holder, timing_holder::iface, and ast_timing_interface::timer_disable_continuous.

Referenced by __ast_read().

00191 {
00192    int res = -1;
00193 
00194    res = handle->holder->iface->timer_disable_continuous(handle->fd);
00195 
00196    return res;
00197 }

int ast_timer_enable_continuous ( const struct ast_timer handle  ) 

Enable continuous mode.

Parameters:
handle timer handle returned from timer_open()

Continuous mode causes poll() on the timer's fd to immediately return always until continuous mode is disabled.

Return values:
-1 failure, with errno set
0 success
Since:
1.6.1

Definition at line 181 of file timing.c.

References ast_timer::fd, ast_timer::holder, timing_holder::iface, and ast_timing_interface::timer_enable_continuous.

Referenced by __ast_queue_frame().

00182 {
00183    int res = -1;
00184 
00185    res = handle->holder->iface->timer_enable_continuous(handle->fd);
00186 
00187    return res;
00188 }

int ast_timer_fd ( const struct ast_timer handle  ) 

Get a poll()-able file descriptor for a timer.

Parameters:
handle timer handle returned from timer_open()
Returns:
file descriptor which can be used with poll() to wait for events
Since:
1.6.1

Definition at line 158 of file timing.c.

References ast_timer::fd.

Referenced by __ast_channel_alloc_ap(), monmp3thread(), network_thread(), softmix_bridge_thread(), spandsp_fax_new(), and timing_test().

00159 {
00160    return handle->fd;
00161 }

enum ast_timer_event ast_timer_get_event ( const struct ast_timer handle  ) 

Retrieve timing event.

Parameters:
handle timer handle returned by timer_open()

After poll() indicates that there is input on the timer's fd, this will be called to find out what triggered it.

Returns:
which event triggered the timer
Since:
1.6.1

Definition at line 199 of file timing.c.

References ast_timer::fd, ast_timer::holder, timing_holder::iface, and ast_timing_interface::timer_get_event.

Referenced by __ast_read().

00200 {
00201    enum ast_timer_event res = -1;
00202 
00203    res = handle->holder->iface->timer_get_event(handle->fd);
00204 
00205    return res;
00206 }

unsigned int ast_timer_get_max_rate ( const struct ast_timer handle  ) 

Get maximum rate supported for a timer.

Parameters:
handle timer handle returned by timer_open()
Returns:
maximum rate supported by timer
Since:
1.6.1

Definition at line 208 of file timing.c.

References ast_timer::fd, ast_timer::holder, timing_holder::iface, and ast_timing_interface::timer_get_max_rate.

Referenced by ast_settimeout_full().

00209 {
00210    unsigned int res = 0;
00211 
00212    res = handle->holder->iface->timer_get_max_rate(handle->fd);
00213 
00214    return res;
00215 }

const char* ast_timer_get_name ( const struct ast_timer handle  ) 

Get name of timer in use.

Parameters:
handle timer handle returned by timer_open()
Returns:
name of timer
Since:
1.6.2

Definition at line 217 of file timing.c.

References ast_timer::holder, timing_holder::iface, and ast_timing_interface::name.

Referenced by __ast_channel_alloc_ap().

00218 {
00219    return handle->holder->iface->name;
00220 }

struct ast_timer* ast_timer_open ( void   )  [read]

Open a timer.

Return values:
NULL on error, with errno set
non-NULL timer handle on success
Since:
1.6.1

Definition at line 123 of file timing.c.

References ast_calloc, ast_heap_peek(), ast_heap_rdlock, ast_heap_unlock, ast_module_ref(), ast_timer::fd, ast_timer::holder, timing_holder::iface, timing_holder::mod, ast_timing_interface::timer_close, and ast_timing_interface::timer_open.

Referenced by __ast_channel_alloc_ap(), init_app_class(), load_module(), local_ast_moh_start(), softmix_bridge_create(), spandsp_fax_new(), and timing_test().

00124 {
00125    int fd = -1;
00126    struct timing_holder *h;
00127    struct ast_timer *t = NULL;
00128 
00129    ast_heap_rdlock(timing_interfaces);
00130 
00131    if ((h = ast_heap_peek(timing_interfaces, 1))) {
00132       fd = h->iface->timer_open();
00133       ast_module_ref(h->mod);
00134    }
00135 
00136    if (fd != -1) {
00137       if (!(t = ast_calloc(1, sizeof(*t)))) {
00138          h->iface->timer_close(fd);
00139       } else {
00140          t->fd = fd;
00141          t->holder = h;
00142       }
00143    }
00144 
00145    ast_heap_unlock(timing_interfaces);
00146 
00147    return t;
00148 }

int ast_timer_set_rate ( const struct ast_timer handle,
unsigned int  rate 
)

Set the timing tick rate.

Parameters:
handle timer handle returned from timer_open()
rate ticks per second, 0 turns the ticks off if needed

Use this function if you want the timer to show input at a certain rate. The other alternative use of a timer is the continuous mode.

Return values:
-1 error, with errno set
0 success
Since:
1.6.1

Definition at line 163 of file timing.c.

References ast_timer::fd, ast_timer::holder, timing_holder::iface, and ast_timing_interface::timer_set_rate.

Referenced by __ast_read(), ast_settimeout_full(), init_app_class(), load_module(), local_ast_moh_start(), set_config(), softmix_bridge_thread(), spandsp_fax_start(), and timing_test().

00164 {
00165    int res = -1;
00166 
00167    res = handle->holder->iface->timer_set_rate(handle->fd, rate);
00168 
00169    return res;
00170 }

int ast_unregister_timing_interface ( void *  handle  ) 

Unregister a previously registered timing interface.

Parameters:
handle The handle returned from a prior successful call to ast_register_timing_interface().
Return values:
0 success
non-zero failure
Since:
1.6.1

Definition at line 105 of file timing.c.

References ast_free, ast_heap_remove(), ast_heap_unlock, and ast_heap_wrlock.

Referenced by unload_module().

00106 {
00107    struct timing_holder *h = handle;
00108    int res = -1;
00109 
00110    ast_heap_wrlock(timing_interfaces);
00111    h = ast_heap_remove(timing_interfaces, h);
00112    ast_heap_unlock(timing_interfaces);
00113 
00114    if (h) {
00115       ast_free(h);
00116       h = NULL;
00117       res = 0;
00118    }
00119 
00120    return res;
00121 }


Generated on 7 Sep 2017 for Asterisk - The Open Source Telephony Project by  doxygen 1.6.1