DEPRECATED see fast_tampon instead! More...

#include <tampon.hpp>

Public Member Functions
	tampon (unsigned int max_block, unsigned int block_size)
	constructor More...

	tampon (const tampon &ref)=delete
	no copy constructor

	tampon (tampon &&ref) noexcept=default
	no move constructor

tampon &	operator= (const tampon &ref)=delete
	no assignment operator

tampon &	operator= (tampon &&ref) noexcept=default
	no move operator

	~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...

void	fetch_push_back_and_skip (T *ptr, unsigned int new_num)
	put back the fetched block and skip to next block for the next fetch() More...

void	fetch_skip_back ()
	reactivate all skipped blocks, next fetch() will be the oldest available block

bool	has_readable_block_next () const
	to known whether next fetch will be blocking (not skipped blocks)

bool	is_empty () const
	to know whether the tampon has objects (readable or skipped)

bool	is_not_empty () const
	to know whether the tampon is not empty

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

bool	is_not_full () const
	to know whether the tampon is not full

bool	is_quiet_full () const
	returns true if only one slot is available before filling the tampon

unsigned int	size () const
	returns the size of the tampon in maximum number of block it can contain More...

unsigned int	block_size () const
	returns the allocation size of each block More...

unsigned int	load () const
	returns the current number of blocks currently used in the tampon (fed but not fetched)

void	reset ()
	reset the object fields and mutex as if the object was just created

Detailed Description

template<class T>
class libthreadar::tampon< T >

DEPRECATED see fast_tampon instead!

Class tampon provides asynchronous communication between two threads

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

The feeder has to proceed in two steps:

first call get_block_to_feed() and write data to the obtained block
once the data has been written to the block, it must call feed() with that block. The feeder must not feed() the tampon with any other block than the one obtained by get_block_to_feed(). The obtained blocks remains the property of the tampon object and will be released by it. Only one block can be obtained at a time, thus get_block_to_feed() and feed() should be called alternatively. The feeder can call feed_cancel_get_block() instead of feed() to return the obtained block as if get_block_to_feed() had not been called.

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

first fetch() a new block of data, read the data from it
then give back the block to the tampon object calling fetch_recycle(). the Fetcher has not to delete the fetched block nor it must fetch_recycle() another block than the one that has been fetched. Only one block can be fetched at a time, thus fetch() and fetch_recycle() should be called alternatively. The fetcher can call fetch_push_back() instead of fetch_recycle() to return the fetched block as if fetch() was not called before. The next time, fetch() will then return the same block that has been fetch_push[ed]_back().

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

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

Note: Class 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>

The fetcher has the possiblity to read data after the next block to be fetched:

same as before, the fetcher has first to fetch() a block
then calling fetch_push_back_and_skip() the block is put back into the pipe but the next call to fetch() will provide the block after this one if there is one available. If no other block is available the calling thread will be suspended up to the feeder provides a new block of data. The block that has been put back this way to the tampon object is preserved.
once the next block is obtained by fetch() it can be remove from the pipe calling fetch_recycle(), put back in place and available for next fetch() calling fetch_push_back() or put back and having the cursor skipped one step further calling fetch_push_back_and_skip().

In that situation the block(s) at the head of the pipe (which is/are the one(s) for which fetch_push_back_and_skip() has been used) is/are still there but not readable. The fetcher has to call fetch_skip_back() to return the cursor at the beginning of the pipe in order to have access to them and possibly remove them from the pipe.

Definition at line 101 of file tampon.hpp.

Constructor & Destructor Documentation

◆ tampon()

template<class T >

libthreadar::tampon< T >::tampon	(	unsigned int	max_block,
		unsigned int	block_size
	)

constructor

Parameters

[in]	max_block	is the maximum number of buffers that can be written to without being read
[in]	block_size	is the maximum size of each buffer

Note: that the object will allocate max_block * block_size * sizeof(T) bytes in consequence

Definition at line 264 of file tampon.hpp.

◆ ~tampon()

template<class T >

libthreadar::tampon< T >::~tampon

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

Definition at line 304 of file tampon.hpp.

Member Function Documentation

◆ block_size()

template<class T >

unsigned int libthreadar::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 210 of file tampon.hpp.

◆ feed()

template<class T >

void libthreadar::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 tampon object

Parameters

[in]	ptr	address of the block to return to the tampon object
[in]	written	is 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 344 of file tampon.hpp.

◆ feed_cancel_get_block()

template<class T >

void libthreadar::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] ptr is the address of the block to put back in place for next feed

Definition at line 366 of file tampon.hpp.

◆ fetch()

template<class T >

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

fetcher call - step 1

obtain the next block to read

Parameters

[out]	ptr	is the address of the data to be read
[out]	num	is the number of element available for reading

Note: that the caller shall never release the address pointed to by ptr

Definition at line 375 of file tampon.hpp.

References THREADAR_BUG.

◆ fetch_push_back()

template<class T >

void libthreadar::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]	ptr	the address of the block to push back into the tampon object
[in]	new_num	is 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 452 of file tampon.hpp.

◆ fetch_push_back_and_skip()

template<class T >

void libthreadar::tampon< T >::fetch_push_back_and_skip	(	T *	ptr,
		unsigned int	new_num
	)

put back the fetched block and skip to next block for the next fetch()

Parameters

[in]	ptr	address of the fetched block to push back
[in]	new_num	possibily modified size of the fetched block to push back

Definition at line 463 of file tampon.hpp.

◆ fetch_recycle()

template<class T >

void libthreadar::tampon< T >::fetch_recycle ( T * ptr )

fetcher call - step 2

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

Parameters

[in] ptr the address of the block to recycle

Definition at line 402 of file tampon.hpp.

◆ get_block_to_feed()

template<class T >

void libthreadar::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]	ptr	the address where the caller can write data to
[out]	num	is 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 317 of file tampon.hpp.

References THREADAR_BUG.

◆ size()

template<class T >

unsigned int libthreadar::tampon< T >::size ( ) const

inline

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

Note: this is the max_block argument given at construction time

Definition at line 205 of file tampon.hpp.

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

tampon.hpp

Public Member Functions

Detailed Description

template<class T> class libthreadar::tampon< T >

Constructor & Destructor Documentation

◆ tampon()

◆ ~tampon()

Member Function Documentation

◆ block_size()

◆ feed()

◆ feed_cancel_get_block()

◆ fetch()

◆ fetch_push_back()

◆ fetch_push_back_and_skip()

◆ fetch_recycle()

◆ get_block_to_feed()

◆ size()

template<class T>
class libthreadar::tampon< T >