diff --git a/doc/initialize.adoc b/doc/initialize.adoc index 9f2c2c3..466e034 100644 --- a/doc/initialize.adoc +++ b/doc/initialize.adoc @@ -40,4 +40,5 @@ auto finalize() -> void; De-allocates the resources allocated by `initialize` for the `Policy`, including resources allocated by the facets in `Policy`. Resources are de-allocated in an arbitrary order. It is not necessary to call `finalize` between calls to -`initialize`. It may be required to cooperate with memory leak detection tools. +`initialize`. It is provided mainly for the benefit of memory leak detection +schemes. diff --git a/doc/overview.adoc b/doc/overview.adoc index 6bddea5..f7bff48 100644 --- a/doc/overview.adoc +++ b/doc/overview.adoc @@ -24,31 +24,121 @@ the `include` directory to your project's include path. #### boost::openmethod The library's main namespace. Contains `method`, `virtual_ptr` and -`virtual_ptr_traits`, `use_classes`, the `debug` and `release` policies, etc. +`virtual_ptr_traits`, `use_classes`, the `default_policy`, etc. #### boost::openmethod::policies -Contains the policy classes and their facets. +Contains the policy framework. ### Headers #### -The library's main header. Contains `method`, `virtual_ptr` and -`virtual_ptr_traits`, `use_classes`, the `debug` and `release` policies, etc. +The library's main header. Provides `method`, `virtual_ptr` and +`virtual_ptr_traits`, `use_classes`, the default policy, etc. -#### - -Defines `intialize` and `finalize`, which are used to register classes and +If `BOOST_OPENMETHOD_DEFAULT_POLICY` is defined before including this header, +its value is used as the default value for the `Policy` template parameter +throughout the code. Otherwise, `boost::openmethod::default_policy` is used. +Setting `BOOST_OPENMETHOD_DEFAULT_POLICY` after including the core header has no +effect. #### +Provides `BOOST_REGISTER_CLASSES`, `BOOST_OPENMETHOD`, +`BOOST_OPENMETHOD_OVERRIDE` and other macros. + #### -#### +Convenience header. Includes `` and +``. + +Also imports `boost::openmethod::virtual_ptr` in the global namespace. This is +usually regarded as bad practice. The rationale is that OpenMethod emulates a +language feature, and `virtual_ptr` is equivalent to keyword, similar to +`virtual`. Besides, the macros are global as well. + +There are two ways to avoid importing `virtual_ptr` while still using the +macros: + +* Define `BOOST_OPENMETHOD_NO_GLOBAL_VIRTUAL_PTR` before including + ``. This disables the import of `virtual_ptr` in the + global namespace. + +* Include ``and ``. + +#### + +Provides `intialize` and `finalize`. Typically included only by the translation +unit that contains `main`, unless dynamic loading is used in other places in the +program. #### +Provides support for using `std::shared_ptr` in place of plain pointers in +virtual parameters. + #### +Provides support for using `std::unique_ptr` in place of plain pointers in +virtual parameters. + #### + +Provides support for storing v-table pointers directly in objects, in the same +manner as native virtual functions. + +#### + +Provides the `debug` and `release` policies in the `boost::openmethod::policies` +namespace, and `default_policy` in the `boost::openmethod` namespace, which is +an alias to either `debug` or `release`, depending on the value of the +preprocessor symbol `NDEBUG`. + +Usually not included directly. Can be used to create custom policies from stock +policies, by forking them and adjusting a few facets. + +#### + +Provides the constructs used in the policy framework, essentially +`basic_policy`, `facet`, and its abstract subclasses (`rtti`, `extern_vptr`, +etc). + +#### + +Implements the `rtti` facet using standard RTTI. + +#### + +Implements the `rtti` facet using a minimal RTTI implementation. Can be used only with the "final" constructs, or with intrusive v-table pointers. + +#### + +Implements the `extern_vptr` facet using a vector of pointers. + +#### + +Implements the `extern_vptr` facet using a map of pointers. + +#### + +Implements the `type_hash` facet using a perfect hash function. + +#### + +Implements the `error_handler` facet by routing the error through a +`std::function`. + +#### + +Implements the `error_handler` facet by throwing an exception. + +#### + +Implements the `error_output` facet using a lightweight version of +`std::ostream`. + +#### + +Implements the `trace_output` facet using a lightweight version of +`std::ostream`.