FLTK 1.4.4: Fl_Timeout Class Reference

FLTK 1.4.4

Loading...
Searching...
No Matches
Fl_Timeout Class Reference

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 int | remove_next_timeout (Fl_Timeout_Handler cb, void *data=NULL, void **data_return=NULL)
| Remove the next matching timeout callback and return its `data` pointer.
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).

Related user documentation:

- Fl_Timeout_Handler
- Fl::add_timeout(double time, Fl_Timeout_Handler cb, void *data)
- Fl::repeat_timeout(double time, Fl_Timeout_Handler cb, void *data)
- Fl::has_timeout(Fl_Timeout_Handler cb, void *data)
- Fl::remove_timeout(Fl_Timeout_Handler cb, void *data)
- Fl::remove_next_timeout(Fl_Timeout_Handler cb, void *data, void **data_return)

## 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:

    void 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:

    int 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_next_timeout()

int Fl_Timeout::remove_next_timeout | ( | Fl_Timeout_Handler | cb,
|  | void * | data = NULL,
|  | void ** | data_return = NULL )
| static

Remove the next matching timeout callback and return its `data` pointer.

Implements:

    int Fl::remove_next_timeout(Fl_Timeout_Handler cb, void *data, void **data_return)

Parameters

  [in] | cb | Timer callback to be removed (must match)
  [in] | data | Wildcard if NULL, must match otherwise
  [in,out] | data_return | pointer to void * to receive the data value

Returns
  non-zero if a timer was found and removed

Return values

  0 | no matching timer was found
  1 | the last matching timeout was found and removed
  N>1 | a matching timeout was removed and there are (N - 1) matching timeouts pending

For details

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

## ◆ 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:

    void 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:

    void 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:

- Fl_Timeout.h
- Fl_Timeout.cxx