src/gromacs/utility/common.h

   1 /*
   2  *
   3  *                This source code is part of
   4  *
   5  *                 G   R   O   M   A   C   S
   6  *
   7  *          GROningen MAchine for Chemical Simulations
   8  *
   9  * Written by David van der Spoel, Erik Lindahl, Berk Hess, and others.
  10  * Copyright (c) 1991-2000, University of Groningen, The Netherlands.
  11  * Copyright (c) 2001-2009, The GROMACS development team,
  12  * check out http://www.gromacs.org for more information.
  13  *
  14  * This program is free software; you can redistribute it and/or
  15  * modify it under the terms of the GNU General Public License
  16  * as published by the Free Software Foundation; either version 2
  17  * of the License, or (at your option) any later version.
  18  *
  19  * If you want to redistribute modifications, please consider that
  20  * scientific software is very special. Version control is crucial -
  21  * bugs must be traceable. We will be happy to consider code for
  22  * inclusion in the official distribution, but derived work must not
  23  * be called official GROMACS. Details are found in the README & COPYING
  24  * files - if they are missing, get the official version at www.gromacs.org.
  25  *
  26  * To help us fund GROMACS development, we humbly ask that you cite
  27  * the papers on the package - you can find them in the top README file.
  28  *
  29  * For more info, check our website at http://www.gromacs.org
  30  */
  31 /*! \file
  32  * \brief
  33  * Declares common utility classes and macros.
  34  *
  35  * This header contains helpers used to implement classes in the library.
  36  * It is installed, because the helpers are used in installed headers, but
  37  * typically users of the library should not need to be aware of these helpers.
  38  *
  39  * \author Teemu Murtola <teemu.murtola@cbr.su.se>
  40  * \inlibraryapi
  41  * \ingroup module_utility
  42  */
  43 #ifndef GMX_UTILITY_COMMON_H
  44 #define GMX_UTILITY_COMMON_H
  45
  46 #include <boost/scoped_ptr.hpp>
  47
  48 /*! \cond libapi */
  49 /*! \libinternal \brief
  50  * Macro to declare a class non-copyable and non-assignable.
  51  *
  52  * For consistency, should appear last in the class declaration.
  53  *
  54  * \inlibraryapi
  55  */
  56 #define GMX_DISALLOW_COPY_AND_ASSIGN(ClassName) \
  57     private: \
  58         ClassName(const ClassName &); \
  59         ClassName                 &operator=(const ClassName &)
  60 /*! \libinternal \brief
  61  * Macro to declare a class non-assignable.
  62  *
  63  * For consistency, should appear last in the class declaration.
  64  *
  65  * \inlibraryapi
  66  */
  67 #define GMX_DISALLOW_ASSIGN(ClassName) \
  68     private: \
  69         ClassName &operator=(const ClassName &)
  70 //! \endcond
  71
  72 namespace gmx
  73 {
  74
  75 /*! \libinternal \brief
  76  * Helper class to manage a pointer to a private implementation class.
  77  *
  78  * This helper provides the following benefits (all but the last could also be
  79  * achieved with boost::scoped_ptr):
  80  *  - Automatic memory management: the implementation pointer is freed in
  81  *    the destructor automatically.  If the destructor is not declared or is
  82  *    defined inline in the header file, a compilation error occurs instead
  83  *    of a memory leak or undefined behavior.
  84  *  - Exception safety in constructors: the implementation pointer is freed
  85  *    correctly even if the constructor of the containing class throws after
  86  *    the implementation class is constructed.
  87  *  - Copy and/or assignment is automatically disallowed if explicit copy
  88  *    constructor and/or assignment operator is not provided.
  89  *  - Compiler helps to manage const-correctness: in const methods, it is not
  90  *    possible to change the implementation class.
  91  *
  92  * Intended use:
  93  * \code
  94    // In exampleclass.h
  95    class ExampleClass
  96    {
  97        public:
  98            ExampleClass();
  99            ~ExampleClass(); // Must not be defined inline
 100
 101            // <...>
 102
 103        private:
 104            class Impl;
 105
 106            PrivateImplPointer<Impl> impl_;
 107    };
 108
 109    // In exampleclass.cpp
 110
 111    // <definition of ExampleClass::Impl>
 112
 113    ExampleClass::ExampleClass()
 114        : impl_(new Impl)
 115    {
 116    }
 117
 118    ExampleClass::~ExampleClass()
 119    {
 120    }
 121  * \endcode
 122  * \inlibraryapi
 123  * \ingroup module_utility
 124  */
 125 template <class Impl>
 126 class PrivateImplPointer
 127 {
 128     public:
 129         //! Initialize with the given implementation class.
 130         explicit PrivateImplPointer(Impl *ptr) : ptr_(ptr) {}
 131         ~PrivateImplPointer() {}
 132
 133         /*! \brief
 134          * Sets a new implementation class and destructs the previous one.
 135          *
 136          * Needed, e.g., to implement assignable classes.
 137          */
 138         void reset(Impl *ptr) { ptr_.reset(ptr); }
 139         //! Access the raw pointer.
 140         Impl *get() { return ptr_.get(); }
 141         //! Access the implementation class as with a raw pointer.
 142         Impl *operator->() { return ptr_.get(); }
 143         //! Access the implementation class as with a raw pointer.
 144         Impl &operator*() { return *ptr_; }
 145         //! Access the raw pointer.
 146         const Impl *get() const { return ptr_.get(); }
 147         //! Access the implementation class as with a raw pointer.
 148         const Impl *operator->() const { return ptr_.get(); }
 149         //! Access the implementation class as with a raw pointer.
 150         const Impl &operator*() const { return *ptr_; }
 151
 152     private:
 153         boost::scoped_ptr<Impl> ptr_;
 154
 155         // Copy and assign disabled by the scoped_ptr member.
 156 };
 157
 158 } // namespace gmx
 159
 160 #endif