Welcome to Kea Host Cache Hooks Library. This documentation is addressed at developers who are interested in internal operation of the library. This file provides information needed to understand and perhaps extend this library.

This documentation is stand-alone: you should have read and understood Kea Developer's Guide and in particular its section about hooks: Hooks Developer's Guide.

Overview

Introduction

This library implements a cache for host reservations, i.e. when a host reservation is looked for a second time the cache answers directly without involving a potentially slow backend.

Interface

The host cache is a host data source: it implements the interface of the isc::dhcp::BaseHostDataSource abstract class extended to isc::dhcp::CacheHostDataSource with a few methods:

insert which inserts a new isc::dhcp::Host in the cache.
remove which removes a host cache entry from the cache.
flush which removes oldest entries.
size returns the number of entries.
capacity returns the maximum number of entries, or 0 if there is none.

Callouts

The host cache can be controlled using callouts:

cache-size returns the number of entries.
cache-clear fully flush the cache.
cache-flush partially flush the cache.
cache-get exports (using toElement) the cache content.
cache-write exports the cache content to a file.
cache-insert imports an entry or a list of entries.
cache-load imports a cache dump done by cache-write to the cache.
cache-get-by-id exports (using toElement) the cache entry(ies) matching an identifier.
cache-remove removes a cache entry.

Internal structure

The host cache is copied from isc::dhcp::CfgHosts class. The container is a similar Boost multi index with two new indexes:

a sequenced access index which organizes entries in the last use order.
a hashed access index which allows to retrieve an iterator from a given entry, i.e. a shared pointer to a isc::dhcp::Host instance.

The cache is implemented by two classes: isc::host_cache::HostCache and its implementation isc::host_cache::HostCacheImpl where access methods are not declared constant.

Control variables are:

maximum_ (impl) is the maximum number of entries, 0 means there is none.

The extended host data source interface is supported with some specific points:

all getAll methods return an empty vector.
insert takes an extra parameter to handle conflicts: if false it does nothing in case of conflicts, if true it removes conflicting entry. The number of conflicts is returned (overwrite false returns at the first conflict so the count can be either 0 or 1).

Multi-Threading Compatibility

The Host Cache Hooks Library reports it is compatible with multi-threading. The cache-flush, cache-clear, cache-get, cache-write and cache-load commands are executed in a critical section so with multi-threading temporarily disabled.