#include <bdlcc_timequeue.h>

Classes
class	Key

Public Types
typedef int	Handle

Public Member Functions
	TimeQueue (bslma::Allocator *basicAllocator=0)

	TimeQueue (int numIndexBits, bslma::Allocator *basicAllocator=0)

	TimeQueue (bool poolTimerMemory, bslma::Allocator *basicAllocator=0)

	TimeQueue (int numIndexBits, bool poolTimerMemory, bslma::Allocator *basicAllocator=0)

	~TimeQueue ()
	Destroy this time queue.

Handle	add (const bsls::TimeInterval &time, const DATA &data, int isNewTop=0, int newLength=0)

Handle	add (const bsls::TimeInterval &time, const DATA &data, const Key &key, int isNewTop=0, int newLength=0)

Handle	add (const TimeQueueItem< DATA > &item, int isNewTop=0, int newLength=0)

int	popFront (TimeQueueItem< DATA > buffer=0, int newLength=0, bsls::TimeInterval *newMinTime=0)

void	popLE (const bsls::TimeInterval &time)

void	popLE (const bsls::TimeInterval &time, bsl::vector< TimeQueueItem< DATA > > buffer, int newLength=0, bsls::TimeInterval *newMinTime=0)

void	popLE (const bsls::TimeInterval &time, std::vector< TimeQueueItem< DATA > > buffer, int newLength=0, bsls::TimeInterval *newMinTime=0)

void	popLE (const bsls::TimeInterval &time, int maxTimers)

void	popLE (const bsls::TimeInterval &time, int maxTimers, bsl::vector< TimeQueueItem< DATA > > buffer, int newLength=0, bsls::TimeInterval *newMinTime=0)

void	popLE (const bsls::TimeInterval &time, int maxTimers, std::vector< TimeQueueItem< DATA > > buffer, int newLength=0, bsls::TimeInterval *newMinTime=0)

int	remove (Handle handle, int newLength=0, bsls::TimeInterval newMinTime=0, TimeQueueItem< DATA > *item=0)

int	remove (Handle handle, const Key &key, int newLength=0, bsls::TimeInterval newMinTime=0, TimeQueueItem< DATA > *item=0)

void	removeAll (bsl::vector< TimeQueueItem< DATA > > *buffer=0)

int	update (Handle handle, const bsls::TimeInterval &newTime, int *isNewTop=0)

int	update (Handle handle, const Key &key, const bsls::TimeInterval &newTime, int *isNewTop=0)

int	length () const

bool	isRegisteredHandle (Handle handle) const

bool	isRegisteredHandle (Handle handle, const Key &key) const

int	minTime (bsls::TimeInterval *buffer) const

int	countLE (const bsls::TimeInterval &time) const

Detailed Description

template<class DATA>
class bdlcc::TimeQueue< DATA >

This parameterized class provides a public interface which is similar in structure and intent to Queue<DATA>, with the exception that each item stored in the TimeQueue has an associated time value. Items are retrieved or exchanged by proxy of a TimeQueueItem<DATA>, and are referred to by an opaque data type TimeQueue::Handle which serves to identify an individual element on the Time Queue. Idiomatic usage of TimeQueue includes the member function popLE, which finds all items on the queue whose bsls::TimeInterval are less than a specified value and transfers those items to a provided vector of items, and the member function update, which can update the time value for a specific TimeQueueItem without removing it from the queue.

See bdlcc_timequeue

Member Typedef Documentation

◆ Handle

template<class DATA >

typedef int bdlcc::TimeQueue< DATA >::Handle

Handle defines an alias for uniquely identifying a valid node in the time queue. Handles are returned when nodes are added to the time queue, and must be supplied to the update and remove methods to identify existing nodes. When a node is removed, the handle value becomes invalid, though invalidated handle values are eventually reused. See the component-level documentation for more details.

Constructor & Destructor Documentation

◆ TimeQueue() [1/4]

template<class DATA >

bdlcc::TimeQueue< DATA >::TimeQueue ( bslma::Allocator * basicAllocator = 0 )

explicit

◆ TimeQueue() [2/4]

template<class DATA >

bdlcc::TimeQueue< DATA >::TimeQueue	(	int	numIndexBits,
		bslma::Allocator *	basicAllocator = `0`
	)

explicit

Create an empty time queue. Optionally specify numIndexBits to configure the number of index bits used by this object. If numIndexBits is not specified a default value of 17 is used. Optionally specify a basicAllocator used to supply memory. If basicAllocator is 0, the currently installed default allocator is used. The behavior is undefined unless 8 <= numIndexBits <= 24. See the component-level documentation for more information regarding numIndexBits.

◆ TimeQueue() [3/4]

template<class DATA >

bdlcc::TimeQueue< DATA >::TimeQueue	(	bool	poolTimerMemory,
		bslma::Allocator *	basicAllocator = `0`
	)

explicit

◆ TimeQueue() [4/4]

template<class DATA >

bdlcc::TimeQueue< DATA >::TimeQueue	(	int	numIndexBits,
		bool	poolTimerMemory,
		bslma::Allocator *	basicAllocator = `0`
	)

[DEPRECATED] Use the other constructor overloads instead. Note that the specified poolTimerMemory argument controlled whether additional memory used by an internal bsl::map was pooled. When bsl::map was modified to pool its own nodes, this option became irrelevant and is now ignored.

◆ ~TimeQueue()

template<class DATA >

bdlcc::TimeQueue< DATA >::~TimeQueue ( )

Member Function Documentation

◆ add() [1/3]

template<class DATA >

TimeQueue< DATA >::Handle bdlcc::TimeQueue< DATA >::add	(	const bsls::TimeInterval &	time,
		const DATA &	data,
		const Key &	key,
		int *	isNewTop = `0`,
		int *	newLength = `0`
	)

Add a new item to this queue having the specified time value, and associated data. Optionally use the specified key to uniquely identify the item in subsequent calls to remove and update. Optionally load into the optionally specified isNewTop a non-zero value if the item is now the lowest item in this queue, and a 0 value otherwise. If specified, load into the optionally specified newLength, the new number of items in this queue. Return a value that may be used to identify the newly added item in future calls to time queue on success, and -1 if the maximum queue length has been reached.

◆ add() [2/3]

template<class DATA >

TimeQueue< DATA >::Handle bdlcc::TimeQueue< DATA >::add	(	const bsls::TimeInterval &	time,
		const DATA &	data,
		int *	isNewTop = `0`,
		int *	newLength = `0`
	)

inline

◆ add() [3/3]

template<class DATA >

TimeQueue< DATA >::Handle bdlcc::TimeQueue< DATA >::add	(	const TimeQueueItem< DATA > &	item,
		int *	isNewTop = `0`,
		int *	newLength = `0`
	)

inline

Add the value of the specified item to this queue. Optionally load into the optionally specified isNewTop a non-zero value if the replaces is now the lowest element in this queue, and a 0 value otherwise. If specified, load into the optionally specified newLength, the new number of elements in this queue. Return a value that may be used to identify the newly added item in future calls to time queue on success, and -1 if the maximum queue length has been reached.

◆ countLE()

template<class DATA >

int bdlcc::TimeQueue< DATA >::countLE ( const bsls::TimeInterval & time ) const

inline

Return the number of items in this queue that have a time value less than or equal to the specified time. Note that the value returned may be obsolete by the time it is received.

◆ isRegisteredHandle() [1/2]

template<class DATA >

bool bdlcc::TimeQueue< DATA >::isRegisteredHandle ( Handle handle ) const

Return true if an item having specified handle is currently registered with this time queue and false otherwise.

◆ isRegisteredHandle() [2/2]

template<class DATA >

bool bdlcc::TimeQueue< DATA >::isRegisteredHandle	(	Handle	handle,
		const Key &	key
	)		const

◆ length()

template<class DATA >

int bdlcc::TimeQueue< DATA >::length ( ) const

inline

Return number of items in this queue. Note that the value returned may be obsolete by the time it is received.

◆ minTime()

template<class DATA >

int bdlcc::TimeQueue< DATA >::minTime ( bsls::TimeInterval * buffer ) const

inline

Load into the specified buffer, the time value of the lowest time in this queue. Return 0 on success, and a non-zero value if this queue is empty.

◆ popFront()

template<class DATA >

int bdlcc::TimeQueue< DATA >::popFront	(	TimeQueueItem< DATA > *	buffer = `0`,
		int *	newLength = `0`,
		bsls::TimeInterval *	newMinTime = `0`
	)

Atomically remove the top item from this queue, and optionally load into the optionally specified buffer the time and associated data of the item removed. Optionally load into the optionally specified newLength, the number of items remaining in the queue. Optionally load into the optionally specified newMinTime the new lowest time in this queue. Return 0 on success, and a non-zero value if there are no items in the queue. Note that if DATA follows the bdema allocator model, the allocator of the buffer is used to supply memory.

◆ popLE() [1/6]

template<class DATA >

void bdlcc::TimeQueue< DATA >::popLE ( const bsls::TimeInterval & time )

inline

◆ popLE() [2/6]

template<class DATA >

void bdlcc::TimeQueue< DATA >::popLE	(	const bsls::TimeInterval &	time,
		bsl::vector< TimeQueueItem< DATA > > *	buffer,
		int *	newLength = `0`,
		bsls::TimeInterval *	newMinTime = `0`
	)

inline

◆ popLE() [3/6]

template<class DATA >

void bdlcc::TimeQueue< DATA >::popLE	(	const bsls::TimeInterval &	time,
		int	maxTimers
	)

inline

◆ popLE() [4/6]

template<class DATA >

void bdlcc::TimeQueue< DATA >::popLE	(	const bsls::TimeInterval &	time,
		int	maxTimers,
		bsl::vector< TimeQueueItem< DATA > > *	buffer,
		int *	newLength = `0`,
		bsls::TimeInterval *	newMinTime = `0`
	)

inline

◆ popLE() [5/6]

template<class DATA >

void bdlcc::TimeQueue< DATA >::popLE	(	const bsls::TimeInterval &	time,
		int	maxTimers,
		std::vector< TimeQueueItem< DATA > > *	buffer,
		int *	newLength = `0`,
		bsls::TimeInterval *	newMinTime = `0`
	)

inline

Remove from this queue up to the specified maxTimers number of items that have a time value less than or equal to the specified time, and optionally append into the optionally specified buffer a list of the removed items, ordered by their corresponding time values (top item first). Optionally load into the optionally specified newLength the number of items remaining in this queue, and into the optionally specified newMinTime the lowest remaining time value in this queue. The behavior is undefined unless maxTimers >= 0. Note that newMinTime is only loaded if there are items remaining in the time queue; therefore, newLength should be specified and examined to determine whether items remain, and newMinTime used only when newLength > 0. Also note that if DATA follows the bdema allocator model, the allocator of the buffer vector is used to supply memory. Note finally that all the items appended into buffer have a time value less than or equal to the elements remaining in this queue.

◆ popLE() [6/6]

template<class DATA >

void bdlcc::TimeQueue< DATA >::popLE	(	const bsls::TimeInterval &	time,
		std::vector< TimeQueueItem< DATA > > *	buffer,
		int *	newLength = `0`,
		bsls::TimeInterval *	newMinTime = `0`
	)

inline

Remove from this queue all the items that have a time value less than or equal to the specified time, and optionally append into the optionally specified buffer a list of the removed items, ordered by their corresponding time values (top item first). Optionally load into the optionally specified newLength the number of items remaining in this queue, and into the optionally specified newMinTime the lowest remaining time value in this queue. Note that newMinTime is only loaded if there are items remaining in the time queue; therefore, newLength should be specified and examined to determine whether items remain, and newMinTime used only when newLength > 0. Also note that if DATA follows the bdema allocator model, the allocator of the buffer vector is used to supply memory for the items appended to the buffer.

◆ remove() [1/2]

template<class DATA >

int bdlcc::TimeQueue< DATA >::remove	(	Handle	handle,
		const Key &	key,
		int *	newLength = `0`,
		bsls::TimeInterval *	newMinTime = `0`,
		TimeQueueItem< DATA > *	item = `0`
	)

Remove from this queue the item having the specified handle, and optionally load into the optionally specified item the time and data values of the recently removed item. Optionally use the specified key to uniquely identify the item. If specified, load into the optionally specified newMinTime, the resulting lowest time value remaining in the queue. Return 0 on success, and a non-zero value if no item with the handle exists in the queue. Note that if DATA follows the bdema allocator model, the allocator of the item instance is used to supply memory.

◆ remove() [2/2]

template<class DATA >

int bdlcc::TimeQueue< DATA >::remove	(	Handle	handle,
		int *	newLength = `0`,
		bsls::TimeInterval *	newMinTime = `0`,
		TimeQueueItem< DATA > *	item = `0`
	)

◆ removeAll()

template<class DATA >

void bdlcc::TimeQueue< DATA >::removeAll ( bsl::vector< TimeQueueItem< DATA > > * buffer = 0 )

Remove all the items from this queue. Optionally specify a buffer in which to load the removed items. The resultant items in the buffer are ordered by increasing time interval; items of equivalent time interval have arbitrary ordering. Note that the allocator of the buffer vector is used to supply memory.

◆ update() [1/2]

template<class DATA >

int bdlcc::TimeQueue< DATA >::update	(	Handle	handle,
		const bsls::TimeInterval &	newTime,
		int *	isNewTop = `0`
	)

◆ update() [2/2]

template<class DATA >

int bdlcc::TimeQueue< DATA >::update	(	Handle	handle,
		const Key &	key,
		const bsls::TimeInterval &	newTime,
		int *	isNewTop = `0`
	)

Update the time value of the item having the specified handle to the specified newTime and optionally load into the optionally specified isNewTop a non-zero value if the modified item is now the lowest time value in the time queue or zero otherwise. Return 0 on success, and a non-zero value if there is currently no item having the handle registered with this time queue.

The documentation for this class was generated from the following file:

bdlcc_timequeue.h

Classes

Public Types

Public Member Functions

Detailed Description

Member Typedef Documentation

◆ Handle

Constructor & Destructor Documentation

◆ TimeQueue() [1/4]

◆ TimeQueue() [2/4]

◆ TimeQueue() [3/4]

◆ TimeQueue() [4/4]

◆ ~TimeQueue()

Member Function Documentation

◆ add() [1/3]

◆ add() [2/3]

◆ add() [3/3]

◆ countLE()

◆ isRegisteredHandle() [1/2]

◆ isRegisteredHandle() [2/2]

◆ length()

◆ minTime()

◆ popFront()

◆ popLE() [1/6]

◆ popLE() [2/6]

◆ popLE() [3/6]

◆ popLE() [4/6]

◆ popLE() [5/6]

◆ popLE() [6/6]

◆ remove() [1/2]

◆ remove() [2/2]

◆ removeAll()

◆ update() [1/2]

◆ update() [2/2]