Seastar
High performance C++ framework for concurrent servers
Classes | Public Member Functions | Related Functions | List of all members
seastar::fair_queue Class Reference

Detailed Description

Fair queuing class.

This is a fair queue, allowing multiple request producers to queue requests that will then be served proportionally to their classes' shares.

To each request, a weight can also be associated. A request of weight 1 will consume 1 share. Higher weights for a request will consume a proportionally higher amount of shares.

The user of this interface is expected to register multiple priority_class objects, which will each have a shares attribute.

Internally, each priority class may keep a separate queue of requests. Requests pertaining to a class can go through even if they are over its share limit, provided that the other classes have empty queues.

When the classes that lag behind start seeing requests, the fair queue will serve them first, until balance is restored. This balancing is expected to happen within a certain time window that obeys an exponential decay.

#include <seastar/core/fair_queue.hh>

Classes

struct  config
 Fair Queue configuration structure. More...
 

Public Member Functions

 fair_queue (config cfg)
 
 fair_queue (unsigned capacity, std::chrono::microseconds tau=std::chrono::milliseconds(100))
 
priority_class_ptr register_priority_class (uint32_t shares)
 
void unregister_priority_class (priority_class_ptr pclass)
 
size_t waiters () const
 
size_t requests_currently_executing () const
 
fair_queue_ticket resources_currently_waiting () const
 
fair_queue_ticket resources_currently_executing () const
 
void queue (priority_class_ptr pc, fair_queue_ticket desc, noncopyable_function< void()> func)
 
void notify_requests_finished (fair_queue_ticket desc, unsigned nr=1) noexcept
 
void dispatch_requests ()
 Try to execute new requests if there is capacity left in the queue.
 

Related Functions

(Note that these are not member functions.)

using priority_class_ptr = lw_shared_ptr< priority_class >
 Priority class, to be used with a given fair_queue. More...
 

Class Documentation

◆ seastar::fair_queue::config

struct seastar::fair_queue::config
Class Members
unsigned max_bytes_count
unsigned max_req_count
microseconds tau

Constructor & Destructor Documentation

◆ fair_queue() [1/2]

seastar::fair_queue::fair_queue ( config  cfg)
explicit

Constructs a fair queue with configuration parameters cfg.

Parameters
cfgan instance of the class config

◆ fair_queue() [2/2]

seastar::fair_queue::fair_queue ( unsigned  capacity,
std::chrono::microseconds  tau = std::chrono::milliseconds(100) 
)
inlineexplicit

Constructs a fair queue with a given capacity, expressed in IOPS.

Parameters
capacityhow many concurrent requests are allowed in this queue.
tauthe queue exponential decay parameter, as in exp(-1/tau * t)

Member Function Documentation

◆ notify_requests_finished()

void seastar::fair_queue::notify_requests_finished ( fair_queue_ticket  desc,
unsigned  nr = 1 
)
noexcept

Notifies that ont request finished

Parameters
descan instance of fair_queue_ticket structure describing the request that just finished.

◆ queue()

void seastar::fair_queue::queue ( priority_class_ptr  pc,
fair_queue_ticket  desc,
noncopyable_function< void()>  func 
)

Queue the function func through this class' fair_queue, with weight weight

It is expected that func doesn't throw. If it does throw, it will be just removed from the queue and discarded.

The user of this interface is supposed to call notify_requests_finished when the request finishes executing - regardless of success or failure.

◆ register_priority_class()

priority_class_ptr seastar::fair_queue::register_priority_class ( uint32_t  shares)

Registers a priority class against this fair queue.

Parameters
shareshow many shares to create this class with

◆ requests_currently_executing()

size_t seastar::fair_queue::requests_currently_executing ( ) const
Returns
the number of requests currently executing

◆ resources_currently_executing()

fair_queue_ticket seastar::fair_queue::resources_currently_executing ( ) const
Returns
the amount of resources (weight, size) currently executing

◆ resources_currently_waiting()

fair_queue_ticket seastar::fair_queue::resources_currently_waiting ( ) const
Returns
how much resources (weight, size) are currently queued for all classes.

◆ unregister_priority_class()

void seastar::fair_queue::unregister_priority_class ( priority_class_ptr  pclass)

Unregister a priority class.

It is illegal to unregister a priority class that still have pending requests.

◆ waiters()

size_t seastar::fair_queue::waiters ( ) const
Returns
how many waiters are currently queued for all classes.

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