libpeak-0.1.2/peak/timer.h

/* PEAK Library
 *
 * Copyright (c) 2003, 2004
 *      Stephane Thiell <mbuna@bugged.org>. All rights reserved.
 *
 * Redistribution and use in source and binary forms, with or without
 * modification, are permitted provided that the following conditions
 * are met:
 *
 * 1. Redistributions of source code must retain the above copyright
 *    notice, this list of conditions and the following disclaimer.
 *
 * 2. Redistributions in binary form must reproduce the above copyright
 *    notice, this list of conditions and the following disclaimer in the
 *    documentation and/or other materials provided with the distribution.
 *
 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
 * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
 * TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
 * PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE COPYRIGHT OWNER OR
 * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
 * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
 * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS;
 * OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
 * WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
 * OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF
 * ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 * 
 * $Id: timer.h,v 1.2 2004/01/04 17:38:49 mbuna Exp $
 */
#ifndef INCLUDED_PEAK_TIMER_H_
#define INCLUDED_PEAK_TIMER_H_

/*!
 * @defgroup timer Timer
 * 
 * Lightweight timer/repeater support within a task. Units are floats in
 * seconds with an internal precision up to usec, but subjects to client's
 * event handlers so don't expect a lot.\n
 * For best results, please use in conjunction with the Time module
 * (\p peak_time*).
 */

/*!
 * @ingroup timer
 * @brief Opaque timer pointer type.
 */
typedef struct __peak_timer * peak_timer;

/*!
 * @ingroup timer
 * @brief Timer callback.
 */
typedef void (*peak_timer_callback)(peak_timer t, void *context);

#if defined(__cplusplus)
extern "C" {
#endif

/*!
 * @ingroup timer
 * @brief Create a timer.
 * 
 * Note that the timer isn't activated until you add it to the task of your
 * choice (usually peak_task_self()) with peak_task_timer_add().
 * 
 * @param fire     Relative fire time in second. 0 means immediate fire (as
 *                 soon as possible, usually during the next event loop).
 *                 A value of -1.0 means never fire, and can be useful to
 *                 temporarily "disable" a timer.
 * @param interval Repeat interval in second. Use -1.0 for a one-shot timer.
 *                 Value must be strictly positive for repeating timer.
 * @param callout  A pointer to your timer callback function which is
 *                 triggered when the timer fires.
 * @param context  An extra application-defined pointer that will be passed
 *                 to your timer callback function (it's not used by the
 *                 library).
 *
 * @return         A newly allocated \p peak_timer reference or \p NULL if the
 *                 timer cannot be created.
 */
extern peak_timer peak_timer_create(double fire,
                                    double interval,
                                    peak_timer_callback callout,
                                    void *context);

/*!
 * @ingroup timer
 * @brief (Re)configure a timer.
 * 
 * @param t        The timer reference to configure.
 * @param fire     Relative fire time in second. 0 means immediate fire (as
 *                 soon as possible, usually during the next event loop).
 *                 A value of -1.0 means never fire, and can be useful to
 *                 temporarily "disable" a timer.
 * @param interval Repeat interval in second. Use -1.0 for a one-shot timer.
 *                 Value must be strictly positive for repeating timer.
 */
extern void peak_timer_configure(peak_timer t, double fire, double interval);

/*!
 * @ingroup timer
 * @brief Get timer's fire date time.
 * 
 * @param t        The timer reference.
 * 
 * @return         Absolute time in second before the timer fires (if it
 *                 is added to a task).
 */
extern double peak_timer_get_firetime(peak_timer t);

/*!
 * @ingroup timer
 * @brief Get timer's repeat-interval time.
 * 
 * @param t        The timer reference.
 * 
 * @return         Interval time in second.
 */
extern double peak_timer_get_interval(peak_timer t);

/*!
 * @ingroup timer
 * @brief Get timer's extra application-defined context.
 * 
 * @param t        The timer reference.
 * 
 * @return         Context pointer.
 */
extern void* peak_timer_get_context(peak_timer t);

/*!
 * @ingroup timer
 * @brief Change the context pointer of a timer.
 * 
 * @param t        The timer reference.
 * @param context  An extra application-defined pointer that will be passed
 *                 to your timer callback function (it's not used by the
 *                 library).
 */
extern void peak_timer_set_context(peak_timer t, void *context);


#if defined(__cplusplus)
}
#endif

#endif /* INCLUDED_PEAK_TIMER_H_ */
Revision:	3251
Committed:	Wed Apr 2 16:58:30 2014 UTC (11 years, 4 months ago) by michael
Content type:	text/x-chdr
File size:	5172 byte(s)
Log Message:	- Imported libpeak-0.1.2
#	Content
1	/* PEAK Library
2	*
3	* Copyright (c) 2003, 2004
4	* Stephane Thiell <mbuna@bugged.org>. All rights reserved.
5	*
6	* Redistribution and use in source and binary forms, with or without
7	* modification, are permitted provided that the following conditions
8	* are met:
9	*
10	* 1. Redistributions of source code must retain the above copyright
11	* notice, this list of conditions and the following disclaimer.
12	*
13	* 2. Redistributions in binary form must reproduce the above copyright
14	* notice, this list of conditions and the following disclaimer in the
15	* documentation and/or other materials provided with the distribution.
16	*
17	* THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
18	* "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
19	* TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
20	* PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR
21	* CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
22	* EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
23	* PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS;
24	* OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
25	* WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
26	* OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF
27	* ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
28	*
29	* $Id: timer.h,v 1.2 2004/01/04 17:38:49 mbuna Exp $
30	*/
31	#ifndef INCLUDED_PEAK_TIMER_H_
32	#define INCLUDED_PEAK_TIMER_H_
33
34	/*!
35	* @defgroup timer Timer
36	*
37	* Lightweight timer/repeater support within a task. Units are floats in
38	* seconds with an internal precision up to usec, but subjects to client's
39	* event handlers so don't expect a lot.\n
40	* For best results, please use in conjunction with the Time module
41	* (\p peak_time*).
42	*/
43
44	/*!
45	* @ingroup timer
46	* @brief Opaque timer pointer type.
47	*/
48	typedef struct __peak_timer * peak_timer;
49
50	/*!
51	* @ingroup timer
52	* @brief Timer callback.
53	*/
54	typedef void (peak_timer_callback)(peak_timer t, void context);
55
56	#if defined(__cplusplus)
57	extern "C" {
58	#endif
59
60	/*!
61	* @ingroup timer
62	* @brief Create a timer.
63	*
64	* Note that the timer isn't activated until you add it to the task of your
65	* choice (usually peak_task_self()) with peak_task_timer_add().
66	*
67	* @param fire Relative fire time in second. 0 means immediate fire (as
68	* soon as possible, usually during the next event loop).
69	* A value of -1.0 means never fire, and can be useful to
70	* temporarily "disable" a timer.
71	* @param interval Repeat interval in second. Use -1.0 for a one-shot timer.
72	* Value must be strictly positive for repeating timer.
73	* @param callout A pointer to your timer callback function which is
74	* triggered when the timer fires.
75	* @param context An extra application-defined pointer that will be passed
76	* to your timer callback function (it's not used by the
77	* library).
78	*
79	* @return A newly allocated \p peak_timer reference or \p NULL if the
80	* timer cannot be created.
81	*/
82	extern peak_timer peak_timer_create(double fire,
83	double interval,
84	peak_timer_callback callout,
85	void *context);
86
87	/*!
88	* @ingroup timer
89	* @brief (Re)configure a timer.
90	*
91	* @param t The timer reference to configure.
92	* @param fire Relative fire time in second. 0 means immediate fire (as
93	* soon as possible, usually during the next event loop).
94	* A value of -1.0 means never fire, and can be useful to
95	* temporarily "disable" a timer.
96	* @param interval Repeat interval in second. Use -1.0 for a one-shot timer.
97	* Value must be strictly positive for repeating timer.
98	*/
99	extern void peak_timer_configure(peak_timer t, double fire, double interval);
100
101	/*!
102	* @ingroup timer
103	* @brief Get timer's fire date time.
104	*
105	* @param t The timer reference.
106	*
107	* @return Absolute time in second before the timer fires (if it
108	* is added to a task).
109	*/
110	extern double peak_timer_get_firetime(peak_timer t);
111
112	/*!
113	* @ingroup timer
114	* @brief Get timer's repeat-interval time.
115	*
116	* @param t The timer reference.
117	*
118	* @return Interval time in second.
119	*/
120	extern double peak_timer_get_interval(peak_timer t);
121
122	/*!
123	* @ingroup timer
124	* @brief Get timer's extra application-defined context.
125	*
126	* @param t The timer reference.
127	*
128	* @return Context pointer.
129	*/
130	extern void* peak_timer_get_context(peak_timer t);
131
132	/*!
133	* @ingroup timer
134	* @brief Change the context pointer of a timer.
135	*
136	* @param t The timer reference.
137	* @param context An extra application-defined pointer that will be passed
138	* to your timer callback function (it's not used by the
139	* library).
140	*/
141	extern void peak_timer_set_context(peak_timer t, void *context);
142
143
144	#if defined(__cplusplus)
145	}
146	#endif
147
148	#endif /* INCLUDED_PEAK_TIMER_H_ */