Hook interface invoked around message enqueue in an dfx::Core::Channel. More...

#include <dfx-hooks/Delivery.hpp>

Inheritance diagram for dfx::Hooks::Delivery:

Public Types
enum class	HookResult { Proceed , Skip , Fail }
	Result code controlling pushMessage() behavior. More...

Public Member Functions
virtual HookResult	preDelivery (Core::NodePtr src, Core::OutputPort const &out, Core::NodePtr dst, Core::InputPort &in, Core::MessagePtr &message)=0
	Called before a message is enqueued into the channel.
virtual HookResult	postDelivery (Core::NodePtr src, Core::OutputPort const &out, Core::NodePtr dst, Core::InputPort &in)=0
	Called after a message has been enqueued into the channel.

Detailed Description

Hook interface invoked around message enqueue in an dfx::Core::Channel.

The dfx runtime transports messages from an output port to an input port through channels. Delivery hooks are invoked by dfx::Core::Channel::pushMessage() around the enqueue operation:

preDelivery(): called before the message is enqueued
postDelivery(): called after the message is enqueued

In this context, "delivery" means "accepted into the channel queue", not "consumed" nor "processed" by the destination node.

When hooks are called

Hooks are invoked only when:

a hook instance is installed on the channel, and
both ports can provide non-null nodes (src and dst).

Hooks are not invoked when:

the queue is full (push fails early),
the hook pointer is null,
src or dst node is null.

Member Enumeration Documentation

◆ HookResult

enum class dfx::Hooks::Delivery::HookResult

strong

Result code controlling pushMessage() behavior.

This enum is interpreted by dfx::Core::Channel::pushMessage() as follows:

Proceed:
- preDelivery(): enqueue proceeds.
- postDelivery(): pushMessage() continues and returns true.
Skip:
- preDelivery(): pushMessage() returns true immediately and the message is not enqueued (i.e., it is dropped/suppressed by the hook).
- postDelivery(): pushMessage() returns true immediately (message is already enqueued).
Fail:
- preDelivery(): pushMessage() returns false and the message is not enqueued.
- postDelivery(): pushMessage() returns false even though the message was already enqueued successfully.

Warning: Returning Fail from postDelivery() does not roll back the enqueue. The caller sees failure, but the destination side can still receive the message. If you need transactional semantics, you do not have them here.

Enumerator
Proceed	Continue normal execution.
Skip	Short-circuit without error (pre: drop message, post: just return success).
Fail	Short-circuit with error (pre: drop message, post: report failure after enqueue).

Member Function Documentation

◆ postDelivery()

virtual HookResult dfx::Hooks::Delivery::postDelivery	(	Core::NodePtr	src,
		Core::OutputPort const &	out,
		Core::NodePtr	dst,
		Core::InputPort &	in )

pure virtual

Called after a message has been enqueued into the channel.

This callback indicates that the message was accepted into the channel queue. It does not imply that the destination node has consumed or processed the message yet.

Parameters

src	Source node owning the output port.
out	Output port from which the message originates.
dst	Destination node owning the input port.
in	Input port that will receive the message (via the channel).

Returns: HookResult controlling whether pushMessage() reports success.

Warning: If this hook returns Fail, pushMessage() returns false even though the message is already enqueued. Use Fail here only if you explicitly want "report failure" semantics without rollback.

Note: If the queue was full, this hook is not called (push fails before enqueue).

Implemented in dfx::Runtime::Scheduler.

◆ preDelivery()

virtual HookResult dfx::Hooks::Delivery::preDelivery	(	Core::NodePtr	src,
		Core::OutputPort const &	out,
		Core::NodePtr	dst,
		Core::InputPort &	in,
		Core::MessagePtr &	message )

pure virtual

Called before a message is enqueued into the channel.

This callback runs only when the channel is not full.
The hook may inspect the message and may modify or replace it by writing to message.
If the hook returns Skip, the message is suppressed: pushMessage() returns true and nothing is enqueued.
If the hook returns Fail, pushMessage() returns false and nothing is enqueued.