diff --git a/doc/Makefile.in b/doc/Makefile.in index a8604e8..b67dfc8 100644 --- a/doc/Makefile.in +++ b/doc/Makefile.in @@ -108,7 +108,15 @@ OBJECTS=ck_ht_count \ ck_pr_btc \ ck_pr_btr \ ck_pr_store \ - ck_pr_load + ck_pr_load \ + ck_ring_init \ + ck_ring_dequeue_spmc \ + ck_ring_enqueue_spmc \ + ck_ring_enqueue_spmc_size \ + ck_ring_trydequeue_spmc \ + ck_ring_dequeue_spsc \ + ck_ring_enqueue_spsc \ + ck_ring_enqueue_spsc_size all: for target in $(OBJECTS); do \ @@ -116,9 +124,11 @@ all: done html: - for target in $(OBJECTS); do \ - echo $$target; \ - groff -man -Tascii $(SRC_DIR)/doc/$$target | man2html -noheads -bare -cgiurl='$$title.html' > $(BUILD_DIR)/doc/$$target$(HTML_SUFFIX); \ + for target in $(OBJECTS); do \ + echo $$target; \ + groff -man -Tascii $(SRC_DIR)/doc/$$target | \ + man2html -noheads -bare -cgiurl='$$title.html' > \ + $(BUILD_DIR)/doc/$$target$(HTML_SUFFIX); \ done install: diff --git a/doc/ck_ring_dequeue_spmc b/doc/ck_ring_dequeue_spmc new file mode 100644 index 0000000..076ceec --- /dev/null +++ b/doc/ck_ring_dequeue_spmc @@ -0,0 +1,107 @@ +.\" +.\" 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 April 20, 2013 +.Dt CK_RING_DEQUEUE_SPMC 3 +.Sh NAME +.Nm ck_ring_dequeue_spmc +.Nd dequeue pointer from bounded FIFO +.Sh LIBRARY +Concurrency Kit (libck, \-lck) +.Sh SYNOPSIS +.In ck_ring.h +.Ft bool +.Fn ck_ring_dequeue_spmc "ck_ring_t *ring" "void *result" +.Sh DESCRIPTION +The +.Fn ck_ring_dequeue_spmc 3 +function dequeues a pointer from the bounded buffer +pointed to by +.Fa ring +in FIFO fashion. The pointer is stored in the pointer +pointed to by +.Fa result . +If you are on non-POSIX platforms or wish for strict +compliance with C, then it is recommended to pass a +pointer of type void ** for +.Fa result . +This function is safe to call without locking for UINT_MAX +concurrent invocations of +.Fn ck_ring_dequeue_spmc 3 +or +.Fn ck_ring_trydequeue_spmc 3 +and up to one concurrent +.Fn ck_ring_enqueue_spmc 3 +or +.Fn ck_ring_tryenqueue_spmc 3 +invocation. This function provides lock-free progress +guarantees. +.Sh EXAMPLE +.Bd -literal -offset indent +#include + +/* This ring was previously initialized with ck_ring_init. */ +ck_ring_t ring; + +void +dequeue(void) +{ + void *result; + + /* Dequeue from ring until it is empty. */ + while (ck_ring_dequeue_spmc(&ring, &result) == true) { + /* + * Results contains the oldest pointer in ring + * since the dequeue operation returned true. + */ + operation(result); + } + + /* An empty ring was encountered, leave. */ + return; +} +.Ed +.Sh RETURN VALUES +The function returns true if the buffer was non-empty. +The result of the dequeue operation is stored in the +value pointed to by +.Fa result . +The function will return false if the buffer was empty +and the value in +.Fa result +will be undefined. +.Sh SEE ALSO +.Xr ck_ring_init 3 , +.Xr ck_ring_trydequeue_spmc 3 , +.Xr ck_ring_enqueue_spmc 3 , +.Xr ck_ring_enqueue_spmc_size 3 , +.Xr ck_ring_dequeue_spsc 3 , +.Xr ck_ring_enqueue_spsc 3 , +.Xr ck_ring_enqueue_spsc_size 3 , +.Xr ck_ring_capacity 3 , +.Xr ck_ring_size 3 +.Pp +Additional information available at http://concurrencykit.org/ diff --git a/doc/ck_ring_dequeue_spsc b/doc/ck_ring_dequeue_spsc new file mode 100644 index 0000000..ed362f1 --- /dev/null +++ b/doc/ck_ring_dequeue_spsc @@ -0,0 +1,103 @@ +.\" +.\" 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 April 20, 2013 +.Dt CK_RING_DEQUEUE_SPSC 3 +.Sh NAME +.Nm ck_ring_dequeue_spsc +.Nd dequeue pointer from bounded FIFO +.Sh LIBRARY +Concurrency Kit (libck, \-lck) +.Sh SYNOPSIS +.In ck_ring.h +.Ft bool +.Fn ck_ring_dequeue_spsc "ck_ring_t *ring" "void *result" +.Sh DESCRIPTION +The +.Fn ck_ring_dequeue_spsc 3 +function dequeues a pointer from the bounded buffer +pointed to by +.Fa ring +in FIFO fashion. The pointer is stored in the pointer +pointed to by +.Fa result . +If you are on non-POSIX platforms or wish for strict +compliance with C, then it is recommended to pass a +pointer of type void ** for +.Fa result . +This function is safe to call without locking for one +concurrent invocation of +.Fn ck_ring_dequeue_spsc 3 +and up to one concurrent +.Fn ck_ring_enqueue_spsc 3 +invocation. This function provides wait-free progress +guarantees. +.Sh EXAMPLE +.Bd -literal -offset indent +#include + +/* This ring was previously initialized with ck_ring_init. */ +ck_ring_t ring; + +void +dequeue(void) +{ + void *result; + + /* Dequeue from ring until it is empty. */ + while (ck_ring_dequeue_spsc(&ring, &result) == true) { + /* + * Results contains the oldest pointer in ring + * since the dequeue operation returned true. + */ + operation(result); + } + + /* An empty ring was encountered, leave. */ + return; +} +.Ed +.Sh RETURN VALUES +The function returns true if the buffer was non-empty. +The result of the dequeue operation is stored in the +value pointed to by +.Fa result . +The function will return false if the buffer was empty +and the value in +.Fa result +will be undefined. +.Sh SEE ALSO +.Xr ck_ring_init 3 , +.Xr ck_ring_trydequeue_spmc 3 , +.Xr ck_ring_enqueue_spmc 3 , +.Xr ck_ring_enqueue_spmc_size 3 , +.Xr ck_ring_dequeue_spmc 3 , +.Xr ck_ring_enqueue_spsc 3 , +.Xr ck_ring_enqueue_spsc_size 3 , +.Xr ck_ring_capacity 3 , +.Xr ck_ring_size 3 +.Pp +Additional information available at http://concurrencykit.org/ diff --git a/doc/ck_ring_enqueue_spmc b/doc/ck_ring_enqueue_spmc new file mode 100644 index 0000000..12732aa --- /dev/null +++ b/doc/ck_ring_enqueue_spmc @@ -0,0 +1,103 @@ +.\" +.\" 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 April 20, 2013 +.Dt CK_RING_ENQUEUE_SPMC 3 +.Sh NAME +.Nm ck_ring_enqueue_spmc +.Nd enqueue pointer into bounded FIFO +.Sh LIBRARY +Concurrency Kit (libck, \-lck) +.Sh SYNOPSIS +.In ck_ring.h +.Ft bool +.Fn ck_ring_enqueue_spmc "ck_ring_t *ring" "void *entry" +.Sh DESCRIPTION +The +.Fn ck_ring_enqueue_spmc 3 +function enqueues the pointer +.Fa entry +into the bounded buffer pointed to by +.Fa ring +in FIFO fashion. +If you are on non-POSIX platforms or wish for strict +compliance with C, then it is recommended to pass a +pointer of type void ** for +.Fa entry . +This function is safe to call without locking for UINT_MAX +concurrent invocations of +.Fn ck_ring_dequeue_spmc 3 +or +.Fn ck_ring_trydequeue_spmc 3 . +This function provides wait-free progress +guarantees for one active invocation. +.Sh EXAMPLE +.Bd -literal -offset indent +#include + +/* This ring was previously initialized with ck_ring_init. */ +ck_ring_t ring; + +void +enqueue(void) +{ + void *entry = some_object; + + /* Attempt to enqueue pointer to some_object into buffer. */ + if (ck_ring_enqueue_spmc(&ring, &entry) == false) { + /* + * The buffer was full and the enqueue operation + * has failed. + */ + return; + } + + /* Enqueue operation completed successfully. */ + return; +} +.Ed +.Sh RETURN VALUES +The function returns true if the value of +.Fa entry +was successfully enqueued into +.Fa ring . +The function will return false if the value of +.Fa entry +could not be enqueued which only occurs if +.Fa ring +was full. +.Sh SEE ALSO +.Xr ck_ring_init 3 , +.Xr ck_ring_dequeue_spmc 3 , +.Xr ck_ring_trydequeue_spmc 3 , +.Xr ck_ring_enqueue_spmc_size 3 , +.Xr ck_ring_dequeue_spsc 3 , +.Xr ck_ring_enqueue_spsc 3 , +.Xr ck_ring_enqueue_spsc_size 3 , +.Xr ck_ring_capacity 3 , +.Xr ck_ring_size 3 +.Pp +Additional information available at http://concurrencykit.org/ diff --git a/doc/ck_ring_enqueue_spmc_size b/doc/ck_ring_enqueue_spmc_size new file mode 100644 index 0000000..a137789 --- /dev/null +++ b/doc/ck_ring_enqueue_spmc_size @@ -0,0 +1,115 @@ +.\" +.\" 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 April 20, 2013 +.Dt CK_RING_ENQUEUE_SPMC_SIZE 3 +.Sh NAME +.Nm ck_ring_enqueue_spmc_size +.Nd enqueue pointer into bounded FIFO and return size of buffer +.Sh LIBRARY +Concurrency Kit (libck, \-lck) +.Sh SYNOPSIS +.In ck_ring.h +.Ft bool +.Fn ck_ring_enqueue_spmc_size "ck_ring_t *ring" "void *entry" "unsigned int *length" +.Sh DESCRIPTION +The +.Fn ck_ring_enqueue_spmc 3 +function enqueues the pointer +.Fa entry +into the bounded buffer pointed to by +.Fa ring +in FIFO fashion. +If you are on non-POSIX platforms or wish for strict +compliance with C, then it is recommended to pass a +pointer of type void ** for +.Fa entry . +This function is safe to call without locking for UINT_MAX +concurrent invocations of +.Fn ck_ring_dequeue_spmc 3 +or +.Fn ck_ring_trydequeue_spmc 3 . +This function provides wait-free progress +guarantees for one active invocation. +.Sh EXAMPLE +.Bd -literal -offset indent +#include + +/* This ring was previously initialized with ck_ring_init. */ +ck_ring_t ring; + +void +enqueue(void) +{ + void *entry = some_object; + unsigned int length; + + /* Attempt to enqueue pointer to some_object into buffer. */ + if (ck_ring_enqueue_spmc_size(&ring, &entry, &length) == false) { + /* + * The buffer was full and the enqueue operation + * has failed. + */ + return; + } + + /* + * If entry was the 101st or greater pointer in the buffer, + * do something. + */ + if (length > 100) { + do_something; + } + + return; +} +.Ed +.Sh RETURN VALUES +The function returns true if the value of +.Fa entry +was successfully enqueued into +.Fa ring . +The function will return false if the value of +.Fa entry +could not be enqueued which only occurs if +.Fa ring +was full. The number of entries in the buffer +with respect to the point in time that +.Fa entry +is enqueued is stored in the integer pointed to by +.Fa length . +.Sh SEE ALSO +.Xr ck_ring_init 3 , +.Xr ck_ring_dequeue_spmc 3 , +.Xr ck_ring_trydequeue_spmc 3 , +.Xr ck_ring_enqueue_spmc 3 , +.Xr ck_ring_dequeue_spsc 3 , +.Xr ck_ring_enqueue_spsc 3 , +.Xr ck_ring_enqueue_spsc_size 3 , +.Xr ck_ring_capacity 3 , +.Xr ck_ring_size 3 +.Pp +Additional information available at http://concurrencykit.org/ diff --git a/doc/ck_ring_enqueue_spsc b/doc/ck_ring_enqueue_spsc new file mode 100644 index 0000000..b1384d5 --- /dev/null +++ b/doc/ck_ring_enqueue_spsc @@ -0,0 +1,101 @@ +.\" +.\" 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 April 20, 2013 +.Dt CK_RING_ENQUEUE_SPSC 3 +.Sh NAME +.Nm ck_ring_enqueue_spsc +.Nd enqueue pointer into bounded FIFO +.Sh LIBRARY +Concurrency Kit (libck, \-lck) +.Sh SYNOPSIS +.In ck_ring.h +.Ft bool +.Fn ck_ring_enqueue_spsc "ck_ring_t *ring" "void *entry" +.Sh DESCRIPTION +The +.Fn ck_ring_enqueue_spsc 3 +function enqueues the pointer +.Fa entry +into the bounded buffer pointed to by +.Fa ring +in FIFO fashion. +If you are on non-POSIX platforms or wish for strict +compliance with C, then it is recommended to pass a +pointer of type void ** for +.Fa entry . +This function is safe to call without locking for up to +one concurrent invocation of +.Fn ck_ring_dequeue_spsc 3 . +This function provides wait-free progress +guarantees. +.Sh EXAMPLE +.Bd -literal -offset indent +#include + +/* This ring was previously initialized with ck_ring_init. */ +ck_ring_t ring; + +void +enqueue(void) +{ + void *entry = some_object; + + /* Attempt to enqueue pointer to some_object into buffer. */ + if (ck_ring_enqueue_spsc(&ring, &entry) == false) { + /* + * The buffer was full and the enqueue operation + * has failed. + */ + return; + } + + /* Enqueue operation completed successfully. */ + return; +} +.Ed +.Sh RETURN VALUES +The function returns true if the value of +.Fa entry +was successfully enqueued into +.Fa ring . +The function will return false if the value of +.Fa entry +could not be enqueued which only occurs if +.Fa ring +was full. +.Sh SEE ALSO +.Xr ck_ring_init 3 , +.Xr ck_ring_dequeue_spmc 3 , +.Xr ck_ring_trydequeue_spmc 3 , +.Xr ck_ring_enqueue_spmc 3 , +.Xr ck_ring_enqueue_spmc_size 3 , +.Xr ck_ring_dequeue_spsc 3 , +.Xr ck_ring_enqueue_spsc_size 3 , +.Xr ck_ring_capacity 3 , +.Xr ck_ring_size 3 +.Pp +Additional information available at http://concurrencykit.org/ diff --git a/doc/ck_ring_enqueue_spsc_size b/doc/ck_ring_enqueue_spsc_size new file mode 100644 index 0000000..3cfb507 --- /dev/null +++ b/doc/ck_ring_enqueue_spsc_size @@ -0,0 +1,116 @@ +.\" +.\" 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 April 20, 2013 +.Dt CK_RING_ENQUEUE_SPSC_SIZE 3 +.Sh NAME +.Nm ck_ring_enqueue_spsc_size +.Nd enqueue pointer into bounded FIFO and return size of buffer +.Sh LIBRARY +Concurrency Kit (libck, \-lck) +.Sh SYNOPSIS +.In ck_ring.h +.Ft bool +.Fn ck_ring_enqueue_spsc_size "ck_ring_t *ring" "void *entry" "unsigned int *size" +.Sh DESCRIPTION +The +.Fn ck_ring_enqueue_spsc_size 3 +function enqueues the pointer +.Fa entry +into the bounded buffer pointed to by +.Fa ring +in FIFO fashion. +If you are on non-POSIX platforms or wish for strict +compliance with C, then it is recommended to pass a +pointer of type void ** for +.Fa entry . +This function is safe to call without locking for up to +one concurrent invocation of +.Fn ck_ring_dequeue_spsc 3 . +This function provides wait-free progress +guarantees. +.Sh EXAMPLE +.Bd -literal -offset indent +#include + +/* This ring was previously initialized with ck_ring_init. */ +ck_ring_t ring; + +void +enqueue(void) +{ + void *entry = some_object; + unsigned int length; + + /* Attempt to enqueue pointer to some_object into buffer. */ + if (ck_ring_enqueue_spsc(&ring, &entry, &length) == false) { + /* + * The buffer was full and the enqueue operation + * has failed. + */ + return; + } + + /* + * If buffer length was 100 items or more at the time entry was + * enqueued, do something. + */ + if (length > 100) { + do_something; + } + + return; +} +.Ed +.Sh RETURN VALUES +The function returns true if the value of +.Fa entry +was successfully enqueued into +.Fa ring . +This function will return the number of items +in +.Fa ring +with respect to the linearization point (the +point in item that +.Fa entry +is enqueued). +The function will return false if the value of +.Fa entry +could not be enqueued which only occurs if +.Fa ring +was full. +.Sh SEE ALSO +.Xr ck_ring_init 3 , +.Xr ck_ring_dequeue_spmc 3 , +.Xr ck_ring_trydequeue_spmc 3 , +.Xr ck_ring_enqueue_spmc 3 , +.Xr ck_ring_enqueue_spmc_size 3 , +.Xr ck_ring_dequeue_spsc 3 , +.Xr ck_ring_enqueue_spsc 3 , +.Xr ck_ring_capacity 3 , +.Xr ck_ring_size 3 +.Pp +Additional information available at http://concurrencykit.org/ diff --git a/doc/ck_ring_init b/doc/ck_ring_init new file mode 100644 index 0000000..11c4074 --- /dev/null +++ b/doc/ck_ring_init @@ -0,0 +1,66 @@ +.\" +.\" 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 April 20, 2013 +.Dt CK_RING_INIT 3 +.Sh NAME +.Nm ck_ring_init +.Nd initialize bounded FIFO +.Sh LIBRARY +Concurrency Kit (libck, \-lck) +.Sh SYNOPSIS +.In ck_ring.h +.Ft void +.Fn ck_ring_init "ck_ring_t *ring" "void *buffer" "unsigned int size" +.Sh DESCRIPTION +The +.Fn ck_ring_init +function initializes a bounded FIFO buffer pointed to by +.Fa ring +for the storage of up to +.Fa size +number of pointers. The +.Fa buffer +argument must be a pointer to an array of void * of +length +.Fa size . +The +.Fa size +argument must be a power-of-two greater than or equal to 4. +.Sh RETURN VALUES +This function has no return value. +.Sh SEE ALSO +.Xr ck_ring_dequeue_spmc 3 , +.Xr ck_ring_trydequeue_spmc 3 , +.Xr ck_ring_enqueue_spmc 3 , +.Xr ck_ring_enqueue_spmc_size 3 , +.Xr ck_ring_dequeue_spsc 3 , +.Xr ck_ring_enqueue_spsc 3 , +.Xr ck_ring_enqueue_spsc_size 3 , +.Xr ck_ring_capacity 3 , +.Xr ck_ring_size 3 +.Pp +Additional information available at http://concurrencykit.org/ diff --git a/doc/ck_ring_trydequeue_spmc b/doc/ck_ring_trydequeue_spmc new file mode 100644 index 0000000..4551724 --- /dev/null +++ b/doc/ck_ring_trydequeue_spmc @@ -0,0 +1,114 @@ +.\" +.\" 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 April 20, 2013 +.Dt CK_RING_TRYDEQUEUE_SPMC 3 +.Sh NAME +.Nm ck_ring_trydequeue_spmc +.Nd dequeue from bounded FIFO and allow for spurious failure +.Sh LIBRARY +Concurrency Kit (libck, \-lck) +.Sh SYNOPSIS +.In ck_ring.h +.Ft bool +.Fn ck_ring_trydequeue_spmc "ck_ring_t *ring" "void *result" +.Sh DESCRIPTION +The +.Fn ck_ring_trydequeue_spmc 3 +function attempts to dequeue a pointer from the bounded buffer +pointed to by +.Fa ring +in FIFO fashion. The pointer is stored in the pointer +pointed to by +.Fa result . +If you are on non-POSIX platforms or wish for strict +compliance with C, then it is recommended to pass a +pointer of type void ** for +.Fa result . +This function is safe to call without locking for UINT_MAX +concurrent +.Fn ck_ring_dequeue_spmc 3 +or +.Fn ck_ring_trydequeue_spmc 3 +invocations and up to one concurrent +.Fn ck_ring_enqueue_spmc 3 +or +.Fn ck_ring_tryenqueue_spmc 3 +invocation. This operation will always complete +in a bounded number of steps. It is +possible for the function to return false even +if +.Fa ring +is non-empty. This +.Sh EXAMPLE +.Bd -literal -offset indent +#include + +/* This ring was previously initialized with ck_ring_init. */ +ck_ring_t ring; + +void +dequeue(void) +{ + void *result; + + /* Dequeue from ring until contention is actively observed. */ + while (ck_ring_trydequeue_spmc(&ring, &result) == true) { + /* + * Results contains the oldest pointer in ring + * since the dequeue operation returned true. + */ + operation(result); + } + + /* An empty ring was encountered, leave. */ + return; +} +.Ed +.Sh RETURN VALUES +The function returns true if the dequeue operation +completely successfully in a bounded number of steps. +The result of the dequeue operation is stored in the +value pointed to by +.Fa result . +Otherwise, the function will return false if the buffer was empty +or if the operation could not be completed in a bounded +number of steps. If the function returns false, then the contents +of +.Fa result +are undefined. +.Sh SEE ALSO +.Xr ck_ring_init 3 , +.Xr ck_ring_dequeue_spmc 3 , +.Xr ck_ring_enqueue_spmc 3 , +.Xr ck_ring_enqueue_spmc_size 3 , +.Xr ck_ring_dequeue_spsc 3 , +.Xr ck_ring_enqueue_spsc 3 , +.Xr ck_ring_enqueue_spsc_size 3 , +.Xr ck_ring_capacity 3 , +.Xr ck_ring_size 3 +.Pp +Additional information available at http://concurrencykit.org/