mmlib/mmat: replace some variables by literal constants
[mmondor.git] / mmsoftware / mmlib / mmlimitrate.3
1 .\" $Id: mmlimitrate.3,v 1.4 2004/05/05 23:59:56 mmondor Exp $
2 .\"
3 .\" Copyright (C) 2001-2004, 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 developed 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 October 19, 2003
35 .Dt MMLIMITRATE 3
36 .Os mmsoftware
37 .Sh NAME
38 .Nm mmlimitrate
39 .Nd Useful library for rate limiting in various situations
40 .Sh SYNOPSIS
41 .Fd #include <sys/types.h>
42 .Fd #include <mmtypes.h>
43 .Fd #include <mmlimitrate.h>
44 .Ft void
45 .Fn LR_INIT "struct limitrate *lr" "long max" "time_t secs" "time_t now"
46 .Ft void
47 .Fn LR_EXPIRE "struct limitrate *lr" "time_t now"
48 .Ft time_t
49 .Fn LR_REMAINS "struct limitrate *lr" "time_t now"
50 .Ft long
51 .Fn LR_POSTS "struct limitrate *lr"
52 .Ft long
53 .Fn LR_MAXPOSTS "struct limitrate *lr"
54 .Ft time_t
55 .Fn LR_PERIOD "struct limitrate *lr"
56 .Ft bool
57 .Fn lr_allow "struct limitrate *lr" "long many" "time_t now" "bool expire"
58 .Sh DESCRIPTION
59 .Nm
60 was written to get rid of code duplication which started to occur in the
61 various mmsoftware daemons which usually need various forms of rate limiting.
62 Most of the system was implemented as macros for speed.
63 .Ss FUNCTIONS
64 .Bl -tag -width indent -offset indent
65 .It void Fn LR_INIT "struct limitrate *lr" "long max" "time_t secs"\
66  "time_t now"
67 Permits to initialize the
68 .Fa lr
69 element of type
70 .Dv struct limitrate ,
71 to allow a maximum of
72 .Fa max
73 posts per period of
74 .Fa secs
75 seconds.
76 The
77 .Fn lr_allow
78 function will then be used for posting.
79 .Fa now
80 provides the current time as obtained from the
81 .Xr time 3
82 function.
83 .It void Fn LR_EXPIRE "struct limitrate *lr" "time_t now"
84 Verifies if the period for the specified
85 .Fa lr
86 expired, and if so, resets it's number of posts to zero and restarts the
87 period.
88 .Fa now
89 provides the current time as obtained from
90 .Xr time 3 .
91 .It void Fn LR_REMAINS "struct limitrate *lr" "time_t now"
92 Returns the remaining number of seconds for the period of
93 .Fa lr
94 to expire, or 0 if expiration already occurred.
95 .Fa now
96 provides the current time as returned by
97 .Xr time 3 .
98 .It long Fn LR_POSTS "struct limitrate *lr"
99 Returns the current number of posts which occurred on
100 .Fa lr
101 within the current period (which may or may not have expired, but was not
102 reset yet). Extraneous posts which were still refused by
103 .Fn lr_allow
104 are included.
105 .It long Fn LR_MAXPOSTS "struct limitrate *lr"
106 Returns the maximum allowed number of posts which can occur within a second
107 for the specified
108 .Fa lr ,
109 as initialized in
110 .Fn LR_INIT .
111 .It time_t Fn LR_PERIOD "struct limitrate *lr"
112 Returns the length of a period for
113 .Fa lr 
114 in seconds, as initialized in
115 .Fn LR_INIT .
116 .It bool Fn lr_allow "struct limitrate *lr" "long many" "time_t now"\
117  "bool expire"
118 This function registers the specified number of posts
119 .Fa ( many )
120 in the specified
121 .Fa lr
122 within the current period for that structure.
123 TRUE is returned on success (the posts were allowed), or FALSE if the maximum
124 allowed number of posts within a period is exceeded. Note that unless this
125 period is specifically reset, subsequent requests will also be refused with
126 FALSE in this case.
127 Note that the
128 .Fa now
129 parameter is ignored if
130 .Fa expire
131 is FALSE. Otherwise,
132 .Fa now
133 specifies the current time as returned by
134 .Xr time 3 .
135 .Fa expire
136 tells
137 .Fn lr_allow
138 to automatically reset the entry if it's period expired, that is, calling
139 .Fn LR_EXPIRE
140 internally.
141 .El
142 .Sh RETURN VALUES
143 .Bl -tag -width indent -offset indent
144 .It Xo
145 .Fn LR_INIT ,
146 .Fn LR_EXPIRE
147 .Xc
148 return nothing.
149 .It Xo
150 .Fn LR_REMAINS ,
151 .Fn LR_PERIOD
152 .Xc
153 return a number of seconds in the form of a
154 .Dv time_t .
155 .It Xo
156 .Fn LR_POSTS ,
157 .Fn LR_MAXPOSTS
158 .Xc
159 return a positive integer or 0.
160 .It Fn lr_allow
161 returns a boolean
162 .Dv TRUE
163 or
164 .Dv FALSE .
165 .El
166 .Sh SEE ALSO
167 .Xr time 3
168 .Sh STANDARDS
169 None
170 .Sh HISTORY
171 .Xr mmlimitrate 3
172 was written for the mmsoftware project in October 2003
173 .Sh AUTHORS
174 The
175 .Nm
176 library was written by Matthew Mondor and is Copyright (c) 2001-2004,
177 Matthew Mondor, All rights reserved.
178 .Sh BUGS
179 Please report any bug to mmondor@accela.net