dfx::Core::SPSCChannel Class Reference

Bounded SPSC (Single Producer / Single Consumer) channel. More...

#include <dfx-core/channels/SPSCChannel.hpp>

Inheritance diagram for dfx::Core::SPSCChannel:

Collaboration diagram for dfx::Core::SPSCChannel:

Public Member Functions
bool	pushMessage (MessagePtr msg) override
	Enqueue a message coming from the producer side.
bool	hasPendingMessage () const override
	Whether at least one message is pending.
std::size_t	pendingMessageCount () const override
	Number of pending messages currently buffered.
std::optional< MessagePtr >	pop () override
	Pop the next pending message.
	Channel (Id id, InputPort &inputPort, OutputPort &outputPort)
	Construct a channel linking one input port to one output port.
Public Member Functions inherited from dfx::Core::Channel
	Channel (Id id, InputPort &inputPort, OutputPort &outputPort)
	Construct a channel linking one input port to one output port.
	DISABLE_COPY_AND_MOVE (Channel)
	Channel is not copiable nor movable.
virtual	~Channel ()=default
	Virtual destructor.
Id	id () const noexcept
	Get the channel id.
template<DerivedFromChannel T>
bool	is () const noexcept
	Check whether this channel is of a given derived type.
template<DerivedFromChannel T>
T &	as () noexcept
	Cast this channel to a derived type (unchecked).
template<DerivedFromChannel T>
T const &	as () const noexcept
	Cast this channel to a derived type (unchecked).
InputPort &	inputPort () const noexcept
	Destination (consumer) endpoint of this channel.
OutputPort &	outputPort () const noexcept
	Source (producer) endpoint of this channel.
void	setDeliveryHook (Hooks::Delivery *hook)
	Set the optional delivery hook for this channel.

Additional Inherited Members
Public Types inherited from dfx::Core::Channel
using	Id = uint32_t
	Identifier type (unique within a graph instance, by convention).
Protected Attributes inherited from dfx::Core::Channel
InputPort &	_inputPort
	Destination port (consumer).
OutputPort &	_outputPort
	Source port (producer).
Hooks::Delivery *	_deliveryHook = nullptr
	Optional delivery hook (non-owning).

Detailed Description

Bounded SPSC (Single Producer / Single Consumer) channel.

Concurrency model

This channel is intended for one producer and one consumer. Using multiple producers or multiple consumers concurrently is undefined. And this is perfect for a Channel since it can only have 1 OutputPort a.k.a. the producer and 1 InputPort a.k.a. the consumer.

Capacity / backpressure

The queue has a fixed capacity of 64 messages.

• If the queue is full, pushMessage returns false and the message is rejected.

Delivery hooks

If a delivery hook is installed on the base Channel (see Channel::setDeliveryHook), pushMessage invokes it as follows (only when both endpoint nodes can be locked):

• preDelivery(srcNode, outPort, dstNode, inPort, msg) is called before enqueue.
  • Proceed: continue
  • Skip: treat as success and do not enqueue
  • Fail: return false and do not enqueue
• After a successful enqueue, postDelivery(...) is called.
  • Proceed: continue
  • Skip: treated as success
  • Fail: returns false even though the message is already enqueued

Note

The post-delivery Fail/Skip results do not roll back the enqueue.

Member Function Documentation

Channel()

dfx::Core::Channel::Channel	(	Id	id,
		InputPort &	inputPort,
		OutputPort &	outputPort )

Construct a channel linking one input port to one output port.

Parameters

id	Channel id.
inputPort	Destination port (consumer).
outputPort	Source port (producer).

hasPendingMessage()

bool dfx::Core::SPSCChannel::hasPendingMessage ( ) const

overridevirtual

Whether at least one message is pending.

Implements dfx::Core::Channel.

pendingMessageCount()

std::size_t dfx::Core::SPSCChannel::pendingMessageCount ( ) const

overridevirtual

Number of pending messages currently buffered.

Implements dfx::Core::Channel.

pop()

std::optional< MessagePtr > dfx::Core::SPSCChannel::pop ( )

overridevirtual

Pop the next pending message.

Uses a non-blocking peek (tryFront()), then moves the stored pointer out and removes the element from the queue.

Returns

The next message if available, otherwise std::nullopt.

Implements dfx::Core::Channel.

pushMessage()

bool dfx::Core::SPSCChannel::pushMessage ( MessagePtr msg )

overridevirtual

Enqueue a message coming from the producer side.

Parameters

msg	Message to enqueue.

Returns

true if accepted (enqueued or skipped by hook), false if rejected.

Implements dfx::Core::Channel.

---

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

• lib/dfx-core/channels/SPSCChannel.hpp