From 86ac63241a4966c9551354c1c7e2519eb7ec9025 Mon Sep 17 00:00:00 2001 From: Samy Al Bahra Date: Mon, 16 Dec 2013 20:26:24 -0500 Subject: [PATCH] doc: Update ck_ring manual pages. --- doc/ck_ring_dequeue_spmc | 14 ++++++++++++-- doc/ck_ring_dequeue_spsc | 16 ++++++++++++++-- doc/ck_ring_enqueue_spmc | 16 ++++++++++++++-- doc/ck_ring_enqueue_spmc_size | 16 ++++++++++++++-- doc/ck_ring_enqueue_spsc | 16 ++++++++++++++-- doc/ck_ring_enqueue_spsc_size | 16 ++++++++++++++-- doc/ck_ring_trydequeue_spmc | 16 ++++++++++++++-- 7 files changed, 96 insertions(+), 14 deletions(-) diff --git a/doc/ck_ring_dequeue_spmc b/doc/ck_ring_dequeue_spmc index 076ceec..82fc2fb 100644 --- a/doc/ck_ring_dequeue_spmc +++ b/doc/ck_ring_dequeue_spmc @@ -34,7 +34,7 @@ Concurrency Kit (libck, \-lck) .Sh SYNOPSIS .In ck_ring.h .Ft bool -.Fn ck_ring_dequeue_spmc "ck_ring_t *ring" "void *result" +.Fn ck_ring_dequeue_spmc "ck_ring_t *ring" "ck_ring_buffer_t *buffer" "void *result" .Sh DESCRIPTION The .Fn ck_ring_dequeue_spmc 3 @@ -44,6 +44,13 @@ pointed to by in FIFO fashion. The pointer is stored in the pointer pointed to by .Fa result . +The buffer pointed to by +.Fa buffer +must be unique to +.Fa ring . +The decoupling of the ring from the buffer serves +to address use-cases involving multiple address spaces +and DMA, among others. 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 @@ -66,13 +73,16 @@ guarantees. /* This ring was previously initialized with ck_ring_init. */ ck_ring_t ring; +/* The ring was initialized for 1023 elements. */ +ck_ring_buffer_t buffer[1024]; + void dequeue(void) { void *result; /* Dequeue from ring until it is empty. */ - while (ck_ring_dequeue_spmc(&ring, &result) == true) { + while (ck_ring_dequeue_spmc(&ring, &buffer, &result) == true) { /* * Results contains the oldest pointer in ring * since the dequeue operation returned true. diff --git a/doc/ck_ring_dequeue_spsc b/doc/ck_ring_dequeue_spsc index ed362f1..75b36ac 100644 --- a/doc/ck_ring_dequeue_spsc +++ b/doc/ck_ring_dequeue_spsc @@ -34,7 +34,7 @@ Concurrency Kit (libck, \-lck) .Sh SYNOPSIS .In ck_ring.h .Ft bool -.Fn ck_ring_dequeue_spsc "ck_ring_t *ring" "void *result" +.Fn ck_ring_dequeue_spsc "ck_ring_t *ring" "ck_ring_buffer_t *buffer" "void *result" .Sh DESCRIPTION The .Fn ck_ring_dequeue_spsc 3 @@ -44,6 +44,15 @@ pointed to by in FIFO fashion. The pointer is stored in the pointer pointed to by .Fa result . +The buffer pointed to by +.Fa buffer +must be unique to +.Fa ring +and point to an array of ck_ring_buffer_t of sufficient +length (according to the power-of-2 elements in the buffer). +The decoupling of the ring from the buffer serves +to address use-cases involving multiple address spaces +and DMA, among others. 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 @@ -62,13 +71,16 @@ guarantees. /* This ring was previously initialized with ck_ring_init. */ ck_ring_t ring; +/* The ring was initialized for 1023 elements. */ +ck_ring_buffer_t buffer[1024]; + void dequeue(void) { void *result; /* Dequeue from ring until it is empty. */ - while (ck_ring_dequeue_spsc(&ring, &result) == true) { + while (ck_ring_dequeue_spsc(&ring, &buffer, &result) == true) { /* * Results contains the oldest pointer in ring * since the dequeue operation returned true. diff --git a/doc/ck_ring_enqueue_spmc b/doc/ck_ring_enqueue_spmc index 12732aa..20fd6a8 100644 --- a/doc/ck_ring_enqueue_spmc +++ b/doc/ck_ring_enqueue_spmc @@ -34,7 +34,7 @@ Concurrency Kit (libck, \-lck) .Sh SYNOPSIS .In ck_ring.h .Ft bool -.Fn ck_ring_enqueue_spmc "ck_ring_t *ring" "void *entry" +.Fn ck_ring_enqueue_spmc "ck_ring_t *ring" "ck_ring_buffer_t *buffer" "void *entry" .Sh DESCRIPTION The .Fn ck_ring_enqueue_spmc 3 @@ -43,6 +43,15 @@ function enqueues the pointer into the bounded buffer pointed to by .Fa ring in FIFO fashion. +The buffer pointed to by +.Fa buffer +must be unique to +.Fa ring +and point to an array of ck_ring_buffer_t of sufficient +length (according to the power-of-2 elements in the buffer). +The decoupling of the ring from the buffer serves +to address use-cases involving multiple address spaces +and DMA, among others. 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 @@ -61,13 +70,16 @@ guarantees for one active invocation. /* This ring was previously initialized with ck_ring_init. */ ck_ring_t ring; +/* The ring was initialized for 1023 elements. */ +ck_ring_buffer_t buffer[1024]; + void enqueue(void) { void *entry = some_object; /* Attempt to enqueue pointer to some_object into buffer. */ - if (ck_ring_enqueue_spmc(&ring, &entry) == false) { + if (ck_ring_enqueue_spmc(&ring, &buffer, &entry) == false) { /* * The buffer was full and the enqueue operation * has failed. diff --git a/doc/ck_ring_enqueue_spmc_size b/doc/ck_ring_enqueue_spmc_size index a137789..900bd28 100644 --- a/doc/ck_ring_enqueue_spmc_size +++ b/doc/ck_ring_enqueue_spmc_size @@ -34,7 +34,7 @@ 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" +.Fn ck_ring_enqueue_spmc_size "ck_ring_t *ring" "ck_ring_buffer_t *buffer" "void *entry" "unsigned int *length" .Sh DESCRIPTION The .Fn ck_ring_enqueue_spmc 3 @@ -43,6 +43,15 @@ function enqueues the pointer into the bounded buffer pointed to by .Fa ring in FIFO fashion. +The buffer pointed to by +.Fa buffer +must be unique to +.Fa ring +and point to an array of ck_ring_buffer_t of sufficient +length (according to the power-of-2 elements in the buffer). +The decoupling of the ring from the buffer serves +to address use-cases involving multiple address spaces +and DMA, among others. 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 @@ -61,6 +70,9 @@ guarantees for one active invocation. /* This ring was previously initialized with ck_ring_init. */ ck_ring_t ring; +/* The ring was initialized for 1023 elements. */ +ck_ring_buffer_t buffer[1024]; + void enqueue(void) { @@ -68,7 +80,7 @@ enqueue(void) unsigned int length; /* Attempt to enqueue pointer to some_object into buffer. */ - if (ck_ring_enqueue_spmc_size(&ring, &entry, &length) == false) { + if (ck_ring_enqueue_spmc_size(&ring, &buffer, &entry, &length) == false) { /* * The buffer was full and the enqueue operation * has failed. diff --git a/doc/ck_ring_enqueue_spsc b/doc/ck_ring_enqueue_spsc index b1384d5..e5fbbec 100644 --- a/doc/ck_ring_enqueue_spsc +++ b/doc/ck_ring_enqueue_spsc @@ -34,7 +34,7 @@ Concurrency Kit (libck, \-lck) .Sh SYNOPSIS .In ck_ring.h .Ft bool -.Fn ck_ring_enqueue_spsc "ck_ring_t *ring" "void *entry" +.Fn ck_ring_enqueue_spsc "ck_ring_t *ring" "ck_ring_buffer_t *buffer" "void *entry" .Sh DESCRIPTION The .Fn ck_ring_enqueue_spsc 3 @@ -43,6 +43,15 @@ function enqueues the pointer into the bounded buffer pointed to by .Fa ring in FIFO fashion. +The buffer pointed to by +.Fa buffer +must be unique to +.Fa ring +and point to an array of ck_ring_buffer_t of sufficient +length (according to the power-of-2 elements in the buffer). +The decoupling of the ring from the buffer serves +to address use-cases involving multiple address spaces +and DMA, among others. 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 @@ -59,13 +68,16 @@ guarantees. /* This ring was previously initialized with ck_ring_init. */ ck_ring_t ring; +/* The ring was initialized for 1023 elements. */ +ck_ring_buffer_t buffer[1024]; + void enqueue(void) { void *entry = some_object; /* Attempt to enqueue pointer to some_object into buffer. */ - if (ck_ring_enqueue_spsc(&ring, &entry) == false) { + if (ck_ring_enqueue_spsc(&ring, &buffer, &entry) == false) { /* * The buffer was full and the enqueue operation * has failed. diff --git a/doc/ck_ring_enqueue_spsc_size b/doc/ck_ring_enqueue_spsc_size index 3cfb507..90bdf12 100644 --- a/doc/ck_ring_enqueue_spsc_size +++ b/doc/ck_ring_enqueue_spsc_size @@ -34,7 +34,7 @@ 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" +.Fn ck_ring_enqueue_spsc_size "ck_ring_t *ring" "ck_ring_buffer_t *buffer" "void *entry" "unsigned int *size" .Sh DESCRIPTION The .Fn ck_ring_enqueue_spsc_size 3 @@ -43,6 +43,15 @@ function enqueues the pointer into the bounded buffer pointed to by .Fa ring in FIFO fashion. +The buffer pointed to by +.Fa buffer +must be unique to +.Fa ring +and point to an array of ck_ring_buffer_t of sufficient +length (according to the power-of-2 elements in the buffer). +The decoupling of the ring from the buffer serves +to address use-cases involving multiple address spaces +and DMA, among others. 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 @@ -59,6 +68,9 @@ guarantees. /* This ring was previously initialized with ck_ring_init. */ ck_ring_t ring; +/* The ring was initialized for 1023 elements. */ +ck_ring_buffer_t buffer[1024]; + void enqueue(void) { @@ -66,7 +78,7 @@ enqueue(void) unsigned int length; /* Attempt to enqueue pointer to some_object into buffer. */ - if (ck_ring_enqueue_spsc(&ring, &entry, &length) == false) { + if (ck_ring_enqueue_spsc(&ring, &buffer, &entry, &length) == false) { /* * The buffer was full and the enqueue operation * has failed. diff --git a/doc/ck_ring_trydequeue_spmc b/doc/ck_ring_trydequeue_spmc index 4551724..52a92b6 100644 --- a/doc/ck_ring_trydequeue_spmc +++ b/doc/ck_ring_trydequeue_spmc @@ -34,7 +34,7 @@ Concurrency Kit (libck, \-lck) .Sh SYNOPSIS .In ck_ring.h .Ft bool -.Fn ck_ring_trydequeue_spmc "ck_ring_t *ring" "void *result" +.Fn ck_ring_trydequeue_spmc "ck_ring_t *ring" "ck_ring_buffer_t *buffer" "void *result" .Sh DESCRIPTION The .Fn ck_ring_trydequeue_spmc 3 @@ -44,6 +44,15 @@ pointed to by in FIFO fashion. The pointer is stored in the pointer pointed to by .Fa result . +The buffer pointed to by +.Fa buffer +must be unique to +.Fa ring +and point to an array of ck_ring_buffer_t of sufficient +length (according to the power-of-2 elements in the buffer). +The decoupling of the ring from the buffer serves +to address use-cases involving multiple address spaces +and DMA, among others. 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 @@ -70,13 +79,16 @@ is non-empty. This /* This ring was previously initialized with ck_ring_init. */ ck_ring_t ring; +/* The ring was initialized for 1023 elements. */ +ck_ring_buffer_t buffer[1024]; + void dequeue(void) { void *result; /* Dequeue from ring until contention is actively observed. */ - while (ck_ring_trydequeue_spmc(&ring, &result) == true) { + while (ck_ring_trydequeue_spmc(&ring, &buffer, &result) == true) { /* * Results contains the oldest pointer in ring * since the dequeue operation returned true.