The internal class Fl_Timeout handles all timeout related functions. More...

#include <Fl_Timeout.h>

Static Public Member Functions
static void	add_timeout (double time, Fl_Timeout_Handler cb, void *data)
	Adds a one-shot timeout callback.

static void	do_timeouts ()
	Elapse timers and call their callbacks if any timers are expired.

static void	elapse_timeouts ()
	Elapse all timers w/o calling their callbacks.

static int	has_timeout (Fl_Timeout_Handler cb, void *data)
	Returns true if the timeout exists and has not been called yet.

static void	remove_timeout (Fl_Timeout_Handler cb, void *data)
	Remove a timeout callback.

static void	repeat_timeout (double time, Fl_Timeout_Handler cb, void *data)
	Repeats a timeout callback from the expiration of the previous timeout, allowing for more accurate timing.

static double	time_to_wait (double ttw)
	Returns the delay in seconds until the next timer expires, limited by `ttw`.

Protected Member Functions
double	delay ()
	Get the timer's delay in seconds.

void	delay (double t)
	Set the timer's delay in seconds.

void	insert ()
	Insert this timer entry into the active timer queue.

void	make_current ()
	Remove the timeout from the active timer queue and push it onto the stack of currently running callbacks.

void	release ()
	Remove the top-most timeout from the stack of currently running timeout callbacks and insert it into the list of free timers.

Static Protected Member Functions
static Fl_Timeout *	current ()
	Returns the first (top-most) timeout from the current timeout stack.

static Fl_Timeout *	get (double time, Fl_Timeout_Handler cb, void *data)
	Get an Fl_Timeout instance for further handling.

Protected Attributes
Fl_Timeout_Handler	callback

void *	data

Fl_Timeout *	next

int	skip

double	time

Static Protected Attributes
static Fl_Timeout *	current_timeout = 0
	The list of current timeouts is used to store the timeout whose callback is called while the callback is executed.

static Fl_Timeout *	first_timeout = 0
	List of active timeouts.

static Fl_Timeout *	free_timeout = 0
	List of free timeouts after use.

Detailed Description

The internal class Fl_Timeout handles all timeout related functions.

All code is platform independent except retrieving a timestamp which requires calling a system driver function and potentially results in different timer resolutions (from milliseconds to microseconds).

Member Function Documentation

◆ add_timeout()

void Fl_Timeout::add_timeout	(	double	time,
		Fl_Timeout_Handler	cb,
		void *	data
	)

static

Adds a one-shot timeout callback.

The callback function cb will be called by Fl::wait() at time seconds after this function is called.

Parameters

[in]	time	delta time in seconds until the timer expires
[in]	cb	callback function
[in]	data	optional user data (default: `NULL`)

Implements Fl::add_timeout(double time, Fl_Timeout_Handler cb, void *data)

See also: Fl::add_timeout(double time, Fl_Timeout_Handler cb, void *data)

◆ current()

Fl_Timeout * Fl_Timeout::current ( )

staticprotected

Returns the first (top-most) timeout from the current timeout stack.

This returns a pointer to the timeout but does not remove it from the list of current timeouts. This should be the timeout that is currently executing its callback.

Returns: Fl_Timeout* The current timeout whose callback is running.

Return values

NULL	if no callback is currently running.

◆ elapse_timeouts()

void Fl_Timeout::elapse_timeouts ( )

static

Elapse all timers w/o calling their callbacks.

All timer values are adjusted by the delta time since the last call. This method does NOT call timer callbacks if timers are expired.

This must be called before new timers are added to the timer queue to make sure that the next timer decrement does not count down too much time.

See also: Fl_Timeout::do_timeouts()

◆ get()

Fl_Timeout * Fl_Timeout::get	(	double	time,
		Fl_Timeout_Handler	cb,
		void *	data
	)

staticprotected

Get an Fl_Timeout instance for further handling.

The timer object will be initialized with the input parameters as given by Fl::add_timeout() or Fl::repeat_timeout().

Fl_Timeout objects are maintained in three queues:

active timer queue
list (stack, i.e. LIFO) of currently executing timer callbacks
free timer entries.

When the FLTK program is launched all queues are empty. Whenever a new timer object is required the get() method is called and a timer object is either found in the queue of free timer entries or a new timer object is created (operator new).

Active timer entries are inserted into the "active timer queue" until they expire and their callback is called.

Before the callback is called the timer entry is inserted into the list of current timers, i.e. it becomes the Fl_Timeout::current() timeout. This can be used in Fl::repeat_timeout() to find out if and how long the current timeout has been delayed.

When a timer is no longer used it is popped from the current list and inserted into the "free timer" list so it can be reused later.

Timer queue entries are never returned to the system, there's no garbage collection. The total number of timer objects is determined by the largest number of concurrently active timers.

Parameters

[in]	time	requested delta time
[in]	cb	timer callback
[in]	data	userdata for timer callback

Returns: Fl_Timeout* Timer entry

See also: Fl::add_timeout(), Fl::repeat_timeout()

◆ has_timeout()

int Fl_Timeout::has_timeout	(	Fl_Timeout_Handler	cb,
		void *	data
	)

static

Returns true if the timeout exists and has not been called yet.

Parameters

[in]	cb	Timer callback (must match)
[in]	data	Callback user data (must match)

Returns: whether the timer was found in the queue

Return values

0	not found
1	found

Implements Fl::has_timeout(Fl_Timeout_Handler cb, void *data)

See also: Fl::has_timeout(Fl_Timeout_Handler cb, void *data)

◆ insert()

void Fl_Timeout::insert ( )

protected

Insert this timer entry into the active timer queue.

The timer is inserted at the required position so the timer queue is always ordered by due time.

◆ make_current()

void Fl_Timeout::make_current ( )

protected

Remove the timeout from the active timer queue and push it onto the stack of currently running callbacks.

This becomes the current() timeout which can be used in Fl::repeat_timeout().

See also: Fl_Timeout::current()

◆ release()

void Fl_Timeout::release ( )

protected

Remove the top-most timeout from the stack of currently running timeout callbacks and insert it into the list of free timers.

Typical code in the library would look like:

// The timeout \p Fl_Timeout *t has exired, run its callback
t->make_current();
(t->callback)(t->data);
t->release();

◆ remove_timeout()

void Fl_Timeout::remove_timeout	(	Fl_Timeout_Handler	cb,
		void *	data
	)

static

Remove a timeout callback.

This method removes all matching timeouts, not just the first one. This may change in the future.

Parameters

[in]	cb	Timer callback to be removed (must match)
[in]	data	Wildcard if NULL, must match otherwise

Implements Fl::remove_timeout(Fl_Timeout_Handler cb, void *data)

See also: Fl::remove_timeout(Fl_Timeout_Handler cb, void *data)

◆ repeat_timeout()

void Fl_Timeout::repeat_timeout	(	double	time,
		Fl_Timeout_Handler	cb,
		void *	data
	)

static

Repeats a timeout callback from the expiration of the previous timeout, allowing for more accurate timing.

Parameters

[in]	time	delta time in seconds until the timer expires
[in]	cb	callback function
[in]	data	optional user data (default: `NULL`)

Implements Fl::repeat_timeout(double time, Fl_Timeout_Handler cb, void *data)

See also: Fl::repeat_timeout(double time, Fl_Timeout_Handler cb, void *data)

◆ time_to_wait()

double Fl_Timeout::time_to_wait ( double ttw )

static

Returns the delay in seconds until the next timer expires, limited by ttw.

This function calculates the time to wait for the FLTK event queue processing, depending on the given value ttw.

If at least one timer is active and its timeout value is smaller than ttw then this value is returned. Fl::wait() will wait no longer than until the next timer expires.

If no timer is active this returns the input value ttw unchanged.

If at least one timer is expired this returns 0.0 so the event processing does not wait.

Parameters

[in] ttw time to wait from Fl::wait() etc. (upper limit)

Returns: delay until next timeout or 0.0 (see description)

Member Data Documentation

◆ current_timeout

Fl_Timeout * Fl_Timeout::current_timeout = 0

staticprotected

The list of current timeouts is used to store the timeout whose callback is called while the callback is executed.

This is used like a stack, the current timeout is pushed to the front of the list and once the callback is finished, that timeout is removed and entered into the free list.

Background: Fl::repeat_timeout() needs to know which timeout triggered it and the exact schedule time and/or the delay of that timeout, i.e. how long the scheduled time was missed before the callback was called. A static, global variable is not sufficient since the user code can call other functions, e.g. dialogs, that run a nested event loop which can run another timeout callback. Hence this list of "current" timeouts is used like a stack (last in, first out).

See also: Fl_Timeout::push() Member function (method)

◆ first_timeout

Fl_Timeout * Fl_Timeout::first_timeout = 0

staticprotected

List of active timeouts.

These timeouts can be triggered when due, which calls their callbacks. The lifetime of a timeout:

active, in this queue
callback running, in queue current_timeout
done, in list of free timeouts, ready to be reused.

◆ free_timeout

Fl_Timeout * Fl_Timeout::free_timeout = 0

staticprotected

List of free timeouts after use.

Timeouts can be reused many times.

The documentation for this class was generated from the following files:

Static Public Member Functions

Protected Member Functions

Static Protected Member Functions

Protected Attributes

Static Protected Attributes

Detailed Description

Member Function Documentation

◆ add_timeout()

◆ current()

◆ elapse_timeouts()

◆ get()

◆ has_timeout()

◆ insert()

◆ make_current()

◆ release()

◆ remove_timeout()

◆ repeat_timeout()

◆ time_to_wait()

Member Data Documentation

◆ current_timeout

◆ first_timeout

◆ free_timeout