Waiting for an event to complete. More...

Data Structures
struct	bio_signal_t
	Handle to a signal. More...

Functions
bio_signal_t	bio_make_signal (void)
	Create a new signal.

bool	bio_raise_signal (bio_signal_t signal)
	Raise a signal.

void	bio_raise_signal_after (bio_signal_t signal, bio_time_t time_ms)
	Raise a signal after a delay.

bool	bio_check_signal (bio_signal_t signal)
	Check whether a signal has been raised.

void	bio_wait_for_signals (bio_signal_t *signals, int num_signals, bool wait_all)
	Wait for signals to be raised.

static void	bio_wait_for_one_signal (bio_signal_t signal)
	Convenient function to wait for a single signal.

Detailed Description

Waiting for an event to complete.

Signal is the primary synchronization primitive in bio. When a coroutine needs to wait for something to happen, it would:

Create a new signal with bio_make_signal.
Pass the signal to a target through a function call or a mailbox.
Wait for the signal to be raised.

It is by design that a signal has no associated state like "future" or "promise" in other languages. This keeps the implementation simple as signal is only meant to be a notification mechanism. To transfer data, use a regular function call with a signal as one of the argument. In addition, there is also mailbox.

Internally, all I/O functions use signals to wait for completion.

Function Documentation

◆ bio_check_signal()

bool bio_check_signal ( bio_signal_t signal )

Check whether a signal has been raised.

Remarks: if the signal comes from an already terminated coroutine, this will always return true.

◆ bio_make_signal()

bio_signal_t bio_make_signal ( void )

Create a new signal.

A signal requires some dynamically allocated memory to track its state. When a signal is created but later deemed unnecessary, it should be discarded with bio_raise_signal. Otherwise, it will continue to take some memory. Signals are bound to the coroutine that created it. When a coroutine terminates, all signals bound to it are freed and no manual cleanup is needed.

See also: bio_wait_for_signals; bio_raise_signal

◆ bio_raise_signal()

bool bio_raise_signal ( bio_signal_t signal )

Raise a signal.

A coroutine waiting on the signal will be resumed. A signal can only be raised once. Raising an already raised signal is not an error. Similarly, it is safe to raise a signal from an already terminated coroutine.

See also: bio_make_signal

◆ bio_raise_signal_after()

void bio_raise_signal_after	(	bio_signal_t	signal,
		bio_time_t	time_ms
	)

Raise a signal after a delay.

This is the primary way to create "timers" in bio.

Parameters

signal	The signal to raise
time_ms	The delay in milliseconds to raise this signal

See also: Timer; bio_raise_signal

◆ bio_wait_for_one_signal()

static void bio_wait_for_one_signal ( bio_signal_t signal )

inlinestatic

Convenient function to wait for a single signal.

See also: bio_wait_for_signals

◆ bio_wait_for_signals()

void bio_wait_for_signals	(	bio_signal_t *	signals,
		int	num_signals,
		bool	wait_all
	)

Wait for signals to be raised.

The calling coroutine will be suspended until all or one of the provided signals is raised (depending on wait_all).

Signals are bound to the coroutines that created it. Only the coroutine that created a signal can wait on that signal. However, any coroutine can raise any signal.

It is not an error to pass a signal created by a different coroutine to this function. However, they will be ignored.

Passing an already raised signal to this function is also safe. When wait_all is false, the calling coroutine would immediately continue execution since at least one signal in the array has been raised.

If all provided signals are already raised or ignored, this function will immediately return. The calling coroutine will continue to execute without switching to another coroutine.