JMailbox< T > Class Template Reference

Inheritance diagram for JMailbox< T >:

Collaboration diagram for JMailbox< T >:

Public Types
enum class	Status {   Ready ,   Congested ,   Empty ,   Full }

Public Member Functions
	JMailbox (size_t threshold=100, size_t locations_count=1, bool enable_work_stealing=false)
	threshold: the (soft) maximum number of items in the queue at any time locations_count: the number of locations. More...
void	set_threshold (size_t threshold)
size_t	size ()
	size() counts the number of items in the queue across all locations This should be used sparingly because it will mess up a bunch of caches. More...
size_t	size (size_t location_id)
	size(location_id) counts the number of items in the queue for a particular location Meant to be used by Scheduler::next_assignment() and measure_perf(), eventually
size_t	reserve (size_t requested_count, size_t location_id=0)
	reserve(requested_count) keeps our queues bounded in size. More...
Status	push (std::vector< T > &buffer, size_t reserved_count=0, size_t location_id=0)
	push(items, reserved_count, location_id) This function will always succeed, although it may exceed the threshold if the caller didn't reserve space, and it may take a long time because it will wait on a mutex. More...
Status	pop (std::vector< T > &buffer, size_t requested_count, size_t location_id=0)
	pop() will pop up to requested_count items for the desired location_id. More...
Status	pop (T &item, bool &success, size_t location_id=0)
bool	try_push (T *buffer, size_t count, size_t location_id=0)
void	push_and_unreserve (T *buffer, size_t count, size_t reserved_count=0, size_t location_id=0)
size_t	pop (T *buffer, size_t min_requested_count, size_t max_requested_count, size_t location_id=0)
size_t	pop_and_reserve (T *buffer, size_t min_requested_count, size_t max_requested_count, size_t location_id=0)
size_t	reserve (size_t min_requested_count, size_t max_requested_count, size_t location_id)
void	unreserve (size_t reserved_count, size_t location_id)
Public Member Functions inherited from JQueue
size_t	get_threshold ()
size_t	get_locations_count ()
bool	is_work_stealing_enabled ()
void	set_logger (JLogger logger)
void	set_id (int id)
	JQueue (size_t threshold, size_t locations_count, bool enable_work_stealing)

Friends
std::ostream &	operator<< (std::ostream &os, const Status &s)

Additional Inherited Members
Protected Attributes inherited from JQueue
size_t	m_capacity
size_t	m_locations_count
bool	m_enable_work_stealing = false
int	m_id = 0
JLogger	m_logger

Constructor & Destructor Documentation

JMailbox()

template<typename T >

JMailbox< T >::JMailbox ( size_t  threshold = 100, size_t  locations_count = 1, bool  enable_work_stealing = false  )

inline

threshold: the (soft) maximum number of items in the queue at any time locations_count: the number of locations.

More locations = better NUMA performance, worse load balancing enable_work_stealing: allow events to cross locations only when no other work is available. Improves aforementioned load balancing.

Member Function Documentation

pop()

template<typename T >

Status JMailbox< T >::pop ( std::vector< T > &  buffer, size_t  requested_count, size_t  location_id = 0  )

inline

pop() will pop up to requested_count items for the desired location_id.

If many threads are contending for the queue, this will fail with Status::Contention, in which case the caller should probably consult the Scheduler.

References JMailbox< T >::size().

push()

template<typename T >

Status JMailbox< T >::push ( std::vector< T > &  buffer, size_t  reserved_count = 0, size_t  location_id = 0  )

inline

push(items, reserved_count, location_id) This function will always succeed, although it may exceed the threshold if the caller didn't reserve space, and it may take a long time because it will wait on a mutex.

Note that if the caller had called reserve(), they must pass in the reserved_count here.

reserve()

template<typename T >

size_t JMailbox< T >::reserve ( size_t  requested_count, size_t  location_id = 0  )

inline

reserve(requested_count) keeps our queues bounded in size.

The caller should reserve their desired chunk size on the output queue first. The output queue will return a reservation which is less than or equal to requested_count. The caller may then request as many items from the input queue as have been reserved on the output queue. Note that because the input queue may return fewer items than requested, the caller must push their original reserved_count alongside the items, to avoid a "reservation leak".

size()

template<typename T >

size_t JMailbox< T >::size ( )

inline

size() counts the number of items in the queue across all locations This should be used sparingly because it will mess up a bunch of caches.

Meant to be used by measure_perf()

Referenced by JMailbox< T >::pop().

---

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

• JMailbox.h