Inter-thread communication primitive to send messages between threads Has a growable Queue. More...

#include <inbox.hpp>

Public Types
using	Message = T

Public Member Functions
Result< void, AllocationError >	init (Allocator &alloc, size_t initCapacity=10)
	Initializes a new message Queue.

void	deinit (Allocator &alloc)
	Cleans up memory Note: All references to the inbox MUST be cleaned up BEFORE calling this method.

void	close ()
	Closes an inbox.

Result< void, ChannelTrySendErrors >	try_send (const T &msg)
	Send message without blocking Will NOT grow inbox Queue and will instead fail.

Result< void, ChannelSendBlockErrors >	send_block (const T &msg)
	Send message, will block indefinitely Will NOT grow inbox Queue and will instead block.

template<typename Clock = std::chrono::steady_clock, typename Duration>
Result< void, ChannelSendBeforeErrors >	send_before (const T &msg, const std::chrono::time_point< Clock, Duration > &when)
	Send message before a timeout Will NOT grow inbox Queue and will instead block.

Result< void, ChannelGrowTrySendErrors >	try_send (Allocator &alloc, const T &msg)
	Send message without blocking Will grow inbox Queue if needed If unable to grow, will return an error.

Result< void, ChannelGrowSendBlockErrors >	send_block (Allocator &alloc, const T &msg)
	Send message and block indefinitely Will grow inbox Queue if needed If unable to grow, will instead block.

template<typename Clock = std::chrono::steady_clock, typename Duration>
Result< void, ChannelGrowSendBeforeErrors >	send_before (Allocator &alloc, const T &msg, const std::chrono::time_point< Clock, Duration > &when)
	Send message before a timeout Will grow inbox Queue if needed If unable to grow, will instead block.

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< T >	receive_block ()
	Receives a message from the channel Blocks indefinitely.

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

bool	is_initialized () const noexcept
	Checks if the inbox is initialized inboxes which aren't initialized will abort if used.

void	shrinkToFit (Allocator &alloc)
	Shrinks Queue to fit current Queue size Useful to lower memory usage.

Detailed Description

template<typename T>
struct mtcore::thread::Inbox< T >

Inter-thread communication primitive to send messages between threads Has a growable Queue.

Locks:

1 for entire data structure

Condition Variables:

2 condition variables (one to send, one to receive)

Non-Blocking Availability:

With Failure

Template Parameters

T	Type of messages to send

Definition at line 75 of file inbox.hpp.

Member Typedef Documentation

◆ Message

template<typename T>

using mtcore::thread::Inbox< T >::Message = T

Definition at line 84 of file inbox.hpp.

Member Function Documentation

◆ close()

template<typename T>

void mtcore::thread::Inbox< T >::close ( )

inline

Closes an inbox.

Does NOT clean up memory Memory cleanup must be handled by deinit

Definition at line 114 of file inbox.hpp.

                 {
      auto lock = std::unique_lock(channelMux);
      ensure(initialized(), "NOT INITIALIZED!");
      closed = true;
      send_cond.notify_all();
      read_cond.notify_all();
    }

◆ deinit()

template<typename T>

void mtcore::thread::Inbox< T >::deinit ( Allocator & alloc )

inline

Cleans up memory Note: All references to the inbox MUST be cleaned up BEFORE calling this method.

Parameters

alloc Allocator to use to clean up memory

Definition at line 104 of file inbox.hpp.

                                  {
      auto lock = std::unique_lock(channelMux);
      q.deinit(alloc);
      ensure(!initialized(), "CLEAN UP FAILED!");
    }

◆ init()

template<typename T>

Result< void, AllocationError > mtcore::thread::Inbox< T >::init	(	Allocator &	alloc,
		size_t	initCapacity = 10 )

inline

Initializes a new message Queue.

Parameters

alloc	Allocator to initialize Queue with
initCapacity	Initial capacity (can optionally grow)

Returns: success or failure

Definition at line 92 of file inbox.hpp.

                                                                                   {
      auto lock = std::unique_lock(channelMux);
      ensure(!initialized(), "Already initialized! memory leak detected!");
      return q.init(alloc, initCapacity);
    }

◆ is_initialized()

template<typename T>

bool mtcore::thread::Inbox< T >::is_initialized ( ) const

inlinenodiscardnoexcept

Checks if the inbox is initialized inboxes which aren't initialized will abort if used.

Returns: true if initialized, false otherwise

Definition at line 417 of file inbox.hpp.

                                                       {
      auto lock = std::unique_lock(channelMux);
      return initialized();
    }

◆ receive_before()

template<typename T>

template<typename Clock, typename Duration>

Result< Optional< T >, ChannelSendBeforeErrors > mtcore::thread::Inbox< T >::receive_before ( const std::chrono::time_point< Clock, Duration > & 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 394 of file inbox.hpp.

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

Here is the call graph for this function:

◆ receive_block()

template<typename T>

Optional< T > mtcore::thread::Inbox< T >::receive_block ( )

inlinenodiscard

Receives a message from the channel Blocks indefinitely.

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

Definition at line 372 of file inbox.hpp.

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

◆ send_before() [1/2]

template<typename T>

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

Result< void, ChannelGrowSendBeforeErrors > mtcore::thread::Inbox< T >::send_before	(	Allocator &	alloc,
		const T &	msg,
		const std::chrono::time_point< Clock, Duration > &	when )

inlinenodiscard

Send message before a timeout Will grow inbox Queue if needed If unable to grow, will instead block.

Template Parameters

Clock Clock for measuring time

Parameters

alloc	Allocator for growing Queue
msg	Message to send
when	Time point to send before

Returns: success or failure

Definition at line 297 of file inbox.hpp.

                                                                                                  {
      auto lock = std::unique_lock(channelMux, when);
      if (!lock.owns_lock()) {
        return error(ChannelGrowSendBeforeErrors::TIMEOUT);
      }
      ensure(initialized(), "NOT INITIALIZED!");
 
      if (is_closed()) {
        return error(ChannelGrowSendBeforeErrors::CHANNEL_CLOSED);
      }
 
      bool emit_notice = q.is_full();
 
      auto res = q.push(alloc, msg);
      if (res.is_error()) {
        ensure(res.error().code == AllocationError::ALLOCATION_FAILED);
        // If we couldn't resize, just wait for room
        emit_notice = false;
        while (!is_closed() && q.is_full()) {
          if (send_cond.wait_until(lock, when) == std::cv_status::timeout) {
            return error(ChannelGrowSendBeforeErrors::TIMEOUT);
          }
        }
 
        // check if we closed
        if (is_closed()) {
          return error(ChannelGrowSendBeforeErrors::CHANNEL_CLOSED);
        }
 
        // try sending again
        if (auto err = q.push(msg); err.is_error()) {
          return error(ChannelGrowSendBeforeErrors::ALLOCATION_FAILED);
        }
      }
      read_cond.notify_one();
 
      // tell everyone else our capacity has grown
      if (emit_notice) {
        send_cond.notify_all();
      }
      return success();
    }

Here is the call graph for this function:

◆ send_before() [2/2]

template<typename T>

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

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

inlinenodiscard

Send message before a timeout Will NOT grow inbox Queue and will instead block.

Template Parameters

Clock Clock for measuring time

Parameters

msg	Message to send
when	Time point to send before

Returns: success or failure

Definition at line 182 of file inbox.hpp.

                                                                                {
      auto lock = std::unique_lock(channelMux, when);
      if (!lock.owns_lock()) {
        return error(ChannelSendBeforeErrors::TIMEOUT);
      }
      ensure(initialized(), "NOT INITIALIZED!");
 
      while (!closed && q.is_full()) {
        if (send_cond.wait_until(lock, when) == std::cv_status::timeout) {
          return error(ChannelSendBeforeErrors::TIMEOUT);
        }
      }
      if (closed) {
        return error(ChannelSendBeforeErrors::CHANNEL_CLOSED);
      }
 
      (void) q.push(msg);
      read_cond.notify_one();
      return success();
    }

Here is the call graph for this function:

◆ send_block() [1/2]

template<typename T>

Result< void, ChannelGrowSendBlockErrors > mtcore::thread::Inbox< T >::send_block	(	Allocator &	alloc,
		const T &	msg )

inlinenodiscard

Send message and block indefinitely Will grow inbox Queue if needed If unable to grow, will instead block.

Parameters

alloc	Allocator for growing Queue
msg	Message to send

Returns: success or failure

Definition at line 245 of file inbox.hpp.

                                                                                                      {
      auto lock = std::unique_lock(channelMux);
      ensure(lock.owns_lock(), "DID NOT LOCK");
      ensure(initialized(), "NOT INITIALIZED!");
 
      while (!closed && q.is_full()) {
        send_cond.wait(lock);
      }
      if (closed) {
        return error(ChannelGrowSendBlockErrors::CHANNEL_CLOSED);
      }
 
      bool emit_notice = q.is_full();
      auto res         = q.push(alloc, msg);
      if (res.is_error()) {
        // If we couldn't resize, just wait for room
        emit_notice = false;
        while (!is_closed() && q.is_full()) {
          send_cond.wait(lock);
        }
 
        // check if we closed
        if (is_closed()) {
          return error(ChannelGrowSendBlockErrors::CHANNEL_CLOSED);
        }
 
        // try sending again
        if (auto err = q.push(msg); err.is_error()) {
          return error(ChannelGrowSendBlockErrors::ALLOCATION_FAILED);
        }
      }
      read_cond.notify_one();
 
      // tell everyone else our capacity has grown
      if (emit_notice) {
        send_cond.notify_all();
      }
      return success();
    }

Here is the call graph for this function:

◆ send_block() [2/2]

template<typename T>

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

inlinenodiscard

Send message, will block indefinitely Will NOT grow inbox Queue and will instead block.

Parameters

msg	Message to send

Returns: success or failure

Definition at line 155 of file inbox.hpp.

                                                                                {
      auto lock = std::unique_lock(channelMux);
      ensure(lock.owns_lock(), "DID NOT LOCK");
      ensure(initialized(), "NOT INITIALIZED!");
 
      while (!closed && q.is_full()) {
        send_cond.wait(lock);
      }
      if (closed) {
        return error(ChannelSendBlockErrors::CHANNEL_CLOSED);
      }
 
      (void) q.push(msg);
      read_cond.notify_one();
      return success();
    }

Here is the call graph for this function:

◆ shrinkToFit()

template<typename T>

void mtcore::thread::Inbox< T >::shrinkToFit ( Allocator & alloc )

inline

Shrinks Queue to fit current Queue size Useful to lower memory usage.

Parameters

alloc Allocator to use to free memory

Definition at line 427 of file inbox.hpp.

                                       {
      auto lock = std::unique_lock(channelMux);
      ensure(lock.owns_lock(), "DID NOT LOCK");
      ensure(initialized(), "NOT INITIALIZED!");
 
      q.shrink_to_fit(alloc);
    }

◆ try_receive()

template<typename T>

Result< Optional< T >, ChannelTryReceiveErrors > mtcore::thread::Inbox< T >::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 348 of file inbox.hpp.

                                                                             {
      auto lock = std::unique_lock(channelMux, std::try_to_lock_t{});
 
      if (!lock.owns_lock()) {
        return error(ChannelTryReceiveErrors::COULD_NOT_LOCK);
      }
      ensure(initialized(), "NOT INITIALIZED!");
 
      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() [1/2]

template<typename T>

Result< void, ChannelGrowTrySendErrors > mtcore::thread::Inbox< T >::try_send	(	Allocator &	alloc,
		const T &	msg )

inlinenodiscard

Send message without blocking Will grow inbox Queue if needed If unable to grow, will return an error.

Parameters

alloc	Allocator for growing Queue
msg	Message to send

Returns: success or failure

Definition at line 211 of file inbox.hpp.

                                                                                                  {
      auto lock = std::unique_lock(channelMux, std::try_to_lock_t{});
 
      if (!lock.owns_lock()) {
        return error(ChannelGrowTrySendErrors::COULD_NOT_LOCK);
      }
      ensure(initialized(), "NOT INITIALIZED!");
 
      if (closed) {
        return error(ChannelGrowTrySendErrors::CHANNEL_CLOSED);
      }
 
      bool emit_notice = q.is_full();
      auto res         = q.push(alloc, msg);
      if (res.is_error()) {
        return error(ChannelGrowTrySendErrors::ALLOCATION_FAILED);
      }
      read_cond.notify_one();
 
      // tell everyone else our capacity has grown
      if (emit_notice) {
        send_cond.notify_all();
      }
      return success();
    }

Here is the call graph for this function:

◆ try_send() [2/2]

template<typename T>

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

inlinenodiscard

Send message without blocking Will NOT grow inbox Queue and will instead fail.

Parameters

msg	Message to send

Returns: success or failure

Definition at line 128 of file inbox.hpp.

                                                                            {
      auto lock = std::unique_lock(channelMux, std::try_to_lock_t{});
      ensure(initialized(), "NOT INITIALIZED!");
 
      if (!lock.owns_lock()) {
        return error(ChannelTrySendErrors::CHANNEL_CLOSED);
      }
 
      if (closed) {
        return error(ChannelTrySendErrors::CHANNEL_CLOSED);
      }
 
      if (q.is_full()) {
        return error(ChannelTrySendErrors::NO_ROOM);
      }
 
      (void) q.push(msg);
      read_cond.notify_one();
      return success();
    }

Here is the call graph for this function:

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

inbox.hpp

Public Types

Public Member Functions

Detailed Description

Member Typedef Documentation

◆ Message

Member Function Documentation

◆ close()

◆ deinit()

◆ init()

◆ is_initialized()

◆ receive_before()

◆ receive_block()

◆ send_before() [1/2]

◆ send_before() [2/2]

◆ send_block() [1/2]

◆ send_block() [2/2]

◆ shrinkToFit()

◆ try_receive()

◆ try_send() [1/2]

◆ try_send() [2/2]