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