Planet
navi homePPSaboutscreenshotsdownloaddevelopmentforum

Ignore:
Timestamp:
Sep 2, 2010, 3:16:08 AM (15 years ago)
Author:
landauf
Message:

added documentation

File:
1 edited

Legend:

Unmodified
Added
Removed

  • code/branches/doc/src/libraries/util/Singleton.h

    r7163 r7323  
    2727 */
    2828
     29/**
     30    @defgroup SingletonScope Singletons and Scope
     31    @ingroup Util
     32*/
     33
     34/**
     35    @file
     36    @ingroup Util SingletonScope
     37    @brief Definition of the Singleton template that is used as base class for classes that allow only one instance.
     38
     39    @anchor SingletonExample
     40
     41    Classes that inherit from orxonox::Singleton follow the singleton pattern and thus
     42    allow only one instance of the class to exist. This istance is stored in a static
     43    variable called @c singletonPtr_s. orxonox::Singleton will access this variable, but
     44    it must be implemented in the deriving class.
     45
     46    Example:
     47    @code
     48    class TestSingleton : public Singleton<TestSingleton>   // inherit from Singleton, pass the own class as template argument
     49    {
     50        friend class Singleton<TestSingleton>;              // friend declaration so Singleton can access singletonPtr_s
     51
     52        public:
     53            TestSingleton();                                // public constructor because we may want to manage this singleton
     54                                                            //     with an orxonox::ScopedSingletonManager (see below)
     55            virtual ~TestSingleton();                       // public destructor
     56
     57            void testFunction();                            // put your functions here
     58
     59        private:
     60            int testValue_;                                 // put your variables here
     61
     62            static TestSingleton* singletonPtr_s;           // static singleton instance pointer, used by the Singleton template
     63    };
     64    @endcode
     65
     66    And don't forget to initialize the static singleton pointer in the source (*.cc) %file:
     67    @code
     68    TestSingleton* TestSingleton::singletonPtr_s = NULL;
     69    @endcode
     70
     71    Usually a singleton gets created automatically when it is first used, but it will never
     72    be destroyed (unless the singleton explicitly deletes itself). To allow controlled
     73    construction and destruction, the singleton can be put within a virtual scope. This is
     74    done by registering the singleton class with orxonox::ScopedSingletonManager. To
     75    do so, the ManageScopedSingleton() macro has to be called:
     76
     77    @code
     78    ManageScopedSingleton(TestSingleton, ScopeID::Graphics, false); // muste be called in a source (*.cc) file
     79    @endcode
     80
     81    @b Important: If you call ManageScopedSingleton(), you don't have to initialize singletonPtr_s anymore,
     82    because that's already done by the macro.
     83
     84    Now the singleton TestSingleton gets automatically created if the scope Graphics becomes
     85    active and also gets destroyed if the scope is deactivated.
     86
     87    Note that not all singletons must register with a scope, but it's recommended.
     88
     89    If a class inherits from orxonox::Singleton, it also inherits its functions. The most important
     90    function is orxonox::Singleton::getInstance() which returns a reference to the only instance
     91    of the singleton.
     92
     93    Example:
     94    @code
     95    TestSingleton::TestSingleton()                          // implement the constructor
     96    {
     97        this->testValue_ = 15;
     98    }
     99
     100    void TestSingleton::testFunction()                      // implement testFunction
     101    {
     102        COUT(0) << "My value is " << this->testValue_ << std::endl;
     103    }
     104
     105    TestSingleton::getInstance().testFunction();            // prints "My value is 15"
     106    @endcode
     107*/
     108
    29109#ifndef __Util_Singleton_H__
    30110#define __Util_Singleton_H__
    … …  
    42122
    43123        Usage:
    44         Inherit publicly from Singleton<MyClass> and provide access to
    45         MyClass::singletonPtr_s.
     124        Inherit publicly from Singleton<MyClass> and provide access to MyClass::singletonPtr_s.
    46125        This can easily be done with a friend declaration.
     126
     127        See @ref SingletonExample "this example" for an exemplary implementation.
    47128    */
    48129    template <class T>
    … …  
    80161        }
    81162
    82         //! Constructor resets the singleton instance pointer
     163        //! Destructor resets the singleton instance pointer
    83164        ~Singleton()
    84165        {
Note: See TracChangeset for help on using the changeset viewer.