Asterisk - The Open Source Telephony Project  18.5.0
Data Structures | Macros | Enumerations | Functions
timing.h File Reference

Timing source management. More...

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Data Structures

struct  ast_timing_interface
 Timing module interface. More...
 

Macros

#define ast_register_timing_interface(i)   _ast_register_timing_interface(i, AST_MODULE_SELF)
 Register a set of timing functions. More...
 

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. More...
 
void ast_timer_close (struct ast_timer *handle)
 Close an opened timing handle. More...
 
int ast_timer_disable_continuous (const struct ast_timer *handle)
 Disable continuous mode. More...
 
int ast_timer_enable_continuous (const struct ast_timer *handle)
 Enable continuous mode. More...
 
int ast_timer_fd (const struct ast_timer *handle)
 Get a poll()-able file descriptor for a timer. More...
 
enum ast_timer_event ast_timer_get_event (const struct ast_timer *handle)
 Retrieve timing event. More...
 
unsigned int ast_timer_get_max_rate (const struct ast_timer *handle)
 Get maximum rate supported for a timer. More...
 
const char * ast_timer_get_name (const struct ast_timer *handle)
 Get name of timer in use. More...
 
struct ast_timerast_timer_open (void)
 Open a timer. More...
 
int ast_timer_set_rate (const struct ast_timer *handle, unsigned int rate)
 Set the timing tick rate. More...
 
int ast_unregister_timing_interface (void *handle)
 Unregister a previously registered timing interface. More...
 

Detailed Description

Timing source management.

Author
Kevin P. Fleming kpfle.nosp@m.ming.nosp@m.@digi.nosp@m.um.c.nosp@m.om
Russell Bryant russe.nosp@m.ll@d.nosp@m.igium.nosp@m..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.

Macro Definition Documentation

◆ ast_register_timing_interface

#define ast_register_timing_interface (   i)    _ast_register_timing_interface(i, AST_MODULE_SELF)

Register a set of timing functions.

Parameters
iAn instance of the ast_timing_interfaces structure with pointers to the functions provided by the timing implementation.
Return values
NULLfailure
non-Nullhandle to be passed to ast_unregister_timing_interface() on success
Since
1.6.1

Definition at line 95 of file timing.h.

Referenced by load_module().

Enumeration Type Documentation

◆ ast_timer_event

Enumerator
AST_TIMING_EVENT_EXPIRED 
AST_TIMING_EVENT_CONTINUOUS 

Definition at line 57 of file timing.h.

Function Documentation

◆ _ast_register_timing_interface()

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

Definition at line 73 of file timing.c.

References ast_calloc, ast_heap_push, ast_heap_unlock, ast_heap_wrlock, timing_holder::iface, timing_holder::mod, NULL, 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_fd, 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.

75 {
76  struct timing_holder *h;
77 
78  if (!funcs->timer_open ||
79  !funcs->timer_close ||
80  !funcs->timer_set_rate ||
81  !funcs->timer_ack ||
82  !funcs->timer_get_event ||
83  !funcs->timer_get_max_rate ||
84  !funcs->timer_enable_continuous ||
85  !funcs->timer_disable_continuous ||
86  !funcs->timer_fd) {
87  return NULL;
88  }
89 
90  if (!(h = ast_calloc(1, sizeof(*h)))) {
91  return NULL;
92  }
93 
94  h->iface = funcs;
95  h->mod = mod;
96 
100 
101  return h;
102 }
struct ast_timing_interface * iface
Definition: timing.c:49
#define ast_heap_unlock(h)
Definition: heap.h:248
void(* timer_close)(void *data)
Definition: timing.h:75
enum ast_timer_event(* timer_get_event)(void *data)
Definition: timing.h:80
void *(* timer_open)(void)
Definition: timing.h:74
#define NULL
Definition: resample.c:96
int(* timer_disable_continuous)(void *data)
Definition: timing.h:79
#define ast_heap_push(h, elm)
Definition: heap.h:126
int(* timer_fd)(void *data)
Definition: timing.h:82
int(* timer_set_rate)(void *data, unsigned int rate)
Definition: timing.h:76
#define ast_calloc(num, len)
A wrapper for calloc()
Definition: astmm.h:204
unsigned int(* timer_get_max_rate)(void *data)
Definition: timing.h:81
static struct ast_heap * timing_interfaces
Definition: timing.c:52
struct ast_module * mod
Definition: timing.c:48
int(* timer_enable_continuous)(void *data)
Definition: timing.h:78
int(* timer_ack)(void *data, unsigned int quantity)
Definition: timing.h:77
#define ast_heap_wrlock(h)
Definition: heap.h:246

◆ ast_timer_ack()

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

Acknowledge a timer event.

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

Definition at line 171 of file timing.c.

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

Referenced by __ast_read(), hook_event_cb(), monmp3thread(), snoop_read(), softmix_mixing_loop(), spandsp_fax_read(), timing_read(), and timing_test().

172 {
173  return handle->holder->iface->timer_ack(handle->data, quantity);
174 }
struct ast_timing_interface * iface
Definition: timing.c:49
void * data
Definition: timing.c:55
struct timing_holder * holder
Definition: timing.c:56
int(* timer_ack)(void *data, unsigned int quantity)
Definition: timing.h:77

◆ ast_timer_close()

void ast_timer_close ( struct ast_timer handle)

Close an opened timing handle.

Parameters
handletimer handle returned from timer_open()
Returns
nothing
Since
1.6.1

Definition at line 154 of file timing.c.

References ast_free, ast_module_unref, ast_timer::data, 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(), jb_framedata_destroy(), load_module(), local_ast_moh_start(), moh_class_destructor(), session_destroy(), snoop_destroy(), softmix_bridge_data_destroy(), and timing_test().

155 {
156  handle->holder->iface->timer_close(handle->data);
157  ast_module_unref(handle->holder->mod);
158  ast_free(handle);
159 }
struct ast_timing_interface * iface
Definition: timing.c:49
void(* timer_close)(void *data)
Definition: timing.h:75
void * data
Definition: timing.c:55
#define ast_module_unref(mod)
Release a reference to the module.
Definition: module.h:469
struct timing_holder * holder
Definition: timing.c:56
#define ast_free(a)
Definition: astmm.h:182
struct ast_module * mod
Definition: timing.c:48

◆ ast_timer_disable_continuous()

int ast_timer_disable_continuous ( const struct ast_timer handle)

Disable continuous mode.

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

Definition at line 181 of file timing.c.

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

Referenced by __ast_read().

182 {
183  return handle->holder->iface->timer_disable_continuous(handle->data);
184 }
struct ast_timing_interface * iface
Definition: timing.c:49
void * data
Definition: timing.c:55
int(* timer_disable_continuous)(void *data)
Definition: timing.h:79
struct timing_holder * holder
Definition: timing.c:56

◆ ast_timer_enable_continuous()

int ast_timer_enable_continuous ( const struct ast_timer handle)

Enable continuous mode.

Parameters
handletimer 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
-1failure, with errno set
0success
Since
1.6.1

Definition at line 176 of file timing.c.

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

Referenced by __ast_queue_frame().

177 {
178  return handle->holder->iface->timer_enable_continuous(handle->data);
179 }
struct ast_timing_interface * iface
Definition: timing.c:49
void * data
Definition: timing.c:55
struct timing_holder * holder
Definition: timing.c:56
int(* timer_enable_continuous)(void *data)
Definition: timing.h:78

◆ ast_timer_fd()

int ast_timer_fd ( const struct ast_timer handle)

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

Parameters
handletimer 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 161 of file timing.c.

References ast_timer::data, ast_timer::holder, timing_holder::iface, and ast_timing_interface::timer_fd.

Referenced by __ast_channel_alloc_ap(), jb_framedata_init(), monmp3thread(), network_thread(), softmix_mixing_loop(), spandsp_fax_new(), stasis_app_control_snoop(), and timing_test().

162 {
163  return handle->holder->iface->timer_fd(handle->data);
164 }
struct ast_timing_interface * iface
Definition: timing.c:49
void * data
Definition: timing.c:55
int(* timer_fd)(void *data)
Definition: timing.h:82
struct timing_holder * holder
Definition: timing.c:56

◆ ast_timer_get_event()

enum ast_timer_event ast_timer_get_event ( const struct ast_timer handle)

Retrieve timing event.

Parameters
handletimer 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 186 of file timing.c.

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

Referenced by __ast_read().

187 {
188  return handle->holder->iface->timer_get_event(handle->data);
189 }
struct ast_timing_interface * iface
Definition: timing.c:49
enum ast_timer_event(* timer_get_event)(void *data)
Definition: timing.h:80
void * data
Definition: timing.c:55
struct timing_holder * holder
Definition: timing.c:56

◆ ast_timer_get_max_rate()

unsigned int ast_timer_get_max_rate ( const struct ast_timer handle)

Get maximum rate supported for a timer.

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

Definition at line 191 of file timing.c.

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

Referenced by ast_settimeout_full().

192 {
193  return handle->holder->iface->timer_get_max_rate(handle->data);
194 }
struct ast_timing_interface * iface
Definition: timing.c:49
void * data
Definition: timing.c:55
struct timing_holder * holder
Definition: timing.c:56
unsigned int(* timer_get_max_rate)(void *data)
Definition: timing.h:81

◆ ast_timer_get_name()

const char* ast_timer_get_name ( const struct ast_timer handle)

Get name of timer in use.

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

Definition at line 196 of file timing.c.

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

Referenced by __ast_channel_alloc_ap().

197 {
198  return handle->holder->iface->name;
199 }
const char * name
Definition: timing.h:70
struct ast_timing_interface * iface
Definition: timing.c:49
struct timing_holder * holder
Definition: timing.c:56

◆ ast_timer_open()

struct ast_timer* ast_timer_open ( void  )

Open a timer.

Return values
NULLon error, with errno set
non-NULLtimer handle on success
Since
1.6.1

Definition at line 122 of file timing.c.

References ast_calloc, ast_heap_peek(), ast_heap_rdlock, ast_heap_unlock, ast_module_running_ref, ast_module_unref, ast_timer::data, ast_timer::holder, timing_holder::iface, timing_holder::mod, NULL, ast_timing_interface::timer_close, and ast_timing_interface::timer_open.

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

123 {
124  void *data = NULL;
125  struct timing_holder *h;
126  struct ast_timer *t = NULL;
127  int idx = 1;
128 
130 
131  while ((h = ast_heap_peek(timing_interfaces, idx))) {
132  if (ast_module_running_ref(h->mod)) {
133  data = h->iface->timer_open();
134  break;
135  }
136  idx++;
137  }
138 
139  if (data) {
140  if (!(t = ast_calloc(1, sizeof(*t)))) {
141  h->iface->timer_close(data);
142  ast_module_unref(h->mod);
143  } else {
144  t->data = data;
145  t->holder = h;
146  }
147  }
148 
150 
151  return t;
152 }
struct ast_timing_interface * iface
Definition: timing.c:49
#define ast_heap_unlock(h)
Definition: heap.h:248
void(* timer_close)(void *data)
Definition: timing.h:75
void *(* timer_open)(void)
Definition: timing.h:74
void * data
Definition: timing.c:55
#define NULL
Definition: resample.c:96
#define ast_module_unref(mod)
Release a reference to the module.
Definition: module.h:469
struct timing_holder * holder
Definition: timing.c:56
#define ast_heap_rdlock(h)
Definition: heap.h:247
#define ast_calloc(num, len)
A wrapper for calloc()
Definition: astmm.h:204
static struct ast_heap * timing_interfaces
Definition: timing.c:52
#define ast_module_running_ref(mod)
Hold a reference to the module if it is running.
Definition: module.h:455
struct ast_module * mod
Definition: timing.c:48
void * ast_heap_peek(struct ast_heap *h, unsigned int index)
Peek at an element on a heap.
Definition: heap.c:267

◆ ast_timer_set_rate()

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

Set the timing tick rate.

Parameters
handletimer handle returned from timer_open()
rateticks 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
-1error, with errno set
0success
Since
1.6.1

Definition at line 166 of file timing.c.

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

Referenced by __ast_read(), ast_deactivate_generator(), ast_settimeout_full(), hook_event_cb(), init_app_class(), jb_framedata_init(), load_module(), local_ast_moh_start(), set_config(), softmix_mixing_loop(), spandsp_fax_start(), stasis_app_control_snoop(), and timing_test().

167 {
168  return handle->holder->iface->timer_set_rate(handle->data, rate);
169 }
struct ast_timing_interface * iface
Definition: timing.c:49
void * data
Definition: timing.c:55
struct timing_holder * holder
Definition: timing.c:56
int(* timer_set_rate)(void *data, unsigned int rate)
Definition: timing.h:76

◆ ast_unregister_timing_interface()

int ast_unregister_timing_interface ( void *  handle)

Unregister a previously registered timing interface.

Parameters
handleThe handle returned from a prior successful call to ast_register_timing_interface().
Return values
0success
non-zerofailure
Since
1.6.1

Definition at line 104 of file timing.c.

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

Referenced by unload_module().

105 {
106  struct timing_holder *h = handle;
107  int res = -1;
108 
112 
113  if (h) {
114  ast_free(h);
115  h = NULL;
116  res = 0;
117  }
118 
119  return res;
120 }
#define ast_heap_unlock(h)
Definition: heap.h:248
#define NULL
Definition: resample.c:96
#define ast_free(a)
Definition: astmm.h:182
static struct ast_heap * timing_interfaces
Definition: timing.c:52
void * ast_heap_remove(struct ast_heap *h, void *elm)
Remove a specific element from a heap.
Definition: heap.c:251
#define ast_heap_wrlock(h)
Definition: heap.h:246