src/api/cpp/context_impl.h

   1 /*
   2  * This file is part of the GROMACS molecular simulation package.
   3  *
   4  * Copyright (c) 2018,2019, by the GROMACS development team, led by
   5  * Mark Abraham, David van der Spoel, Berk Hess, and Erik Lindahl,
   6  * and including many others, as listed in the AUTHORS file in the
   7  * top-level source directory and at http://www.gromacs.org.
   8  *
   9  * GROMACS is free software; you can redistribute it and/or
  10  * modify it under the terms of the GNU Lesser General Public License
  11  * as published by the Free Software Foundation; either version 2.1
  12  * of the License, or (at your option) any later version.
  13  *
  14  * GROMACS is distributed in the hope that it will be useful,
  15  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  16  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  17  * Lesser General Public License for more details.
  18  *
  19  * You should have received a copy of the GNU Lesser General Public
  20  * License along with GROMACS; if not, see
  21  * http://www.gnu.org/licenses, or write to the Free Software Foundation,
  22  * Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301  USA.
  23  *
  24  * If you want to redistribute modifications to GROMACS, please
  25  * consider that scientific software is very special. Version
  26  * control is crucial - bugs must be traceable. We will be happy to
  27  * consider code for inclusion in the official distribution, but
  28  * derived work must not be called official GROMACS. Details are found
  29  * in the README & COPYING files - if they are missing, get the
  30  * official version at http://www.gromacs.org.
  31  *
  32  * To help us fund GROMACS development, we humbly ask that you cite
  33  * the research papers on the package. Check out http://www.gromacs.org.
  34  */
  35 #ifndef GMXAPI_CONTEXT_IMPL_H
  36 #define GMXAPI_CONTEXT_IMPL_H
  37 /*! \file
  38  * \brief Declare gmxapi::ContextImpl
  39  *
  40  * \author M. Eric Irrgang <ericirrgang@gmail.com>
  41  * \ingroup gmxapi
  42  */
  43
  44 #include <memory>
  45 #include <string>
  46
  47 #include "gromacs/mdrun/legacymdrunoptions.h"
  48
  49 #include "gmxapi/context.h"
  50 #include "gmxapi/session.h"
  51
  52 namespace gmxapi
  53 {
  54
  55 /*!
  56  * \brief Context implementation base class.
  57  *
  58  * Execution contexts have a uniform interface specified by the API. Implementations for
  59  * particular execution environments can specialize / derive from this base.
  60  *
  61  * \todo Separate interface and implementation.
  62  * \ingroup gmxapi
  63  */
  64 class ContextImpl final : public std::enable_shared_from_this<ContextImpl>
  65 {
  66     public:
  67         /*!
  68          * \brief Default constructor.
  69          *
  70          * Don't use this. Use create() to get a shared pointer right away.
  71          * Otherwise, shared_from_this() is potentially dangerous.
  72          *
  73          * \todo Make default constructor private or otherwise reduce brittleness of construction.
  74          */
  75         ContextImpl();
  76
  77         /*!
  78          * \brief Factory function
  79          *
  80          * Since this class provides `shared_from_this`, we need to make sure
  81          * that it never exists without a shared_ptr owning it.
  82          *
  83          * If we can confirm `shared_from_this` is no longer necessary, implementation may change.
  84          *
  85          * \return ownership of a new object
  86          */
  87         static std::shared_ptr<gmxapi::ContextImpl> create();
  88
  89         /*!
  90          * \brief Copy disallowed because Session state would become ambiguous.
  91          *
  92          * The API implementation needs to unambiguously determine
  93          * which Sessions and Contexts are associated with each other.
  94          * \{
  95          */
  96         ContextImpl(const ContextImpl&) = delete;
  97         ContextImpl                  &operator=(const ContextImpl &) = delete;
  98         //! \}
  99
 100         /*!
 101          * \brief Objects are not trivial to move.
 102          *
 103          * \todo Implement move semantics.
 104          * \{
 105          */
 106         ContextImpl(ContextImpl &&)            = delete;
 107         ContextImpl &operator=(ContextImpl &&) = delete;
 108         //! \}
 109
 110         /*!
 111          * \brief Translate the workflow to the execution context and launch.
 112          *
 113          * \param work workflow graph
 114          * \return ownership of a new session
 115          *
 116          * \todo This probably makes more sense as a free function, but we need to determine access policies.
 117          *
 118          * Session is returned with shared_ptr ownership so that Context
 119          * can hold a weak_ptr and because Session Resources handles
 120          * are still evolving.
 121          * \todo Hide lifetime management and ownership from handle object.
 122          * We can achieve the necessary aspects of this shared_ptr at a lower level of implementation.
 123          */
 124         std::shared_ptr<Session> launch(const Workflow &work);
 125
 126         /*!
 127          * \brief Retain the ability to find a launched session while it exists.
 128          *
 129          * The client owns the Session launched by a Context, but it is helpful
 130          * for the Context to know if it has an active Session associated with it.
 131          */
 132         std::weak_ptr<Session>  session_;
 133
 134         /*!
 135          * \brief mdrun command line arguments.
 136          *
 137          * Store arguments provided by the client and pass them when launching
 138          * a simulation runner. This allows client code to access the same
 139          * options as are available to mdrun on the command line while the API
 140          * evolves.
 141          */
 142         MDArgs                  mdArgs_;
 143
 144         /*!
 145          * \brief Legacy option-handling and set up for mdrun.
 146          *
 147          * This object should not exist, but is necessary now to introduce
 148          * the API in a way that means CLI and API work similarly and do not
 149          * duplicate definitions e.g. of command-line options.
 150          */
 151         gmx::LegacyMdrunOptions options_;
 152 };
 153
 154 }      // end namespace gmxapi
 155 #endif //GMXAPI_CONTEXT_IMPL_H