Triggers

Macros
#define	LTRX_TRIGGER_WAIT(trigger, timeout_in_milliseconds)
	Wait for a trigger. More...

Functions
void	ltrx_trigger_clear (struct ltrx_trigger *trigger)
	Clear a trigger. More...
bool	ltrx_trigger_create (struct ltrx_trigger *trigger, const char *name)
	Create a trigger. More...
bool	ltrx_trigger_destroy (struct ltrx_trigger *trigger)
	Destroy a trigger. More...
void	ltrx_trigger_signal (struct ltrx_trigger *trigger)
	Signal a trigger. More...

Detailed Description

A trigger facilitates directed wakeups among two or more concurrent threads.

One or more threads may wait on the same trigger.

One or more threads may signal the same trigger.

Macro Definition Documentation

#define LTRX_TRIGGER_WAIT	(		trigger,
			timeout_in_milliseconds
	)

Value:

ltrx_trigger_wait_do_not_call_directly( \
    __FILE__, __LINE__, trigger, timeout_in_milliseconds \
)

Wait for a trigger.

Block this thread up to the specified timeout_in_milliseconds while waiting for a trigger.

Trigger events are produced when any thread calls ltrx_trigger_signal().

Warning: Check the return value even if you specify TIME_WAIT_FOREVER because your thread can return early if another thread calls ltrx_thread_wake().

Parameters

[in,out]	trigger	Pointer to the trigger.
[in]	timeout_in_milliseconds	Time to wait for the trigger before giving up. To wait indefinitely, use TIME_WAIT_FOREVER.

Return values

true	Trigger was detected.
false	Failed to detect the trigger.

Function Documentation

void ltrx_trigger_clear

(

struct ltrx_trigger *

trigger

)

Clear a trigger.

Resets the trigger only from the point of view of this thread so that a subsequent LTRX_TRIGGER_WAIT call in this thread will wait for the first trigger event subsequent to this call.

Trigger events are produced when any thread calls ltrx_trigger_signal().

Parameters

[in,out]

trigger

Pointer to the trigger.

bool ltrx_trigger_create	(	struct ltrx_trigger *	trigger,
		const char *	name
	)

Create a trigger.

First you declare a struct to house the trigger, then initialize it by calling this function.

Return values

true	Trigger was successfully initialized.
false	Failed to initialize the trigger.

Parameters

[out]	trigger	Trigger struct to initialize.
[in]	name	Name of trigger.

bool ltrx_trigger_destroy

(

struct ltrx_trigger *

trigger

)

Destroy a trigger.

First you create the trigger via ltrx_trigger_create(). Later you may destroy it by calling this function.

Warning: This function must be called before the trigger struct itself is destroyed by going out of scope; otherwise the operating environment will be corrupted.

Return values

true	Trigger was successfully destroyed.
false	Failed to destroy the trigger.

Parameters

[in,out]

trigger

Pointer to the trigger.

void ltrx_trigger_signal

(

struct ltrx_trigger *

trigger

)

Signal a trigger.

This fires off a trigger event that one or more other threads may be waiting for.

Parameters

[in,out]

trigger

Pointer to the trigger.