C++ wrapper for plumed. More...

#include <Plumed.h>

Classes
class	Exception
	Base class used to rethrow PLUMED exceptions. More...

class	ExceptionDebug
	Used to rethrow a PLMD::ExceptionDebug. More...

class	ExceptionError
	Used to rethrow a PLMD::ExceptionError. More...

class	ExceptionTypeError
	Thrown when a wrong pointer is passed to the PLUMED interface. More...

class	Invalid
	Thrown when trying to access an invalid plumed object. More...

class	LeptonException
	Class used to rethrow Lepton exceptions. More...

struct	NothrowHandler
	Error handler used to rethrow exceptions. More...

class	SafePtr
	Small class that wraps plumed_safeptr in order to make its initialization easier. More...

Public Member Functions
	Plumed () noexcept
	Constructor. More...

	Plumed (const char *c) noexcept
	Clone a Plumed object from a FORTRAN char* handler. More...

	Plumed (const Plumed &p) noexcept
	Copy constructor. More...

	Plumed (Plumed &&p) noexcept
	Move constructor. More...

	Plumed (plumed p) noexcept
	Clone a Plumed object from a C plumed structure. More...

	Plumed (void *v) noexcept
	Create a reference from a void* pointer. More...

virtual	~Plumed () noexcept
	Destructor. More...

void	cmd (const char *key)
	Send a command to this plumed object. More...

template<typename T >
void	cmd (const char key, T val, __PLUMED_WRAPPER_STD size_t nelem)
	Send a command to this plumed object. More...

template<typename T >
void	cmd (const char key, T val, const __PLUMED_WRAPPER_STD size_t *shape)
	Send a command to this plumed object. More...

template<typename T >
void	cmd (const char key, T val, std::initializer_list< std::size_t > shape)
	Send a command to this plumed object. More...

template<typename T >
void	cmd (const char *key, T val)
	Send a command to this plumed object. More...

Plumed &	decref () noexcept
	Decrease reference counter. More...

Plumed &	incref () noexcept
	Increase reference counter. More...

	operator bool () const noexcept
	Same as valid(). More...

	operator plumed () const noexcept
	Retrieve the C plumed structure for this object. More...

Plumed &	operator= (const Plumed &p) noexcept
	Assignment operator. More...

Plumed &	operator= (Plumed &&p) noexcept
	Move assignment. More...

void	toFortran (char *c) const noexcept
	Retrieve a FORTRAN handler for this object. More...

void *	toVoid () const noexcept
	Retrieve a void* handler for this object. More...

int	useCount () const noexcept
	Returns the number of references to this object. More...

bool	valid () const noexcept
	Check if Plumed object is valid. More...

Static Public Member Functions
static Plumed	dlopen (const char *path) noexcept
	Create a PLUMED object loading a specific kernel. More...

static Plumed	dlopen (const char *path, int mode) noexcept
	Create a PLUMED object loading a specific kernel. More...

static Plumed	dlsym (void *dlhandle) noexcept
	Create a PLUMED object loading from an already opened shared library. More...

static void	gcmd (const char *key)
	Send a command to global-plumed. More...

template<typename T >
static void	gcmd (const char key, T val, __PLUMED_WRAPPER_STD size_t nelem)
	Send a command to global-plumed. More...

template<typename T >
static void	gcmd (const char key, T val, const __PLUMED_WRAPPER_STD size_t *shape)
	Send a command to global-plumed. More...

template<typename T >
static void	gcmd (const char key, T val, std::initializer_list< std::size_t > shape)
	Send a command to global-plumed. More...

template<typename T >
static void	gcmd (const char *key, T val)
	Send a command to global-plumed. More...

static void	gcreate () noexcept
	Initialize global-plumed. More...

static void	gfinalize () noexcept
	Finalize global-plumed. More...

static bool	ginitialized () noexcept
	Check if global-plumed has been initialized. More...

static Plumed	global () noexcept
	Returns the Plumed global object. More...

static bool	gvalid () noexcept
	Check if global-plumed is valid. More...

static bool	installed () noexcept
	Check if plumed is installed (for runtime binding) More...

static Plumed	makeInvalid () noexcept
	Invalid constructor. More...

static Plumed	makeValid () noexcept
	Create a valid PLMD::Plumed object. More...

static void	plumed_cmd_cxx (plumed p, const char key, plumed_error error=__PLUMED_WRAPPER_CXX_NULLPTR)
	These functions can be used to make plumed_cmd behave as the C++ wrapper PLMD::Plumed::cmd, namely implement typechecks and rethrowing exception. More...

template<typename T >
static void	plumed_cmd_cxx (plumed p, const char key, T val, __PLUMED_WRAPPER_STD size_t nelem, plumed_error *error=__PLUMED_WRAPPER_CXX_NULLPTR)
	These functions can be used to make plumed_cmd behave as the C++ wrapper PLMD::Plumed::cmd, namely implement typechecks and rethrowing exception. More...

template<typename T >
static void	plumed_cmd_cxx (plumed p, const char key, T val, const __PLUMED_WRAPPER_STD size_t shape, plumed_error error=__PLUMED_WRAPPER_CXX_NULLPTR)
	These functions can be used to make plumed_cmd behave as the C++ wrapper PLMD::Plumed::cmd, namely implement typechecks and rethrowing exception. More...

template<typename T >
static void	plumed_cmd_cxx (plumed p, const char key, T val, plumed_error *error=__PLUMED_WRAPPER_CXX_NULLPTR)
	These functions can be used to make plumed_cmd behave as the C++ wrapper PLMD::Plumed::cmd, namely implement typechecks and rethrowing exception. More...

template<typename T >
static void	plumed_cmd_cxx (plumed p, const char key, T val, plumed_error error=__PLUMED_WRAPPER_CXX_NULLPTR)
	These functions can be used to make plumed_cmd behave as the C++ wrapper PLMD::Plumed::cmd, namely implement typechecks and rethrowing exception. More...

template<typename T >
static void	plumed_gcmd_cxx (const char key, T val, __PLUMED_WRAPPER_STD size_t nelem, plumed_error error=__PLUMED_WRAPPER_CXX_NULLPTR)
	These functions can be used to make plumed_cmd behave as the C++ wrapper PLMD::Plumed::cmd, namely implement typechecks and rethrowing exception. More...

template<typename T >
static void	plumed_gcmd_cxx (const char key, T val, const __PLUMED_WRAPPER_STD size_t shape, plumed_error *error=__PLUMED_WRAPPER_CXX_NULLPTR)
	These functions can be used to make plumed_cmd behave as the C++ wrapper PLMD::Plumed::cmd, namely implement typechecks and rethrowing exception. More...

template<typename T >
static void	plumed_gcmd_cxx (const char key, T val, plumed_error error=__PLUMED_WRAPPER_CXX_NULLPTR)
	These functions can be used to make plumed_cmd behave as the C++ wrapper PLMD::Plumed::cmd, namely implement typechecks and rethrowing exception. More...

Static Private Member Functions
static void	cmd_priv (plumed main, const char key, SafePtr safe=__PLUMED_WRAPPER_CXX_NULLPTR, const void unsafe=__PLUMED_WRAPPER_CXX_NULLPTR, plumed_error error=__PLUMED_WRAPPER_CXX_NULLPTR)
	Private version of cmd. More...

static void	nothrow_handler (void ptr, int code, const char what, const void *opt) noexcept
	Callback function that sets the error handler. More...

static __PLUMED_WRAPPER_CXX_NORETURN void	rethrow ()
	Rethrow the current exception. More...

static __PLUMED_WRAPPER_CXX_NORETURN void	rethrow (const NothrowHandler &h)
	Rethrow the exception based on the information saved in the NothrowHandler. More...

Private Attributes
plumed	main
	C structure. More...

Related Functions
(Note that these are not member functions.)
bool	operator!= (const Plumed &a, const Plumed &b) noexcept

bool	operator< (const Plumed &a, const Plumed &b) noexcept

bool	operator<= (const Plumed &a, const Plumed &b) noexcept

bool	operator== (const Plumed &a, const Plumed &b) noexcept

bool	operator> (const Plumed &a, const Plumed &b) noexcept

bool	operator>= (const Plumed &a, const Plumed &b) noexcept

static void	plumed_gcmd_cxx (const char key, plumed_error error=__PLUMED_WRAPPER_CXX_NULLPTR)
	These functions can be used to make plumed_cmd behave as the C++ wrapper PLMD::Plumed::cmd, namely implement typechecks and rethrowing exception. More...

Detailed Description

C++ wrapper for plumed.

This class provides a C++ interface to PLUMED. It only containts a plumed object, but wraps it with a number of useful methods. All methods are inlined so as to avoid the compilation of an extra c++ file.

Constructor & Destructor Documentation

◆ Plumed() [1/6]

PLMD::Plumed::Plumed ( )

inlinenoexcept

Constructor.

Notice that when using runtime binding the constructed object might be invalid. One might check it using the valid() method.

Note: Performs the same task a plumed_create()

◆ Plumed() [2/6]

PLMD::Plumed::Plumed ( const char * c )

inlineexplicitnoexcept

Clone a Plumed object from a FORTRAN char* handler.

Parameters

c	The FORTRAN handler (a char[32]).

The reference counter for the corresponding object will be increased to make sure that the object will be available after plumed_f_finalize is called if the created object is still in scope.

◆ Plumed() [3/6]

PLMD::Plumed::Plumed ( void * v )

inlineexplicitnoexcept

Create a reference from a void* pointer.

Available as of PLUMED 2.5.

◆ Plumed() [4/6]

PLMD::Plumed::Plumed ( plumed p )

inlineexplicitnoexcept

Clone a Plumed object from a C plumed structure.

Parameters

p	The C plumed structure.

The reference counter for the corresponding object will be increased to make sure that the object will be available after plumed_finalize is called if the created object is still in scope.

◆ Plumed() [5/6]

PLMD::Plumed::Plumed ( const Plumed & p )

inlinenoexcept

Copy constructor.

Takes a reference, incrementing the reference counter of the corresponding object.

◆ Plumed() [6/6]

PLMD::Plumed::Plumed ( Plumed && p )

inlinenoexcept

Move constructor.

Available as of PLUMED 2.5. Only if move semantics is enabled.

◆ ~Plumed()

virtual PLMD::Plumed::~Plumed ( )

inlinevirtualnoexcept

Destructor.

It calls plumed_finalize(). Notice that this is done also if the constructor failed (that is, if it returned an invalid object). This allows declaring Plumed objects also if PLUMED is actually not available, provided one does not use the cmd method.

Destructor is virtual so as to allow correct inheritance from Plumed object.

Member Function Documentation

◆ cmd() [1/5]

void PLMD::Plumed::cmd ( const char * key )

inline

Send a command to this plumed object.

Parameters

key	The name of the command to be executed

Note: Similar to plumed_cmd(). It actually called plumed_cmd_nothrow() and rethrow any exception raised within PLUMED.

◆ cmd() [2/5]

template<typename T >

void PLMD::Plumed::cmd	(	const char *	key,
		T *	val,
		__PLUMED_WRAPPER_STD size_t	nelem
	)

inline

Send a command to this plumed object.

Parameters

key	The name of the command to be executed
val	The argument, passed by pointer.
nelem	The number of elements passed.

Note: Similar to plumed_cmd(). It actually called plumed_cmd_nothrow() and rethrow any exception raised within PLUMED.; Unless one defines __PLUMED_WRAPPER_CXX_TYPESAFE=0 or PLUMED library is <=2.7, the type of the argument is checked. nelem is used to check the maximum index interpreting the array as flattened.

◆ cmd() [3/5]

template<typename T >

void PLMD::Plumed::cmd	(	const char *	key,
		T *	val,
		const __PLUMED_WRAPPER_STD size_t *	shape
	)

inline

Send a command to this plumed object.

Parameters

key	The name of the command to be executed
val	The argument, passed by pointer.
shape	A zero-terminated array containing the shape of the data.

Note: Similar to plumed_cmd(). It actually called plumed_cmd_nothrow() and rethrow any exception raised within PLUMED.; Unless one defines __PLUMED_WRAPPER_CXX_TYPESAFE=0 or PLUMED library is <=2.7, the type of the argument is checked. If shape is passed, it is also checked that PLUMED access only compatible indexes.

◆ cmd() [4/5]

template<typename T >

void PLMD::Plumed::cmd	(	const char *	key,
		T *	val,
		std::initializer_list< std::size_t >	shape
	)

inline

Send a command to this plumed object.

Parameters

key	The name of the command to be executed
val	The argument, passed by pointer.
shape	The shape of the argument, in the form of an initialier_list (e.g., {10,3}).

Note: Similar to plumed_cmd(). It actually called plumed_cmd_nothrow() and rethrow any exception raised within PLUMED.; Unless one defines __PLUMED_WRAPPER_CXX_TYPESAFE=0 or PLUMED library is <=2.7, the type of the argument is checked. If shape is passed, it is also checked that PLUMED access only compatible indexes.

◆ cmd() [5/5]

template<typename T >

void PLMD::Plumed::cmd	(	const char *	key,
		T	val
	)

inline

Send a command to this plumed object.

Parameters

key	The name of the command to be executed
val	The argument, passed by value.

Note: Similar to plumed_cmd(). It actually called plumed_cmd_nothrow() and rethrow any exception raised within PLUMED.; Unless one defines __PLUMED_WRAPPER_CXX_TYPESAFE=0 or PLUMED library is <=2.7, the type of the argument is checked.

◆ cmd_priv()

static void PLMD::Plumed::cmd_priv	(	plumed	main,
		const char *	key,
		SafePtr *	safe = `__PLUMED_WRAPPER_CXX_NULLPTR`,
		const void *	unsafe = `__PLUMED_WRAPPER_CXX_NULLPTR`,
		plumed_error *	error = `__PLUMED_WRAPPER_CXX_NULLPTR`
	)

inlinestaticprivate

Private version of cmd.

It is used here to avoid duplication of code between typesafe and not-typesafe versions

◆ decref()

Plumed& PLMD::Plumed::decref ( )

inlinenoexcept

Decrease reference counter.

Available as of PLUMED 2.5.

Using this method improperly might interfere with correct object construction and destruction. If you want to play with this, also try to compile using -D__PLUMED_WRAPPER_DEBUG_REFCOUNT=1 and see what happens.

◆ dlopen() [1/2]

static Plumed PLMD::Plumed::dlopen ( const char * path )

inlinestaticnoexcept

Create a PLUMED object loading a specific kernel.

Available as of PLUMED 2.5.

It returns an object created with plumed_create_dlopen. The object is owned and is then finalized in the destructor. It can be used as follows:

  PLMD::Plumed p = PLMD::Plumed::dlopen("/path/to/libplumedKernel.so");
// or, equivalenty:
//    PLMD::Plumed p(PLMD::Plumed::dlopen("/path/to/libplumedKernel.so"));
  p.cmd("init");

or, equivalently, as

  auto p = PLMD::Plumed::dlopen("/path/to/libplumedKernel.so");
  p.cmd("init");

◆ dlopen() [2/2]

static Plumed PLMD::Plumed::dlopen	(	const char *	path,
		int	mode
	)

inlinestaticnoexcept

Create a PLUMED object loading a specific kernel.

Available as of PLUMED 2.5.

Same as dlopen(const char* path), but allows a dlopen mode to be chosen explicitly.

◆ dlsym()

static Plumed PLMD::Plumed::dlsym ( void * dlhandle )

inlinestaticnoexcept

Create a PLUMED object loading from an already opened shared library.

Available as of PLUMED 2.8.

Same as dlopen(const char* path), but searches functions in an already loaded library. See plumed_create_dlsym.

◆ gcmd() [1/5]

static void PLMD::Plumed::gcmd ( const char * key )

inlinestatic

Send a command to global-plumed.

Parameters

key	The name of the command to be executed

Note: Equivalent to plumed_gcmd()

◆ gcmd() [2/5]

template<typename T >

static void PLMD::Plumed::gcmd	(	const char *	key,
		T *	val,
		__PLUMED_WRAPPER_STD size_t	nelem
	)

inlinestatic

Send a command to global-plumed.

Parameters

key	The name of the command to be executed
val	The argument.
nelem	Number of elements in the passed array, for typechecking.

Note: Equivalent to plumed_gcmd()

◆ gcmd() [3/5]

template<typename T >

static void PLMD::Plumed::gcmd	(	const char *	key,
		T *	val,
		const __PLUMED_WRAPPER_STD size_t *	shape
	)

inlinestatic

Send a command to global-plumed.

Parameters

key	The name of the command to be executed
val	The argument.
shape	The shape of the argument.

Note: Equivalent to plumed_gcmd()

◆ gcmd() [4/5]

template<typename T >

static void PLMD::Plumed::gcmd	(	const char *	key,
		T *	val,
		std::initializer_list< std::size_t >	shape
	)

inlinestatic

Send a command to global-plumed.

Parameters

key	The name of the command to be executed
val	The argument.
shape	The shape of the argument, in the form of an initialier_list (e.g., {10,3}).

Note: Equivalent to plumed_gcmd()

◆ gcmd() [5/5]

template<typename T >

static void PLMD::Plumed::gcmd	(	const char *	key,
		T	val
	)

inlinestatic

Send a command to global-plumed.

Parameters

key	The name of the command to be executed
val	The argument.

Note: Equivalent to plumed_gcmd()

◆ gcreate()

static void PLMD::Plumed::gcreate ( )

inlinestaticnoexcept

Initialize global-plumed.

Warning: Using the global objects in C++ is not recommended since they are difficult to use in an exception safe manner. In particular, one should explicitly catch exceptions to properly call gfinalize()

Note: Equivalent to plumed_gcreate()

◆ gfinalize()

static void PLMD::Plumed::gfinalize ( )

inlinestaticnoexcept

Finalize global-plumed.

◆ ginitialized()

static bool PLMD::Plumed::ginitialized ( )

inlinestaticnoexcept

Check if global-plumed has been initialized.

Returns: true if global plumed object (see global()) is initialized (i.e. if gcreate() has been called), false otherwise.

Note: Equivalent to plumed_ginitialized() but returns a bool

◆ global()

static Plumed PLMD::Plumed::global ( )

inlinestaticnoexcept

Returns the Plumed global object.

Notice that the object is copied, thus increasing the reference counter of the global object. In this manner, the global object will survive after a call to gfinalize() if the resulting object is still in scope.

Returns: The Plumed global object

◆ gvalid()

static bool PLMD::Plumed::gvalid ( )

inlinestaticnoexcept

Check if global-plumed is valid.

Returns: true if global plumed object (see global()) is valid.

Note: Equivalent to plumed_gvalid() but returns a bool

◆ incref()

Plumed& PLMD::Plumed::incref ( )

inlinenoexcept

Increase reference counter.

Available as of PLUMED 2.5.

Using this method improperly might interfere with correct object construction and destruction. If you want to play with this, also try to compile using -D__PLUMED_WRAPPER_DEBUG_REFCOUNT=1 and see what happens.

A possible usage is to transfer the ownership of a temporary object when it is converted

plumed p=Plumed::dlopen(path).incref()
// without incref(), the just constructed object will be destroyed
// when the temporary object is deleted.
... do stuff ...
plumed_finalize(p);

◆ installed()

static bool PLMD::Plumed::installed ( )

inlinestaticnoexcept

Check if plumed is installed (for runtime binding)

Returns: true if plumed is installed, false otherwise

Note: Equivalent to plumed_installed() but returns a bool

◆ makeInvalid()

static Plumed PLMD::Plumed::makeInvalid ( )

inlinestaticnoexcept

Invalid constructor.

Available as of PLUMED 2.5.

Can be used to initialize an invalid object. It might be useful to postpone the initialization of a Plumed object. Consider the following case

  Plumed p;
  setenv("PLUMED_KERNEL","/path/to/kernel/libplumedKernel.so",1);
  p.cmd("init")

Here the p object will be initialized before the PLUMED_KERNEL env var has been set. This can be particularly problematic if p is stored in some high level class. The following case would do the job

  Plumed p;
  setenv("PLUMED_KERNEL","/path/to/kernel/libplumedKernel.so",1);
  p=Plumed();
  p.cmd("init")

However, there will be some error reported related to the attempt to load the kernel when p is initialized. The following solution is the optimal one:

  Plumed p(Plumed::makeInvalid());
  setenv("PLUMED_KERNEL","/path/to/kernel/libplumedKernel.so",1);
  p=Plumed();
  p.cmd("init")

◆ makeValid()

static Plumed PLMD::Plumed::makeValid ( )

inlinestaticnoexcept

Create a valid PLMD::Plumed object.

Can be used to create a valid object e.g. when Plumed.h was compiled with -D__PLUMED_WRAPPER_CXX_DEFAULT_INVALID. For internal usage.

◆ nothrow_handler()

static void PLMD::Plumed::nothrow_handler	(	void *	ptr,
		int	code,
		const char *	what,
		const void *	opt
	)

inlinestaticprivatenoexcept

Callback function that sets the error handler.

opt argument is interpreted as the pointer to a null terminated array of void*. The number of non-null element is expected to be even, and there should be a null element that follows. Every pair of pointers should point to a char, identifying the type of argument passed, and an arbitrary object. Currently used to (optionally) pass error_code.

◆ operator bool()

PLMD::Plumed::operator bool ( ) const

inlineexplicitnoexcept

Same as valid().

Available as of PLUMED 2.5.

Allow code such as

Plumed p;
if(!p) raise_error();
p.cmd("init");

In order to avoid ambiguous conversions, this is only allowed when compiling with C++11 where it is marked as explicit.

◆ operator plumed()

PLMD::Plumed::operator plumed ( ) const

inlinenoexcept

Retrieve the C plumed structure for this object.

Notice that the resulting plumed structure is a weak reference and should NOT be finalized, unless a new reference is explicitly added

Plumed p;
plumed c=p;
plumed_finalize(c); // <- this is wrong

Plumed p;
plumed c=plumed_create_reference(p);
plumed_finalize(c); // <- this is right

◆ operator=() [1/2]

Plumed& PLMD::Plumed::operator= ( const Plumed & p )

inlinenoexcept

Assignment operator.

Available as of PLUMED 2.5.

Takes a reference,incrementing the reference counter of the corresponding object.

◆ operator=() [2/2]

Plumed& PLMD::Plumed::operator= ( Plumed && p )

inlinenoexcept

Move assignment.

Available as of PLUMED 2.5. Only if move semantics is enabled.

◆ plumed_cmd_cxx() [1/5]

static void PLMD::Plumed::plumed_cmd_cxx	(	plumed	p,
		const char *	key,
		plumed_error *	error = `__PLUMED_WRAPPER_CXX_NULLPTR`
	)

inlinestatic

These functions can be used to make plumed_cmd behave as the C++ wrapper PLMD::Plumed::cmd, namely implement typechecks and rethrowing exception.