api/cpp/gmxapi/session_impl.h

   1 /*
   2  * This file is part of the GROMACS molecular simulation package.
   3  *
   4  * Copyright (c) 2018,2019,2020, 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
  36 #ifndef GMXAPI_SESSION_IMPL_H
  37 #define GMXAPI_SESSION_IMPL_H
  38 /*! \file
  39  * \brief Declare implementation interface for Session API class(es).
  40  *
  41  * \ingroup gmxapi
  42  */
  43
  44 #include <map>
  45
  46 #include "gromacs/mdrun/runner.h"
  47 #include "gromacs/mdrun/simulationcontext.h"
  48 #include "gromacs/mdrunutility/logging.h"
  49
  50 // Above are the public headers from other modules.
  51 // Following are public headers for the current module.
  52 #include "gmxapi/context.h"
  53 #include "gmxapi/md.h"
  54 #include "gmxapi/status.h"
  55 #include "gmxapi/md/mdmodule.h"
  56 #include "gmxapi/session/resources.h"
  57
  58
  59 namespace gmxapi
  60 {
  61
  62 // Forward declaration
  63 class MpiContextManager; // Locally defined in session.cpp
  64 class ContextImpl;       // locally defined in context.cpp
  65 class SignalManager;     // defined in mdsignals_impl.h
  66
  67 /*!
  68  * \brief Implementation class for executing sessions.
  69  *
  70  * Since 0.0.3, there is only one context and only one session type. This may
  71  * change at some point to allow templating on different resource types or
  72  * implementations provided by different libraries.
  73  * \ingroup gmxapi
  74  */
  75 class SessionImpl
  76 {
  77 public:
  78     //! Use create() factory to get an object.
  79     SessionImpl() = delete;
  80     ~SessionImpl();
  81
  82     /*!
  83      * \brief Check if the session is (still) running.
  84      *
  85      * When a session is launched, it should be returned in an "open" state by the launcher
  86      * function. \return True if running, false if already closed.
  87      */
  88     bool isOpen() const noexcept;
  89
  90     /*!
  91      * \brief Explicitly close the session.
  92      *
  93      * Sessions should be explicitly `close()`ed to allow for exceptions to be caught by the client
  94      * and because closing a session involves a more significant state change in the program than
  95      * implied by a typical destructor. If close() can be shown to be exception safe, this protocol may be removed.
  96      *
  97      * \return On closing a session, a status object is transferred to the caller.
  98      */
  99     Status close();
 100
 101     /*!
 102      * \brief Run the configured workflow to completion or error.
 103      *
 104      * \return copy of the resulting status.
 105      *
 106      * \internal
 107      * By the time we get to the run() we shouldn't have any unanticipated exceptions.
 108      * If there are, they can be incorporated into richer future Status implementations
 109      * or some other more appropriate output type.
 110      */
 111     Status run() noexcept;
 112
 113     /*!
 114      * \brief Create a new implementation object and transfer ownership.
 115      *
 116      * \param context Shared ownership of a Context implementation instance.
 117      * \param runnerBuilder MD simulation builder to take ownership of.
 118      * \param simulationContext Take ownership of the simulation resources.
 119      * \param logFilehandle Take ownership of filehandle for MD logging
 120      *
 121      * \todo Log file management will be updated soon.
 122      *
 123      * \return Ownership of new Session implementation instance.
 124      */
 125     static std::unique_ptr<SessionImpl> create(std::shared_ptr<ContextImpl> context,
 126                                                gmx::MdrunnerBuilder&&       runnerBuilder,
 127                                                gmx::SimulationContext&&     simulationContext,
 128                                                gmx::LogFilePtr              logFilehandle);
 129
 130     /*!
 131      * \brief Add a restraint to the simulation.
 132      *
 133      * \param module
 134      * \return
 135      */
 136     Status addRestraint(std::shared_ptr<gmxapi::MDModule> module);
 137
 138     /*!
 139      * \brief Get a handle to the resources for the named session operation.
 140      *
 141      * \param name unique name of element in workflow
 142      * \return temporary access to the resources.
 143      *
 144      * If called on a non-const Session, creates the resource if it does not yet exist.
 145      * If called on a const Session,
 146      * returns nullptr if the resource does not exist.
 147      */
 148     gmxapi::SessionResources* getResources(const std::string& name) const noexcept;
 149
 150     /*!
 151      * \brief Create SessionResources for a module and bind the module.
 152      *
 153      * Adds a new managed resources object to the Session for the uniquely named module.
 154      * Allows the module to bind to the SignalManager and to the resources object.
 155      *
 156      * \param module
 157      * \return non-owning pointer to created resources or nullptr for error.
 158      *
 159      * If the named module is already registered, calling createResources again is considered an
 160      * error and nullptr is returned.
 161      */
 162     gmxapi::SessionResources* createResources(std::shared_ptr<gmxapi::MDModule> module) noexcept;
 163
 164     /*! \internal
 165      * \brief API implementation function to retrieve the current runner.
 166      *
 167      * \return non-owning pointer to the current runner or nullptr if none.
 168      */
 169     gmx::Mdrunner* getRunner();
 170
 171     /*!
 172      * \brief Get a non-owning handle to the SignalManager for the active MD runner.
 173      *
 174      * Calling code is responsible for ensuring that the SessionImpl is kept alive and "open"
 175      * while the returned SignalManager handle is in use.
 176      *
 177      * \return non-owning pointer if runner and signal manager are active, else nullptr.
 178      */
 179     SignalManager* getSignalManager();
 180
 181     /*!
 182      * \brief Constructor for use by create()
 183      *
 184      * \param context specific context to keep alive during session.
 185      * \param runnerBuilder ownership of the MdrunnerBuilder object.
 186      * \param simulationContext take ownership of a SimulationContext
 187      * \param logFilehandle Take ownership of filehandle for MD logging
 188      *
 189      */
 190     SessionImpl(std::shared_ptr<ContextImpl> context,
 191                 gmx::MdrunnerBuilder&&       runnerBuilder,
 192                 gmx::SimulationContext&&     simulationContext,
 193                 gmx::LogFilePtr              logFilehandle);
 194
 195 private:
 196     /*!
 197      * \brief Manage session resources for named workflow elements.
 198      */
 199     std::map<std::string, std::unique_ptr<SessionResources>> resources_;
 200
 201     /*!
 202      * \brief Extend the life of the owning context.
 203      *
 204      * The session will get handles for logging, UI status messages,
 205      * and other facilities through this interface.
 206      */
 207     std::shared_ptr<ContextImpl> context_;
 208
 209     /*!
 210      * \brief RAII management of gmx::init() and gmx::finalize()
 211      *
 212      * Uses smart pointer to avoid exposing type definition.
 213      * \todo Not fully implemented.
 214      */
 215     std::unique_ptr<MpiContextManager> mpiContextManager_;
 216
 217     /*!
 218      * \brief Simulation runner object.
 219      *
 220      * If a simulation Session is active, points to a valid Mdrunner object.
 221      * Null if simulation is inactive.
 222      */
 223     std::unique_ptr<gmx::Mdrunner> runner_;
 224
 225     /*!
 226      * \brief An active session owns the resources it is using.
 227      */
 228     gmx::SimulationContext simulationContext_;
 229
 230     /*! \brief Handle to file used for logging.
 231      *
 232      * \todo Move to RAII filehandle management; open and close in one place.
 233      */
 234     gmx::LogFilePtr logFilePtr_;
 235
 236     /*!
 237      * \brief Own and manager the signalling pathways for the current session.
 238      *
 239      * Registers a stop signal issuer with the stopConditionBuilder that is
 240      * passed to the Mdrunner at launch. Session members issuing stop signals
 241      * are proxied through this resource.
 242      */
 243     std::unique_ptr<SignalManager> signalManager_;
 244
 245     /*!
 246      * \brief Restraints active in this session.
 247      *
 248      * Client owns these restraint objects, but session has the ability to
 249      * lock the resource to take temporary ownership in case the client
 250      * releases its handle.
 251      * \todo clarify and update object lifetime management
 252      * A restraint module manager and / or a mapping of factory functions with
 253      * which the runner can get objects at run time can encapsulate object management.
 254      */
 255     std::map<std::string, std::weak_ptr<gmx::IRestraintPotential>> restraints_;
 256 };
 257
 258 } // end namespace gmxapi
 259
 260 #endif // GMXAPI_SESSION_IMPL_H