carb::tasking::IFiberEvents

struct IFiberEvents

Defines the fiber events interface that receives fiber-related notifications.

This is a reverse interface. It is not implemented by carb.tasking.plugin. Instead, carb.tasking.plugin looks for all instances of this interface and will call the functions to inform other plugins of fiber events. This can be used, for example, by a profiler that wants to keep track of which fiber is running on a thread.

Once IFiberEvents::notifyFiberStart() has been called, this is a signal to the receiver that a task is executing on the current thread, and will be executing on the current thread until IFiberEvents::notifyFiberStop() is called on the same thread. Between these two calls, the thread is executing in Task context, that is, within a task submitted to carb.tasking.plugin. As such, it is possible to query information about the task, such as the context handle ( ITasking::getTaskContext()) or access task-local storage ( ITasking::getTaskStorage() / ITasking::setTaskStorage()). However, anything that could cause a task to yield is strictly prohibited in these functions and will produce undefined behavior. This includes but is not limited to yielding, waiting on any task-aware synchronization primitive (i.e. locking a Mutex), sleeping in a task-aware manner, suspending a task, etc.

Note

Notification functions are called in the context of the thread which caused the fiber event.

Warning

carb.tasking.plugin queries for all IFiberEvents interfaces only during startup, during ITasking::changeParameters() and ITasking::reloadFiberEvents(). If a plugin is loaded which exports IFiberEvents then you must perform one of these methods to receive notifications about fiber events.

Warning

DO NOT EVER call the functions; only carb.tasking.plugin should be calling these functions. Receiving one of these function calls implies that carb.tasking.plugin is loaded, and these function calls can be coordinated with certain carb.tasking.plugin actions (reading task-specific data, for instance).

Public Members

void (*notifyFiberStart)(const uint64_t fiberId)

Specifies that a fiber started or resumed execution on the calling thread.

Specifies that the calling thread is now running fiber with ID fiberId until notifyFiberStop() is called on the same thread.

Note

A thread switching fibers will always call notifyFiberStop() before calling notifyFiberStart() with the new fiber ID.

Param fiberId: A unique identifier for a fiber.

void (*notifyFiberStop)(const uint64_t fiberId)

Specifies that a fiber yielded execution on the calling thread.

It may or may not restart again at some later point, on the same thread or a different one.

Specifies that the calling thread has yielded fiber with ID fiberId and is now running its own context.

Param fiberId: A unique identifier for a fiber.

Public Static Functions

static inline constexpr carb::InterfaceDesc getInterfaceDesc() noexcept

Returns information about this interface.

Auto-generated by CARB_PLUGIN_INTERFACE() or CARB_PLUGIN_INTERFACE_EX.

Returns: The carb::InterfaceDesc struct with information about this interface.

static inline constexpr carb::InterfaceDesc getLatestInterfaceDesc() noexcept

Returns information about the latest version of this interface.

Auto-generated by CARB_PLUGIN_INTERFACE() or CARB_PLUGIN_INTERFACE_EX.

Returns: The carb::InterfaceDesc struct with information about the latest version of this interface.