Commit b59e1eb4 authored by Michal 'vorner' Vaner's avatar Michal 'vorner' Vaner
Browse files

[2207] Documentation of the base ZoneUpdater

parent 98127986
......@@ -16,10 +16,57 @@ namespace isc {
namespace datasrc {
namespace memory {
/// \brief Does an update to a zone.
///
/// This abstract base class represents the work of a reload of a zone.
/// The work is divided into three stages -- load(), install() and cleanup().
/// They should be called in this order for the effect to take place.
///
/// We divide them so the update of zone data can be done asynchronously,
/// in a different thread. The install() operation is the only one that needs
/// to be done in a critical section.
class ZoneUpdater {
public:
/// \brief Get the zone data into memory.
///
/// This is the part that does the time-consuming loading into the memory.
/// This can be run in a separate thread, for example. It has no effect on
/// the data actually served, it only prepares them for future use.
///
/// This is the first method you should call on the object. Never call it
/// multiple times.
///
/// \note As this contains reading of files or other data sources, or with
/// some other source of the data to load, it may throw quite anything.
/// If it throws, do not call any other methods on the object and
/// discard it.
/// \note After successful load(), you have to call cleanup() some time
/// later.
/// \throw isc::Unexpected if called second time.
virtual void load() = 0;
/// \brief Put the changes to effect.
///
/// This replaces the old version of zone with the one previously prepared
/// by load(). It takes ownership of the old zone data, if any.
///
/// You may call it only after successful load() and at most once.
///
/// The operation is expected to be fast and is meant to be used inside
/// a critical section.
///
/// This may throw in rare cases, depending on the concrete implementation.
/// If it throws, you still need to call cleanup().
///
/// \throw isc::Unexpected if called without previous load() or for the
/// second time.
virtual void install() = 0;
/// \brief Clean up resources.
///
/// This releases all resources held by owned zone data. That means the
/// one loaded by load() in case install() was not called or was not
/// successful, or the one replaced in install().
///
/// Generally, this should never throw.
virtual void cleanup() = 0;
};
......
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment