Commit 7a90bcdb authored by M. Eric Irrgang's avatar M. Eric Irrgang Committed by Mark Abraham
Browse files

Add gmxapi::Context.

The Context holds the details necessary to launch work in a given
environment. A runtime session is launched using the configured details
of a Context implementation and the object bindings configured by the
user (managed by the Context).

Part of a sequence of changes introducing gmxapi classes System,
Context, Session, and Workflow.

Supports gmxapi milestone 5

Refs: #2587

Change-Id: I75baed9b5c856f284bc2c2370ef284319e95f13e
parent 4f481ff8
......@@ -57,6 +57,7 @@ set(GMXAPI_RELEASE ${GMXAPI_MAJOR}.${GMXAPI_MINOR}.${GMXAPI_PATCH})
# absolute paths in the build tree. Path component before `gmxapi` can be
# stripped as appropriate by consumers of this list.
set(GMXAPI_PUBLIC_HEADERS
${CMAKE_CURRENT_SOURCE_DIR}/cpp/include/gmxapi/context.h
${CMAKE_CURRENT_SOURCE_DIR}/cpp/include/gmxapi/exceptions.h
${CMAKE_CURRENT_SOURCE_DIR}/cpp/include/gmxapi/gmxapi.h
${CMAKE_CURRENT_SOURCE_DIR}/cpp/include/gmxapi/md.h
......
......@@ -50,6 +50,7 @@ add_subdirectory(include)
configure_file(include/version.h.in include/gmxapi/version.h)
add_library(gmxapi SHARED
context.cpp
exceptions.cpp
md.cpp
mdmodule.cpp
......
/*
* This file is part of the GROMACS molecular simulation package.
*
* Copyright (c) 2018, by the GROMACS development team, led by
* Mark Abraham, David van der Spoel, Berk Hess, and Erik Lindahl,
* and including many others, as listed in the AUTHORS file in the
* top-level source directory and at http://www.gromacs.org.
*
* GROMACS is free software; you can redistribute it and/or
* modify it under the terms of the GNU Lesser General Public License
* as published by the Free Software Foundation; either version 2.1
* of the License, or (at your option) any later version.
*
* GROMACS is distributed in the hope that it will be useful,
* but WITHOUT ANY WARRANTY; without even the implied warranty of
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
* Lesser General Public License for more details.
*
* You should have received a copy of the GNU Lesser General Public
* License along with GROMACS; if not, see
* http://www.gnu.org/licenses, or write to the Free Software Foundation,
* Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
*
* If you want to redistribute modifications to GROMACS, please
* consider that scientific software is very special. Version
* control is crucial - bugs must be traceable. We will be happy to
* consider code for inclusion in the official distribution, but
* derived work must not be called official GROMACS. Details are found
* in the README & COPYING files - if they are missing, get the
* official version at http://www.gromacs.org.
*
* To help us fund GROMACS development, we humbly ask that you cite
* the research papers on the package. Check out http://www.gromacs.org.
*/
#ifndef GMXAPI_CONTEXT_IMPL_H
#define GMXAPI_CONTEXT_IMPL_H
/*! \file
* \brief Declare gmxapi::ContextImpl
*
* \author M. Eric Irrgang <ericirrgang@gmail.com>
* \ingroup gmxapi
*/
#include <memory>
#include <string>
#include "gmxapi/context.h"
namespace gmxapi
{
/*!
* \brief Context implementation base class.
*
* Execution contexts have a uniform interface specified by the API. Implementations for
* particular execution environments can specialize / derive from this base.
*
* \todo Separate interface and implementation.
* \ingroup gmxapi
*/
class ContextImpl final : public std::enable_shared_from_this<ContextImpl>
{
public:
/*!
* \brief Default constructor.
*
* Don't use this. Use create() to get a shared pointer right away.
* Otherwise, shared_from_this() is potentially dangerous.
*
* \todo Make default constructor private or otherwise reduce brittleness of construction.
*/
ContextImpl();
/*!
* \brief Factory function
*
* Since this class provides `shared_from_this`, we need to make sure
* that it never exists without a shared_ptr owning it.
*
* If we can confirm `shared_from_this` is no longer necessary, implementation may change.
*
* \return ownership of a new object
*/
static std::shared_ptr<gmxapi::ContextImpl> create();
/*!
* \brief Copy disallowed because Session state would become ambiguous.
*
* The API implementation needs to unambiguously determine
* which Sessions and Contexts are associated with each other.
* \{
*/
ContextImpl(const ContextImpl&) = delete;
ContextImpl &operator=(const ContextImpl &) = delete;
//! \}
/*!
* \brief Objects are not trivial to move.
*
* \todo Implement move semantics.
* \{
*/
ContextImpl(ContextImpl &&) = delete;
ContextImpl &operator=(ContextImpl &&) = delete;
//! \}
/*!
* \brief Retain the ability to find a launched session while it exists.
*
* The client owns the Session launched by a Context, but it is helpful
* for the Context to know if it has an active Session associated with it.
*/
std::weak_ptr<Session> session_;
/*!
* \brief mdrun command line arguments.
*
* Store arguments provided by the client and pass them when launching
* a simulation runner. This allows client code to access the same
* options as are available to mdrun on the command line while the API
* evolves.
*/
MDArgs mdArgs_;
};
} // end namespace gmxapi
#endif //GMXAPI_CONTEXT_IMPL_H
/*
* This file is part of the GROMACS molecular simulation package.
*
* Copyright (c) 2018, by the GROMACS development team, led by
* Mark Abraham, David van der Spoel, Berk Hess, and Erik Lindahl,
* and including many others, as listed in the AUTHORS file in the
* top-level source directory and at http://www.gromacs.org.
*
* GROMACS is free software; you can redistribute it and/or
* modify it under the terms of the GNU Lesser General Public License
* as published by the Free Software Foundation; either version 2.1
* of the License, or (at your option) any later version.
*
* GROMACS is distributed in the hope that it will be useful,
* but WITHOUT ANY WARRANTY; without even the implied warranty of
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
* Lesser General Public License for more details.
*
* You should have received a copy of the GNU Lesser General Public
* License along with GROMACS; if not, see
* http://www.gnu.org/licenses, or write to the Free Software Foundation,
* Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
*
* If you want to redistribute modifications to GROMACS, please
* consider that scientific software is very special. Version
* control is crucial - bugs must be traceable. We will be happy to
* consider code for inclusion in the official distribution, but
* derived work must not be called official GROMACS. Details are found
* in the README & COPYING files - if they are missing, get the
* official version at http://www.gromacs.org.
*
* To help us fund GROMACS development, we humbly ask that you cite
* the research papers on the package. Check out http://www.gromacs.org.
*/
/*! \file
* \brief Implementation details of gmxapi::Context
*
* \author M. Eric Irrgang <ericirrgang@gmail.com>
* \ingroup gmxapi
*/
#include "gmxapi/context.h"
#include <cassert>
#include <cstring>
#include <memory>
#include <vector>
#include "gromacs/commandline/filenm.h"
#include "gromacs/compat/make_unique.h"
#include "gromacs/mdrun/runner.h"
#include "gmxapi/version.h"
#include "context-impl.h"
namespace gmxapi
{
ContextImpl::ContextImpl()
{
GMX_ASSERT(session_.expired(), "This implementation assumes an expired weak_ptr at initialization.");
}
std::shared_ptr<gmxapi::ContextImpl> ContextImpl::create()
{
std::shared_ptr<ContextImpl> impl = std::make_shared<ContextImpl>();
return impl;
}
// As of gmxapi 0.0.3 there is only one Context type
Context::Context() :
Context {ContextImpl::create()}
{
GMX_ASSERT(impl_, "Context requires a non-null implementation member.");
}
Context::Context(std::shared_ptr<ContextImpl> impl) :
impl_ {std::move(impl)}
{
GMX_ASSERT(impl_, "Context requires a non-null implementation member.");
}
void Context::setMDArgs(const MDArgs &mdArgs)
{
impl_->mdArgs_ = mdArgs;
}
Context::~Context() = default;
} // end namespace gmxapi
/*
* This file is part of the GROMACS molecular simulation package.
*
* Copyright (c) 2018, by the GROMACS development team, led by
* Mark Abraham, David van der Spoel, Berk Hess, and Erik Lindahl,
* and including many others, as listed in the AUTHORS file in the
* top-level source directory and at http://www.gromacs.org.
*
* GROMACS is free software; you can redistribute it and/or
* modify it under the terms of the GNU Lesser General Public License
* as published by the Free Software Foundation; either version 2.1
* of the License, or (at your option) any later version.
*
* GROMACS is distributed in the hope that it will be useful,
* but WITHOUT ANY WARRANTY; without even the implied warranty of
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
* Lesser General Public License for more details.
*
* You should have received a copy of the GNU Lesser General Public
* License along with GROMACS; if not, see
* http://www.gnu.org/licenses, or write to the Free Software Foundation,
* Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
*
* If you want to redistribute modifications to GROMACS, please
* consider that scientific software is very special. Version
* control is crucial - bugs must be traceable. We will be happy to
* consider code for inclusion in the official distribution, but
* derived work must not be called official GROMACS. Details are found
* in the README & COPYING files - if they are missing, get the
* official version at http://www.gromacs.org.
*
* To help us fund GROMACS development, we humbly ask that you cite
* the research papers on the package. Check out http://www.gromacs.org.
*/
#ifndef GMXAPI_CONTEXT_H
#define GMXAPI_CONTEXT_H
/*! \file
* \brief Declares classes representing execution context.
*
* \author M. Eric Irrgang <ericirrgang@gmail.com>
* \ingroup gmxapi
*/
#include <memory>
#include <string>
#include <vector>
namespace gmxapi
{
class Session;
/*!
* \brief Container for arguments passed to the simulation runner.
*
* This is part of an implementation that essentially wraps the command line
* implementation at a high level.
* \todo Modernize expression and handling of MD user options.
*/
using MDArgs = std::vector<std::string>;
/*!
* \brief Context implementation abstract base class.
*
* Context Implementations depend on the execution environment, hardware resources, and
* possibly other factors, and so are not constructed directly but by helper functions.
* Their details are not exposed at the high level API.
* \ingroup gmxapi
*/
class ContextImpl;
/*!
* \brief Execution context.
*
* The execution context represents computing resources and zero, one, or more
* workflows to execute. All API objects exist in some context, which determines
* how the API objects interact underneath the hood.
*
* A proxy can be configured with information needed to initialize a runtime
* environment capable of executing a work load, independently of defining the
* work.
* The actual execution
* environment is not necessarily instantiated / configured until the work is
* performed.
* Thus, construction of a Context object does not necessarily imply
* initialization of compute resources, but any active compute resources are
* appropriately deinitialized when the object is destroyed. However, to allow
* opportunities for exception handling, resources should be deinitialized when
* and as work is completed by the Runner.
*
* Ultimately, the class in this header file should just define an interface.
* Implementations for different execution environments will be provided by the
* library or extension code and documented separately,
* and it should be straight-forward to
* write extension code for other execution environments.
*
* \todo Further encapsulate resource state transitions with Session objects.
*
* \ingroup gmxapi
*/
class Context
{
public:
/*!
* \brief Get a handle to a new default context object.
*/
Context();
~Context();
/*!
* \brief Nearly trivial copy
*
* \{
*/
Context(const Context &) = default;
Context &operator=(const Context &) = default;
//! \}
/*!
* \brief Allow move
*
* \{
*/
Context(Context &&) = default;
Context &operator=(Context &&) = default;
//! \}
/*!
* \brief Construct by wrapping an implementation object.
*
* \param impl Ownership of Context definition and resources.
*/
explicit Context(std::shared_ptr<ContextImpl> impl);
/*!
* \brief Set the simulation runtime arguments for this instance.
*
* \param mdArgs User-provided runtime parameters (such as for `gmx mdrun`)
*
* This is awkwardly named and due for some evolution, since most of the mdrun CLI options pertain
* to the execution environment rather than the simulation parameters. For the first implementation,
* we just map user arguments to the equivalent command-line substrings.
*/
void setMDArgs(const MDArgs &mdArgs);
private:
/*!
* \brief Private implementation
*
* Early implementation has not yet developed distinct handle classes
* for different levels of access to the Context. In this implementation,
* new Context handles to the same resources can be created (in library code)
* by constructing from a smart pointer to an implementation object.
*
* \todo Consider client requirements and ownership contracts.
* Whether/how API client might be required to create and hold a Context
* and/or Session object for the length of a process.
*/
std::shared_ptr<ContextImpl> impl_;
};
} // end namespace gmxapi
#endif // header guard
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment