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_timer *	ast_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

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 95 of file timing.h.

Referenced by load_module().

Enumeration Type Documentation

ast_timer_event

enum ast_timer_event

Enumerator
AST_TIMING_EVENT_EXPIRED
AST_TIMING_EVENT_CONTINUOUS

Definition at line 57 of file timing.h.

                     {
   AST_TIMING_EVENT_EXPIRED = 1,
   AST_TIMING_EVENT_CONTINUOUS = 2,
};

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.

{
   struct timing_holder *h;

   if (!funcs->timer_open ||
       !funcs->timer_close ||
       !funcs->timer_set_rate ||
       !funcs->timer_ack ||
       !funcs->timer_get_event ||
       !funcs->timer_get_max_rate ||
       !funcs->timer_enable_continuous ||
       !funcs->timer_disable_continuous ||
       !funcs->timer_fd) {
      return NULL;
   }

   if (!(h = ast_calloc(1, sizeof(*h)))) {
      return NULL;
   }

   h->iface = funcs;
   h->mod = mod;

   ast_heap_wrlock(timing_interfaces);
   ast_heap_push(timing_interfaces, h);
   ast_heap_unlock(timing_interfaces);

   return h;
}

ast_timer_ack()

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 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().

{
   return handle->holder->iface->timer_ack(handle->data, quantity);
}

ast_timer_close()

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 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().

{
   handle->holder->iface->timer_close(handle->data);
   ast_module_unref(handle->holder->mod);
   ast_free(handle);
}

ast_timer_disable_continuous()

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 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().

{
   return handle->holder->iface->timer_disable_continuous(handle->data);
}

ast_timer_enable_continuous()

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 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().

{
   return handle->holder->iface->timer_enable_continuous(handle->data);
}

ast_timer_fd()

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 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().

{
   return handle->holder->iface->timer_fd(handle->data);
}

ast_timer_get_event()

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 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().

{
   return handle->holder->iface->timer_get_event(handle->data);
}

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

handle

timer 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().

{
   return handle->holder->iface->timer_get_max_rate(handle->data);
}

ast_timer_get_name()

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 196 of file timing.c.

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

Referenced by __ast_channel_alloc_ap().

{
   return handle->holder->iface->name;
}

ast_timer_open()

struct ast_timer* ast_timer_open

(

void

)

Open a timer.

Return values

NULL	on error, with errno set
non-NULL	timer 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().

{
   void *data = NULL;
   struct timing_holder *h;
   struct ast_timer *t = NULL;
   int idx = 1;

   ast_heap_rdlock(timing_interfaces);

   while ((h = ast_heap_peek(timing_interfaces, idx))) {
      if (ast_module_running_ref(h->mod)) {
         data = h->iface->timer_open();
         break;
      }
      idx++;
   }

   if (data) {
      if (!(t = ast_calloc(1, sizeof(*t)))) {
         h->iface->timer_close(data);
         ast_module_unref(h->mod);
      } else {
         t->data = data;
         t->holder = h;
      }
   }

   ast_heap_unlock(timing_interfaces);

   return t;
}

ast_timer_set_rate()

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 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().

{
   return handle->holder->iface->timer_set_rate(handle->data, rate);
}

ast_unregister_timing_interface()

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 104 of file timing.c.

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

Referenced by unload_module().

{
   struct timing_holder *h = handle;
   int res = -1;

   ast_heap_wrlock(timing_interfaces);
   h = ast_heap_remove(timing_interfaces, h);
   ast_heap_unlock(timing_interfaces);

   if (h) {
      ast_free(h);
      h = NULL;
      res = 0;
   }

   return res;
}