Libthreadar 1.6.0
Public Member Functions | List of all members
libthreadar::fast_tampon< T > Class Template Reference

Class fast_tampon provides asynchronous communication between two threads. More...

#include <fast_tampon.hpp>

Public Member Functions

 fast_tampon (unsigned int max_block, unsigned int block_size)
 constructor More...
 
 fast_tampon (const fast_tampon &ref)=delete
 no copy constructor
 
 fast_tampon (fast_tampon &&ref)=default
 no move constructor
 
fast_tamponoperator= (const fast_tampon &ref)=delete
 no assignment operator
 
fast_tamponoperator= (fast_tampon &&ref) noexcept=default
 no move operator
 
 ~fast_tampon ()
 
void get_block_to_feed (T *&ptr, unsigned int &num)
 feeder call - step 1 More...
 
void feed (T *ptr, unsigned int written)
 feeder call - step 2 More...
 
void feed_cancel_get_block (T *ptr)
 feeder call - step 2 alternative More...
 
void fetch (T *&ptr, unsigned int &num)
 fetcher call - step 1 More...
 
void fetch_recycle (T *ptr)
 fetcher call - step 2 More...
 
void fetch_push_back (T *ptr, unsigned int new_num)
 fetcher call - step 2 alternative More...
 
bool is_empty () const
 to know whether the fast_tampon has objects (readable or skipped) More...
 
bool is_not_empty () const
 to know whether the fast_tampon is not empty More...
 
bool is_full () const
 for feeder to know whether the next call to get_block_to_feed() will be blocking More...
 
bool is_not_full () const
 to know whether the fast_tampon is not full More...
 
unsigned int size () const
 
unsigned int block_size () const
 
void reset ()
 reset the object fields and mutex as if the object was just created More...
 

Detailed Description

template<class T>
class libthreadar::fast_tampon< T >

Class fast_tampon provides asynchronous communication between two threads.

A first thread is defined as a feeder and feeds the fast_tampon object with data that the other thread known as the fetcher will read at a later time. If the fast_tampon is empty the fetcher thread is suspended, if it is full the feeder thread is suspended. Feeding an empty fast_tampon automatically awakes the fetcher thread if it was suspended for reading, reading a full fast_tampon automatically awakes a feeder that was suspended for writing.

The feeder has to proceed in two steps:

The fetcher interface is almost symmetric, and also has two steps:

Only on thread can be a feeder, only one (other) thread can be a fetcher.

fast_tampon objects cannot be copied, once created they can only be passed as reference or using a pointer to them.

Note
Class fast_tampon is a template with a single type 'T' as argument. This type is the base type of the memory block. If you want to exchanges blocks of char between two threads by use of char * pointers, use tampon<char>
Examples
/doc/examples/fast_tampon_example.cpp.

Definition at line 87 of file fast_tampon.hpp.

Constructor & Destructor Documentation

◆ fast_tampon()

template<class T >
libthreadar::fast_tampon< T >::fast_tampon ( unsigned int  max_block,
unsigned int  block_size 
)

constructor

Parameters
[in]max_blockis the maximum number of buffers that can be written to without being read
[in]block_sizeis the maximum size of each buffer
Note
that the object will allocate max_block * block_size * sizeof(T) bytes in consequence

Definition at line 213 of file fast_tampon.hpp.

References libthreadar::fast_tampon< T >::block_size(), and libthreadar::fast_tampon< T >::reset().

◆ ~fast_tampon()

template<class T >
libthreadar::fast_tampon< T >::~fast_tampon

the destructor releases all internally allocated blocks even if they have been fetched or obtained for feeding.

Definition at line 255 of file fast_tampon.hpp.

Member Function Documentation

◆ block_size()

template<class T >
unsigned int libthreadar::fast_tampon< T >::block_size ( ) const
inline

returns the allocation size of each block

Note
this is the block_size argument given at construction time

Definition at line 181 of file fast_tampon.hpp.

Referenced by libthreadar::fast_tampon< T >::fast_tampon().

◆ feed()

template<class T >
void libthreadar::fast_tampon< T >::feed ( T *  ptr,
unsigned int  written 
)

feeder call - step 2

Once data has been copied into the block obtained by a call to get_block_to_feed(), use this call to given back this block to the fast_tampon object

Parameters
[in]ptraddress of the block to return to the fast_tampon object
[in]writtenis the number of element of the block that contain meaninful information, written shall be less than or equal to the argument "num" given by get_block_to_feed().

Definition at line 304 of file fast_tampon.hpp.

◆ feed_cancel_get_block()

template<class T >
void libthreadar::fast_tampon< T >::feed_cancel_get_block ( T *  ptr)

feeder call - step 2 alternative

put back the block obtained by get_block_to_feed() for example because it was not used. This block will be the next one returned by get_block_to_feed

Parameters
[in]ptris the address of the block to put back in place for next feed

Definition at line 329 of file fast_tampon.hpp.

◆ fetch()

template<class T >
void libthreadar::fast_tampon< T >::fetch ( T *&  ptr,
unsigned int &  num 
)

fetcher call - step 1

obtain the next block to read

Parameters
[out]ptris the address of the data to be read
[out]numis the number of element available for reading
Note
that the caller shall never release the address pointed to by ptr

Definition at line 338 of file fast_tampon.hpp.

References THREADAR_BUG.

◆ fetch_push_back()

template<class T >
void libthreadar::fast_tampon< T >::fetch_push_back ( T *  ptr,
unsigned int  new_num 
)

fetcher call - step 2 alternative

put back the fetched block if some data remain unfetched for now in this block,

Parameters
[in]ptrthe address of the block to push back into the fast_tampon object
[in]new_numis the new amount of data that is left for reading assuming some data but not all could be read from that buffer.
Note
this is the duty of the caller to modify the block for the part of the data that has been fetch be suppressed and the unfetched data be moved at the beginning of the block. The size is thus modified and provided as new amount of available data in that block which will be returned again by the next call to fetch().

Definition at line 397 of file fast_tampon.hpp.

◆ fetch_recycle()

template<class T >
void libthreadar::fast_tampon< T >::fetch_recycle ( T *  ptr)

fetcher call - step 2

Once data has been read, the fetcher must recycle the block into the fast_tampon object

Parameters
[in]ptrthe address of the block to recycle

Definition at line 374 of file fast_tampon.hpp.

◆ get_block_to_feed()

template<class T >
void libthreadar::fast_tampon< T >::get_block_to_feed ( T *&  ptr,
unsigned int &  num 
)

feeder call - step 1

provides a single block where the caller will be able to write data to in order to be transmitted to the fetcher thread

Parameters
[out]ptrthe address where the caller can write data to
[out]numis the size of the block in number of objects of type T
Note
note that the caller shall never release the address pointed to by ptr

Definition at line 268 of file fast_tampon.hpp.

References THREADAR_BUG.

◆ is_empty()

template<class T >
bool libthreadar::fast_tampon< T >::is_empty ( ) const
inline

to know whether the fast_tampon has objects (readable or skipped)

Definition at line 162 of file fast_tampon.hpp.

Referenced by libthreadar::fast_tampon< T >::is_not_empty().

◆ is_full()

template<class T >
bool libthreadar::fast_tampon< T >::is_full ( ) const
inline

for feeder to know whether the next call to get_block_to_feed() will be blocking

Definition at line 168 of file fast_tampon.hpp.

Referenced by libthreadar::fast_tampon< T >::is_not_full().

◆ is_not_empty()

template<class T >
bool libthreadar::fast_tampon< T >::is_not_empty ( ) const
inline

to know whether the fast_tampon is not empty

Definition at line 165 of file fast_tampon.hpp.

References libthreadar::fast_tampon< T >::is_empty().

◆ is_not_full()

template<class T >
bool libthreadar::fast_tampon< T >::is_not_full ( ) const
inline

to know whether the fast_tampon is not full

Definition at line 171 of file fast_tampon.hpp.

References libthreadar::fast_tampon< T >::is_full().

◆ reset()

template<class T >
void libthreadar::fast_tampon< T >::reset

reset the object fields and mutex as if the object was just created

Definition at line 409 of file fast_tampon.hpp.

Referenced by libthreadar::fast_tampon< T >::fast_tampon().

◆ size()

template<class T >
unsigned int libthreadar::fast_tampon< T >::size ( ) const
inline

returns the size of the fast_tampon in maximum number of block it can contain

Note
this is the max_block argument given at construction time

Definition at line 176 of file fast_tampon.hpp.


The documentation for this class was generated from the following file: