PluginInterface.h File Reference

C-ABI for the dfx framework plugin system. More...

Include dependency graph for PluginInterface.h:

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Classes
struct	dfx_env_api_t
	Host environment services provided to the plugin. More...
struct	dfx_poller_api_t
	Interface to the host's event loop (Poller). More...
struct	dfx_task_api_t
	Host-provided API for interacting with a scheduled task. More...
struct	dfx_task_executor_interface_t
	Interface for a plugin-defined task executor. More...
struct	dfx_message_api_t
	Host-provided API for interrogating message handles. More...
struct	dfx_node_api_t
	Host-provided services for a node instance. More...
struct	dfx_node_interface_t
	The vtable that a plugin must implement to define a Node. More...
struct	dfx_transport_interface_t
	The Transport Plugin Interface. More...
struct	dfx_registration_api_t
	Transient registration context used during plugin discovery. More...

Macros
#define	DFX_OK   0
	Returned value in case of success.
#define	DFX_ERROR   -1
	Returned value in case of error.
#define	DFX_INVALID_PORT_ID   UINT32_MAX
	Represent an invalid port ID.
#define	DFX_INVALID_SIZE   SIZE_MAX
	Represent an invalid size.
#define	DFX_PLUGIN_VISIBLE_ATTR   __attribute__((visibility("default")))
	Used to mark a symbol as exported a.k.a. visible.
#define	DFX_PLUGIN_METADATA(json_str)
	Used to declare JSON metadata and place it in a dedicated ELF section .dfx_metadata.
Logging Levels
Standardized levels passed to the host's log callback.
#define	DFX_LOG_LEVEL_TRACE   0
	Equivalent to spdlog::level::trace.
#define	DFX_LOG_LEVEL_DEBUG   1
	Equivalent to spdlog::level::debug.
#define	DFX_LOG_LEVEL_INFO   2
	Equivalent to spdlog::level::info.
#define	DFX_LOG_LEVEL_WARN   3
	Equivalent to spdlog::level::warn.
#define	DFX_LOG_LEVEL_ERROR   4
	Equivalent to spdlog::level::err.
#define	DFX_LOG_LEVEL_CRITICAL   5
	Equivalent to spdlog::level::critical.

Typedefs
typedef void(*	dfx_fd_callback_t) (int fd, dfx_event_trigger_t events, void *user_data)
	Callback signature for file descriptor events.
typedef void(*	dfx_callback_t) (void *user_data)
	General purpose callback signature.
typedef int(*	dfx_on_message_received_t) (uint8_t const *message, size_t size, void *host_ctx)
	Callback signature for Source transport plugins to push data to the host.
Handle
typedef void *	dfx_transport_handle_t
	Opaque handle representing a transport instance created by the plugin.
typedef void *	dfx_node_handle_t
	Opaque handle representing a node instance created by the plugin.
typedef void *	dfx_node_api_handle_t
	Opaque handle representing a node instance created by the host.
typedef void *	dfx_env_handle_t
	Opaque handle representing the env context created by the host.
typedef void *	dfx_poller_handle_t
	Opaque handle representing the poller instance created by the host.
typedef void *	dfx_message_handle_t
	Opaque handle representing a message instance created by the host.
typedef void *	dfx_registration_handle_t
	Opaque handle representing a registration instance created by the host.
typedef void *	dfx_task_handle_t
	Opaque handle representing a task instance created by the host.
typedef void *	dfx_task_executor_handle_t
	Opaque handle representing a custom node executor created by the plugin.

Functions
Plugin entrypoint
DFX_PLUGIN_VISIBLE_ATTR int	dfx_init_plugin (dfx_env_api_t const *env, size_t env_size, dfx_registration_api_t const *reg, size_t reg_size, char const *plugin_config, char const *base_path)
	Main entry point to initialize the plugin.
DFX_PLUGIN_VISIBLE_ATTR void	dfx_deinit_plugin (dfx_env_api_t const *env, size_t env_size)
	Cleanup entry point called before the plugin is unloaded.

Event Interest Flags
Used to register which FD events (with dfx_poller_api_t::register_fd) the plugin wants to listen for. Matches dfx::FdWatch::EventInterests. dfx::FdWatch::EventInterest::OneShot is not represented here since in the context of the plugins it is forced and the FD is automatically re-armed after the callback has finished its work.
#define	DFX_EVENT_READ   0x01u
	Equivalent to dfx::FdWatch::EventInterest::Read.
#define	DFX_EVENT_WRITE   0x02u
	Equivalent to dfx::FdWatch::EventInterest::Write.
#define	DFX_EVENT_READ_CLOSE   0x04u
	Equivalent to dfx::FdWatch::EventInterest::ReadClose.
#define	DFX_EVENT_MASK   (DFX_EVENT_READ | DFX_EVENT_WRITE | DFX_EVENT_READ_CLOSE)
	Internal mask of all valid interest bits.
typedef uint32_t	dfx_event_interest_t
	C-compatible event triggers matching dfx::FdWatch::EventInterests.

Event Trigger Flags
Signals which events actually occurred on an FD. Matches dfx::FdWatch::EventTriggers.
#define	DFX_EVENT_READABLE   0x01u
	Equivalent to dfx::FdWatch::EventTrigger::Readable.
#define	DFX_EVENT_WRITABLE   0x02u
	Equivalent to dfx::FdWatch::EventTrigger::Writable.
#define	DFX_EVENT_PEER_CLOSED   0x04u
	Equivalent to dfx::FdWatch::EventTrigger::PeerClosed.
#define	DFX_EVENT_HANGUP   0x08u
	Equivalent to dfx::FdWatch::EventTrigger::Hangup.
#define	DFX_EVENT_ERROR   0x10u
	Equivalent to dfx::FdWatch::EventTrigger::Error.
typedef uint32_t	dfx_event_trigger_t
	C-compatible event triggers matching dfx::FdWatch::EventTriggers.

Port/Message Kinds
#define	DFX_KIND_INVALID   UINT32_MAX
	Represent an invalid port dfx::Core::Kind.
#define	DFX_KIND_DATA   0u
	Equivalent to dfx::Core::Kind::Data.
#define	DFX_KIND_CONTROL   1u
	Equivalent to dfx::Core::Kind::Control.
typedef uint32_t	dfx_port_kind_t
	C-compatible kind matching dfx::Core::Kind.

Detailed Description

C-ABI for the dfx framework plugin system.

This file defines the binary contract between the dfx core (Host) and external plugins (Nodes and Transports). To ensure clarity in ownership and responsibility, this library distinguishes between two types of structures:

• Interfaces (_interface_t): These are "Plugin-side" implementations. They contain function pointers that the plugin MUST provide for the Host to call. They define the behavior of the plugin.
• APIs (_api_t): These are "Host-side" services. They contain function pointers provided by the dfx core that the plugin MAY call to interact with the graph, interrogate messages, or access environment services.

This separation ensures that plugins can be written in any language with C interoperability while maintaining performance parity and strict architectural boundaries with native C++ components.

Macro Definition Documentation

DFX_ERROR

#define DFX_ERROR   -1

Returned value in case of error.

DFX_EVENT_ERROR

#define DFX_EVENT_ERROR   0x10u

Equivalent to dfx::FdWatch::EventTrigger::Error.

DFX_EVENT_HANGUP

#define DFX_EVENT_HANGUP   0x08u

Equivalent to dfx::FdWatch::EventTrigger::Hangup.

DFX_EVENT_MASK

#define DFX_EVENT_MASK   (DFX_EVENT_READ | DFX_EVENT_WRITE | DFX_EVENT_READ_CLOSE)

Internal mask of all valid interest bits.

DFX_EVENT_PEER_CLOSED

#define DFX_EVENT_PEER_CLOSED   0x04u

Equivalent to dfx::FdWatch::EventTrigger::PeerClosed.

DFX_EVENT_READ

#define DFX_EVENT_READ   0x01u

Equivalent to dfx::FdWatch::EventInterest::Read.

DFX_EVENT_READ_CLOSE

#define DFX_EVENT_READ_CLOSE   0x04u

Equivalent to dfx::FdWatch::EventInterest::ReadClose.

DFX_EVENT_READABLE

#define DFX_EVENT_READABLE   0x01u

Equivalent to dfx::FdWatch::EventTrigger::Readable.

DFX_EVENT_WRITABLE

#define DFX_EVENT_WRITABLE   0x02u

Equivalent to dfx::FdWatch::EventTrigger::Writable.

DFX_EVENT_WRITE

#define DFX_EVENT_WRITE   0x02u

Equivalent to dfx::FdWatch::EventInterest::Write.

DFX_INVALID_PORT_ID

#define DFX_INVALID_PORT_ID   UINT32_MAX

Represent an invalid port ID.

DFX_INVALID_SIZE

#define DFX_INVALID_SIZE   SIZE_MAX

Represent an invalid size.

DFX_KIND_CONTROL

#define DFX_KIND_CONTROL   1u

Equivalent to dfx::Core::Kind::Control.

DFX_KIND_DATA

#define DFX_KIND_DATA   0u

Equivalent to dfx::Core::Kind::Data.

DFX_KIND_INVALID

#define DFX_KIND_INVALID   UINT32_MAX

Represent an invalid port dfx::Core::Kind.

DFX_LOG_LEVEL_CRITICAL

#define DFX_LOG_LEVEL_CRITICAL   5

Equivalent to spdlog::level::critical.

DFX_LOG_LEVEL_DEBUG

#define DFX_LOG_LEVEL_DEBUG   1

Equivalent to spdlog::level::debug.

DFX_LOG_LEVEL_ERROR

#define DFX_LOG_LEVEL_ERROR   4

Equivalent to spdlog::level::err.

DFX_LOG_LEVEL_INFO

#define DFX_LOG_LEVEL_INFO   2

Equivalent to spdlog::level::info.

DFX_LOG_LEVEL_TRACE

#define DFX_LOG_LEVEL_TRACE   0

Equivalent to spdlog::level::trace.

DFX_LOG_LEVEL_WARN

#define DFX_LOG_LEVEL_WARN   3

Equivalent to spdlog::level::warn.

DFX_OK

#define DFX_OK   0

Returned value in case of success.

DFX_PLUGIN_METADATA

#define DFX_PLUGIN_METADATA

(

json_str

)

Value:

    __attribute__((section(".dfx_metadata"), used)) \
    char const _dfx_metadata_blob[] = json_str

Used to declare JSON metadata and place it in a dedicated ELF section .dfx_metadata.

DFX_PLUGIN_VISIBLE_ATTR

#define DFX_PLUGIN_VISIBLE_ATTR   __attribute__((visibility("default")))

Used to mark a symbol as exported a.k.a. visible.

Typedef Documentation

dfx_callback_t

typedef void(* dfx_callback_t) (void *user_data)

General purpose callback signature.

Parameters

[in]

user_data

Data provided during registration of the callback.

dfx_env_handle_t

typedef void* dfx_env_handle_t

Opaque handle representing the env context created by the host.

dfx_event_interest_t

typedef uint32_t dfx_event_interest_t

C-compatible event triggers matching dfx::FdWatch::EventInterests.

dfx_event_trigger_t

typedef uint32_t dfx_event_trigger_t

C-compatible event triggers matching dfx::FdWatch::EventTriggers.

dfx_fd_callback_t

typedef void(* dfx_fd_callback_t) (int fd, dfx_event_trigger_t events, void *user_data)

Callback signature for file descriptor events.

Parameters

[in]	fd	The file descriptor that triggered.
[in]	events	The triggered events (mask of DFX_EVENT_READABLE, etc).
[in]	user_data	Data provided during registration.

dfx_message_handle_t

typedef void* dfx_message_handle_t

Opaque handle representing a message instance created by the host.

dfx_node_api_handle_t

typedef void* dfx_node_api_handle_t

Opaque handle representing a node instance created by the host.

dfx_node_handle_t

typedef void* dfx_node_handle_t

Opaque handle representing a node instance created by the plugin.

dfx_on_message_received_t

typedef int(* dfx_on_message_received_t) (uint8_t const *message, size_t size, void *host_ctx)

Callback signature for Source transport plugins to push data to the host.

Parameters

[in]	message	Raw byte array of a single, fully-formed "packed" message.
[in]	size	Size of the message in bytes.
[in]	host_ctx	The context provided during build_source.

Returns

0 on success, non-zero on failure.

dfx_poller_handle_t

typedef void* dfx_poller_handle_t

Opaque handle representing the poller instance created by the host.

dfx_port_kind_t

typedef uint32_t dfx_port_kind_t

C-compatible kind matching dfx::Core::Kind.

dfx_registration_handle_t

typedef void* dfx_registration_handle_t

Opaque handle representing a registration instance created by the host.

dfx_task_executor_handle_t

typedef void* dfx_task_executor_handle_t

Opaque handle representing a custom node executor created by the plugin.

dfx_task_handle_t

typedef void* dfx_task_handle_t

Opaque handle representing a task instance created by the host.

dfx_transport_handle_t

typedef void* dfx_transport_handle_t

Opaque handle representing a transport instance created by the plugin.

Function Documentation

dfx_deinit_plugin()

DFX_PLUGIN_VISIBLE_ATTR void dfx_deinit_plugin	(	dfx_env_api_t const *	env,
		size_t	env_size )

Cleanup entry point called before the plugin is unloaded.

This is only called if dfx_init_plugin previously returned 0. The plugin should release all global resources, stop any running VMs, and prepare for dlclose.

This function is optional and a plugin doesn't have to declare it if no particular cleanup step should be taken.

Parameters

env	Pointer to the host environment services. Same as the one passed during dfx_init_plugin.
env_size	Size of the dfx_env_api_t structure.

dfx_init_plugin()

DFX_PLUGIN_VISIBLE_ATTR int dfx_init_plugin	(	dfx_env_api_t const *	env,
		size_t	env_size,
		dfx_registration_api_t const *	reg,
		size_t	reg_size,
		char const *	plugin_config,
		char const *	base_path )

Main entry point to initialize the plugin.

This is called by the host immediately after the library is loaded. The plugin should initialize its internal state and register its capabilities using the provided reg context.

Parameters

env	Pointer to the host environment services. Valid until dfx_deinit_plugin returns.
env_size	Size of the dfx_env_api_t structure.
reg	Transient registration context. Valid ONLY for the duration of this function call.
reg_size	Size of the dfx_registration_api_t structure.
plugin_config	JSON plugin specific configuration. This pointer is valid only for the duration of this call.
base_path	Base path that must be used when resolving relative path from the configuration.

Returns

DFX_OK on success. On failure, returns any non-zero value which triggers the host to immediately unload the plugin without calling deinit.