Asterisk - The Open Source Telephony Project  18.5.0
timing.h
Go to the documentation of this file.
1 /*
2  * Asterisk -- An open source telephony toolkit.
3  *
4  * Copyright (C) 2008 - 2009, Digium, Inc.
5  *
6  * Kevin P. Fleming <[email protected]>
7  * Russell Bryant <[email protected]>
8  *
9  * See http://www.asterisk.org for more information about
10  * the Asterisk project. Please do not directly contact
11  * any of the maintainers of this project for assistance;
12  * the project provides a web site, mailing lists and IRC
13  * channels for your use.
14  *
15  * This program is free software, distributed under the terms of
16  * the GNU General Public License Version 2. See the LICENSE file
17  * at the top of the source tree.
18  */
19 
20 /*!
21  \file timing.h
22  \brief Timing source management
23  \author Kevin P. Fleming <[email protected]>
24  \author Russell Bryant <[email protected]>
25 
26  Portions of Asterisk require a timing source, a periodic trigger
27  for media handling activities. The functions in this file allow
28  a loadable module to provide a timing source for Asterisk and its
29  modules, so that those modules can request a 'timing handle' when
30  they require one. These handles are file descriptors, which can be
31  used with select() or poll().
32 
33  The timing source used by Asterisk must provide the following
34  features:
35 
36  1) Periodic triggers, with a configurable interval (specified as
37  number of triggers per second).
38 
39  2) Multiple outstanding triggers, each of which must be 'acked'
40  to clear it. Triggers must also be 'ackable' in quantity.
41 
42  3) Continuous trigger mode, which when enabled causes every call
43  to poll() on the timer handle to immediately return.
44 
45  4) Multiple 'event types', so that the code using the timer can
46  know whether the wakeup it received was due to a periodic trigger
47  or a continuous trigger.
48  */
49 
50 #ifndef _ASTERISK_TIMING_H
51 #define _ASTERISK_TIMING_H
52 
53 #if defined(__cplusplus) || defined(c_plusplus)
54 extern "C" {
55 #endif
56 
60 };
61 
62 /*!
63  * \brief Timing module interface
64  *
65  * The public API calls for the timing API directly map to this interface.
66  * So, the behavior of these calls should match the documentation of the
67  * public API calls.
68  */
70  const char *name;
71  /*! This handles the case where multiple timing modules are loaded.
72  * The highest priority timing interface available will be used. */
73  unsigned int priority;
74  void *(*timer_open)(void);
75  void (*timer_close)(void *data);
76  int (*timer_set_rate)(void *data, unsigned int rate);
77  int (*timer_ack)(void *data, unsigned int quantity);
78  int (*timer_enable_continuous)(void *data);
79  int (*timer_disable_continuous)(void *data);
80  enum ast_timer_event (*timer_get_event)(void *data);
81  unsigned int (*timer_get_max_rate)(void *data);
82  int (*timer_fd)(void *data);
83 };
84 
85 /*!
86  * \brief Register a set of timing functions.
87  *
88  * \param i An instance of the \c ast_timing_interfaces structure with pointers
89  * to the functions provided by the timing implementation.
90  *
91  * \retval NULL failure
92  * \retval non-Null handle to be passed to ast_unregister_timing_interface() on success
93  * \since 1.6.1
94  */
95 #define ast_register_timing_interface(i) _ast_register_timing_interface(i, AST_MODULE_SELF)
97  struct ast_module *mod);
98 
99 /*!
100  * \brief Unregister a previously registered timing interface.
101  *
102  * \param handle The handle returned from a prior successful call to
103  * ast_register_timing_interface().
104  *
105  * \retval 0 success
106  * \retval non-zero failure
107  * \since 1.6.1
108  */
109 int ast_unregister_timing_interface(void *handle);
110 
111 struct ast_timer;
112 
113 /*!
114  * \brief Open a timer
115  *
116  * \retval NULL on error, with errno set
117  * \retval non-NULL timer handle on success
118  * \since 1.6.1
119  */
120 struct ast_timer *ast_timer_open(void);
121 
122 /*!
123  * \brief Close an opened timing handle
124  *
125  * \param handle timer handle returned from timer_open()
126  *
127  * \return nothing
128  * \since 1.6.1
129  */
130 void ast_timer_close(struct ast_timer *handle);
131 
132 /*!
133  * \brief Get a poll()-able file descriptor for a timer
134  *
135  * \param handle timer handle returned from timer_open()
136  *
137  * \return file descriptor which can be used with poll() to wait for events
138  * \since 1.6.1
139  */
140 int ast_timer_fd(const struct ast_timer *handle);
141 
142 /*!
143  * \brief Set the timing tick rate
144  *
145  * \param handle timer handle returned from timer_open()
146  * \param rate ticks per second, 0 turns the ticks off if needed
147  *
148  * Use this function if you want the timer to show input at a certain
149  * rate. The other alternative use of a timer is the continuous
150  * mode.
151  *
152  * \retval -1 error, with errno set
153  * \retval 0 success
154  * \since 1.6.1
155  */
156 int ast_timer_set_rate(const struct ast_timer *handle, unsigned int rate);
157 
158 /*!
159  * \brief Acknowledge a timer event
160  *
161  * \param handle timer handle returned from timer_open()
162  * \param quantity number of timer events to acknowledge
163  *
164  * \note This function should only be called if timer_get_event()
165  * returned AST_TIMING_EVENT_EXPIRED.
166  *
167  * \retval -1 failure, with errno set
168  * \retval 0 success
169  * \since 10.5.2
170  */
171 int ast_timer_ack(const struct ast_timer *handle, unsigned int quantity);
172 
173 /*!
174  * \brief Enable continuous mode
175  *
176  * \param handle timer handle returned from timer_open()
177  *
178  * Continuous mode causes poll() on the timer's fd to immediately return
179  * always until continuous mode is disabled.
180  *
181  * \retval -1 failure, with errno set
182  * \retval 0 success
183  * \since 1.6.1
184  */
185 int ast_timer_enable_continuous(const struct ast_timer *handle);
186 
187 /*!
188  * \brief Disable continuous mode
189  *
190  * \param handle timer handle returned from timer_close()
191  *
192  * \retval -1 failure, with errno set
193  * \retval 0 success
194  * \since 1.6.1
195  */
196 int ast_timer_disable_continuous(const struct ast_timer *handle);
197 
198 /*!
199  * \brief Retrieve timing event
200  *
201  * \param handle timer handle returned by timer_open()
202  *
203  * After poll() indicates that there is input on the timer's fd, this will
204  * be called to find out what triggered it.
205  *
206  * \return which event triggered the timer
207  * \since 1.6.1
208  */
209 enum ast_timer_event ast_timer_get_event(const struct ast_timer *handle);
210 
211 /*!
212  * \brief Get maximum rate supported for a timer
213  *
214  * \param handle timer handle returned by timer_open()
215  *
216  * \return maximum rate supported by timer
217  * \since 1.6.1
218  */
219 unsigned int ast_timer_get_max_rate(const struct ast_timer *handle);
220 
221 /*!
222  * \brief Get name of timer in use
223  *
224  * \param handle timer handle returned by timer_open()
225  *
226  * \return name of timer
227  * \since 1.6.2
228  */
229 const char *ast_timer_get_name(const struct ast_timer *handle);
230 
231 #if defined(__cplusplus) || defined(c_plusplus)
232 }
233 #endif
234 
235 #endif /* _ASTERISK_TIMING_H */
const char * name
Definition: timing.h:70
Timing module interface.
Definition: timing.h:69
unsigned int ast_timer_get_max_rate(const struct ast_timer *handle)
Get maximum rate supported for a timer.
Definition: timing.c:191
int ast_unregister_timing_interface(void *handle)
Unregister a previously registered timing interface.
Definition: timing.c:104
ast_timer_event
Definition: timing.h:57
void(* timer_close)(void *data)
Definition: timing.h:75
enum ast_timer_event(* timer_get_event)(void *data)
Definition: timing.h:80
void ast_timer_close(struct ast_timer *handle)
Close an opened timing handle.
Definition: timing.c:154
struct ast_timer * ast_timer_open(void)
Open a timer.
Definition: timing.c:122
int(* timer_disable_continuous)(void *data)
Definition: timing.h:79
int(* timer_fd)(void *data)
Definition: timing.h:82
unsigned int priority
Definition: timing.h:73
int ast_timer_disable_continuous(const struct ast_timer *handle)
Disable continuous mode.
Definition: timing.c:181
int ast_timer_ack(const struct ast_timer *handle, unsigned int quantity)
Acknowledge a timer event.
Definition: timing.c:171
void * _ast_register_timing_interface(struct ast_timing_interface *funcs, struct ast_module *mod)
Definition: timing.c:73
int(* timer_set_rate)(void *data, unsigned int rate)
Definition: timing.h:76
unsigned int(* timer_get_max_rate)(void *data)
Definition: timing.h:81
int ast_timer_fd(const struct ast_timer *handle)
Get a poll()-able file descriptor for a timer.
Definition: timing.c:161
int ast_timer_set_rate(const struct ast_timer *handle, unsigned int rate)
Set the timing tick rate.
Definition: timing.c:166
int ast_timer_enable_continuous(const struct ast_timer *handle)
Enable continuous mode.
Definition: timing.c:176
int(* timer_enable_continuous)(void *data)
Definition: timing.h:78
int(* timer_ack)(void *data, unsigned int quantity)
Definition: timing.h:77
enum ast_timer_event ast_timer_get_event(const struct ast_timer *handle)
Retrieve timing event.
Definition: timing.c:186
const char * ast_timer_get_name(const struct ast_timer *handle)
Get name of timer in use.
Definition: timing.c:196