From 3d188aa5537424eced6eb6d4812b44ae4dd71c94 Mon Sep 17 00:00:00 2001 From: Samy Al Bahra Date: Fri, 18 Oct 2013 15:59:08 -0400 Subject: [PATCH] doc: Remaining ck_array manual pages and additional fixes. --- doc/CK_ARRAY_FOREACH | 79 ++++++++++++++++++++++++++++++++++++++++ doc/Makefile.in | 8 +++- doc/ck_array_buffer | 60 ++++++++++++++++++++++++++++++ doc/ck_array_deinit | 62 +++++++++++++++++++++++++++++++ doc/ck_array_initialized | 62 +++++++++++++++++++++++++++++++ doc/ck_array_length | 57 +++++++++++++++++++++++++++++ doc/ck_array_put_unique | 4 +- doc/ck_array_remove | 2 +- 8 files changed, 330 insertions(+), 4 deletions(-) create mode 100644 doc/CK_ARRAY_FOREACH create mode 100644 doc/ck_array_buffer create mode 100644 doc/ck_array_deinit create mode 100644 doc/ck_array_initialized create mode 100644 doc/ck_array_length diff --git a/doc/CK_ARRAY_FOREACH b/doc/CK_ARRAY_FOREACH new file mode 100644 index 0000000..d85b767 --- /dev/null +++ b/doc/CK_ARRAY_FOREACH @@ -0,0 +1,79 @@ +.\" +.\" Copyright 2013 Samy Al Bahra. +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" +.Dd October 18, 2013 +.Dt CK_ARRAY_FOREACH 3 +.Sh NAME +.Nm CK_ARRAY_FOREACH +.Nd iterate through an array +.Sh LIBRARY +Concurrency Kit (libck, \-lck) +.Sh SYNOPSIS +.In ck_array.h +.Ft bool +.Fn CK_ARRAY_FOREACH "ck_array_t *array" "ck_array_iterator_t *iterator" "void **b" +.Sh DESCRIPTION +The +.Fn CK_ARRAY_FOREACH 3 +macro iterates through the array pointed to by +.Fa array . +A pointer to an iterator object must be specified by +.Fa iterator +and +.Fa b +must point to a void pointer. +.Sh EXAMPLE +.Bd -literal -offset indent +#include + +/* Assume this was already previously initialized. */ +ck_array_t array; + +void +example(void) +{ + ck_array_iterator_t iterator; + void *pointer; + + CK_ARRAY_FOREACH(&array, &iterator, &pointer) { + do_something(pointer); + } +} +.Ed +.Sh RETURN VALUES +This macro has no return value. +.Sh SEE ALSO +.Xr ck_array_init 3 , +.Xr ck_array_commit 3 , +.Xr ck_array_put 3 , +.Xr ck_array_put_unique 3 , +.Xr ck_array_remove 3 , +.Xr ck_array_deinit 3 +.Xr ck_array_length 3 , +.Xr ck_array_buffer 3 , +.Xr ck_array_initialized 3 +.Pp +Additional information available at http://concurrencykit.org/ diff --git a/doc/Makefile.in b/doc/Makefile.in index 57bea1a..e01536b 100644 --- a/doc/Makefile.in +++ b/doc/Makefile.in @@ -7,11 +7,17 @@ BUILD_DIR=@BUILD_DIR@ SRC_DIR=@SRC_DIR@ HTML_SUFFIX=.html -OBJECTS=ck_array_commit \ +OBJECTS=CK_ARRAY_FOREACH \ + ck_array_buffer \ + ck_array_commit \ + ck_array_deinit \ ck_array_init \ + ck_array_initialized \ + ck_array_length \ ck_array_put \ ck_array_put_unique \ ck_array_remove \ + ck_array_deinit \ ck_brlock \ ck_ht_count \ ck_ht_destroy \ diff --git a/doc/ck_array_buffer b/doc/ck_array_buffer new file mode 100644 index 0000000..7a8ded3 --- /dev/null +++ b/doc/ck_array_buffer @@ -0,0 +1,60 @@ +.\" +.\" Copyright 2012-2013 Samy Al Bahra. +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" +.Dd October 18, 2013 +.Dt CK_ARRAY_BUFFER 3 +.Sh NAME +.Nm ck_array_buffer +.Nd return length and pointer to array of reader-visible pointers +.Sh LIBRARY +Concurrency Kit (libck, \-lck) +.Sh SYNOPSIS +.In ck_array.h +.Ft void * +.Fn ck_array_buffer "ck_array_t *array" "unsigned int *length" +.Sh DESCRIPTION +The +.Fn ck_array_buffer 3 +returns a pointer to the array of pointers currently visible +to readers after the last commit operation in +.Fa array . +The unsigned integer pointed to by +.Fa length +is updated to reflect the length of the array. +.Sh RETURN VALUES +This function returns a pointer to an array of pointers. +.Sh SEE ALSO +.Xr ck_array_commit 3 , +.Xr ck_array_put 3 , +.Xr ck_array_put_unique 3 , +.Xr ck_array_remove 3 , +.Xr ck_array_init 3 +.Xr ck_array_deinit 3 , +.Xr ck_array_length 3 , +.Xr ck_array_initialized 3 , +.Xr CK_ARRAY_FOREACH 3 +.Pp +Additional information available at http://concurrencykit.org/ diff --git a/doc/ck_array_deinit b/doc/ck_array_deinit new file mode 100644 index 0000000..3a5e5ab --- /dev/null +++ b/doc/ck_array_deinit @@ -0,0 +1,62 @@ +.\" +.\" Copyright 2012-2013 Samy Al Bahra. +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" +.Dd October 18, 2013 +.Dt CK_ARRAY_DEINIT 3 +.Sh NAME +.Nm ck_array_deinit +.Nd destroy and deinitialize a pointer array +.Sh LIBRARY +Concurrency Kit (libck, \-lck) +.Sh SYNOPSIS +.In ck_array.h +.Ft void +.Fn ck_array_deinit "ck_array_t *array" "bool defer" +.Sh DESCRIPTION +The +.Fn ck_array_deinit 3 +destroys the memory associated with the array pointed +to by +.Fa array . +The +.Fa defer +argument is true if the allocator must destroy +the memory using safe memory reclamation or false +if the allocator can destroy this memory immediately. +.Sh RETURN VALUES +This function has no return value. +.Sh SEE ALSO +.Xr ck_array_commit 3 , +.Xr ck_array_put 3 , +.Xr ck_array_put_unique 3 , +.Xr ck_array_remove 3 , +.Xr ck_array_init 3 +.Xr ck_array_length 3 , +.Xr ck_array_buffer 3 , +.Xr ck_array_initialized 3 , +.Xr CK_ARRAY_FOREACH 3 +.Pp +Additional information available at http://concurrencykit.org/ diff --git a/doc/ck_array_initialized b/doc/ck_array_initialized new file mode 100644 index 0000000..3a06413 --- /dev/null +++ b/doc/ck_array_initialized @@ -0,0 +1,62 @@ +.\" +.\" Copyright 2012-2013 Samy Al Bahra. +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" +.Dd October 18, 2013 +.Dt CK_ARRAY_INITIALIZED 3 +.Sh NAME +.Nm ck_array_initialized +.Nd indicates whether an array was recently initialized or deinitialized +.Sh LIBRARY +Concurrency Kit (libck, \-lck) +.Sh SYNOPSIS +.In ck_array.h +.Ft bool +.Fn ck_array_initialized "ck_array_t *array" +.Sh DESCRIPTION +The +.Fn ck_array_initialized 3 +can be used to determine whether an array was recently initialized +with +.Fn ck_array_init 3 +or deinitialized with +.Fn ck_array_deinit 3 . +Behavior is undefined if a user allocates internal allocator data +in through other means. +.Sh RETURN VALUES +This function returns true if the array is initialized, and false +otherwise. +.Sh SEE ALSO +.Xr ck_array_commit 3 , +.Xr ck_array_put 3 , +.Xr ck_array_put_unique 3 , +.Xr ck_array_remove 3 , +.Xr ck_array_init 3 +.Xr ck_array_deinit 3 , +.Xr ck_array_length 3 , +.Xr ck_array_buffer 3 , +.Xr CK_ARRAY_FOREACH 3 +.Pp +Additional information available at http://concurrencykit.org/ diff --git a/doc/ck_array_length b/doc/ck_array_length new file mode 100644 index 0000000..e60c6c3 --- /dev/null +++ b/doc/ck_array_length @@ -0,0 +1,57 @@ +.\" +.\" Copyright 2012-2013 Samy Al Bahra. +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" +.Dd October 18, 2013 +.Dt CK_ARRAY_LENGTH 3 +.Sh NAME +.Nm ck_array_length +.Nd returns the number of pointers committed to an array +.Sh LIBRARY +Concurrency Kit (libck, \-lck) +.Sh SYNOPSIS +.In ck_array.h +.Ft unsigned int +.Fn ck_array_length "ck_array_t *array" +.Sh DESCRIPTION +The +.Fn ck_array_length 3 +function returns the number of items a concurrent +traversal operation would encounter at completion +time. +.Sh RETURN VALUES +The number of traversal-visible pointers is returned. +.Sh SEE ALSO +.Xr ck_array_commit 3 , +.Xr ck_array_put 3 , +.Xr ck_array_put_unique 3 , +.Xr ck_array_remove 3 , +.Xr ck_array_init 3 +.Xr ck_array_deinit 3 , +.Xr ck_array_buffer 3 , +.Xr ck_array_initialized 3 , +.Xr CK_ARRAY_FOREACH 3 +.Pp +Additional information available at http://concurrencykit.org/ diff --git a/doc/ck_array_put_unique b/doc/ck_array_put_unique index bc5775b..bb355fe 100644 --- a/doc/ck_array_put_unique +++ b/doc/ck_array_put_unique @@ -25,10 +25,10 @@ .\" .\" .Dd October 18, 2013 -.Dt CK_ARRAY_PUT 3 +.Dt CK_ARRAY_PUT_UNIQUE 3 .Sh NAME .Nm ck_array_put_unique -.Nd attempt immediate or deferred insertion of a pointer into array +.Nd attempt immediate or deferred insertion of a unique pointer into array .Sh LIBRARY Concurrency Kit (libck, \-lck) .Sh SYNOPSIS diff --git a/doc/ck_array_remove b/doc/ck_array_remove index 60f6d62..8df454d 100644 --- a/doc/ck_array_remove +++ b/doc/ck_array_remove @@ -28,7 +28,7 @@ .Dt CK_ARRAY_REMOVE 3 .Sh NAME .Nm ck_array_remove -.Nd attempt immediate or deferred insertion of a pointer into array +.Nd attempt immediate or deferred removal of a pointer from an array .Sh LIBRARY Concurrency Kit (libck, \-lck) .Sh SYNOPSIS