From 9c727a8d8cfe60fcd0d8dbabb8edda2865ebb3e0 Mon Sep 17 00:00:00 2001 From: Patrick Pelissier Date: Sun, 7 Jan 2018 21:57:23 +0100 Subject: [PATCH] Update doc --- README.md | 31 ++++++++++++++++++++++++------- 1 file changed, 24 insertions(+), 7 deletions(-) diff --git a/README.md b/README.md index 4d28fdf4..f0eab3fd 100644 --- a/README.md +++ b/README.md @@ -1919,26 +1919,36 @@ This method is only defined if the type of the element defines a HASH method its Define the buffer 'name##\_t' and its associated methods as "static inline" functions. A buffer is a fixed size queue or stack. -If it is built with the BUFFER\_THREAD\_SAFE option it can be used to transfert message -from mutiple producer threads to multiple consummer threads. This is done internaly using -a mutex. +If it is built with the BUFFER\_THREAD\_SAFE option (default) it can be used to transfert message +from mutiple producer threads to multiple consummer threads. +This is done internaly using a mutex and conditional waits. 'name' shall be a C identifier which will be used to identify the container. -The size parameter defined the fixed size of the queue. It can be 0, in which case, the fixed size will be defined at initialization time. +The size parameter defined the fixed size of the queue. +It can be 0, in which case, the fixed size will be defined at initialization time +and the needed objects to handle the buffer will be allocated at initialization time too. +Otherwise the needed objects will be embedded within the structure, preventing +any other allocations. Multiple additional policy can be applied to the buffer by performing a logical or of the following properties: * BUFFER\_QUEUE : define a FIFO queue (default), * BUFFER\_STACK : define a stack (exclusive with BUFFER\_QUEUE), -* BUFFER\_BLOCKING : define blocking calls for push/pop (default), -* BUFFER\_UNBLOCKING : define unblocking calls for push/pop, +* BUFFER\_BLOCKING : define blocking calls for the default push/pop methods (default); this is a synonym to BUFFER\_BLOCKING\_PUSH|BUFFER\_BLOCKING\_POP, +* BUFFER\_UNBLOCKING : define unblocking calls for the default push/pop methods; this is a synonum to BUFFER\_UNBLOCKING\_PUSH|BUFFER\_UNBLOCKING\_POP, +* BUFFER\_BLOCKING\_PUSH : define blocking calls for the default push methods (default), +* BUFFER\_UNBLOCKING\_PUSH : define unblocking calls for the default push methods, +* BUFFER\_BLOCKING\_POP : define blocking calls for the default pop methods (default), +* BUFFER\_UNBLOCKING\_POP : define unblocking calls for the default pop methods, * BUFFER\_THREAD\_SAFE : define thread safe functions (default), * BUFFER\_THREAD\_UNSAFE : define thread unsafe functions, * BUFFER\_PUSH\_INIT\_POP\_MOVE : change the behavior of PUSH to push a new initialized object, and POP as moving this new object into the new emplacement (this is mostly used for performance reasons or to handle properly a shared_ptr semantic). In practice, it works as if POP performs the initialization of the object. * BUFFER\_PUSH\_OVERWRITE : PUSH will always overwrite the first entry (this is mostly used to reduce latency). +* BUFFER\_DEFERRED\_POP : do not consider the object to be fully popped from the buffer by calling the pop method until the call to pop_deferred ; this allows to handle object which are in-progress of being consummed by the thread. -This container is designed to be used for easy synchronization inter-threads (and the variable shall be a global shared one). +This container is designed to be used for easy synchronization inter-threads +(and the variable shall be a global shared one). It shall be done once per type and per compilation unit. @@ -2024,6 +2034,13 @@ Returns true if a data was popped, false otherwise. Always return true if the buffer is blocking. This function is thread safe if the buffer was built thread safe. +##### bool name\_push\_blocking(buffer\_t buffer, const type data, bool blocking) + +Same as name\_push except that the blocking policity is decided by the 'blocking' parameter. + +##### bool name\_pop\_blocking(buffer\_t buffer, const type data, bool blocking) + +Same as name\_pop except that the blocking policity is decided by the 'blocking' parameter. ### M-SNAPSHOT