st::channel Struct Reference

Interthread message passing queue. More...

#include <channel.hpp>

Inheritance diagram for st::channel:

Classes
class	iterator
	implementation of an input iterator for st::channel More...

Public Member Functions
bool	closed () const
void	close (bool soft=true)
	st::channel is set to the closed state More...
std::size_t	blocked_receivers () const
bool	recv (st::message &msg)
	receive a message over the channel More...
state	try_recv (st::message &msg)
	do a non-blocking message receive over the channel More...
std::size_t	queued () const
template<typename... As>
bool	send (As &&... as)
	send an st::message with given parameters into the internal message queue More...
iterator	begin () const
iterator	end () const
template<typename F , typename... As>
bool	async (std::size_t resp_id, F &&f, As &&... as)
	asynchronously execute user Callable on a system thread More...
template<class Rep , class Period , typename P >
bool	timer (std::size_t resp_id, const std::chrono::duration< Rep, Period > &timeout, P &&payload)
	start a timer More...
template<class Rep , class Period >
bool	timer (std::size_t resp_id, const std::chrono::duration< Rep, Period > &timeout)
	start a timer More...

Static Public Member Functions
static channel	make ()
	Construct an allocated channel. More...

Detailed Description

Interthread message passing queue.

The internal mechanism used by this library to communicate between system threads.

All methods in this object are threadsafe.

Member Function Documentation

async()

template<typename F , typename... As>

bool st::channel::async ( std::size_t  resp_id, F &&  f, As &&...  as  )

inline

asynchronously execute user Callable on a system thread

Internally calls std::async to asynchronously execute user function (Callable). This behavior is useful for evaluating long running functions in a way that will not block the current thread. Additionally, the internal usage of std::async() allows for optimizations made by the standard library when launching temporary worker threads.

The resulting st::message's st::message::id() will equal the value of argument resp_id.

If the user function returns no value, then st::message::data() will be unallocated. Otherwise, st::message::data() will contain the value returned by Callable f.

Parameters

resp_id	of the message that will be sent back to the this st::channel when std::async completes
f	a Callable to execute on another system thread
as	optional arguments for f

Returns

true if the asynchronous call was scheduled, false if this st::channel is closed

begin()

iterator st::channel::begin ( ) const

inline

Returns

an iterator to the beginning of the channel

blocked_receivers()

std::size_t st::channel::blocked_receivers ( ) const

inline

Returns

count of system threads blocked on recv() for this st::channel

close()

void st::channel::close ( bool  soft = true )

inline

st::channel is set to the closed state

Parameters

soft	if false clear all messages from the internal message queue, otherwise leave messages to be received with recv()

closed()

bool st::channel::closed ( ) const

inline

Returns

true if the st::channel::close() has been called or if st::channel::make() was never called, else false

end()

iterator st::channel::end ( ) const

inline

If another st::channel::iterator == the iterator returned by this method, then the iterator has reached the end of the st::channel.

Returns

an iterator to the end of the channel

make()

static channel st::channel::make ( )

inlinestatic

Construct an allocated channel.

Returns

the allocated channel

queued()

std::size_t st::channel::queued ( ) const

inline

Returns

count of currently unhandled messages sent to the st::channel's queue

recv()

bool st::channel::recv ( st::message &  msg )

inline

receive a message over the channel

This is a blocking operation that will not complete until there is a message available in the message queue, after which the argument message reference will be overwritten by the front of the queue. The front of the queue will then be popped.

This will return early if st::channel::close(false) is called. If st::channel::close(true) or st::channel::close() is called instead, then calls to this function will succeed until the internal message queue is empty.

Multiple simultaneous recv() calls will be served in the order they were called.

Parameters

msg	interprocess message object reference to contain the received message

Returns

true on success, false if channel is closed

send()

template<typename... As>

bool st::channel::send ( As &&...  as )

inline

send an st::message with given parameters into the internal message queue

This method is non-blocking.

This method will immediately return false if the channel is closed or if argument is an empty st::message.

Parameters

as	arguments passed to st::message::make()

Returns

true on success, false if the st::channel is closed

timer() [1/2]

template<class Rep , class Period >

bool st::channel::timer ( std::size_t  resp_id, const std::chrono::duration< Rep, Period > &  timeout  )

inline

start a timer

This method is an abstraction of st::channel::async(). Once the timer elapses a message containing resp_id as its id will be sent back to this channel. The message data payload will be empty.

Parameters

resp_id	of the message to be sent back to this channel after timeout
timeout	a duration to elapse before timer times out

Returns

true if the timer was started, false if this st::channel is closed

timer() [2/2]

template<class Rep , class Period , typename P >

bool st::channel::timer ( std::size_t  resp_id, const std::chrono::duration< Rep, Period > &  timeout, P &&  payload  )

inline

start a timer

This method is an abstraction of st::channel::async(). Once the timer elapses a message containing resp_id as its id will be sent back to this channel.

Parameters

resp_id	of the message to be sent back to this channel after timeout
timeout	a duration to elapse before timer times out
payload	of the message to be sent back to this channel after timeout

Returns

true if the timer was started, false if this st::channel is closed

try_recv()

state st::channel::try_recv ( st::message &  msg )

inline

do a non-blocking message receive over the channel

Behavior of this function is the same as st::channel::recv() except that it can fail early and returns an enumeration instead of a boolean.

Parameters

msg	interprocess message object reference to contain the received message

Returns

the result state of the operation

---

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

• inc/channel.hpp