/// Indexes range between 1 and n (where n is the number of the libraries
/// loaded) and are assigned to libraries based on the order the libraries
/// presented to the hooks framework for loading (something that occurs in the
-/// isc::util::HooksManager) class. However, two other indexes are recognised,
+/// isc::util::HooksManager) class. However, two other indexes are recognized,
/// 0 and INT_MAX. These are used when the server itself registers callouts -
/// the server is able to register callouts that get called before any
/// user-library callouts, and ones that get called after user-library callouts.
/// C2 as before, and that the server registers S1 (to run before the
/// user-registered callouts) and S2 (to run after them), the callouts are
/// stored (and executed) in the order S1, A1, A2, B1, B2, B3, C2, C2, S2. In
-/// summary, the recognised index values are:
+/// summary, the recognized index values are:
///
/// - < 0: invalid.
/// - 0: used for server-registered callouts that are called before
/// @param name Name of the hook to which the callout is added.
/// @param callout Pointer to the callout function to be registered.
///
- /// @throw NoSuchHook The hook name is unrecognised.
+ /// @throw NoSuchHook The hook name is unrecognized.
/// @throw Unexpected The hook name is valid but an internal data structure
/// is of the wrong size.
void registerCallout(const std::string& name, CalloutPtr callout);
///
/// @return true if a one or more callouts were deregistered.
///
- /// @throw NoSuchHook The hook name is unrecognised.
+ /// @throw NoSuchHook The hook name is unrecognized.
/// @throw Unexpected The hook name is valid but an internal data structure
/// is of the wrong size.
bool deregisterCallout(const std::string& name, CalloutPtr callout);
///
/// @return true if one or more callouts were deregistered.
///
- /// @throw NoSuchHook Thrown if the hook name is unrecognised.
+ /// @throw NoSuchHook Thrown if the hook name is unrecognized.
bool deregisterAllCallouts(const std::string& name);
/// @brief Checks if callouts are present on a hook
- Component - a Kea process, e.g. the DHCPv4 or DHCPv6 server.
-- Hook/Hook Point - used interchageably, this is a point in the code at
+- Hook/Hook Point - used interchangeably, this is a point in the code at
which a call to user-written functions is made. Each hook has a name and
each hook can have any number (including 0) of user-written functions
attached to it.
The following sections will describe these tasks in more detail.
-@section hooksComponentDefinition Determing the Hook Points
+@section hooksComponentDefinition Determining the Hook Points
Before any other action takes place, the location of the hook points
in the code need to be determined. This of course depends on the
step in the processing of a request, at a point where either useful
information can be passed to a callout and/or the callout can affect
the processing of the component. The latter is achieved in either or both
-of the following eays:
+of the following ways:
- Setting the "skip" flag. This is a boolean flag that the callout can set
and is a quick way of passing information back to the component. It is used
Previous sections have discussed callout registration by user libraries.
It is possible for a component to register its own functions (i.e. within
its own address space) as hook callouts. These functions are called
-in eactly the same way as user callouts, being passed their arguments
+in exactly the same way as user callouts, being passed their arguments
though a CalloutHandle object. (Guidelines for writing callouts can be
found in @ref hooksdgDevelopersGuide.)
Kea has the configuration option to allow static linking. What this
means is that it links against the static Kea libraries and not
- the shareable ones - although it links against the shareable system
+ the sharable ones - although it links against the sharable system
libraries like "libc" and "libstdc++" and well as the sharable libraries
for third-party packages such as log4cplus and MySql.
a Kea shared library containing a global object, address space
is assigned for it. When the hooks framework loads a user-library
linked against the same Kea shared library, the operating system
- recognises that the library is already loaded (and initialized) and
+ recognizes that the library is already loaded (and initialized) and
uses its definition of the global object. Thus both the code in the
Kea image and the code in the user-written shared library
reference the same object.
In particular, there appears to be an issue with the scenario where a
user-written hooks library is run by a statically-linked Kea and then
unloaded. As far as can be determined, on unload the system attempts to
- delete the same logger twice. This is alleviated by explictly clearing
+ delete the same logger twice. This is alleviated by explicitly clearing
the loggerptr_ variable in the isc::log::Logger destructor, but there
is a suspicion that some memory might be lost in these circumstances.
This is still under investigation.
/// @brief Calls the callouts for a given hook
///
- /// Iterates through the libray handles and calls the callouts associated
+ /// Iterates through the library handles and calls the callouts associated
/// with the given hook index.
///
/// @note This method invalidates the current library index set with
/// @brief Constructor
///
- /// This is private as the object is a singleton and can only be addessed
+ /// This is private as the object is a singleton and can only be addressed
/// through the getHooksManager() static method.
HooksManager();
/// in some cases, server authors may not do that. This method is called
/// whenever any hooks execution function is invoked (checking callouts,
/// calling callouts or returning a callout handle). If the HooksManager
- /// is unitialised, it will initialize it with an "empty set" of libraries.
+ /// is uninitialized, it will initialize it with an "empty set"
+ /// of libraries.
///
/// For speed, the test of whether initialization is required is done
/// in-line here. The actual initialization is performed in
data that the user code can examine and, if required, modify.
Kea uses the modified data in the remainder of its processing.
-In order to minimise the interaction between Kea and the user
+In order to minimize the interaction between Kea and the user
code, the latter is built independently of Kea in the form of
a shared library (or libraries). These are made known to Kea
through its configuration mechanism, and Kea loads the library at
@subsubsection hooksdgCalloutContext Per-Request Context
-Although the Kea modules can be characterised as handling a single
+Although the Kea modules can be characterized as handling a single
packet at a time - e.g. the DHCPv4 server receives a DHCPDISCOVER packet,
processes it and responds with an DHCPOFFER, this may not always be true.
Future developments may have the server processing multiple packets
@subsection hooksdgBuild Building the Library
-Building the code requires building a shareable library. This requires
-the the code be compiled as positition-independent code (using the
+Building the code requires building a sharable library. This requires
+the the code be compiled as position-independent code (using the
compiler's "-fpic" switch) and linked as a shared library (with the
linker's "-shared" switch). The build command also needs to point to
the Kea include directory and link in the appropriate libraries.
si->setSomething(...);
// The pointed-to information has been updated but the pointer has not
- // altered, so theree is no need to reset the context.
+ // altered, so there is no need to reset the context.
}
// No context_destroy callout is needed to delete the allocated
change made to the CalloutHandle's arguments, "skip" flag, or per-request
context by the first is visible to the second.
-@subsubsection hooksdgDynamicRegistration Dynamic Registration and Reregistration of Callouts
+@subsubsection hooksdgDynamicRegistration Dynamic Registration and Re-registration of Callouts
The previous sections have dealt with callouts being registered during
the call to "load". The hooks framework is more flexible than that
/// @param name Name of the hook to which the callout is added.
/// @param callout Pointer to the callout function to be registered.
///
- /// @throw NoSuchHook The hook name is unrecognised.
+ /// @throw NoSuchHook The hook name is unrecognized.
/// @throw Unexpected The hook name is valid but an internal data structure
/// is of the wrong size.
void registerCallout(const std::string& name, CalloutPtr callout);
///
/// @return true if a one or more callouts were deregistered.
///
- /// @throw NoSuchHook The hook name is unrecognised.
+ /// @throw NoSuchHook The hook name is unrecognized.
/// @throw Unexpected The hook name is valid but an internal data structure
/// is of the wrong size.
bool deregisterCallout(const std::string& name, CalloutPtr callout);
///
/// @return true if one or more callouts were deregistered.
///
- /// @throw NoSuchHook Thrown if the hook name is unrecognised.
+ /// @throw NoSuchHook Thrown if the hook name is unrecognized.
bool deregisterAllCallouts(const std::string& name);
private:
// Get iterator to matching element.
InverseHookCollection::const_iterator i = inverse_hooks_.find(index);
if (i == inverse_hooks_.end()) {
- isc_throw(NoSuchHook, "hook index " << index << " is not recognised");
+ isc_throw(NoSuchHook, "hook index " << index << " is not recognized");
}
return (i->second);
// Get iterator to matching element.
HookCollection::const_iterator i = hooks_.find(name);
if (i == hooks_.end()) {
- isc_throw(NoSuchHook, "hook name " << name << " is not recognised");
+ isc_throw(NoSuchHook, "hook name " << name << " is not recognized");
}
return (i->second);
/// Sets up a collection of three LibraryHandle objects to use in the test.
CalloutManagerTest() {
- // Set up the server hooks. There is sone singleton for all tests,
+ // Set up the server hooks. There is one singleton for all tests,
// so reset it and explicitly set up the hooks for the test.
ServerHooks& hooks = ServerHooks::getServerHooks();
hooks.reset();
EXPECT_EQ(13465, callout_value_);
// Add a callout from library index 1 - this should appear between the
- // callouts from library index 0 and linrary index 2.
+ // callouts from library index 0 and library index 2.
getCalloutManager()->setLibraryIndex(1);
getCalloutManager()->registerCallout("alpha", callout_seven);
callout_value_ = 0;
/// operation on it and r0 yielding a result r1. Hence we can say that
/// @f[ r1 = hookpt_one(r0, d1) @f]
///
- /// Callout hookpt_two is passed a value d2 and peforms another simple
+ /// Callout hookpt_two is passed a value d2 and performs another simple
/// arithmetic operation on it and d2, yielding r2, i.e.
/// @f[ r2 = hookpt_two(d1, d2) @f]
///
void executeCallCallouts(
const boost::shared_ptr<isc::hooks::CalloutManager>& manager,
int r0, int d1, int r1, int d2, int r2, int d3, int r3) {
- static const char* COMMON_TEXT = " callout returned the wong value";
+ static const char* COMMON_TEXT = " callout returned the wrong value";
static const char* RESULT = "result";
int result;
return (0);
}
-// Final callout multplies the current running total by data_3.
+// Final callout multiplies the current running total by data_3.
static int
hook_nonstandard_three(CalloutHandle& handle) {
/// the order they are used.
void executeCallCallouts(int r0, int d1, int r1, int d2, int r2, int d3,
int r3) {
- static const char* COMMON_TEXT = " callout returned the wong value";
+ static const char* COMMON_TEXT = " callout returned the wrong value";
static const char* RESULT = "result";
// Get a CalloutHandle for the calculation.
// Load the libraries.
EXPECT_TRUE(HooksManager::loadLibraries(library_names));
- // Execute the callouts. Thiis library implements:
+ // Execute the callouts. This library implements:
//
// r3 = (7 * d1 - d2) * d3
{
// Load the libraries.
EXPECT_TRUE(HooksManager::loadLibraries(library_names));
- // Execute the callouts. Thiis library implements:
+ // Execute the callouts. This library implements:
//
// r3 = (7 * d1 - d2) * d3
{
boost::shared_ptr<CalloutManager> manager =
lm_collection.getCalloutManager();
- // Eecute the calculation - callouts can be called but as nothing
+ // Execute the calculation - callouts can be called but as nothing
// happens, the result should always be -1.
executeCallCallouts(manager, -1, 3, -1, 22, -1, 83, -1);
}
}
// Check that the case of the library's unload() function returning a
-// success is handled correcty.
+// success is handled correctly.
TEST_F(LibraryManagerTest, CheckUnload) {
projects / thirdparty / kea.git / commitdiff
