Plumed.h File Reference

#include <cstddef>
#include <cstring>
#include <cstdio>
#include <cstdlib>
#include <cassert>
#include <climits>
#include <exception>
#include <stdexcept>
#include <string>
#include <ios>
#include <new>
#include <typeinfo>
#include <array>
#include <initializer_list>

Classes
class	PLMD::Plumed::add_buffer_to< T >
class	PLMD::Plumed::Exception
	Base class used to rethrow PLUMED exceptions. More...
class	PLMD::Plumed::ExceptionDebug
	Used to rethrow a PLMD::ExceptionDebug. More...
class	PLMD::Plumed::ExceptionError
	Used to rethrow a PLMD::ExceptionError. More...
class	PLMD::Plumed::ExceptionTypeError
	Thrown when a wrong pointer is passed to the PLUMED interface. More...
class	PLMD::Plumed::finalize_plumed_error
	Internal class to simplify plumed_error finalization. More...
class	PLMD::Plumed::Invalid
	Thrown when trying to access an invalid plumed object. More...
class	PLMD::Plumed::LeptonException
	Class used to rethrow Lepton exceptions. More...
class	PLMD::Plumed
	C++ wrapper for plumed. More...
struct	plumed
	Main plumed object. More...
struct	plumed_error
	Small structure that is only defined locally to retrieve errors. More...
struct	plumed_error_filesystem_path
struct	plumed_nothrow_handler
struct	plumed_safeptr
	Structure holding a typesafe pointer. More...
class	PLMD::Plumed::rethrow_nested
	Internal class used by exception_dispatch. More...
class	PLMD::Plumed::rethrow_not_nested
	Internal class used by exception_dispatch. More...
class	PLMD::Plumed::SafePtr
	Small class that wraps plumed_safeptr in order to make its initialization easier. More...

Namespaces
	PLMD

Macros
#define	__PLUMED_WRAPPER_ANONYMOUS_BEGIN
#define	__PLUMED_WRAPPER_ANONYMOUS_END
#define	__PLUMED_WRAPPER_C_BEGIN   __PLUMED_WRAPPER_EXTERN_C_BEGIN extern
#define	__PLUMED_WRAPPER_C_END   __PLUMED_WRAPPER_EXTERN_C_END
#define	__PLUMED_WRAPPER_C_TYPESAFE   0
#define	__PLUMED_WRAPPER_CXX   1
#define	__PLUMED_WRAPPER_CXX_ANONYMOUS_NAMESPACE   0
#define	__PLUMED_WRAPPER_CXX_ANONYMOUS_NAMESPACE_PLMD_EXCEPTIONS   0
#define	__PLUMED_WRAPPER_CXX_BIND_C   1
#define	__PLUMED_WRAPPER_CXX_DEFAULT_INVALID   0
#define	__PLUMED_WRAPPER_CXX_ENABLE_NESTED_EXCEPTIONS   1
#define	__PLUMED_WRAPPER_CXX_EXCEPTION_BUFFER   512
#define	__PLUMED_WRAPPER_CXX_EXPLICIT   explicit
#define	__PLUMED_WRAPPER_CXX_LONGLONG   1
#define	__PLUMED_WRAPPER_CXX_NOEXCEPT   noexcept
#define	__PLUMED_WRAPPER_CXX_NORETURN   [[ noreturn ]]
#define	__PLUMED_WRAPPER_CXX_NULLPTR   nullptr
#define	__PLUMED_WRAPPER_CXX_OVERRIDE   override
#define	__PLUMED_WRAPPER_CXX_POLYMORPHIC   1
#define	__PLUMED_WRAPPER_CXX_STD   1
#define	__PLUMED_WRAPPER_CXX_TYPESAFE   1
#define	__PLUMED_WRAPPER_ENABLE_RTLD_DEEPBIND   1
#define	__PLUMED_WRAPPER_EXTERN   1
#define	__PLUMED_WRAPPER_EXTERN_C_BEGIN   extern "C" {
#define	__PLUMED_WRAPPER_EXTERN_C_END   }
#define	__PLUMED_WRAPPER_GLOBAL   1
#define	__PLUMED_WRAPPER_IMPLEMENTATION_   0
#define	__PLUMED_WRAPPER_INTERNALS_BEGIN   __PLUMED_WRAPPER_EXTERN_C_BEGIN static
#define	__PLUMED_WRAPPER_INTERNALS_END   __PLUMED_WRAPPER_EXTERN_C_END
#define	__PLUMED_WRAPPER_LIBCXX11   0
#define	__PLUMED_WRAPPER_LIBCXX17   0
#define	__PLUMED_WRAPPER_REDEFINE_CMD   ::PLMD::Plumed::plumed_cmd_cxx
#define	__PLUMED_WRAPPER_REDEFINE_ERROR_RETHROW   ::PLMD::Plumed::plumed_error_rethrow_cxx
#define	__PLUMED_WRAPPER_REDEFINE_GCMD   ::PLMD::Plumed::plumed_gcmd_cxx
#define	__PLUMED_WRAPPER_SAFEPTR(type, code, size)
	Macro that uses __PLUMED_WRAPPER_SAFEPTR_INNER to generate constructors with all possible pointer-const combinations. More...
#define	__PLUMED_WRAPPER_SAFEPTR_EMPTY(type, code)   __PLUMED_WRAPPER_SAFEPTR(type,code,0)
	Macro that generates the constructors from empy types (those of which sizeof cannot be computed) More...
#define	__PLUMED_WRAPPER_SAFEPTR_INNER(type_, flags_)
	Macro that generate a constructor with given type and flags. More...
#define	__PLUMED_WRAPPER_SAFEPTR_SIZED(type, code)
	Macro that generates the constructors from sized types (those of which sizeof can be computed). More...
#define	__PLUMED_WRAPPER_STATIC_INLINE   static inline
#define	__PLUMED_WRAPPER_STD   ::std::
#define	plumed_error_rethrow   __PLUMED_WRAPPER_REDEFINE_ERROR_RETHROW

Typedefs
typedef struct plumed_error	plumed_error
	Small structure that is only defined locally to retrieve errors. More...
typedef struct plumed_error_filesystem_path	plumed_error_filesystem_path

Functions
void	plumed_cmd_safe (plumed p, const char *key, plumed_safeptr)
void	plumed_cmd_safe_nothrow (plumed p, const char *key, plumed_safeptr, plumed_nothrow_handler nothrow)
plumed	plumed_create_dlopen2 (const char *path, int mode)
	Constructor from path. More...
plumed	plumed_create_dlsym (void *dlhandle)
	Constructor from dlopen handle. More...
__PLUMED_WRAPPER_STATIC_INLINE void	plumed_error_finalize (plumed_error error) noexcept
	Finalize error - should be called when an error is raised to avoid leaks. More...
__PLUMED_WRAPPER_STATIC_INLINE void	plumed_error_init (plumed_error *error) noexcept
	Initialize error (for internal usage) More...
__PLUMED_WRAPPER_STATIC_INLINE void	plumed_error_merge_with_nested (plumed_error *error) noexcept
	Merge with nested exceptions. More...
__PLUMED_WRAPPER_STATIC_INLINE void	plumed_error_recursive_merge (plumed_error *error, char *buffer, const char *join, __PLUMED_WRAPPER_STD size_t *len) noexcept
	Recursive merge (for internal usage) More...
__PLUMED_WRAPPER_CXX_NORETURN __PLUMED_WRAPPER_STATIC_INLINE void	plumed_error_rethrow (plumed_error h)
	Rethrow error (calling abort) More...
__PLUMED_WRAPPER_STATIC_INLINE void	plumed_error_set (void *ptr, int code, const char *what, const void *opt) noexcept
	Callback (for internal usage) More...
__PLUMED_WRAPPER_STATIC_INLINE void	plumed_error_set_bad_alloc (plumed_error *error)
	Set error to bad_alloc (for internal usage). More...
const __PLUMED_WRAPPER_STATIC_INLINE char *	plumed_error_what (plumed_error error) noexcept
	Access message - more robust than directly accessing what ptr, for future extensibility. More...
void	plumed_free (void *ptr)
	This is an internal tool, to make sure that all free calls inside the plumed library refer to the same implementation. More...
void *	plumed_malloc (__PLUMED_WRAPPER_STD size_t size)
	This is an internal tool, to make sure that all malloc calls inside the plumed library refer to the same implementation. More...
static __PLUMED_WRAPPER_ANONYMOUS_BEGIN bool	PLMD::PlumedGetenvExceptionsDebug () noexcept
	Retrieve PLUMED_EXCEPTIONS_DEBUG (internal utility). More...

Macro Definition Documentation

__PLUMED_WRAPPER_ANONYMOUS_BEGIN

#define __PLUMED_WRAPPER_ANONYMOUS_BEGIN

__PLUMED_WRAPPER_ANONYMOUS_END

#define __PLUMED_WRAPPER_ANONYMOUS_END

__PLUMED_WRAPPER_C_BEGIN

#define __PLUMED_WRAPPER_C_BEGIN   __PLUMED_WRAPPER_EXTERN_C_BEGIN extern

__PLUMED_WRAPPER_C_END

#define __PLUMED_WRAPPER_C_END   __PLUMED_WRAPPER_EXTERN_C_END

__PLUMED_WRAPPER_C_TYPESAFE

#define __PLUMED_WRAPPER_C_TYPESAFE   0

__PLUMED_WRAPPER_CXX

#define __PLUMED_WRAPPER_CXX   1

__PLUMED_WRAPPER_CXX_ANONYMOUS_NAMESPACE

#define __PLUMED_WRAPPER_CXX_ANONYMOUS_NAMESPACE   0

__PLUMED_WRAPPER_CXX_ANONYMOUS_NAMESPACE_PLMD_EXCEPTIONS

#define __PLUMED_WRAPPER_CXX_ANONYMOUS_NAMESPACE_PLMD_EXCEPTIONS   0

__PLUMED_WRAPPER_CXX_BIND_C

#define __PLUMED_WRAPPER_CXX_BIND_C   1

__PLUMED_WRAPPER_CXX_DEFAULT_INVALID

#define __PLUMED_WRAPPER_CXX_DEFAULT_INVALID   0

__PLUMED_WRAPPER_CXX_ENABLE_NESTED_EXCEPTIONS

#define __PLUMED_WRAPPER_CXX_ENABLE_NESTED_EXCEPTIONS   1

__PLUMED_WRAPPER_CXX_EXCEPTION_BUFFER

#define __PLUMED_WRAPPER_CXX_EXCEPTION_BUFFER   512

__PLUMED_WRAPPER_CXX_EXPLICIT

#define __PLUMED_WRAPPER_CXX_EXPLICIT   explicit

__PLUMED_WRAPPER_CXX_LONGLONG

#define __PLUMED_WRAPPER_CXX_LONGLONG   1

__PLUMED_WRAPPER_CXX_NOEXCEPT

#define __PLUMED_WRAPPER_CXX_NOEXCEPT   noexcept

__PLUMED_WRAPPER_CXX_NORETURN

#define __PLUMED_WRAPPER_CXX_NORETURN   [[ noreturn ]]

__PLUMED_WRAPPER_CXX_NULLPTR

#define __PLUMED_WRAPPER_CXX_NULLPTR   nullptr

__PLUMED_WRAPPER_CXX_OVERRIDE

#define __PLUMED_WRAPPER_CXX_OVERRIDE   override

__PLUMED_WRAPPER_CXX_POLYMORPHIC

#define __PLUMED_WRAPPER_CXX_POLYMORPHIC   1

__PLUMED_WRAPPER_CXX_STD

#define __PLUMED_WRAPPER_CXX_STD   1

__PLUMED_WRAPPER_CXX_TYPESAFE

#define __PLUMED_WRAPPER_CXX_TYPESAFE   1

__PLUMED_WRAPPER_ENABLE_RTLD_DEEPBIND

#define __PLUMED_WRAPPER_ENABLE_RTLD_DEEPBIND   1

__PLUMED_WRAPPER_EXTERN

#define __PLUMED_WRAPPER_EXTERN   1

__PLUMED_WRAPPER_EXTERN_C_BEGIN

#define __PLUMED_WRAPPER_EXTERN_C_BEGIN   extern "C" {

__PLUMED_WRAPPER_EXTERN_C_END

#define __PLUMED_WRAPPER_EXTERN_C_END   }

__PLUMED_WRAPPER_GLOBAL

#define __PLUMED_WRAPPER_GLOBAL   1

__PLUMED_WRAPPER_IMPLEMENTATION_

#define __PLUMED_WRAPPER_IMPLEMENTATION_   0

__PLUMED_WRAPPER_INTERNALS_BEGIN

#define __PLUMED_WRAPPER_INTERNALS_BEGIN   __PLUMED_WRAPPER_EXTERN_C_BEGIN static

__PLUMED_WRAPPER_INTERNALS_END

#define __PLUMED_WRAPPER_INTERNALS_END   __PLUMED_WRAPPER_EXTERN_C_END

__PLUMED_WRAPPER_LIBCXX11

#define __PLUMED_WRAPPER_LIBCXX11   0

__PLUMED_WRAPPER_LIBCXX17

#define __PLUMED_WRAPPER_LIBCXX17   0

__PLUMED_WRAPPER_REDEFINE_CMD

#define __PLUMED_WRAPPER_REDEFINE_CMD   ::PLMD::Plumed::plumed_cmd_cxx

__PLUMED_WRAPPER_REDEFINE_ERROR_RETHROW

#define __PLUMED_WRAPPER_REDEFINE_ERROR_RETHROW   ::PLMD::Plumed::plumed_error_rethrow_cxx

__PLUMED_WRAPPER_REDEFINE_GCMD

#define __PLUMED_WRAPPER_REDEFINE_GCMD   ::PLMD::Plumed::plumed_gcmd_cxx

__PLUMED_WRAPPER_SAFEPTR

#define __PLUMED_WRAPPER_SAFEPTR	(		type,
			code,
			size
	)

Value:

  __PLUMED_WRAPPER_SAFEPTR_INNER(type,             size | (0x10000*(code)) | (0x2000000*2)) \
  __PLUMED_WRAPPER_SAFEPTR_INNER(type const,       size | (0x10000*(code)) | (0x2000000*3)) \
  __PLUMED_WRAPPER_SAFEPTR_INNER(type*,            size | (0x10000*(code)) | (0x2000000*4)) \
  __PLUMED_WRAPPER_SAFEPTR_INNER(type*const,       size | (0x10000*(code)) | (0x2000000*5)) \
  __PLUMED_WRAPPER_SAFEPTR_INNER(type const*,      size | (0x10000*(code)) | (0x2000000*6)) \
  __PLUMED_WRAPPER_SAFEPTR_INNER(type const*const, size | (0x10000*(code)) | (0x2000000*7))

Macro that uses __PLUMED_WRAPPER_SAFEPTR_INNER to generate constructors with all possible pointer-const combinations.

__PLUMED_WRAPPER_SAFEPTR_EMPTY

#define __PLUMED_WRAPPER_SAFEPTR_EMPTY	(		type,
			code
	)		__PLUMED_WRAPPER_SAFEPTR(type,code,0)

Macro that generates the constructors from empy types (those of which sizeof cannot be computed)

__PLUMED_WRAPPER_SAFEPTR_INNER

#define __PLUMED_WRAPPER_SAFEPTR_INNER	(		type_,
			flags_
	)

Value:

  SafePtr(type_*ptr, __PLUMED_WRAPPER_STD size_t nelem, const __PLUMED_WRAPPER_STD size_t* shape) __PLUMED_WRAPPER_CXX_NOEXCEPT { \
    safe.ptr=ptr; \
    safe.nelem=nelem; \
    safe.shape=const_cast<__PLUMED_WRAPPER_STD size_t*>(shape); \
    safe.flags=flags_; \
    safe.opt=__PLUMED_WRAPPER_CXX_NULLPTR; \
    buffer[0]='\0'; \
  }

Macro that generate a constructor with given type and flags.

__PLUMED_WRAPPER_SAFEPTR_SIZED

#define __PLUMED_WRAPPER_SAFEPTR_SIZED	(		type,
			code
	)

Value:

  __PLUMED_WRAPPER_SAFEPTR(type,code,sizeof(type)) \
  SafePtr(type val, __PLUMED_WRAPPER_STD size_t nelem, const __PLUMED_WRAPPER_STD size_t* shape) __PLUMED_WRAPPER_CXX_NOEXCEPT { \
    assert(sizeof(type)<=32); \
    (void) nelem; \
    (void) shape; \
    safe.ptr=buffer; \
    safe.nelem=1; \
    safe.shape=__PLUMED_WRAPPER_CXX_NULLPTR; \
    safe.flags=sizeof(type) | (0x10000*(code)) | (0x2000000*1); \
    safe.opt=__PLUMED_WRAPPER_CXX_NULLPTR; \
    __PLUMED_WRAPPER_STD memcpy(buffer,&val,sizeof(type)); \
  }

Macro that generates the constructors from sized types (those of which sizeof can be computed).

In addition to generating constructors with all pointer types, it generates a constructor to allow pass-by-value

__PLUMED_WRAPPER_STATIC_INLINE

#define __PLUMED_WRAPPER_STATIC_INLINE   static inline

__PLUMED_WRAPPER_STD

#define __PLUMED_WRAPPER_STD   ::std::

plumed_error_rethrow

#define plumed_error_rethrow   __PLUMED_WRAPPER_REDEFINE_ERROR_RETHROW

Typedef Documentation

plumed_error

typedef struct plumed_error plumed_error

related

Small structure that is only defined locally to retrieve errors.

It is supposed to be used in the C11/C++ plumed_cmd interface as follows:

  plumed p;
  plumed_error error;

  p=plumed_create();

  plumed_cmd(p,"setNatoms",10,&error);
  if(error.code) {
    fprintf(errors,"%d\n",error.code);
    plumed_error_finalize(error); // make sure the error object is finalized!
  }
  // if no error was raised (error.code==0), it is not necessary to call plumed_error_finalize.
  // but doing it is harmless

  // no need to initialize error, it is written in the plumed_cmd function
  plumed_cmd(p,"init",&error);
  if(error.code) {
    fprintf(errors,"%d\n",error.code);
    plumed_error_finalize(error); // make sure the error object is finalized!
  }

The layout of this structure is subject to change, thus all the functions manipulating it are defined as inline/static functions. In the future, we might reach some form of ABI stability, and these functions might be moved below to the implementation file.

Notice that there is a macro plumed_error() defined in the PLUMED source code (at tools/Exception.h). There is no conflict with this type since C preprocessor distinguishes macros and function-like macros.

plumed_error_filesystem_path

typedef struct plumed_error_filesystem_path plumed_error_filesystem_path

Function Documentation

plumed_cmd_safe()

void plumed_cmd_safe	(	plumed	p,
		const char *	key,
		plumed_safeptr
	)

plumed_cmd_safe_nothrow()

void plumed_cmd_safe_nothrow	(	plumed	p,
		const char *	key,
		plumed_safeptr	,
		plumed_nothrow_handler	nothrow
	)

plumed_create_dlopen2()

plumed plumed_create_dlopen2	(	const char *	path,
		int	mode
	)

Constructor from path.

Available as of PLUMED 2.5

Same as plumed_create_dlopen, but also allows to specify the mode for dlopen.

Warning

Use with care, since not all the possible modes work correctly with PLUMED.

plumed_create_dlsym()

plumed plumed_create_dlsym

(

void *

dlhandle

)

Constructor from dlopen handle.

Available as of PLUMED 2.8

Same as plumed_create_dlopen, but it acts on an already loaded library. This allows to separate the library loading from the construction of the plumed object. By using this function, the caller takes the responsibility to later use dlclose on this handle.

plumed_error_finalize()

__PLUMED_WRAPPER_STATIC_INLINE void plumed_error_finalize ( plumed_error  error )

noexcept

Finalize error - should be called when an error is raised to avoid leaks.

plumed_error_init()

__PLUMED_WRAPPER_STATIC_INLINE void plumed_error_init ( plumed_error *  error )

noexcept

Initialize error (for internal usage)

plumed_error_merge_with_nested()

__PLUMED_WRAPPER_STATIC_INLINE void plumed_error_merge_with_nested ( plumed_error *  error )

noexcept

Merge with nested exceptions.

plumed_error_recursive_merge()

__PLUMED_WRAPPER_STATIC_INLINE void plumed_error_recursive_merge ( plumed_error *  error, char *  buffer, const char *  join, __PLUMED_WRAPPER_STD size_t *  len  )

noexcept

Recursive merge (for internal usage)

plumed_error_rethrow()

__PLUMED_WRAPPER_CXX_NORETURN __PLUMED_WRAPPER_STATIC_INLINE void plumed_error_rethrow

(

plumed_error

h

)

Rethrow error (calling abort)

plumed_error_set()

__PLUMED_WRAPPER_STATIC_INLINE void plumed_error_set ( void *  ptr, int  code, const char *  what, const void *  opt  )

noexcept

Callback (for internal usage)

plumed_error_set_bad_alloc()

__PLUMED_WRAPPER_STATIC_INLINE void plumed_error_set_bad_alloc

(

plumed_error *

error

)

Set error to bad_alloc (for internal usage).

At variance with plumed_error_init, it also finalizes the error, possibly deallocating any buffer.

plumed_error_what()

const __PLUMED_WRAPPER_STATIC_INLINE char* plumed_error_what ( plumed_error  error )

noexcept

Access message - more robust than directly accessing what ptr, for future extensibility.

plumed_free()

void plumed_free

(

void *

ptr

)

This is an internal tool, to make sure that all free calls inside the plumed library refer to the same implementation.

When compiling with __PLUMED_WRAPPER_DEBUG_REFCOUNT=1 it is possible to log allocations and deallocations, so as to debug the wrappers.

plumed_malloc()

void* plumed_malloc

(

__PLUMED_WRAPPER_STD size_t

size

)

This is an internal tool, to make sure that all malloc calls inside the plumed library refer to the same implementation.

When compiling with __PLUMED_WRAPPER_DEBUG_REFCOUNT=1 it is possible to log allocations and deallocations, so as to debug the wrappers.