boost::openmethod::initialize

Initialize a registry.

Synopsis

Declared in <boost/openmethod/initialize.hpp>

template<
    class Registry = boost::openmethod::default_registry,
    class... Options>
auto
initialize(Options&&... options);

Description

Initialize the registry passed as an explicit function template argument, or default_registry if the registry is not specified. The default can be changed by defining BOOST_OPENMETHOD_DEFAULT_REGISTRY. Option objects can be passed to change the behavior of the function. Currently two options exist:

  • trace Enable tracing of the initialization process.

  • n2216 Enable resolution of ambiguities according to the N2216 paper.

initialize must be called, typically at the beginning of main, before using any of the methods in a registry. It sets up the v‐tables, multi‐method dispatch tables, and any other data required by the policies.

The function returns an object of an unspecified type that contains a report member, itself an object of an unspecified type, thatcontains the following members:

  • std::size_t cells The number of cells in all multi‐method dispatch tables.

  • std::size_t not_implemented The number of multi‐method dispatch tables that contain at least one not implemented entry.

  • std::size_t ambiguous The number of multi‐method dispatch tables that contain at least one ambiguous entry.

A translation unit that calls initialize must include the <boost/openmethod/initialize.hpp> header.

Each policy's initialize is called in the order the policies appear in the registry's policy_list (left to right). If a policy depends on another policy having been initialized first, the dependency must appear earlier in the list; ensuring this is the user's responsibility. finalize finalizes the policies in the reverse order.

Errors

  • missing_class. A class used in a virtual parameter was not registered.

  • The registry's policies may report additional errors.

Exception safety

If initialize throws ‐ because a policy's initialize does, or an allocation fails ‐ the registry keeps the dispatch state it had before the call: no static v‐table pointer, next pointer, dispatch table or policy state is modified. The registry is nonetheless marked as not initialized, since that state does not reflect the current registrations; initialize must be called again, successfully, before any method is called.

Only the policies that define initialize have their state saved and restored, so only those states have to be copyable. A state that no initialize writes to is configuration, not derived data, and is left alone: an error_handler policy is called during initialize, and a handler that changes the configuration ‐ installing a different handler with set, say ‐ keeps that change whether the call succeeds or throws.

Example

Initialize the default registry with tracing enabled, and exit with an error message if there were any possibility of a bad_call error. User may run the program again after setting environment variable BOOST_OPENMETHOD_TRACE to 1 to troubleshoot.

auto report = bom::initialize(bom::trace::from_env()).report;

if (report.not_implemented != 0 || report.ambiguous) {
    std::cerr << "some methods are ambiguous or not implemented for "
                 "some combinations of virtual arguments\n"
                 "set BOOST_OPENMETHOD_TRACE=1 to troubleshoot\n";
    exit(1);
}

Return Value

An object of an unspecified type.

Template Parameters

Name

Description

Registry

The registry to initialize.

Options...

Zero or more option types, deduced from the function arguments.

Parameters

Name

Description

options

Zero or more option objects.

See Also

Methods and Overriders, Shared Libraries

Created with MrDocs