Kea: isc::dhcp::TrackingLeaseMgr Class Reference

| Kea 3.2.0-git

isc::dhcp::TrackingLeaseMgr Class Reference

Introduces callbacks into the `LeaseMgr`. More...

`#include <tracking_lease_mgr.h>`

Inheritance diagram for isc::dhcp::TrackingLeaseMgr:
[legend]

## Classes
struct | Callback
| A structure representing a registered callback. More...

## Public Types
typedef std::function< void(LeasePtr)> | CallbackFn
| Type of a callback function invoked upon a lease insertion, update or deletion.
enum | CallbackType { TRACK_ADD_LEASE , TRACK_UPDATE_LEASE , TRACK_DELETE_LEASE }
| An enumeration differentiating between lease write operations. More...

## Public Member Functions
bool | hasCallbacks () const
| Checks if any callbacks have been registered.
bool | isLocked (const LeasePtr &lease)
| Checks if the lease is locked.
void | registerCallback (CallbackType type, std::string owner, Lease::Type lease_type, CallbackFn callback_fn)
| Registers a callback function for all subnets.
void | registerCallback (CallbackType type, std::string owner, SubnetID subnet_id, Lease::Type lease_type, CallbackFn callback_fn)
| Registers a callback function for a subnet.
void | unregisterAllCallbacks ()
| Unregisters all callbacks.
void | unregisterCallbacks (SubnetID subnet_id, Lease::Type lease_type)
| Unregisters all callbacks for a given subnet identifier.
Public Member Functions inherited from isc::dhcp::LeaseMgr
| LeaseMgr ()
| Constructor.
virtual | ~LeaseMgr ()
| Destructor.
virtual bool | addLease (const Lease4Ptr &lease)=0
| Adds an IPv4 lease.
virtual bool | addLease (const Lease6Ptr &lease)=0
| Adds an IPv6 lease.
virtual size_t | byRelayId6size () const
| Return the by-relay-id table size.
virtual size_t | byRemoteId6size () const
| Return the by-remote-id table size.
virtual std::string | checkLimits4 (isc::data::ConstElementPtr const &user_context) const =0
| Checks if the IPv4 lease limits set in the given user context are exceeded.
virtual std::string | checkLimits6 (isc::data::ConstElementPtr const &user_context) const =0
| Checks if the IPv6 lease limits set in the given user context are exceeded.
virtual void | clearClassLeaseCounts ()=0
| Clears the class-lease count map.
virtual void | commit ()=0
| Commit Transactions.
virtual uint64_t | deleteExpiredReclaimedLeases4 (const uint32_t secs)=0
| Deletes all expired and reclaimed DHCPv4 leases.
virtual uint64_t | deleteExpiredReclaimedLeases6 (const uint32_t secs)=0
| Deletes all expired and reclaimed DHCPv6 leases.
virtual bool | deleteLease (const Lease4Ptr &lease)=0
| Deletes an IPv4 lease.
virtual bool | deleteLease (const Lease6Ptr &lease)=0
| Deletes an IPv6 lease.
virtual size_t | getClassLeaseCount (const ClientClass &client_class, const Lease::Type &ltype=Lease::TYPE_V4) const =0
| Returns the class lease count for a given class and lease type.
virtual std::string | getDescription () const =0
| Returns description of the backend.
virtual void | getExpiredLeases4 (Lease4Collection &expired_leases, const size_t max_leases) const =0
| Returns a collection of expired DHCPv4 leases.
virtual void | getExpiredLeases6 (Lease6Collection &expired_leases, const size_t max_leases) const =0
| Returns a collection of expired DHCPv6 leases.
bool | getExtendedInfoTablesEnabled () const
| Returns the setting indicating if lease6 extended info tables are enabled.
virtual Lease4Collection | getLease4 (const ClientId &clientid) const =0
| Returns existing IPv4 lease for specified client-id.
virtual Lease4Ptr | getLease4 (const ClientId &clientid, SubnetID subnet_id) const =0
| Returns existing IPv4 lease for specified client-id.
virtual Lease4Ptr | getLease4 (const isc::asiolink::IOAddress &addr) const =0
| Returns an IPv4 lease for specified IPv4 address.
virtual Lease4Collection | getLease4 (const isc::dhcp::HWAddr &hwaddr) const =0
| Returns existing IPv4 leases for specified hardware address.
virtual Lease4Ptr | getLease4 (const isc::dhcp::HWAddr &hwaddr, SubnetID subnet_id) const =0
| Returns existing IPv4 leases for specified hardware address and a subnet.
virtual Lease6Collection | getLease6 (const isc::dhcp::HWAddr &hwaddr) const =0
| Returns existing IPv6 leases for specified hardware address.
Lease6Ptr | getLease6 (Lease::Type type, const DUID &duid, uint32_t iaid, SubnetID subnet_id) const
| returns zero or one IPv6 lease for a given duid+iaid+subnet_id
virtual Lease6Ptr | getLease6 (Lease::Type type, const isc::asiolink::IOAddress &addr) const =0
| Returns existing IPv6 lease for a given IPv6 address.
virtual Lease4Collection | getLeases4 () const =0
| Returns all IPv4 leases.
virtual Lease4Collection | getLeases4 (const asiolink::IOAddress &lower_bound_address, const LeasePageSize &page_size) const =0
| Returns range of IPv4 leases using paging.
virtual Lease4Collection | getLeases4 (const std::string &hostname) const =0
| Returns all IPv4 leases for the particular hostname.
virtual Lease4Collection | getLeases4 (SubnetID subnet_id) const =0
| Returns all IPv4 leases for the particular subnet identifier.
virtual Lease4Collection | getLeases4 (uint32_t state, SubnetID subnet_id) const =0
| Returns all IPv4 leases for the particular state and subnet.
virtual Lease4Collection | getLeases4ByRelayId (const OptionBuffer &relay_id, const asiolink::IOAddress &lower_bound_address, const LeasePageSize &page_size, const time_t &qry_start_time=0, const time_t &qry_end_time=0)=0
| Returns existing IPv4 leases with a given relay-id.
virtual Lease4Collection | getLeases4ByRemoteId (const OptionBuffer &remote_id, const asiolink::IOAddress &lower_bound_address, const LeasePageSize &page_size, const time_t &qry_start_time=0, const time_t &qry_end_time=0)=0
| Returns existing IPv4 leases with a given remote-id.
virtual Lease6Collection | getLeases6 () const =0
| Returns all IPv6 leases.
virtual Lease6Collection | getLeases6 (const asiolink::IOAddress &lower_bound_address, const LeasePageSize &page_size) const =0
| Returns range of IPv6 leases using paging.
virtual Lease6Collection | getLeases6 (const DUID &duid) const =0
| Returns collection of leases for matching DUID.
virtual Lease6Collection | getLeases6 (const std::string &hostname) const =0
| Returns all IPv6 leases for the particular hostname.
virtual Lease6Collection | getLeases6 (Lease::Type type, const DUID &duid, uint32_t iaid) const =0
| Returns existing IPv6 leases for a given DUID+IA combination.
virtual Lease6Collection | getLeases6 (Lease::Type type, const DUID &duid, uint32_t iaid, SubnetID subnet_id) const =0
| Returns existing IPv6 lease for a given DUID+IA combination.
virtual Lease6Collection | getLeases6 (SubnetID subnet_id) const =0
| Returns all IPv6 leases for the particular subnet identifier.
virtual Lease6Collection | getLeases6 (SubnetID subnet_id, const asiolink::IOAddress &lower_bound_address, const LeasePageSize &page_size) const =0
| Returns a page of IPv6 leases for a subnet identifier.
virtual Lease6Collection | getLeases6 (uint32_t state, SubnetID subnet_id) const =0
| Returns all IPv6 leases for the particular state and subnet.
virtual Lease6Collection | getLeases6ByRelayId (const DUID &relay_id, const asiolink::IOAddress &lower_bound_address, const LeasePageSize &page_size)=0
| Returns existing IPv6 leases with a given relay-id.
virtual Lease6Collection | getLeases6ByRemoteId (const OptionBuffer &remote_id, const asiolink::IOAddress &lower_bound_address, const LeasePageSize &page_size)=0
| Returns existing IPv6 leases with a given remote-id.
virtual std::string | getName () const =0
| Returns backend name.
virtual data::ElementPtr | getStatus () const
| Return status information.
virtual std::string | getType () const =0
| Return backend type.
virtual VersionPair | getVersion (const std::string &timer_name=std::string()) const =0
| Returns backend version.
virtual isc::data::ConstElementPtr | lfcStartHandler ()
| Handler for kea-lfc-start command.
virtual void | recountClassLeases4 ()=0
| Recount the leases per class for V4 leases.
virtual void | recountClassLeases6 ()=0
| Recount the leases per class for V6 leases.
void | recountLeaseStats4 ()
| Recalculates per-subnet and global stats for IPv4 leases.
void | recountLeaseStats6 ()
| Recalculates per-subnet and global stats for IPv6 leases.
virtual void | rollback ()=0
| Rollback Transactions.
void | setExtendedInfoTablesEnabled (const bool enabled)
| Modifies the setting whether the lease6 extended info tables are enabled.
virtual bool | sflqCreateFlqPool4 (asiolink::IOAddress start_address, asiolink::IOAddress end_address, SubnetID subnet_id, bool recreate=false)
| Creates a v4 SFLQ Pool.
virtual bool | sflqCreateFlqPool6 (asiolink::IOAddress start_address, asiolink::IOAddress end_address, Lease::Type lease_type, uint8_t delegated_len, SubnetID subnet_id, bool recreate=false)
| Calls stored procedure to create an SFLQ pool for v6.
virtual asiolink::IOAddress | sflqPickFreeLease4 (asiolink::IOAddress start_address, asiolink::IOAddress end_address)
| Finds a free V4 address within the given pool range.
virtual asiolink::IOAddress | sflqPickFreeLease6 (asiolink::IOAddress start_address, asiolink::IOAddress end_address)
| Finds a free V6 address/prefix within the given pool range.
virtual bool | sflqPool4Del (asiolink::IOAddress start_address, asiolink::IOAddress end_address, bool force=false)
| Delete the SFLQ V4 pool that matches a start and end address.
virtual SflqPoolInfoCollectionPtr | sflqPool4Get (asiolink::IOAddress start_address, asiolink::IOAddress end_address)
| Fetch all SFLQ V4 pools that overlap an address range.
virtual SflqPoolInfoCollectionPtr | sflqPool4Get (SubnetID subnet_id)
| Fetch all SFLQ V4 pools belonging to a subnet.
virtual SflqPoolInfoCollectionPtr | sflqPool4GetAll ()
| Fetch all SFLQ V4 pools.
virtual bool | sflqPool6Del (asiolink::IOAddress start_address, asiolink::IOAddress end_address, bool force=false)
| Delete the SFLQ V6 pool that matches a start and end address.
virtual SflqPoolInfoCollectionPtr | sflqPool6Get (asiolink::IOAddress start_address, asiolink::IOAddress end_address)
| Fetch all SFLQ V6 pools that overlap an address range.
virtual SflqPoolInfoCollectionPtr | sflqPool6Get (SubnetID subnet_id)
| Fetch all SFLQ V6 pools belonging to a subnet.
virtual SflqPoolInfoCollectionPtr | sflqPool6GetAll ()
| Fetch all SFLQ V6 pools.
virtual LeaseStatsQueryPtr | startLeaseStatsQuery4 ()
| Creates and runs the IPv4 lease stats query for all subnets.
virtual LeaseStatsQueryPtr | startLeaseStatsQuery6 ()
| Creates and runs the IPv6 lease stats query for all subnets.
virtual LeaseStatsQueryPtr | startPoolLeaseStatsQuery4 ()
| Creates and runs the IPv4 lease stats query for all subnets and pools.
virtual LeaseStatsQueryPtr | startPoolLeaseStatsQuery6 ()
| Creates and runs the IPv6 lease stats query for all subnets and pools.
virtual LeaseStatsQueryPtr | startSubnetLeaseStatsQuery4 (const SubnetID &subnet_id)
| Creates and runs the IPv4 lease stats query for a single subnet.
virtual LeaseStatsQueryPtr | startSubnetLeaseStatsQuery6 (const SubnetID &subnet_id)
| Creates and runs the IPv6 lease stats query for a single subnet.
virtual LeaseStatsQueryPtr | startSubnetRangeLeaseStatsQuery4 (const SubnetID &first_subnet_id, const SubnetID &last_subnet_id)
| Creates and runs the IPv4 lease stats query for a single subnet.
virtual LeaseStatsQueryPtr | startSubnetRangeLeaseStatsQuery6 (const SubnetID &first_subnet_id, const SubnetID &last_subnet_id)
| Creates and runs the IPv6 lease stats query for a single subnet.
virtual void | updateLease4 (const Lease4Ptr &lease4)=0
| Updates IPv4 lease.
virtual void | updateLease6 (const Lease6Ptr &lease6)=0
| Updates IPv6 lease.
virtual size_t | upgradeExtendedInfo4 (const LeasePageSize &page_size)=0
| Upgrade extended info (v4).
virtual size_t | upgradeExtendedInfo6 (const LeasePageSize &page_size)=0
| Upgrade extended info (v6).
virtual void | wipeExtendedInfoTables6 ()=0
| Wipe extended info table (v6).
virtual size_t | wipeLeases4 (const SubnetID &subnet_id)=0
| Virtual method which removes specified leases.
virtual size_t | wipeLeases6 (const SubnetID &subnet_id)=0
| Virtual method which removes specified leases.
virtual void | writeLeases4 (const std::string &filename)=0
| Write V4 leases to a file.
virtual void | writeLeases6 (const std::string &filename)=0
| Write V6 leases to a file.

## Protected Types
typedef boost::multi_index_container< Callback, boost::multi_index::indexed_by< boost::multi_index::ordered_non_unique< boost::multi_index::composite_key< Callback, boost::multi_index::member< Callback, CallbackType, &Callback::type >, boost::multi_index::member< Callback, SubnetID, &Callback::subnet_id >, boost::multi_index::member< Callback, Lease::Type, &Callback::lease_type > > >, boost::multi_index::ordered_non_unique< boost::multi_index::composite_key< Callback, boost::multi_index::member< Callback, SubnetID, &Callback::subnet_id >, boost::multi_index::member< Callback, Lease::Type, &Callback::lease_type > > > > > | CallbackContainer
| A multi-index container holding registered callbacks.
typedef boost::shared_ptr< CallbackContainer > | CallbackContainerPtr
| Pointer to the callback container.

## Protected Member Functions
| TrackingLeaseMgr ()
| Constructor.
void | runCallbacks (CallbackType type, const LeasePtr &lease)
| Runs registered callbacks of the particular type.
void | runCallbacksForSubnetID (CallbackType type, SubnetID subnet_id, const LeasePtr &lease)
| Runs registered callbacks of the particular type for a subnet id.
void | trackAddLease (const LeasePtr &lease)
| Invokes the callbacks when a new lease is added.
void | trackDeleteLease (const LeasePtr &lease)
| Invokes the callbacks when a lease is deleted.
void | trackUpdateLease (const LeasePtr &lease)
| Invokes the callbacks when a lease is updated.
bool | tryLock (const LeasePtr &lease)
| Attempts to lock a lease.
void | unlock (const LeasePtr &lease)
| Attempts to unlock a lease.
Protected Member Functions inherited from isc::dhcp::LeaseMgr
virtual bool | addExtendedInfo6 (const Lease6Ptr &lease)
| Extract extended info from a lease6 and add it into tables.
virtual void | addRelayId6 (const isc::asiolink::IOAddress &lease_addr, const std::vector< uint8_t > &relay_id)=0
| Add lease6 extended info into by-relay-id table.
virtual void | addRemoteId6 (const isc::asiolink::IOAddress &lease_addr, const std::vector< uint8_t > &remote_id)=0
| Add lease6 extended info into by-remote-id table.
virtual void | deleteExtendedInfo6 (const isc::asiolink::IOAddress &addr)=0
| Delete lease6 extended info from tables.
void | setExtendedInfoTablesEnabled (const db::DatabaseConnection::ParameterMap &parameters)
| Extended information / Bulk Lease Query shared interface.

## Static Protected Member Functions
static std::string | callbackTypeToString (CallbackType type)
| Converts callback type to string for logging purposes.

## Protected Attributes
CallbackContainerPtr | callbacks_
| The multi-index container holding registered callbacks.
std::unordered_set< asiolink::IOAddress, asiolink::IOAddress::Hash > | locked_leases_
| A set of locked leases.

## Friends
class | LeaseMgrFactory
| The `LeaseMgrFactory` manages the `LeaseMgr` instances and has to be able to move installed callbacks between them.

## Additional Inherited Members
Static Public Member Functions inherited from isc::dhcp::LeaseMgr
static void | bumpStat (const std::string &stat, SubnetID &subnet_id, PoolPtr pool, int value)
| Helper function that adds a value to an address stat's global, subnet, and pool level values.
static void | bumpStatPrefix (const std::string &stat, SubnetID &subnet_id, PoolPtr pool, int value)
| Helper function that adds a value to a prefix stat's global, subnet, and pool level values.
static void | extractLease4ExtendedInfo (const Lease4Ptr &lease, bool ignore_errors=true)
| Extract relay and remote identifiers from the extended info.
static std::string | getDBVersion ()
| Class method to return extended version info This class method must be redeclared and redefined in derived classes.
static void | updateStatsOnAdd (const Lease4Ptr &lease)
| Update in-memory stats when adding a v4 lease.
static void | updateStatsOnAdd (const Lease6Ptr &lease)
| Update in-memory stats when adding a V6 lease.
static void | updateStatsOnDelete (const Lease4Ptr &lease)
| Update in-memory stats when deleting a v4 lease.
static void | updateStatsOnDelete (const Lease6Ptr &lease)
| Update in-memory stats when deleting a v6 lease.
static void | updateStatsOnUpdate (const Lease4Ptr &existing, const Lease4Ptr &lease)
| Update in-memory stats when updating a v4 lease.
static void | updateStatsOnUpdate (const Lease6Ptr &existing, const Lease6Ptr &lease)
| Update in-memory stats when updating a v6 lease.
static bool | upgradeLease4ExtendedInfo (const Lease4Ptr &lease, CfgConsistency::ExtendedInfoSanity check=CfgConsistency::EXTENDED_INFO_CHECK_FIX)
| The following queries are used to fulfill Bulk Lease Query queries.
static bool | upgradeLease6ExtendedInfo (const Lease6Ptr &lease, CfgConsistency::ExtendedInfoSanity check=CfgConsistency::EXTENDED_INFO_CHECK_FIX)
| Upgrade a V6 lease user context to the new extended info entry.
static bool | useSharedFlqStatement (Lease4Ptr lease)
| Determine if SFLQ alternate SQL statements should be used for a given v4 lease.
static bool | useSharedFlqStatement (Lease6Ptr lease)
| Determine if SFLQ alternate SQL statements should be used for a given v6 lease.

## Detailed Description

Introduces callbacks into the `LeaseMgr`.

The LeaseMgr is a central point of lease management and is aware of all lease changes within the server instance. Thus, it is a good opportunity to allow installing callbacks in the `LeaseMgr` to track all lease changes. An allocator maintaining a list of free leases (FLQ allocator) can benefit from it by/ installing the callbacks that add or remove free leases from this list, depending on the lease manager's activity. The callbacks are invoked regardless if the lease changes result from a normal lease allocation or a control command. The callbacks can also be useful for maintaining a log of lease changes. Such a log could be made available externally and consumed by another application (e.g., Stork).

The lease manager can track three types of calls: new lease insertion (add), an existing lease update, and lease deletion. Even though the lease reclamation is similar to deleting a lease because it becomes free, it is a lease update from the lease manager's standpoint. Currently, the lease manager cannot track the deletion of the reclaimed leases (i.e., the leases in the expired-reclaimed state).

The lease backends should call the suitable tracking functions: `trackAddLease`, `trackUpdateLease`, and `trackDeleteLease`. However, the backends must ensure that there are no race conditions between modifying the lease in the database and running the callbacks. Suppose that two threads modify the same lease. Thread A inserts the lease in the database, and thread B removes it. The callback for thread A should be invoked before the callback for thread B. If they are invoked in reverse order, it can result in an inconsistent state in the free lease queue allocator because the allocator should record the lease as available after the thread B callback. The reverse invocation order would result in marking the lease as unavailable for allocation after both callbacks.

The race condition does not occur for the Memfile backend because it guards entire functions with a mutex. However, the SQL backends rely on the database to guard against concurrent writes. In these cases, the backend must protect against the reverse order of callbacks. They should use the lease locking mechanism introduced in the `TrackingLeaseMgr`.

The lease locking is modeled on an `unordered_set` container holding the leases with the ongoing allocations. The leases are inserted into this container by the `tryLock` function. If another thread has already locked the lease, this function returns `false` to indicate an unsuccessful attempt. In this case, the thread should resign from updating the lease and return early. It can result in a lease allocation failure, but two concurrent threads extremely rarely work on allocating a lease for the same client. A passive wait could be another option here, but it is a much more complicated solution for a bit of gain.

Definition at line 76 of file tracking_lease_mgr.h.

## Member Typedef Documentation

## ◆ CallbackContainer

typedef boost::multi_index_container< Callback, boost::multi_index::indexed_by< boost::multi_index::ordered_non_unique< boost::multi_index::composite_key< Callback, boost::multi_index::member<Callback, CallbackType, &Callback::type>, boost::multi_index::member<Callback, SubnetID, &Callback::subnet_id>, boost::multi_index::member<Callback, Lease::Type, &Callback::lease_type> > >, boost::multi_index::ordered_non_unique< boost::multi_index::composite_key< Callback, boost::multi_index::member<Callback, SubnetID, &Callback::subnet_id>, boost::multi_index::member<Callback, Lease::Type, &Callback::lease_type> > > > > isc::dhcp::TrackingLeaseMgr::CallbackContainer
| protected

A multi-index container holding registered callbacks.

The callbacks are accessible via two indexes. The first composite index filters the callbacks by the callback type (i.e., lease add, update or delete) and the subnet id. The second index filters the callbacks by the subnet id and the lease type.

Definition at line 150 of file tracking_lease_mgr.h.

## ◆ CallbackContainerPtr

typedef boost::shared_ptr<CallbackContainer> isc::dhcp::TrackingLeaseMgr::CallbackContainerPtr
| protected

Pointer to the callback container.

Definition at line 153 of file tracking_lease_mgr.h.

## ◆ CallbackFn

typedef std::function<void(LeasePtr)> isc::dhcp::TrackingLeaseMgr::CallbackFn

Type of a callback function invoked upon a lease insertion, update or deletion.

The first argument is a pointer to the lease for which the callback is invoked.

Definition at line 97 of file tracking_lease_mgr.h.

## Member Enumeration Documentation

## ◆ CallbackType

enum isc::dhcp::TrackingLeaseMgr::CallbackType

An enumeration differentiating between lease write operations.

Enumerator
TRACK_ADD_LEASE |
TRACK_UPDATE_LEASE |
TRACK_DELETE_LEASE |

Definition at line 86 of file tracking_lease_mgr.h.

## Constructor & Destructor Documentation

## ◆ TrackingLeaseMgr()

isc::dhcp::TrackingLeaseMgr::TrackingLeaseMgr | ( |  | ) |
| protected

Constructor.

Definition at line 22 of file tracking_lease_mgr.cc.

References isc::dhcp::LeaseMgr::LeaseMgr(), TrackingLeaseMgr(), and callbacks_.

Referenced by isc::dhcp::Memfile_LeaseMgr::Memfile_LeaseMgr(), and TrackingLeaseMgr().

Here is the call graph for this function:

## Member Function Documentation

## ◆ callbackTypeToString()

std::string isc::dhcp::TrackingLeaseMgr::callbackTypeToString | ( | CallbackType | type | ) |
| staticprotected

Converts callback type to string for logging purposes.

Parameters

  type | callback type.

Returns
  callback type name or the 'unknown' string.

Definition at line 114 of file tracking_lease_mgr.cc.

References TRACK_ADD_LEASE, TRACK_DELETE_LEASE, and TRACK_UPDATE_LEASE.

Referenced by runCallbacksForSubnetID().

## ◆ hasCallbacks()

bool isc::dhcp::TrackingLeaseMgr::hasCallbacks | ( |  | ) | const

Checks if any callbacks have been registered.

It is a quick check to be performed by the backends whether or not the callbacks mechanism is used.

Returns
  true if any callbacks have been registered.

Definition at line 109 of file tracking_lease_mgr.cc.

References callbacks_.

## ◆ isLocked()

bool isc::dhcp::TrackingLeaseMgr::isLocked | ( | const LeasePtr & | lease | ) |

Checks if the lease is locked.

This function is useful in the unit tests.

Returns
  true if the lease is locked, false otherwise.

Definition at line 40 of file tracking_lease_mgr.cc.

References locked_leases_.

## ◆ registerCallback() [1/2]

void isc::dhcp::TrackingLeaseMgr::registerCallback | ( | TrackingLeaseMgr::CallbackType | type,
|  | std::string | owner,
|  | Lease::Type | lease_type,
|  | TrackingLeaseMgr::CallbackFn | callback_fn )

Registers a callback function for all subnets.

Parameters

  type | callback type.
  owner | callback owner identifier.
  lease_type | a lease type.
  callback_fn | callback function instance.

Exceptions

  InvalidOperation | when the callback has been already registered for the given owner and all subnets.

Definition at line 85 of file tracking_lease_mgr.cc.

References registerCallback().

Here is the call graph for this function:

## ◆ registerCallback() [2/2]

void isc::dhcp::TrackingLeaseMgr::registerCallback | ( | TrackingLeaseMgr::CallbackType | type,
|  | std::string | owner,
|  | SubnetID | subnet_id,
|  | Lease::Type | lease_type,
|  | TrackingLeaseMgr::CallbackFn | callback_fn )

Registers a callback function for a subnet.

Parameters

  type | callback type.
  owner | callback owner identifier.
  subnet_id | subnet identifier; it can be set to 0 if the callback should be called for all subnets.
  lease_type | a lease type.
  callback_fn | callback function instance.

Exceptions

  InvalidOperation | when the callback has been already registered for the given owner and the subnet identifier.

Definition at line 60 of file tracking_lease_mgr.cc.

References callbacks_, isc_throw, and isc::dhcp::Lease::typeToText().

Referenced by registerCallback().

Here is the call graph for this function:

## ◆ runCallbacks()

void isc::dhcp::TrackingLeaseMgr::runCallbacks | ( | TrackingLeaseMgr::CallbackType | type,
|  | const LeasePtr & | lease )
| protected

Runs registered callbacks of the particular type.

The specified lease instance contains the subnet identifier used to filter the callbacks to be invoked.

Parameters

  type | callback type.
  lease | lease instance for which the callbacks are invoked.

Definition at line 128 of file tracking_lease_mgr.cc.

References runCallbacksForSubnetID().

Referenced by trackAddLease(), trackDeleteLease(), and trackUpdateLease().

Here is the call graph for this function:

## ◆ runCallbacksForSubnetID()

void isc::dhcp::TrackingLeaseMgr::runCallbacksForSubnetID | ( | CallbackType | type,
|  | SubnetID | subnet_id,
|  | const LeasePtr & | lease )
| protected

Runs registered callbacks of the particular type for a subnet id.

It is called internally by the `runCallbacks` function.

Parameters

  type | callback type.
  subnet_id | subnet identifier for which the callbacks are invoked.
  lease | lease instance for which the callbacks are invoked.

Definition at line 135 of file tracking_lease_mgr.cc.

References callbacks_, callbackTypeToString(), isc::dhcp::DHCPSRV_LEASE_MGR_CALLBACK_EXCEPTION, isc::dhcp::DHCPSRV_LEASE_MGR_CALLBACK_UNKNOWN_EXCEPTION, isc::dhcp::dhcpsrv_logger, and LOG_WARN.

Referenced by runCallbacks().

Here is the call graph for this function:

## ◆ trackAddLease()

void isc::dhcp::TrackingLeaseMgr::trackAddLease | ( | const LeasePtr & | lease | ) |
| protected

Invokes the callbacks when a new lease is added.

It executes all callbacks of the `TRACK_ADD_LEASE` type for a subnet id of 0 and the subnet id associated with the lease.

The callbacks execution order is not guaranteed.

Parameters

  lease | new lease instance.

Definition at line 45 of file tracking_lease_mgr.cc.

References runCallbacks(), and TRACK_ADD_LEASE.

Here is the call graph for this function:

## ◆ trackDeleteLease()

void isc::dhcp::TrackingLeaseMgr::trackDeleteLease | ( | const LeasePtr & | lease | ) |
| protected

Invokes the callbacks when a lease is deleted.

It executes all callbacks of the `TRACK_DELETE_LEASE` type for a subnet id of 0 and the subnet id associated with the lease.

The callbacks execution order is not guaranteed.

Parameters

  lease | deleted lease instance.

Definition at line 55 of file tracking_lease_mgr.cc.

References runCallbacks(), and TRACK_DELETE_LEASE.

Here is the call graph for this function:

## ◆ trackUpdateLease()

void isc::dhcp::TrackingLeaseMgr::trackUpdateLease | ( | const LeasePtr & | lease | ) |
| protected

Invokes the callbacks when a lease is updated.

It executes all callbacks of the `TRACK_UPDATE_LEASE` type for a subnet id of 0 and the subnet id associated with the lease.

The callbacks execution order is not guaranteed.

Parameters

  lease | updated lease instance.

Definition at line 50 of file tracking_lease_mgr.cc.

References runCallbacks(), and TRACK_UPDATE_LEASE.

Here is the call graph for this function:

## ◆ tryLock()

bool isc::dhcp::TrackingLeaseMgr::tryLock | ( | const LeasePtr & | lease | ) |
| protected

Attempts to lock a lease.

If a lease is successfully locked, no other thread can lock it. It protects against running the callbacks out of order when two threads modify the same lease. Such a locking should only be used when the lease allocation followed by the callbacks invocation are not protected by some other synchronization mechanism. In particular, the Memfile backend uses a mutex for locking in the lease allocation functions. In this case, it is unnecessary to apply a lock at the lease level. The SQL backends rely on the database locking mechanisms to prevent the concurrent updates of the same lease. These backends must use the lease locking to ensure the correct callbacks invocation order.

This function is not thread-safe and must be invoked in a thread-safe context.

Parameters

  lease | a lease instance for which the lock should be attempted.

Returns
  true when locking was successful, false otherwise. In the latter case, the thread should stop a lease allocation or deallocation attempt.

Definition at line 27 of file tracking_lease_mgr.cc.

References locked_leases_.

## ◆ unlock()

void isc::dhcp::TrackingLeaseMgr::unlock | ( | const LeasePtr & | lease | ) |
| protected

Attempts to unlock a lease.

This function is not thread-safe and must be invoked in a thread-safe context.

Parameters

  lease | a lease instance for which unlocking should be attempted.

Definition at line 34 of file tracking_lease_mgr.cc.

References locked_leases_.

## ◆ unregisterAllCallbacks()

void isc::dhcp::TrackingLeaseMgr::unregisterAllCallbacks | ( |  | ) |

Unregisters all callbacks.

Definition at line 104 of file tracking_lease_mgr.cc.

References callbacks_.

## ◆ unregisterCallbacks()

void isc::dhcp::TrackingLeaseMgr::unregisterCallbacks | ( | SubnetID | subnet_id,
|  | Lease::Type | lease_type )

Unregisters all callbacks for a given subnet identifier.

Parameters

  subnet_id | a subnet identifier.
  lease_type | a lease type.

Definition at line 93 of file tracking_lease_mgr.cc.

References callbacks_.

Referenced by isc::dhcp::Allocator::~Allocator().

## Friends And Related Symbol Documentation

## ◆ LeaseMgrFactory

friend class LeaseMgrFactory
| friend

The `LeaseMgrFactory` manages the `LeaseMgr` instances and has to be able to move installed callbacks between them.

No other external class can have access to the callbacks container. Thus, we can't make the container public. The friend declaration deals with it cleanly.

Definition at line 83 of file tracking_lease_mgr.h.

References LeaseMgrFactory.

Referenced by LeaseMgrFactory.

## Member Data Documentation

## ◆ callbacks_

CallbackContainerPtr isc::dhcp::TrackingLeaseMgr::callbacks_
| protected

The multi-index container holding registered callbacks.

Definition at line 296 of file tracking_lease_mgr.h.

Referenced by TrackingLeaseMgr(), hasCallbacks(), isc::dhcp::LeaseMgrFactory::recreate(), registerCallback(), runCallbacksForSubnetID(), unregisterAllCallbacks(), and unregisterCallbacks().

## ◆ locked_leases_

std::unordered_set<asiolink::IOAddress, asiolink::IOAddress::Hash> isc::dhcp::TrackingLeaseMgr::locked_leases_
| protected

A set of locked leases.

It is empty if locking is not used (e.g. Memfile backend) or when there are no ongoing allocations.

Definition at line 302 of file tracking_lease_mgr.h.

Referenced by isLocked(), tryLock(), and unlock().

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

- tracking_lease_mgr.h
- tracking_lease_mgr.cc