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::Endpoint const &src, Core::Endpoint const &dst, Core::MessagePtr &message)=0
	Called before a message is enqueued into the channel.
virtual HookResult	postDelivery (Core::Endpoint const &src, Core::Endpoint const &dst)=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::transmit() around the delivery operation:

preDelivery(): called before the message is passed to the destination transport
postDelivery(): called after the message is passed to the destination transport

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

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::Endpoint const &	src,
		Core::Endpoint const &	dst )

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	Endpoint from which the message originates.
dst	Endpoint 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::Endpoint const &	src,
		Core::Endpoint const &	dst,
		Core::MessagePtr &	message )

pure virtual

Called before a message is enqueued into the channel.

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.