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