*** empty log message ***
[mmondor.git] / mmsoftware / mmlib / mmalarm.3
CommitLineData
d806e1a7
MM
1.\" $Id: mmalarm.3,v 1.1 2003/08/03 00:04:17 mmondor Exp $
2.\"
3.\" Copyright (C) 2003, Matthew Mondor
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:
16.\" This product includes software written by Matthew Mondor.
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
51.Fn timer_init "timerctx_t *ctx" "time_t now" "u_int32_t delay" \
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)"
76.Pp
77Initializes the specified timer context object
78.Fa ctx
79to be useable with the other functions.
80.Pp
81.Fa mallocfunc
82and
83.Fa freefunc
84specify the wanted
85.Xr malloc 3
86and
87.Xr free 3
88replacements to use to manage the necessary internal memory, and may be
89.Fn malloc
90and
91.Fn free ,
92respectively.
93.Pp
94.Fa timefunc
95allows to specify a custom replacement function to
96.Xr time 3 ,
97and can be
98.Fn time .
99.Pp
100.Fa alarmfunc
101permits to specify a custom replacement function to
102.Xr alarm 3 ,
103and can of course be
104.Fn alarm .
105.It void Fn timer_ctx_destroy "timerctx_t *ctx"
106.Pp
107Aborts and destroys any current timers pending into the specified
108.Fa ctx
109context, and invalidates the context, freeing any internal resources which it
110was using.
111.It timerid_t Fn timer_init "timerctx_t *ctx" "time_t now" "u_int32_t delay" \
112"void (*func)(timerid_t, void *)" "void *udata" "bool repeat"
113.Pp
114Creates and attaches a new timer to the specified
115.Fa ctx
116context.
117.Pp
118.Fa now
119permits to optimize operations passing the current time if it is known by the
120caller function. If 0 is specified,
121.Fn timer_init
122will automatically query the
123.Fa timefunc
124specified for that context to obtain the current time.
125.Pp
126.Fa delay
127specifies the number of seconds in which the timer will expire.
128.Pp
129.Fa func
130tells which function should be called when the timer expires. This function
131will be passed the timerid_t of the timer, which is guaranteed to be unique
132to that timer, and the supplied
133.Ar udata
134pointer, which can be used to share a global state or context with other
135timers or software. This
136.Fa udata
137pointer may be NULL if wanted. Note that this handler function should NOT
138call any other function of this library, which would cause recursion problems.
139It should instead trigger flags using variables or similar system for the
140indended software components to know that the timer has expired, and perform
141the appropriate actions, in the main state switcher loop for instance.
142.Pp
143.Fa repeat
144tells if the timer is contiguous, that is, automatically restarts when it
145expires and that
146.Fa func
147was called. If TRUE, the timer will automatically restart, but specifying FALSE will
148cause the timer to only expire once and automatically be destroyed after the
149handler function was called.
150.Pp
151Note that the returned timerid_t is guarenteed to be unique within the
152.Fa ctx
153context. This ID may safely be used to attempt to use
154.Fn timer_destroy
155anytime on this timer, even if it expired and was destroyed. 0 will be returned
156if there is an internal problem to create the timer (I.E. an out of memory
157condition).
158.It void Fn timer_destroy "timerctx_t *ctx" "time_t now" "timerid_t timer"
159.Pp
160Attempts to destroy the specified
161.Fa timer
162timer within the
163.Fa ctx
164context. If the timer was already destroyed, either using this function or
165as the result of expiration, nothing is done.
166.Pp
167.Fa now
168permits to optimize operations if the current time is known by the caller
169function. If 0 is specified,
170.Fn timer_destroy
171will obtain the time using the supplied
172.Fa timefunc
173for the context.
174.It void Fn timer_ctx_execute "timerctx_t *ctx" "time_t now"
175.Pp
176This function is internally called by the
177.Fn timer_init
178and
179.Fn timer_destroy
180functions. It also is expected to be called by the user application whenever
181a timer started with the specified
182.Fa alarmfunc
183expires.
184.Pp
185Typically, an application using
186.Xr alarm 3
187calls this function within the
188.Sy SIGALRM
189signal handler of the process, typically setup using 4.0BSD
190.Xr signal 3
191or POSIX
192.Xr sigaction 2 .
193.Pp
194All active timers of the supplied
195.Fa ctx
196are verified for expiration, and the handler function is called for each one
197which expires. The non-contiguous timers which expire are then destroyed.
198.Pp
199.Fa now
200can be used to optimize the execution if the current time is already known
201by the timer. If 0 is specified,
202.Fn timer_ctx_execute
203will automatically call the supplied
204.Fa timefunc
205for this context to obtain the current time.
206.Pp
207The handler functions for the expireing timers are expected to return quickly
208and to not call any functions of this library.
209.El
210.Sh RETURN VALUES
211.Bl -tag -width indent -offset indent
212.It Fn timer_ctx_init
213returns TRUE on success, or FALSE on internal resource allocation problems
214or invalid parameters.
215.It Fn timer_init
216returns a unique timer ID corresponding to the newly created timer for the
217context, or 0 on error (internal resource allocation problems or invalid
218parameters).
219.It Xo
220.Fn timer_ctx_destroy ,
221.Fn timer_destroy ,
222.Fn timer_ctx_execute
223.Xc
224return nothing.
225.El
226.Sh SEE ALSO
227.Xr malloc 3 ,
228.Xr free 3 ,
229.Xr time 3 ,
230.Xr alarm 3 ,
231.Xr signal 3 ,
232.Xr sigaction 2 .
233.Sh STANDARDS
234None
235.Sh HISTORY
236.Nm
237was primarily developped for use with the mmSNGId server project from
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
243Copyright (c) 2003, Matthew Mondor, All rights reserved.
244.Sh BUGS
245Please report any bug to mmondor@gobot.ca