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_tsqueue_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.
when 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
void* squeue_peek ( squeue_t q  ) 

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
void* squeue_pop ( 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.
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
 All Data Structures Files Functions Variables Typedefs Defines

Generated on 16 Apr 2015 for Nagios by  doxygen 1.6.1