Plumed.h File Reference

#include <stddef.h>
#include <string.h>
#include <stdio.h>
#include <stdlib.h>
#include <limits.h>
#include <assert.h>

Classes
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...

Macros
#define	__PLUMED_WRAPPER_ANONYMOUS_BEGIN
#define	__PLUMED_WRAPPER_ANONYMOUS_END
#define	__PLUMED_WRAPPER_C_BEGIN   __PLUMED_WRAPPER_ANONYMOUS_BEGIN inline
#define	__PLUMED_WRAPPER_C_END   __PLUMED_WRAPPER_ANONYMOUS_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_DETECT_SHAPES_STRICT   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_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_GLOBAL   0
#define	__PLUMED_WRAPPER_IMPLEMENTATION_   0
#define	__PLUMED_WRAPPER_INTERNALS_BEGIN   __PLUMED_WRAPPER_C_BEGIN
#define	__PLUMED_WRAPPER_INTERNALS_END   __PLUMED_WRAPPER_C_END
#define	__PLUMED_WRAPPER_LIBCXX11   0
#define	__PLUMED_WRAPPER_LIBCXX17   0
#define	__PLUMED_WRAPPER_REINTERPRET_CAST(to, what)
#define	__PLUMED_WRAPPER_STATIC_CAST(to, what)
#define	__PLUMED_WRAPPER_STATIC_INLINE   static inline
#define	__PLUMED_WRAPPER_STD

Typedefs
typedef struct plumed_error	plumed_error
	Small structure that is only defined locally to retrieve errors.
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.
plumed	plumed_create_dlsym (void *dlhandle)
	Constructor from dlopen handle.
__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_WRAPPER_STATIC_INLINE void	plumed_error_init (plumed_error *error) noexcept
	Initialize error (for internal usage)
__PLUMED_WRAPPER_STATIC_INLINE void	plumed_error_merge_with_nested (plumed_error *error) noexcept
	Merge with nested exceptions.
__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_WRAPPER_CXX_NORETURN __PLUMED_WRAPPER_STATIC_INLINE void	plumed_error_rethrow (plumed_error h)
	Rethrow error (calling abort)
__PLUMED_WRAPPER_STATIC_INLINE void	plumed_error_set (void *ptr, int code, const char *what, const void *opt) noexcept
	Callback (for internal usage)
__PLUMED_WRAPPER_STATIC_INLINE void	plumed_error_set_bad_alloc (plumed_error *error)
	Set error to bad_alloc (for internal usage).
__PLUMED_WRAPPER_STATIC_INLINE const char *	plumed_error_what (plumed_error error) noexcept
	Access message - more robust than directly accessing what ptr, for future extensibility.
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.
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.

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_ANONYMOUS_BEGIN inline

__PLUMED_WRAPPER_C_END

#define __PLUMED_WRAPPER_C_END   __PLUMED_WRAPPER_ANONYMOUS_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_DETECT_SHAPES_STRICT

#define __PLUMED_WRAPPER_CXX_DETECT_SHAPES_STRICT   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_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 [1/2]

#define __PLUMED_WRAPPER_GLOBAL   1

__PLUMED_WRAPPER_GLOBAL [2/2]

#define __PLUMED_WRAPPER_GLOBAL   0

__PLUMED_WRAPPER_IMPLEMENTATION_

#define __PLUMED_WRAPPER_IMPLEMENTATION_   0

__PLUMED_WRAPPER_INTERNALS_BEGIN

#define __PLUMED_WRAPPER_INTERNALS_BEGIN   __PLUMED_WRAPPER_C_BEGIN

__PLUMED_WRAPPER_INTERNALS_END

#define __PLUMED_WRAPPER_INTERNALS_END   __PLUMED_WRAPPER_C_END

__PLUMED_WRAPPER_LIBCXX11

#define __PLUMED_WRAPPER_LIBCXX11   0

__PLUMED_WRAPPER_LIBCXX17

#define __PLUMED_WRAPPER_LIBCXX17   0

__PLUMED_WRAPPER_REINTERPRET_CAST

#define __PLUMED_WRAPPER_REINTERPRET_CAST	(		to,
			what )

Value:

reinterpret_cast<to>(what)

__PLUMED_WRAPPER_STATIC_CAST

#define __PLUMED_WRAPPER_STATIC_CAST	(		to,
			what )

Value:

static_cast<to>(what)

__PLUMED_WRAPPER_STATIC_INLINE

#define __PLUMED_WRAPPER_STATIC_INLINE   static inline

__PLUMED_WRAPPER_STD

#define __PLUMED_WRAPPER_STD

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()

__PLUMED_WRAPPER_STATIC_INLINE const 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.