| 1 | /*
|
|---|
| 2 | * Project: MoleCuilder
|
|---|
| 3 | * Description: creates and alters molecular systems
|
|---|
| 4 | * Copyright (C) 2010 University of Bonn. All rights reserved.
|
|---|
| 5 | * Please see the LICENSE file or "Copyright notice" in builder.cpp for details.
|
|---|
| 6 | */
|
|---|
| 7 |
|
|---|
| 8 | /**
|
|---|
| 9 | * \file observer.dox
|
|---|
| 10 | *
|
|---|
| 11 | * Created on: Dec 1, 2011
|
|---|
| 12 | * Author: heber
|
|---|
| 13 | */
|
|---|
| 14 |
|
|---|
| 15 | /** \page pattern-observer
|
|---|
| 16 | *
|
|---|
| 17 | * Basic structure for the observer pattern
|
|---|
| 18 | *
|
|---|
| 19 | * Observers register themselves with the observables to be notified when something changes.
|
|---|
| 20 | * In the Observable code that changes, attributes should be started with OBSERVE;. This macro
|
|---|
| 21 | * locks the observer mechanism while changes are done. At the end of the scope in which the
|
|---|
| 22 | * macro was placed the lock is released. When the last lock is released all changes are
|
|---|
| 23 | * propagated to the observers.
|
|---|
| 24 | *
|
|---|
| 25 | * Each observerable can have sub-observables. When one of these sub-observables changes and
|
|---|
| 26 | * notifies its observers the observable that contains them will also notify its observers.
|
|---|
| 27 | * This passing on of updates is blocked, when the main-observable is in the process of
|
|---|
| 28 | * updating many of its internal sub-observables. This means the update is not passed, if
|
|---|
| 29 | * it is produced while the main-observable itself is within any Observation block.
|
|---|
| 30 | *
|
|---|
| 31 | * \section pattern-observer-howtos Howto
|
|---|
| 32 | *
|
|---|
| 33 | * Below you find various howtos to guide you through how to use the various
|
|---|
| 34 | * observer patterns.
|
|---|
| 35 | *
|
|---|
| 36 | * \section pattern-observer-howtos-observer Observers
|
|---|
| 37 | *
|
|---|
| 38 | * \todo write howto for using an Observer
|
|---|
| 39 | *
|
|---|
| 40 | * \section pattern-observer-howtos-observables Observables
|
|---|
| 41 | *
|
|---|
| 42 | * \todo write howto for using an Observable
|
|---|
| 43 | *
|
|---|
| 44 | * \section pattern-observer-howtos-relay Relays
|
|---|
| 45 | *
|
|---|
| 46 | * Lets us assume that you want to observe all instances of class "foo".
|
|---|
| 47 | * In order to create a Relay you have to do the following:
|
|---|
| 48 | * -# Create a new class "bar" that inherits the Relay pattern.
|
|---|
| 49 | * \code
|
|---|
| 50 | * #include "CodePatterns/Relay.hpp"
|
|---|
| 51 | * class bar : public Relay {
|
|---|
| 52 | * ...
|
|---|
| 53 | * };
|
|---|
| 54 | * \endcode
|
|---|
| 55 | * -# In the constructor bar::bar() create a Channels object for your Relay and
|
|---|
| 56 | * add a channel for each of foo's channels, use foo's enum for this:
|
|---|
| 57 | * \code
|
|---|
| 58 | * bar::bar() {
|
|---|
| 59 | * Channels *OurChannel = new Channels();
|
|---|
| 60 | * NotificationChannels.insert( std::make_pair(this, OurChannel) );
|
|---|
| 61 | * OurChannel->addChannel(foo::Notification1);
|
|---|
| 62 | * OurChannel->addChannel(foo::Notification2);
|
|---|
| 63 | * ...
|
|---|
| 64 | * }
|
|---|
| 65 | * \endcode
|
|---|
| 66 | * -# Someplace else you have add all Observers that need to check on all
|
|---|
| 67 | * instances of "foo" to be signed on.
|
|---|
| 68 | * \code
|
|---|
| 69 | * bar barInstance;
|
|---|
| 70 | * ... someObserverInstance;
|
|---|
| 71 | * barInstance.signOn(someObserverInstance);
|
|---|
| 72 | * \endcode
|
|---|
| 73 | * -# ... or maybe just for a specific channel of foo.
|
|---|
| 74 | * \code
|
|---|
| 75 | * bar barInstance;
|
|---|
| 76 | * ... someObserverInstance;
|
|---|
| 77 | * barInstance.signOn(someObserverInstance, foo::Notification1);
|
|---|
| 78 | * \endcode
|
|---|
| 79 | *
|
|---|
| 80 | *
|
|---|
| 81 | * \date 2011-12-01
|
|---|
| 82 | */
|
|---|
| 83 |
|
|---|
