/*
 * Project: MoleCuilder
 * Description: creates and alters molecular systems
 * Copyright (C)  2010 University of Bonn. All rights reserved.
 * Please see the LICENSE file or "Copyright notice" in builder.cpp for details.
 */

/**
 * \file observer.dox
 *
 * Created on: Dec 1, 2011
 *    Author: heber
 */

/** \page pattern-observer
 *
 * Basic structure for the observer pattern
 *
 * Observers register themselves with the observables to be notified when something changes.
 * In the Observable code that changes, attributes should be started with OBSERVE;. This macro
 * locks the observer mechanism while changes are done. At the end of the scope in which the
 * macro was placed the lock is released. When the last lock is released all changes are
 * propagated to the observers.
 *
 * Each observerable can have sub-observables. When one of these sub-observables changes and
 * notifies its observers the observable that contains them will also notify its observers.
 * This passing on of updates is blocked, when the main-observable is in the process of
 * updating many of its internal sub-observables. This means the update is not passed, if
 * it is produced while the main-observable itself is within any Observation block.
 *
 * \section pattern-observer-howtos Howto
 *
 *  Below you find various howtos to guide you through how to use the various
 *  observer patterns.
 *
 * \section pattern-observer-howtos-observer Observers
 *
 *  \todo write howto for using an Observer
 *
 * \section pattern-observer-howtos-observables Observables
 *
 *  \todo write howto for using an Observable
 *
 * \section pattern-observer-howtos-relay Relays
 *
 *  Lets us assume that you want to observe all instances of class "foo".
 *  In order to create a Relay you have to do the following:
 *  -# Create a new class "bar" that inherits the Relay pattern.
 *  \code
 *    #include "CodePatterns/Relay.hpp"
 *    class bar : public Relay {
 *    ...
 *    };
 *  \endcode
 *  -# In the constructor bar::bar() create a Channels object for your Relay and
 *     add a channel for each of foo's channels, use foo's enum for this:
 *   \code
 *     bar::bar() {
 *      Channels *OurChannel = new Channels();
 *      NotificationChannels.insert( std::make_pair(this, OurChannel) );
 *      OurChannel->addChannel(foo::Notification1);
 *      OurChannel->addChannel(foo::Notification2);
 *      ...
 *     }
 *   \endcode
 *   -# Someplace else you have add all Observers that need to check on all
 *      instances of "foo" to be signed on.
 *    \code
 *    bar barInstance;
 *    ... someObserverInstance;
 *    barInstance.signOn(someObserverInstance);
 *    \endcode
 *   -# ... or maybe just for a specific channel of foo.
 *    \code
 *    bar barInstance;
 *    ... someObserverInstance;
 *    barInstance.signOn(someObserverInstance, foo::Notification1);
 *    \endcode
 *
 *
 * \date 2011-12-01
 */