1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
//
// Header for timeout support functions for the Fast Light Tool Kit (FLTK).
//
// Author: Albrecht Schlosser
// Copyright 2021-2024 by Bill Spitzak and others.
//
// This library is free software. Distribution and use rights are outlined in
// the file "COPYING" which should have been included with this file. If this
// file is missing or damaged, see the license at:
//
// https://www.fltk.org/COPYING.php
//
// Please see the following page on how to report bugs and issues:
//
// https://www.fltk.org/bugs.php
//
#ifndef _src_Fl_Timeout_h_
#define _src_Fl_Timeout_h_
#include <FL/Fl.H>
#define FL_TIMEOUT_DEBUG 0 // 1 = include debugging features, 0 = no
/** \file
Fl_Timeout handling.
This file contains implementations of:
- Fl::add_timeout()
- Fl::repeat_timeout()
- Fl::has_timeout()
- Fl::remove_timeout()
- Fl::remove_next_timeout()
and related methods of class Fl_Timeout.
*/
/**
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:
- \ref 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)
*/
class Fl_Timeout {
protected:
Fl_Timeout *next; // ** Link to next timeout
Fl_Timeout_Handler callback; // the user's callback
void *data; // the user's callback data
double time; // delay until timeout
int skip; // skip "new" (inserted) timers (issue #450)
// constructor
Fl_Timeout() {
next = 0;
callback = 0;
data = 0;
time = 0;
skip = 0;
}
// destructor
~Fl_Timeout() {}
// get a new timer entry from the pool or allocate a new one
static Fl_Timeout *get(double time, Fl_Timeout_Handler cb, void *data);
// insert this timer into the active timer queue, sorted by expiration time
void insert();
// remove this timer from the active timer queue and
// add it to the "current" timer stack
void make_current();
// remove this timer from the current timer stack and
// add it to the list of free timers
void release();
/** Get the timer's delay in seconds. */
double delay() {
return time;
}
/** Set the timer's delay in seconds. */
void delay(double t) {
time = t;
}
public:
// Returns whether the given timeout is active.
static int has_timeout(Fl_Timeout_Handler cb, void *data);
// Add or remove timeouts
static void add_timeout(double time, Fl_Timeout_Handler cb, void *data);
static void repeat_timeout(double time, Fl_Timeout_Handler cb, void *data);
static void remove_timeout(Fl_Timeout_Handler cb, void *data);
static int remove_next_timeout(Fl_Timeout_Handler cb, void *data = NULL, void **data_return = NULL);
// Elapse timeouts, i.e. calculate new delay time of all timers.
// This does not call the timer callbacks.
static void elapse_timeouts();
// Elapse timeouts and call timer callbacks.
static void do_timeouts();
// Return the delay in seconds until the next timer expires.
static double time_to_wait(double ttw);
#if FL_TIMEOUT_DEBUG
// Write some statistics to stdout
static void debug(int level = 1);
#endif
protected:
static Fl_Timeout *current();
/**
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 \p current_timeout
- done, in list of free timeouts, ready to be reused.
*/
static Fl_Timeout *first_timeout;
/**
List of free timeouts after use.
Timeouts can be reused many times.
*/
static Fl_Timeout *free_timeout;
/**
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 Fl_Timeout::push() Member function (method)
*/
static Fl_Timeout *current_timeout; // list of "current" timeouts
}; // class Fl_Timeout
#endif // _src_Fl_Timeout_h_