-
Notifications
You must be signed in to change notification settings - Fork 30
Primer
This page discusses important core concepts for the Centurion API.
All implementation details in the library are located in the cen::detail namespace.
Do not explicitly use anything from this namespace.
Implementation details are subject to change and/or removal often and without notice.
An important concept in the library is the notion of owners and handles. Essentially, some types come in two flavors, that differ in ownership of the underlying resources.
In accordance to the C++ Core Guidelines, all raw pointers in the library should be considered non-owning by default.
For example, given a function that returns a raw pointer, you should not attempt to free the pointer.
Likewise, given a function accepting a raw pointer parameter, it will not claim ownership of it.
Owning raw pointers are explicitly designated using the owner type alias, e.g. owner<char*>.
There's also the maybe_owner alias, which is typically used in constructors of owner/handle-enabled classes.
Since the owning version will claim ownership of the pointer, and the handle version will not.
Wherever possible, assertions are used to abort the execution of the program whenever null pointers are provided to an API that disallows them.
In general, avoid passing null pointers as C-style strings (const char*), since that is almost always disallowed in the library.
Most types feature stringification support in the form of overloads of the to_string function.
Additionally, all types that provide a to_string overload also provide an overload of operator<< (the stream operator).
This allows for use with standard streams such as std::cout and std::clog from <iostream>.
Certain types provide serialization support, using the API of the Cereal library.
As such, classes with serialization support either have a serialize member function, or an associated overload of the cen::serialize function.
These serialize functions accept a generic "archive" function object, on which operator() is applied to serialize the associated data.
To be clear, you do not need to install Cereal to use Centurion, and it should be relatively straight forward to write archive wrappers for use with other serialization libraries.