Scheduling queue function declarations. More...

#include <sys/time.h>
#include <time.h>
#include "prqueue.h"

#define	SQUEUE_FREE_DATA (1 << 0) /** Call free() on all data pointers */
	Options for squeue_destroy()'s flag parameter.

typedef prqueue_t	squeue_t

typedef struct squeue_event	squeue_event

const 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 prqueue 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_add()

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_add_msec()

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_add_tv()

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_add_usec()

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

◆ squeue_change_priority_tv()

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_create()

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

◆ squeue_destroy()

void squeue_destroy	(	squeue_t *	q,
		int	flags
	)

Destroys a scheduling queue completely.

Parameters

[in]	q	The doomed queue
[in]	flags	Flags determining the level of destruction

◆ squeue_event_data()

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

◆ squeue_event_runtime()

const struct timeval * squeue_event_runtime ( squeue_event * evt )

Get the scheduled runtime of this event.

Parameters

[in] evt The event to get runtime of

Returns: struct timeval on success, NULL on errors

◆ squeue_evt_when_is_after()

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

◆ squeue_peek()

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

◆ squeue_pop()

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

◆ squeue_remove()

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

◆ squeue_size()

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