isc::hooks::ParkingLot Class Reference

Parking lot for objects, e.g. More...

#include <parking_lots.h>

Classes
struct	ParkingInfo
	Holds information about parked object. More...

Public Member Functions
template<typename T >
int	dereference (T parked_object)
	Decreases the reference counter for the parked object.
template<typename T >
bool	drop (T parked_object)
	Removes parked object without calling a callback.
template<typename T >
void	park (T parked_object, std::function< void()> unpark_callback)
	Parks an object.
template<typename T >
int	reference (T parked_object)
	Increases reference counter for the parked object.
size_t	size ()
	Returns the current number of objects.
template<typename T >
bool	unpark (T parked_object, bool force=false)
	Signals that the object should be unparked.

Detailed Description

Parking lot for objects, e.g.

packets, for a hook point.

Callouts may instruct the servers to "park" processed packets, i.e. suspend their processing until explicitly unparked. This is useful in cases when callouts need to perform asynchronous operations related to the packet processing and the packet must not be further processed until the asynchronous operations are completed. While the packet is parked, the new packets can be processed, so the server remains responsive to the new requests.

Parking lots are created per hook point, so the callouts installed on the particular hook point only have access to the parking lots dedicated to them.

The parking lot object supports 5 actions: "park", "reference", "dereference", "unpark", and "drop".

In the typical case, the server parks the object and the callouts reference and unpark the objects. Therefore, the ParkingLot object is not passed directly to the callouts. Instead, a ParkingLotHandle object is provided to the callout, which only provides access to "reference", "dereference", and "unpark" operations.

Parking an object is performed, proactively by the server, before callouts are invoked. Referencing (and dereferencing) an object is performed by the callouts before the CalloutHandle::NEXT_STEP_PARK is returned to the server.

Trying to reference (or deference) and unparked object will result in error. Referencing (reference counting) is an important part of the parking mechanism, which allows multiple callouts, installed on the same hook point, to perform asynchronous operations and guarantees that the object remains parked until all those asynchronous operations complete. Each such callout must call unpark() when it desires the object to be unparked, but the object will only be unparked when all callouts call this function, i.e. when all callouts signal completion of their respective asynchronous operations.

Dereferencing, decrements the reference count without invoking the unpark callback. This allows hook callouts to proactively reference the object in a callout and then cancel the reference should further processing deem it the reference unnecessary.

The types of the parked objects provided as T parameter of respective functions are most often shared pointers. One should not use references to parked objects nor references to shared pointers to avoid premature destruction of the parked objects.

Definition at line 73 of file parking_lots.h.

Member Function Documentation

dereference()

template<typename T >

int isc::hooks::ParkingLot::dereference ( T parked_object )

inline

Decreases the reference counter for the parked object.

This method is called by the callouts to decrease the reference count on a parked object.

Template Parameters

Type	of the parked object.

Parameters

parked_object

parked object whose count should be reduced.

Returns

the integer number of references for this object.

Definition at line 126 of file parking_lots.h.

References isc_throw.

drop()

template<typename T >

bool isc::hooks::ParkingLot::drop ( T parked_object )

inline

Removes parked object without calling a callback.

Template Parameters

Type	of the parked object.

Parameters

parked_object

parked object to be removed.

Returns

false if the object couldn't be removed because there is no such object, true otherwise.

Definition at line 195 of file parking_lots.h.

park()

template<typename T >

void isc::hooks::ParkingLot::park ( T parked_object, std::function< void()> unpark_callback )

inline

Parks an object.

Template Parameters

Type	of the parked object.

Parameters

parked_object	object to be parked, e.g. pointer to a packet.
unpark_callback	callback function to be invoked when the object is unparked.

Exceptions

InvalidOperation

if this object has already been parked.

Definition at line 83 of file parking_lots.h.

References isc_throw.

reference()

template<typename T >

int isc::hooks::ParkingLot::reference ( T parked_object )

inline

Increases reference counter for the parked object.

This method is called by the callouts to increase a reference count on the object to be parked. It may only be called after the object has been parked

Template Parameters

Type	of the parked object.

Parameters

parked_object

object which will be parked.

Returns

the integer number of references for this object.

Definition at line 105 of file parking_lots.h.

References isc_throw.

size()

size_t isc::hooks::ParkingLot::size ( )

inline

Returns the current number of objects.

Definition at line 209 of file parking_lots.h.

unpark()

template<typename T >

bool isc::hooks::ParkingLot::unpark ( T parked_object, bool force = false )

inline

Signals that the object should be unparked.

If the specified object is parked in this parking lot, the reference count is decreased as a result of this method. If the reference count is 0, the object is unparked and the callback is invoked. Typically, the callback points to a function which resumes processing of a packet.

Template Parameters

Type	of the parked object.

Parameters

parked_object	parked object to be unparked.
force	boolean value indicating if the reference counting should be ignored and the object should be unparked immediately.

Returns

false if the object couldn't be unparked because there is no such object, true otherwise.

Definition at line 152 of file parking_lots.h.

---

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

• parking_lots.h