forked from Telodendria/Telodendria
Write documentation for Queue
This commit is contained in:
parent
79fc20314f
commit
0419bc3707
3 changed files with 104 additions and 1 deletions
4
TODO.txt
4
TODO.txt
|
@ -105,6 +105,8 @@ Documentation
|
|||
[x] Base64
|
||||
[ ] CanonicalJson
|
||||
[ ] Config
|
||||
[ ] API (Config.3)
|
||||
[ ] File format (Config.5)
|
||||
[ ] Constants
|
||||
[ ] HashMap
|
||||
[ ] Http
|
||||
|
@ -113,7 +115,7 @@ Documentation
|
|||
[ ] Log
|
||||
[ ] Matrix
|
||||
[ ] NonPosix
|
||||
[ ] Queue
|
||||
[x] Queue
|
||||
[ ] Routes
|
||||
[ ] TelodendriaConfig
|
||||
[ ] Util
|
||||
|
|
100
man/man3/Queue.3
Normal file
100
man/man3/Queue.3
Normal file
|
@ -0,0 +1,100 @@
|
|||
.Dd $Mdocdate: October 10 2022 $
|
||||
.Dt QUEUE 3
|
||||
.Os Telodendria Project
|
||||
.Sh NAME
|
||||
.Nm Array
|
||||
.Nd A simple static queue data structure.
|
||||
.Sh SYNOPSIS
|
||||
.In Queue.h
|
||||
.Ft Queue *
|
||||
.Fn QueueCreate "void"
|
||||
.Ft void
|
||||
.Fn QueueFree "Array *"
|
||||
.Ft int
|
||||
.Fn QueuePush "Queue *" "void *"
|
||||
.Ft void *
|
||||
.Fn QueuePop "Queue *"
|
||||
.Ft void *
|
||||
.Fn QueuePeek "Queue *"
|
||||
.Ft int
|
||||
.Fn QueueFull "Queue *"
|
||||
.Ft int
|
||||
.Fn QueueEmpty "Queue *"
|
||||
.Sh DESCRIPTION
|
||||
These functions implement a simple queue data structure that
|
||||
is statically sized.
|
||||
This implementation does not actually store the values of the
|
||||
items in it; it only stores pointers to the data. As such, you will
|
||||
still have to manually maintain all your data. The advantage of this
|
||||
is that these functions don't have to copy data, and thus don't care
|
||||
how big the data is. Furthermore, arbitrary data can be stored in the
|
||||
queue.
|
||||
.Pp
|
||||
This queue implementation operates on the heap. It is a circular
|
||||
queue, and it does not grow as it is used. Once the size is set, the
|
||||
queue never gets any bigger.
|
||||
.Pp
|
||||
These functions operate on a queue structure which is opaque to the
|
||||
caller.
|
||||
.Pp
|
||||
.Fn QueueCreate
|
||||
and
|
||||
.Fn QueueFree
|
||||
allocate and deallocate a queue, respectively.
|
||||
Note that
|
||||
.Fn QueueFree
|
||||
does not free any of the values stored in the queue; it is the caller's
|
||||
job to manage the memory for each item. Typically, the caller would
|
||||
dequeue all the items in the queue and free them before freeing
|
||||
the queue itself.
|
||||
.Pp
|
||||
.Fn QueuePush
|
||||
and
|
||||
.Fn QueuePop
|
||||
are the main functions used to modify the array. They enqueue and dequeue
|
||||
elements from the queue structure, respectively.
|
||||
.Pp
|
||||
.Fn QueuePeek
|
||||
simply returns the pointer that is next up in the queue without actually
|
||||
discarding it, such that the next call to
|
||||
.Fn QueuePeek
|
||||
or
|
||||
.Fn QueuePop
|
||||
return the same pointer.
|
||||
.Pp
|
||||
.Fn QueueFull
|
||||
and
|
||||
.Fn QueueEmpty
|
||||
return a boolean value that indicates whether or not the queue is full
|
||||
or empty, respectively.
|
||||
.Sh RETURN VALUES
|
||||
.Pp
|
||||
.Fn QueueCreate
|
||||
returns a queue structure, or
|
||||
.Dv NULL
|
||||
if there was a memory allocation error.
|
||||
.Pp
|
||||
.Fn QueuePush
|
||||
as well as
|
||||
.Fn QueueFull
|
||||
and
|
||||
.Fn QueueEmpty
|
||||
all return boolean values. In the case of
|
||||
.Fn QueuePush
|
||||
whether or not the push was actually successful is returned. This will
|
||||
only happen if the queue is already full, or a
|
||||
.Dv NULL
|
||||
pointer is passed.
|
||||
.Pp
|
||||
.Fn QueuePop
|
||||
and
|
||||
.Fn QueuePeek
|
||||
both return caller-managed pointers that would have been at some point
|
||||
pushed into the queue with the
|
||||
.Fn QueuePush
|
||||
function. They may also return
|
||||
.Dv NULL
|
||||
if the queue is empty.
|
||||
.Sh SEE ALSO
|
||||
.Xr Array 3 ,
|
||||
.Xr HashMap 3
|
|
@ -62,6 +62,7 @@ Developer documentation:
|
|||
<ul>
|
||||
<li><a href="/man/man3/Array.3.html">Array(3)</a> - Dynamic array structure</li>
|
||||
<li><a href="/man/man3/Base64.3.html">Base64(3)</a> - Base64 encoder/decoder with unpadded support</li>
|
||||
<li><a href="/man/man3/Queue.3.html">Queue(3)</a> - Basic circular queue implementation</li>
|
||||
</ul>
|
||||
<h2 id="download">Download</h2>
|
||||
<p>
|
||||
|
|
Loading…
Reference in a new issue