Initial CVS repository import (last CVS history was lost)
[mmondor.git] / mmsoftware / mmlib / mmfifo.3
CommitLineData
47071c2b
MM
1.\" $Id: mmfifo.3,v 1.1 2002/12/11 10:12:54 mmondor Exp $
2.Dd April 16, 2002
3.Os
4.Dt MMFIFO 3
5.Sh NAME
6.Nm mmfifo
7.Nd General purpose portable FIFO buffers library.
8.Sh SYNOPSIS
9.Fd #include <sys/types.h>
10.Fd #include <mmtypes.h>
11.Fd #include <mmfifo.h>
12.Ft fifo8 *
13.Fn openfifo8 "void * (*malloc)(size_t)" "void (*free)(void *)" \
14"size_t elements"
15.Ft fifo8 *
16.Fn closefifo8 "fifo8 *fifo"
17.Ft size_t
18.Fn statfifo8 "fifo8 *fifo"
19.Ft void
20.Fn flushfifo8 "fifo8 *fifo"
21.Ft bool
22.Fn getfifo8 "uint8 *data" "fifo8 *fifo"
23.Ft bool
24.Fn putfifo8 "fifo8 *fifo" "uint8 data"
25.Ft size_t
26.Fn getnfifo8 "uint8 *buffer" "fifo8 *fifo" "size_t max"
27.Ft size_t
28.Fn putnfifo8 "fifo8 *fifo" "uint8 *buffer" "size_t size"
29.Ft fifo32 *
30.Fn openfifo32 "void * (*malloc)(size_t)" "void (*free)(void *)" \
31"size_t elements"
32.Ft fifo32 *
33.Fn closefifo32 "fifo32 *fifo"
34.Ft size_t
35.Fn statfifo32 "fifo32 *fifo"
36.Ft void
37.Fn flushfifo32 "fifo32 *fifo"
38.Ft bool
39.Fn getfifo32 "u_int32_t *data" "fifo32 *fifo"
40.Ft bool
41.Fn putfifo32 "fifo32 *fifo" "u_int32_t data"
42.Ft fifo64 *
43.Fn openfifo64 "void * (*malloc)(size_t)" "void (*free)(void *)" \
44"size_t elements"
45.Ft fifo64 *
46.Fn closefifo64 "fifo64 *fifo"
47.Ft size_t
48.Fn statfifo64 "fifo64 *fifo"
49.Ft void
50.Fn flushfifo64 "fifo64 *fifo"
51.Ft bool
52.Fn getfifo64 "u_int64_t *data" "fifo64 *fifo"
53.Ft bool
54.Fn putfifo64 "fifo64 *fifo" "u_int64_t data"
55.Sh DESCRIPTION
56FIFO buffers (First In First Out) are usually especially useful when
57implementing asynchronous systems. For instance in the implementation of
58serial RS-232 read/write functions, a trap or interrupt occurs when a byte
59is available to read or when the device is ready to be written more data to.
60The user API has to be able to be used at anytime however so that the
61application may read and write bytes at any time (in fact queueing them for
62the trap handler). So two FIFO buffers are required, user API and the trap
63handler each share one side of each queue. Unlike a simple buffer, each side
64do not know when the other side will insert or unqueue elements at the other
65end. It therefore is extremely useful to synchronize two asynchonous
66applications.
67.Pp
68The
69.Fn openfifo8 ,
70.Fn openfifo32
71and
72.Fn openfifo64
73functions create a FIFO buffer that can hold at maximum
74.Fa max
75elements. 8, 32 and 64 refer to the number of bits of each element. Obviously
76for byte storage
77.Fa fifo8
78would be used while
79.Fa fifo32
80may be useful for holding 32-bit elements.
81.Fa malloc
82and
83.Fa free
84allow the caller to supply custom memory allocation/free routines. Those should
85still be passed if standard
86.Fn malloc
87and
88.Fn free
89functions are wanted.
90.Pp
91.Fn closefifo8 ,
92.Fn closefifo32
93and
94.Fn closefifo64
95functions release all resources allocated by
96.Fn openfifo8 ,
97.Fn openfifo32
98and
99.Fn openfifo64 ,
100respectively, for the specified
101.Fa fifo8 * ,
102.Fa fifo32 *
103or
104.Fa fifo64 *
105buffer.
106.Pp
107The functions
108.Fn statfifo8 ,
109.Fn statfifo32
110and
111.Fn statfifo64
112allow to know how many elements are currently queued in the specified FIFO
113buffer.
114.Pp
115.Fn flushfifo8 ,
116.Fn flushfifo32
117and
118.Fn flushfifo64
119flush or order to forget any currently queued elements stored in the specified
120FIFO buffer, if any.
121.Pp
122.Fn getfifo8 ,
123.Fn getfifo32
124and
125.Fn getfifo64
126functions attempt to extract a single element from
127.Fa fifo
128buffer, if any. The element will be stored where
129.Fa data
130pointer points. Obviously the returned element will be the older one in the
131queue.
132.Pp
133.Fn putfifo8 ,
134.Fn putfifo32
135and
136.Fn putfifo64
137attempt to queue specified element
138.Fa data
139to the specified
140.Fa fifo.
141.Pp
142The
143.Fn getnfifo8
144and
145.Fn putnfifo8
146functions are variants of
147.Fn getfifo8
148and
149.Fn putfifo8
150which can process multiple elements (bytes in this case) at once. They are
151more efficient than looping while inserting or extracting single elements
152from the queue.
153.Fa buffer
154points to the location where data should be read from or written to.
155.Fa max
156parameter to
157.Fn getnfifo8
158specifies the size of the supplied read buffer to prevent overflowing it.
159The
160.Fa size
161argument to
162.Fn putnfifo8
163instructs the function about how many elements (bytes) should be queued.
164.Sh RETURN VALUES
165.Fn openfifo8 ,
166.Fn openfifo32
167and
168.Fn openfifo64
169return a
170.Fa fifo8 * ,
171.Fa fifo32 *
172or
173.Fa fifo64 * ,
174respectively, or NULL pointer on error (out of memory).
175.Pp
176.Fn closefifo8 ,
177.Fn closefifo32
178and
179.Fn closefifo64
180return NULL pointer.
181.Pp
182.Fn statfifo8 ,
183.Fn statfifo32
184and
185.Fn statfifo64
186return the number of queued elements that can be extracted from specified
187.Fa fifo
188buffer.
189.Pp
190.Fn getfifo8 ,
191.Fn getfifo32 ,
192.Fn getfifo64 ,
193.Fn putfifo8 ,
194.Fn putfifo32
195and
196.Fn putfifo64
197return TRUE if an element could be inserted or extracted, or FALSE if the
198buffer is empty or full.
199.Pp
200.Fn getnfifo8
201and
202.Fn putnfifo8
203return the number of elements (bytes) that could be extracted or inserted.
204Zero will be returned if nothing could be done.
205.Sh SEE ALSO
206.Xr malloc 3 ,
207.Xr free 3
208.Sh STANDARDS
209None
210.Sh HISTORY
211mmfifo was originally developped on NetBSD 1.5 for the Xisop portable kernel
212project from Matthew Mondor.
213.Sh AUTHORS
214The mmfifo library was written by Matthew Mondor and is
215Copyright 2001-2002 Matthew Mondor, All rights reserved.
216.Sh BUGS
217These would be faster implemented as macros.
218.Pp
219Please report any bug to mmondor@gobot.ca