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
170
|
#ifndef LIBNAGIOS_SQUEUE_H_INCLUDED
#define LIBNAGIOS_SQUEUE_H_INCLUDED
#include <sys/time.h>
#include <time.h>
#include "pqueue.h"
/**
* @file squeue.h
* @brief Scheduling queue function declarations
*
* This library is based on the pqueue api, which implements a
* priority queue based on a binary heap, providing O(lg n) times
* for insert() and remove(), and O(1) time for peek().
* @note There is no "find". Callers must maintain pointers to their
* scheduled events if they wish to be able to remove them.
*
* @{
*/
/*
* All opaque types here.
* The pqueue library can be useful on its own though, so we
* don't block that from user view.
*/
typedef pqueue_t squeue_t;
struct squeue_event;
typedef struct squeue_event squeue_event;
/**
* Options for squeue_destroy()'s flag parameter
*/
#define SQUEUE_FREE_DATA (1 << 0) /** Call free() on all data pointers */
/**
* Get the scheduled runtime of this event
* @param[in] evt The event to get runtime of
* @return struct timeval on success, NULL on errors
*/
extern const struct timeval *squeue_event_runtime(squeue_event *evt);
/**
* Get data of an squeue_event struct
* @param[in] evt The event to operate on
* @return The data object pointed to by the event
*/
extern void *squeue_event_data(squeue_event *evt);
/**
* Creates a scheduling queue optimized for handling events within
* the given timeframe. Callers should take care to create a queue
* of a decent but not overly large size, as too small or too large
* a queue will impact performance negatively. A queue can hold any
* number of events. A good value for "horizon" would be the max
* seconds into the future one expects to schedule things, although
* with few scheduled items in that timeframe you'd be better off
* using a more narrow horizon.
*
* @param size Hint about how large this queue will get
* @return A pointer to a scheduling queue
*/
extern squeue_t *squeue_create(unsigned int size);
/**
* Destroys a scheduling queue completely
* @param[in] q The doomed queue
* @param[in] flags Flags determining the the level of destruction
*/
extern void squeue_destroy(squeue_t *q, int flags);
/**
* Enqueue an event with microsecond precision.
* It's up to the caller to keep the event pointer in case he/she
* wants to remove the event from the queue later.
*
* @param q The scheduling queue to add to
* @param tv When this event should occur
* @param data Pointer to any kind of data
* @return The complete scheduled event
*/
extern squeue_event *squeue_add_tv(squeue_t *q, struct timeval *tv, void *data);
/**
* Adds an event to the scheduling queue.
* See notes for squeue_add_tv() for details
*
* @param q The scheduling queue to add to
* @param when The unix timestamp when this event is to occur
* @param data Pointer to any kind of data
* @return The complete scheduled event
*/
extern squeue_event *squeue_add(squeue_t *q, time_t when, void *data);
/**
* Adds an event to the scheduling queue with millisecond precision
* See notes on squeue_add_tv() for details
*
* @param[in] q The scheduling queue to add to
* @param[in] when Unix timestamp when this event should occur
* @param[in] usec Millisecond of above this event should occur
* @param[in] data Pointer to any kind of data
* @return NULL on errors. squeue_event pointer on success
*/
extern squeue_event *squeue_add_usec(squeue_t *q, time_t when, time_t usec, void *data);
/**
* Adds an event to the scheduling queue with millisecond precision
* See notes on squeue_add_tv() for details
*
* @param[in] q The scheduling queue to add to
* @param[in] when Unix timestamp when this event should occur
* @param[in] msec Millisecond of above this event should occur
* @param[in] data Pointer to any kind of data
* @return NULL on errors. squeue_event pointer on success
*/
extern squeue_event *squeue_add_msec(squeue_t *q, time_t when, time_t msec, void *data);
/**
* Change an event's priority to a new time.
*
* @param q The scheduling queue holding the event.
* @param evt The event to reschedule.
* @param tv When the event should be rescheduled to.
*/
extern void squeue_change_priority_tv(squeue_t *q, squeue_event *evt, struct timeval *tv);
/**
* Returns the data of the next scheduled event from the scheduling
* queue without removing it from the queue.
*
* @param q The scheduling queue to peek into
*/
extern void *squeue_peek(squeue_t *q);
/**
* Pops the next scheduled event from the scheduling queue and
* returns the data for it.
* This is equivalent to squeue_peek() + squeue_pop()
* @note This causes the squeue_event to be free()'d.
*
* @param q The scheduling queue to pop from
*/
extern void *squeue_pop(squeue_t *q);
/**
* Removes the given event from the scheduling queue
* @note This causes the associated squeue_event() to be free()'d.
* @param[in] q The scheduling queue to remove from
* @param[in] evt The event to remove
*/
extern int squeue_remove(squeue_t *q, squeue_event *evt);
/**
* Returns the number of events in the scheduling queue. This
* function never fails.
*
* @param[in] q The scheduling queue to inspect
* @return number of events in the inspected queue
*/
extern unsigned int squeue_size(squeue_t *q);
/**
* Returns true if passed timeval is after the time for the event
*
* @param[in] evt The queue event to inspect
* @param[in] reftime The reference time to compare to the queue event time
* @return 1 if reftime > event time, 0 otherwise
*/
extern int squeue_evt_when_is_after(squeue_event *evt, struct timeval *reftime);
#endif
/** @} */
|
