mmlib/mmat: replace some variables by literal constants
[mmondor.git] / mmsoftware / mmlib / mmalarm.3
CommitLineData
b232bd02 1.\" $Id: mmalarm.3,v 1.7 2007/12/05 23:47:56 mmondor Exp $
d806e1a7 2.\"
d4aaa170 3.\" Copyright (C) 2003-2004, Matthew Mondor
d806e1a7
MM
4.\" 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.\" 1. Redistributions of source code must retain the above copyright
10.\" notice, this list of conditions and the following disclaimer.
11.\" 2. Redistributions in binary form must reproduce the above copyright
12.\" notice, this list of conditions and the following disclaimer in the
13.\" documentation and/or other materials provided with the distribution.
14.\" 3. All advertising materials mentioning features or use of this software
15.\" must display the following acknowledgement:
d4aaa170 16.\" This product includes software developed by Matthew Mondor.
d806e1a7
MM
17.\" 4. The name of Matthew Mondor may not be used to endorse or promote
18.\" products derived from this software without specific prior written
19.\" permission.
20.\" 5. Redistribution of source code may not be released under the terms of
21.\" any GNU Public License derivate.
22.\"
23.\" THIS SOFTWARE IS PROVIDED BY MATTHEW MONDOR ``AS IS'' AND ANY EXPRESS OR
24.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
25.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
26.\" IN NO EVENT SHALL MATTHEW MONDOR BE LIABLE FOR ANY DIRECT, INDIRECT,
27.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING,
28.\" BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF
29.\" USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
30.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
31.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
32.\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
33.\"
34.Dd August 2, 2003
35.Dt MMALARM 3
36.Os mmsoftware
37.Sh NAME
38.Nm mmalarm
39.Nd General purpose second-resolution timer events support
40.Sh SYNOPSIS
41.Fd #include <sys/types.h>
42.Fd #include <mmtypes.h>
43.Fd #include <mmalarm.h>
44.Ft bool
45.Fn timer_ctx_init "timerctx_t *ctx" "void *(*mallocfunc)(size_t)" \
46"void (*freefunc)(void *)" "time_t (*timefunc)(time_t *)" \
47"unsigned int (*alarmfunc)(unsigned int)"
48.Ft void
49.Fn timer_ctx_destroy "timerctx_t *ctx"
50.Ft timerid_t
b232bd02 51.Fn timer_init "timerctx_t *ctx" "time_t now" "uint32_t delay" \
d806e1a7
MM
52"void (*func)(timerid_t, void *)" "void *udata" "bool repeat"
53.Ft void
54.Fn timer_destroy "timerctx_t *ctx" "time_t now" "timerid_t timer"
55.Ft void
56.Fn timer_ctx_execute "timerctx_t *ctx" "timer_t now"
57.Sh DESCRIPTION
58The
59.Nm
60library provides a useful set of functions to easily implement simultaneous
61second-resolution timers. There can be multiple sets, each corresponding to
62an independant context, if wanted. Each timer can be in one-time or contiguous
63mode, and will trigger the execution of a function when it expires, being
64automatically restarted if in contiguous mode. This systems basically consists
65of a multiplexer around a single alarm timer. For instance, one may use
66.Xr alarm 3
67with a simple
68.Sy SIGALRM
69handler, and implement multiple timers around that system using this library.
70.Pp
71.Ss FUNCTIONS
72.Bl -tag -width indent -offset indent
73.It bool Fn timer_ctx_init "timerctx_t *ctx" "void *(*mallocfunc)(size_t)" \
74"void (*freefunc)(void *)" "time_t (*timefunc)(time_t *)" \
75"unsigned int (*alarmfunc)(unsigned int)"
d806e1a7
MM
76Initializes the specified timer context object
77.Fa ctx
78to be useable with the other functions.
79.Pp
80.Fa mallocfunc
81and
82.Fa freefunc
83specify the wanted
84.Xr malloc 3
85and
86.Xr free 3
87replacements to use to manage the necessary internal memory, and may be
88.Fn malloc
89and
90.Fn free ,
91respectively.
92.Pp
93.Fa timefunc
94allows to specify a custom replacement function to
95.Xr time 3 ,
96and can be
97.Fn time .
98.Pp
99.Fa alarmfunc
100permits to specify a custom replacement function to
101.Xr alarm 3 ,
102and can of course be
103.Fn alarm .
104.It void Fn timer_ctx_destroy "timerctx_t *ctx"
d806e1a7
MM
105Aborts and destroys any current timers pending into the specified
106.Fa ctx
107context, and invalidates the context, freeing any internal resources which it
108was using.
b232bd02 109.It timerid_t Fn timer_init "timerctx_t *ctx" "time_t now" "uint32_t delay" \
d806e1a7 110"void (*func)(timerid_t, void *)" "void *udata" "bool repeat"
d806e1a7
MM
111Creates and attaches a new timer to the specified
112.Fa ctx
113context.
114.Pp
115.Fa now
116permits to optimize operations passing the current time if it is known by the
117caller function. If 0 is specified,
118.Fn timer_init
119will automatically query the
120.Fa timefunc
121specified for that context to obtain the current time.
122.Pp
123.Fa delay
124specifies the number of seconds in which the timer will expire.
125.Pp
126.Fa func
127tells which function should be called when the timer expires. This function
128will be passed the timerid_t of the timer, which is guaranteed to be unique
129to that timer, and the supplied
130.Ar udata
131pointer, which can be used to share a global state or context with other
132timers or software. This
133.Fa udata
134pointer may be NULL if wanted. Note that this handler function should NOT
135call any other function of this library, which would cause recursion problems.
136It should instead trigger flags using variables or similar system for the
137indended software components to know that the timer has expired, and perform
138the appropriate actions, in the main state switcher loop for instance.
139.Pp
140.Fa repeat
141tells if the timer is contiguous, that is, automatically restarts when it
142expires and that
143.Fa func
144was called. If TRUE, the timer will automatically restart, but specifying FALSE will
145cause the timer to only expire once and automatically be destroyed after the
146handler function was called.
147.Pp
148Note that the returned timerid_t is guarenteed to be unique within the
149.Fa ctx
150context. This ID may safely be used to attempt to use
151.Fn timer_destroy
152anytime on this timer, even if it expired and was destroyed. 0 will be returned
153if there is an internal problem to create the timer (I.E. an out of memory
154condition).
155.It void Fn timer_destroy "timerctx_t *ctx" "time_t now" "timerid_t timer"
d806e1a7
MM
156Attempts to destroy the specified
157.Fa timer
158timer within the
159.Fa ctx
160context. If the timer was already destroyed, either using this function or
161as the result of expiration, nothing is done.
162.Pp
163.Fa now
164permits to optimize operations if the current time is known by the caller
165function. If 0 is specified,
166.Fn timer_destroy
167will obtain the time using the supplied
168.Fa timefunc
169for the context.
170.It void Fn timer_ctx_execute "timerctx_t *ctx" "time_t now"
d806e1a7
MM
171This function is internally called by the
172.Fn timer_init
173and
174.Fn timer_destroy
175functions. It also is expected to be called by the user application whenever
176a timer started with the specified
177.Fa alarmfunc
178expires.
179.Pp
180Typically, an application using
181.Xr alarm 3
182calls this function within the
183.Sy SIGALRM
184signal handler of the process, typically setup using 4.0BSD
185.Xr signal 3
186or POSIX
187.Xr sigaction 2 .
188.Pp
189All active timers of the supplied
190.Fa ctx
191are verified for expiration, and the handler function is called for each one
192which expires. The non-contiguous timers which expire are then destroyed.
06553665
MM
193The
194.Fa alarmfunc
195for this context is then executed with a delay corresponding to the time of
196the next (soonest) to expire timer.
d806e1a7
MM
197.Pp
198.Fa now
199can be used to optimize the execution if the current time is already known
200by the timer. If 0 is specified,
201.Fn timer_ctx_execute
202will automatically call the supplied
203.Fa timefunc
204for this context to obtain the current time.
205.Pp
206The handler functions for the expireing timers are expected to return quickly
207and to not call any functions of this library.
208.El
209.Sh RETURN VALUES
210.Bl -tag -width indent -offset indent
211.It Fn timer_ctx_init
212returns TRUE on success, or FALSE on internal resource allocation problems
213or invalid parameters.
214.It Fn timer_init
215returns a unique timer ID corresponding to the newly created timer for the
216context, or 0 on error (internal resource allocation problems or invalid
217parameters).
218.It Xo
219.Fn timer_ctx_destroy ,
220.Fn timer_destroy ,
221.Fn timer_ctx_execute
222.Xc
223return nothing.
224.El
225.Sh SEE ALSO
226.Xr malloc 3 ,
227.Xr free 3 ,
228.Xr time 3 ,
229.Xr alarm 3 ,
230.Xr signal 3 ,
d4b75004
MM
231.Xr sigaction 2 ,
232.Xr signal 7 .
d806e1a7
MM
233.Sh STANDARDS
234None
235.Sh HISTORY
236.Nm
2f9ea7dc 237was primarily developped for use with the PSFDEPd server project from
d806e1a7
MM
238Matthew Mondor, which is closed source, but the library has been exported
239publically.
240.Sh AUTHORS
241.Nm
242was written by Matthew Mondor and is
93447690 243Copyright (c) 2003-2004, Matthew Mondor, All rights reserved.
d806e1a7 244.Sh BUGS
93447690 245Please report any bug to mmondor@accela.net