Add Doxygen documentation for API changes from 1.6.0 to 1.6.1
[asterisk/asterisk.git] / include / asterisk / timing.h
1 /*
2  * Asterisk -- An open source telephony toolkit.
3  *
4  * Copyright (C) 2008 - 2009, Digium, Inc.
5  *
6  * Kevin P. Fleming <kpfleming@digium.com>
7  * Russell Bryant <russell@digium.com>
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 <kpfleming@digium.com>
24   \author Russell Bryant <russell@digium.com>
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   \todo Create an implementation of this API for Linux based on the
50    following API: http://www.kernel.org/doc/man-pages/online/pages/man2/timerfd_create.2.html
51  */
52
53 #ifndef _ASTERISK_TIMING_H
54 #define _ASTERISK_TIMING_H
55
56 #if defined(__cplusplus) || defined(c_plusplus)
57 extern "C" {
58 #endif
59
60 enum ast_timer_event {
61         AST_TIMING_EVENT_EXPIRED = 1,
62         AST_TIMING_EVENT_CONTINUOUS = 2,
63 };
64
65 /*!
66  * \brief Timing module interface
67  *
68  * The public API calls for the timing API directly map to this interface.
69  * So, the behavior of these calls should match the documentation of the
70  * public API calls.
71  */
72 struct ast_timing_interface {
73         const char *name;
74         /*! This handles the case where multiple timing modules are loaded.
75          *  The highest priority timing interface available will be used. */
76         unsigned int priority;
77         int (*timer_open)(void);
78         void (*timer_close)(int handle);
79         int (*timer_set_rate)(int handle, unsigned int rate);
80         void (*timer_ack)(int handle, unsigned int quantity);
81         int (*timer_enable_continuous)(int handle);
82         int (*timer_disable_continuous)(int handle);
83         enum ast_timer_event (*timer_get_event)(int handle);
84         unsigned int (*timer_get_max_rate)(int handle);
85 };
86
87 /*!
88  * \brief Register a set of timing functions.
89  *
90  * \param funcs An instance of the \c ast_timing_interfaces structure with pointers
91  *        to the functions provided by the timing implementation.
92  *
93  * \retval NULL failure 
94  * \retval non-Null handle to be passed to ast_unregister_timing_interface() on success
95  * \since 1.6.1
96  */
97 #define ast_register_timing_interface(i) _ast_register_timing_interface(i, ast_module_info->self)
98 void *_ast_register_timing_interface(struct ast_timing_interface *funcs,
99                 struct ast_module *mod);
100
101 /*!
102  * \brief Unregister a previously registered timing interface.
103  *
104  * \param handle The handle returned from a prior successful call to
105  *        ast_register_timing_interface().
106  *
107  * \retval 0 success
108  * \retval non-zero failure
109  * \since 1.6.1
110  */
111 int ast_unregister_timing_interface(void *handle);
112
113 /*!
114  * \brief Open a timing fd
115  *
116  * \retval -1 error, with errno set
117  * \retval >=0 success
118  * \since 1.6.1
119  */
120 int ast_timer_open(void);
121
122 /*!
123  * \brief Close an opened timing handle
124  *
125  * \param handle timing fd returned from timer_open()
126  *
127  * \return nothing
128  * \since 1.6.1
129  */
130 void ast_timer_close(int handle);
131
132 /*!
133  * \brief Set the timing tick rate
134  *
135  * \param handle timing fd returned from timer_open()
136  * \param rate ticks per second, 0 turns the ticks off if needed
137  *
138  * Use this function if you want the timing fd to show input at a certain
139  * rate.  The other alternative use of a timing fd, is using the continuous
140  * mode.
141  *
142  * \retval -1 error, with errno set
143  * \retval 0 success
144  * \since 1.6.1
145  */
146 int ast_timer_set_rate(int handle, unsigned int rate);
147
148 /*!
149  * \brief Acknowledge a timer event
150  *
151  * \param handle timing fd returned from timer_open()
152  * \param quantity number of timer events to acknowledge
153  *
154  * \note This function should only be called if timer_get_event()
155  *       returned AST_TIMING_EVENT_EXPIRED.
156  *
157  * \return nothing
158  * \since 1.6.1
159  */
160 void ast_timer_ack(int handle, unsigned int quantity);
161
162 /*!
163  * \brief Enable continuous mode
164  *
165  * \param handle timing fd returned from timer_open()
166  *
167  * Continuous mode causes poll() on the timing fd to immediately return
168  * always until continuous mode is disabled.
169  *
170  * \retval -1 failure, with errno set
171  * \retval 0 success
172  * \since 1.6.1
173  */
174 int ast_timer_enable_continuous(int handle);
175
176 /*!
177  * \brief Disable continuous mode
178  *
179  * \param handle timing fd returned from timer_close()
180  *
181  * \retval -1 failure, with errno set
182  * \retval 0 success
183  * \since 1.6.1
184  */
185 int ast_timer_disable_continuous(int handle);
186
187 /*!
188  * \brief Determine timing event
189  *
190  * \param handle timing fd returned by timer_open()
191  *
192  * After poll() indicates that there is input on the timing fd, this will
193  * be called to find out what triggered it.
194  *
195  * \return which event triggered the timing fd
196  * \since 1.6.1
197  */
198 enum ast_timer_event ast_timer_get_event(int handle);
199
200 /*!
201  * \brief Get maximum rate supported for a timing handle
202  *
203  * \param handle timing fd returned by timer_open()
204  *
205  * \return maximum rate supported for timing handle
206  * \since 1.6.1
207  */
208 unsigned int ast_timer_get_max_rate(int handle);
209
210 #if defined(__cplusplus) || defined(c_plusplus)
211 }
212 #endif
213
214 #endif /* _ASTERISK_TIMING_H */