Channel is a message-passing primitive between two threads A channel has blocking and non-blocking (or auto timed out for a size of 0) methods Timeout methods are also present A channel will have a buffer size for how many messages can be queued up If there is a buffer size of 0, then a reader and writer must both be accessing the channel simultaneously for messages to be transmitted. More...

#include <channels.hpp>

Public Types
using	Message = T

Public Member Functions
void	close ()
	Closes the channel.

Result< void, ChannelTrySendErrors >	try_send (const T &msg)
	Tries to send a message Does not block If there is no room or would have to block for locking, will fail If the channel is closed, will fail.

Result< void, ChannelSendBlockErrors >	send_block (const T &msg)
	Will send a message (unless the channel is closed, then will fail) Will block as long as is needed to send a message.

template<typename Clock = std::chrono::steady_clock>
Result< void, ChannelSendBeforeErrors >	send_before (const T &msg, const std::chrono::time_point< Clock > &when)
	Will send a message (unless the channel is closed, will fail) Will block up to a certain time point, then will fail if unable to send before that time point.

Result< Optional< T >, ChannelTryReceiveErrors >	try_receive ()
	Tries to receive a message Will fail if it would have to block If the channel is empty and closed, will return nullopt instead of a message.

Optional< Message >	receive_block ()
	Receives a message from the channel Blocks indefinitely.

template<typename Clock>
Result< Optional< T >, ChannelReceiveBeforeErrors >	receive_before (const std::chrono::time_point< Clock > &when)
	Receives a message before a time point Blocks until a time point.

Detailed Description

template<typename T, size_t Size = 1>
struct mtcore::thread::Channel< T, Size >

Channel is a message-passing primitive between two threads A channel has blocking and non-blocking (or auto timed out for a size of 0) methods Timeout methods are also present A channel will have a buffer size for how many messages can be queued up If there is a buffer size of 0, then a reader and writer must both be accessing the channel simultaneously for messages to be transmitted.

Guaranteed to implement the ChannelLike trait

Locks:

1 lock for entire structure

Condition Variables:

2 condition variables (one to signal sending available, one to signal receiving available)

Non-Blocking Availability:

With Failure

Template Parameters

T	Message type
Size	Channel size

Definition at line 117 of file channels.hpp.

Member Typedef Documentation

◆ Message

template<typename T, size_t Size = 1>

using mtcore::thread::Channel< T, Size >::Message = T

Definition at line 128 of file channels.hpp.

Member Function Documentation

◆ close()

template<typename T, size_t Size = 1>

void mtcore::thread::Channel< T, Size >::close ( )

inline

Closes the channel.

Definition at line 133 of file channels.hpp.

                 {
      auto lock = std::unique_lock(channelMux);
      closed    = true;
      read_cond.notify_all();
      send_cond.notify_all();
    }

◆ receive_before()

template<typename T, size_t Size = 1>

template<typename Clock>

Result< Optional< T >, ChannelReceiveBeforeErrors > mtcore::thread::Channel< T, Size >::receive_before ( const std::chrono::time_point< Clock > & when )

inlinenodiscard

Receives a message before a time point Blocks until a time point.

If does not receive before then, will fail

Template Parameters

Clock Clock type for the time point

Parameters

when	When should it timeout

Returns: Message received or nullopt if channel is closed, or error if timed out

Definition at line 265 of file channels.hpp.

                                                           {
      auto lock = std::unique_lock(channelMux, when);
 
      if (!lock.owns_lock()) {
        return error(ChannelReceiveBeforeErrors::TIMEOUT);
      }
 
      while (!closed && q.is_empty()) {
        if (read_cond.wait_until(lock, when) == std::cv_status::timeout) {
          return error(ChannelReceiveBeforeErrors::TIMEOUT);
        }
      }
 
      ensure(lock.owns_lock(), "DID NOT LOCK");
      return readImpl();
    }

Here is the call graph for this function:

◆ receive_block()

template<typename T, size_t Size = 1>

Optional< Message > mtcore::thread::Channel< T, Size >::receive_block ( )

inlinenodiscard

Receives a message from the channel Blocks indefinitely.

Returns: Returns message received, or nullopt if channel is closed

Definition at line 244 of file channels.hpp.

                                                    {
      auto lock = std::unique_lock(channelMux);
 
      while (!closed && q.is_empty()) {
        read_cond.wait(lock);
      }
 
      ensure(lock.owns_lock(), "DID NOT LOCK");
      return readImpl();
    }

◆ send_before()

template<typename T, size_t Size = 1>

template<typename Clock = std::chrono::steady_clock>

Result< void, ChannelSendBeforeErrors > mtcore::thread::Channel< T, Size >::send_before	(	const T &	msg,
		const std::chrono::time_point< Clock > &	when )

inlinenodiscard

Will send a message (unless the channel is closed, will fail) Will block up to a certain time point, then will fail if unable to send before that time point.

Template Parameters

Clock Clock for tracking time with

Parameters

msg	Message to send
when	When should there be a timeout

Returns

Definition at line 192 of file channels.hpp.

                                                                                                            {
      auto lock = std::unique_lock(channelMux, when);
 
      if (!lock.owns_lock()) {
        return error(ChannelSendBeforeErrors::TIMEOUT);
      }
 
      while (!closed && q.is_full()) {
        if (send_cond.wait_until(lock, when) == std::cv_status::timeout) {
          return error(ChannelSendBeforeErrors::TIMEOUT);
        }
      }
 
      ensure(lock.owns_lock(), "DID NOT LOCK!");
      if (sendImpl(msg).is_error()) {
        return error(ChannelSendBeforeErrors::CHANNEL_CLOSED);
      }
      return success();
    }

Here is the call graph for this function:

◆ send_block()

template<typename T, size_t Size = 1>

Result< void, ChannelSendBlockErrors > mtcore::thread::Channel< T, Size >::send_block ( const T & msg )

inlinenodiscard

Will send a message (unless the channel is closed, then will fail) Will block as long as is needed to send a message.

Parameters

msg	Message to send

Returns: success or failure

Definition at line 172 of file channels.hpp.

                                                                                {
      auto lock = std::unique_lock(channelMux);
      while (!closed && q.is_full()) {
        send_cond.wait(lock);
      }
 
      ensure(lock.owns_lock(), "DID NOT LOCK!");
      return sendImpl(msg);
    }

◆ try_receive()

template<typename T, size_t Size = 1>

Result< Optional< T >, ChannelTryReceiveErrors > mtcore::thread::Channel< T, Size >::try_receive ( )

inlinenodiscard

Tries to receive a message Will fail if it would have to block If the channel is empty and closed, will return nullopt instead of a message.

Returns: Message, nullopt, or failure. Message if available, nullopt if closed, failure if would have to block

Definition at line 221 of file channels.hpp.

                                                                             {
      auto lock = std::unique_lock(channelMux, std::try_to_lock_t{});
 
      if (!lock.owns_lock()) {
        return error(ChannelTryReceiveErrors::COULD_NOT_LOCK);
      }
 
      if (q.is_empty()) {
        if (closed) {
          return readImpl();
        }
        return error(ChannelTryReceiveErrors::MESSAGE_NOT_READY);
      }
 
      ensure(lock.owns_lock(), "DID NOT LOCK!");
      return readImpl();
    }

Here is the call graph for this function:

◆ try_send()

template<typename T, size_t Size = 1>

Result< void, ChannelTrySendErrors > mtcore::thread::Channel< T, Size >::try_send ( const T & msg )

inlinenodiscard

Tries to send a message Does not block If there is no room or would have to block for locking, will fail If the channel is closed, will fail.

Parameters

msg	Message to send

Returns: success or failure

Definition at line 148 of file channels.hpp.

                                                                            {
      auto lock = std::unique_lock(channelMux, std::try_to_lock_t{});
 
      if (!lock.owns_lock()) {
        return error(ChannelTrySendErrors::COULD_NOT_LOCK);
      }
 
      if (q.is_full()) {
        return error(ChannelTrySendErrors::NO_ROOM);
      }
 
      ensure(lock.owns_lock(), "DID NOT LOCK!");
      if (sendImpl(msg).is_error()) {
        return error(ChannelTrySendErrors::CHANNEL_CLOSED);
      }
      return success();
    }

Here is the call graph for this function:

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

channels.hpp

Public Types

Public Member Functions

Detailed Description

Member Typedef Documentation

◆ Message

Member Function Documentation

◆ close()

◆ receive_before()

◆ receive_block()

◆ send_before()

◆ send_block()

◆ try_receive()

◆ try_send()