Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
CK_RING_TRYDEQUEUE_SP... BSD Library Functions Manual CK_RING_TRYDEQUEUE_SP...

NAME
     ck_ring_trydequeue_spmc --	dequeue	from bounded FIFO and allow for	spuri-
     ous failure

LIBRARY
     Concurrency Kit (libck, -lck)

SYNOPSIS
     #include <ck_ring.h>

     bool
     ck_ring_trydequeue_spmc(ck_ring_t *ring, ck_ring_buffer_t *buffer,
	 void *result);

DESCRIPTION
     The ck_ring_trydequeue_spmc(3) function attempts to dequeue a pointer
     from the bounded buffer pointed to	by ring	in FIFO	fashion. The pointer
     is	stored in the pointer pointed to by result.  The buffer	pointed	to by
     buffer must be unique to ring and point to	an array of ck_ring_buffer_t
     of	sufficient length (according to	the power-of-2 elements	in the buf-
     fer).  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 result.  This	func-
     tion is safe to call without locking for UINT_MAX concurrent
     ck_ring_dequeue_spmc(3) or	ck_ring_trydequeue_spmc(3) invocations and up
     to	one concurrent ck_ring_enqueue_spmc(3) or 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 ring is
     non-empty.	This

EXAMPLE
	   #include <ck_ring.h>

	   /* 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, &buffer, &result) == true) {
			   /*
			    * Results contains the oldest pointer in ring
			    * since the	dequeue	operation returned true.
			    */
			   operation(result);
		   }

		   /* An empty ring was	encountered, leave. */
		   return;
	   }

RETURN VALUES
     The function returns true if the dequeue operation	completely success-
     fully in a	bounded	number of steps.  The result of	the dequeue operation
     is	stored in the value pointed to by 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 result are undefined.

SEE ALSO
     ck_ring_init(3), ck_ring_dequeue_spmc(3), ck_ring_enqueue_spmc(3),
     ck_ring_enqueue_spmc_size(3), ck_ring_dequeue_spsc(3),
     ck_ring_enqueue_spsc(3), ck_ring_enqueue_spsc_size(3),
     ck_ring_capacity(3), ck_ring_size(3)

     Additional	information available at http://concurrencykit.org/

				April 20, 2013

NAME | LIBRARY | SYNOPSIS | DESCRIPTION | EXAMPLE | RETURN VALUES | SEE ALSO

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=ck_ring_trydequeue_spmc&sektion=3&manpath=FreeBSD+12.0-RELEASE+and+Ports>

home | help