squeue.h File Reference
Scheduling queue function declarations.
More...
#include <sys/time.h>
#include <time.h>
#include "pqueue.h"
Go to the source code of this file.
|
#define | SQUEUE_FREE_DATA (1 << 0) |
| Options for squeue_destroy()'s flag parameter.
|
typedef pqueue_t | squeue_t |
typedef struct squeue_event | squeue_event |
struct timeval * | squeue_event_runtime (squeue_event *evt) |
| Get the scheduled runtime of this event.
|
void * | squeue_event_data (squeue_event *evt) |
| Get data of an squeue_event struct.
|
squeue_t * | squeue_create (unsigned int size) |
| Creates a scheduling queue optimized for handling events within the given timeframe.
|
void | squeue_destroy (squeue_t *q, int flags) |
| Destroys a scheduling queue completely.
|
squeue_event * | squeue_add_tv (squeue_t *q, struct timeval *tv, void *data) |
| Enqueue an event with microsecond precision.
|
squeue_event * | squeue_add (squeue_t *q, time_t when, void *data) |
| Adds an event to the scheduling queue.
|
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.
|
squeue_event * | squeue_add_msec (squeue_t *q, time_t when, time_t msec, void *data) |
| Adds an event to the scheduling queue with millisecond precision See notes on squeue_add_tv() for details.
|
void | squeue_change_priority_tv (squeue_t *q, squeue_event *evt, struct timeval *tv) |
| Change an event's priority to a new time.
|
void * | squeue_peek (squeue_t *q) |
| Returns the data of the next scheduled event from the scheduling queue without removing it from the queue.
|
void * | squeue_pop (squeue_t *q) |
| Pops the next scheduled event from the scheduling queue and returns the data for it.
|
int | squeue_remove (squeue_t *q, squeue_event *evt) |
| Removes the given event from the scheduling queue.
|
unsigned int | squeue_size (squeue_t *q) |
| Returns the number of events in the scheduling queue.
|
int | squeue_evt_when_is_after (squeue_event *evt, struct timeval *reftime) |
| Returns true if passed timeval is after the time for the event.
|
Detailed Description
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.
Function Documentation
squeue_event* squeue_add |
( |
squeue_t * |
q, |
|
|
time_t |
when, |
|
|
void * |
data | |
|
) |
| | |
Adds an event to the scheduling queue.
See notes for squeue_add_tv() for details
- Parameters:
-
| q | The scheduling queue to add to |
| when | The unix timestamp when this event is to occur |
| data | Pointer to any kind of data |
- Returns:
- The complete scheduled event
squeue_event* squeue_add_msec |
( |
squeue_t * |
q, |
|
|
time_t |
when, |
|
|
time_t |
msec, |
|
|
void * |
data | |
|
) |
| | |
Adds an event to the scheduling queue with millisecond precision See notes on squeue_add_tv() for details.
- Parameters:
-
[in] | q | The scheduling queue to add to |
[in] | when | Unix timestamp when this event should occur |
[in] | msec | Millisecond of above this event should occur |
[in] | data | Pointer to any kind of data |
- Returns:
- NULL on errors. squeue_event pointer on success
squeue_event* squeue_add_tv |
( |
squeue_t * |
q, |
|
|
struct timeval * |
tv, |
|
|
void * |
data | |
|
) |
| | |
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.
- Parameters:
-
| q | The scheduling queue to add to |
| tv | When this event should occur |
| data | Pointer to any kind of data |
- Returns:
- The complete scheduled event
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.
- Parameters:
-
[in] | q | The scheduling queue to add to |
[in] | when | Unix timestamp when this event should occur |
[in] | usec | Millisecond of above this event should occur |
[in] | data | Pointer to any kind of data |
- Returns:
- NULL on errors. squeue_event pointer on success
void squeue_change_priority_tv |
( |
squeue_t * |
q, |
|
|
squeue_event * |
evt, |
|
|
struct timeval * |
tv | |
|
) |
| | |
Change an event's priority to a new time.
- Parameters:
-
| q | The scheduling queue holding the event. |
| evt | The event to reschedule. |
| tv | When the event should be rescheduled to. |
squeue_t* squeue_create |
( |
unsigned int |
size |
) |
|
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.
- Parameters:
-
| size | Hint about how large this queue will get |
- Returns:
- A pointer to a scheduling queue
void squeue_destroy |
( |
squeue_t * |
q, |
|
|
int |
flags | |
|
) |
| | |
Destroys a scheduling queue completely.
- Parameters:
-
[in] | q | The doomed queue |
[in] | flags | Flags determining the the level of destruction |
void* squeue_event_data |
( |
squeue_event * |
evt |
) |
|
Get data of an squeue_event struct.
- Parameters:
-
[in] | evt | The event to operate on |
- Returns:
- The data object pointed to by the event
struct timeval* squeue_event_runtime |
( |
squeue_event * |
evt |
) |
[read] |
Get the scheduled runtime of this event.
- Parameters:
-
[in] | evt | The event to get runtime of |
- Returns:
- struct timeval on success, NULL on errors
int squeue_evt_when_is_after |
( |
squeue_event * |
evt, |
|
|
struct timeval * |
reftime | |
|
) |
| | |
Returns true if passed timeval is after the time for the event.
- Parameters:
-
[in] | evt | The queue event to inspect |
[in] | reftime | The reference time to compare to the queue event time |
- Returns:
- 1 if reftime > event time, 0 otherwise
Returns the data of the next scheduled event from the scheduling queue without removing it from the queue.
- Parameters:
-
| q | The scheduling queue to peek into |
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.
- Parameters:
-
| q | The scheduling queue to pop from |
int squeue_remove |
( |
squeue_t * |
q, |
|
|
squeue_event * |
evt | |
|
) |
| | |
Removes the given event from the scheduling queue.
- Note:
- This causes the associated squeue_event() to be free()'d.
- Parameters:
-
[in] | q | The scheduling queue to remove from |
[in] | evt | The event to remove |
unsigned int squeue_size |
( |
squeue_t * |
q |
) |
|
Returns the number of events in the scheduling queue.
This function never fails.
- Parameters:
-
[in] | q | The scheduling queue to inspect |
- Returns:
- number of events in the inspected queue