dfx_poller_api_t Struct Reference

Interface to the host's event loop (Poller). More...

#include <dfx-plugins-interface/PluginInterface.h>

Public Attributes
dfx_poller_handle_t	handle
	Internal host context. Must be passed as the first argument to all functions.
int(*	register_fd )(dfx_poller_handle_t handle, int fd, dfx_event_interest_t interests, dfx_fd_callback_t cb, void *user_data)
	Registers a file descriptor with the host's poller.
int(*	update_fd )(dfx_poller_handle_t handle, int fd, dfx_event_interest_t interests)
	Updates the event interests for a previously registered file descriptor.
void(*	deregister_fd )(dfx_poller_handle_t handle, int fd)
	Deregisters a file descriptor from the host's poller.
int(*	defer_call )(dfx_poller_handle_t handle, dfx_callback_t cb, void *user_data)
	Defers a function call to the next iteration of the event loop.

Detailed Description

Interface to the host's event loop (Poller).

This struct provides a bridge to the dfx::FdWatch::Poller. It allows plugins to register file descriptors (sockets, pipes, timers) to be monitored by the host's main event loop.

Member Data Documentation

defer_call

int(* dfx_poller_api_t::defer_call) (dfx_poller_handle_t handle, dfx_callback_t cb, void *user_data)

Defers a function call to the next iteration of the event loop.

This function allows the plugin to schedule a callback to be executed as soon as possible by the host's event loop thread, but not immediately. It is useful for:

• Avoiding deep recursion.
• Offloading work from a high-priority context.
• Ensuring a task runs after the current event processing cycle completes.

Parameters

[in]	handle	The poller handle provided in this struct.
[in]	cb	The callback function to be invoked.
[in]	user_data	Opaque pointer passed back to cb.

Note

This function is thread-safe and can be called from any thread.

Returns

DFX_OK on success, DFX_ERROR on error.

Errors

On failure, errno is set to:

• EINVAL: handle or cb is NULL.

See also

dfx::FdWatch::Poller::deferCall

deregister_fd

void(* dfx_poller_api_t::deregister_fd) (dfx_poller_handle_t handle, int fd)

Deregisters a file descriptor from the host's poller.

After this call, the host will no longer monitor the FD and the callback provided during registration will no longer be invoked.

Parameters

[in]	handle	The poller handle provided in this struct.
[in]	fd	The file descriptor to remove.

Note

It is safe to call this on an FD that is not currently registered.

This function is thread-safe and can be called from any thread.

Warning

The plugin is responsible for closing the FD after deregistration.

See also

dfx::FdWatch::Poller::deregisterFd

handle

dfx_poller_handle_t dfx_poller_api_t::handle

Internal host context. Must be passed as the first argument to all functions.

register_fd

int(* dfx_poller_api_t::register_fd) (dfx_poller_handle_t handle, int fd, dfx_event_interest_t interests, dfx_fd_callback_t cb, void *user_data)

Registers a file descriptor with the host's poller.

Once registered, the host will monitor fd for the specified interests. When an event occurs, cb will be invoked from the host's event loop thread.

Parameters

[in]	handle	The poller handle provided in this struct.
[in]	fd	The file descriptor to monitor. The plugin remains the owner of this FD.
[in]	interests	Mask of DFX_EVENT_READ, DFX_EVENT_WRITE, etc.
[in]	cb	The callback function to trigger on events.
[in]	user_data	User-provided pointer passed back to the callback (typically the transport handle).

Note

Registering an FD that is already registered is a no-op. To change interests, use update_fd.

This function is thread-safe and can be called from any thread.

Returns

DFX_OK on success, DFX_ERROR on error.

Errors

On failure, errno is set to:

• EINVAL: handle or cb is NULL, or interests is invalid.
• EBADF: fd is not a valid file descriptor.

See also

dfx::FdWatch::Poller::registerFd

update_fd

int(* dfx_poller_api_t::update_fd) (dfx_poller_handle_t handle, int fd, dfx_event_interest_t interests)

Updates the event interests for a previously registered file descriptor.

Use this to toggle between reading and writing, or to temporarily disable event triggers for an FD without deregistering it.

Parameters

[in]	handle	The poller handle provided in this struct.
[in]	fd	A previously registered file descriptor.
[in]	interests	The new mask of interests to apply.

Note

This function is thread-safe and can be called from any thread.

Returns

DFX_OK on success, DFX_ERROR on error.

Errors

On failure, errno is set to:

• EINVAL: handle is NULL, or interests is invalid.
• EBADF: fd is not a valid file descriptor.
• ENOENT: fd is not registered in this poller.

See also

dfx::FdWatch::Poller::updateFd

---

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

• lib/dfx-plugins-interface/PluginInterface.h