Main plumed object. More...
#include <Plumed.h>
Private Attributes | |
void * | p |
Void pointer holding the real PlumedMain structure. More... | |
Related Functions | |
(Note that these are not member functions.) | |
void | plumed_c2f (plumed p, char *c) |
Converts a C handler to a FORTRAN handler. More... | |
void * | plumed_c2v (plumed p) |
Converts a plumed object to a void pointer. Available as of PLUMED 2.5. More... | |
#define | plumed_cmd __PLUMED_WRAPPER_REDEFINE_CMD |
Tells p to execute a command. More... | |
void | plumed_cmd_nothrow (plumed p, const char *key, const void *val, plumed_nothrow_handler nothrow) |
Same as plumed_cmd, but does not throw exceptions. More... | |
plumed | plumed_create (void) |
Constructor. More... | |
plumed | plumed_create_dlopen (const char *path) |
Constructor from path. Available as of PLUMED 2.5. More... | |
plumed | plumed_create_invalid () |
Constructor as invalid. Available as of PLUMED 2.5. More... | |
plumed | plumed_create_reference (plumed p) |
plumed | plumed_create_reference_f (const char *f) |
Create a new reference to an existing object passed as a fortran string, increasing its reference count. Available as of PLUMED 2.5. More... | |
plumed | plumed_create_reference_v (void *v) |
Create a new reference to an existing object passed as a void pointer, increasing its reference count. Available as of PLUMED 2.5. More... | |
plumed | plumed_f2c (const char *c) |
Converts a FORTRAN handler to a C handler. More... | |
void | plumed_finalize (plumed p) |
Destructor. More... | |
#define | plumed_gcmd __PLUMED_WRAPPER_REDEFINE_GCMD |
Tells to the global interface to execute a command. More... | |
void | plumed_gcmd_safe (const char *key, plumed_safeptr) |
Tells to the global interface to execute a command. More... | |
void | plumed_gcreate (void) |
Constructor for the global interface. More... | |
void | plumed_gfinalize (void) |
Destructor for the global interface. More... | |
int | plumed_ginitialized (void) |
Check if the global interface has been initialized. More... | |
plumed | plumed_global (void) |
Retrieves an handler to the global structure. More... | |
int | plumed_gvalid () |
Check if global plumed object is valid. Available as of PLUMED 2.5. More... | |
int | plumed_installed (void) |
Check if plumed is installed (for runtime binding). More... | |
int | plumed_use_count (plumed p) |
Returns the number of references to the underlying object. Available as of PLUMED 2.5. More... | |
plumed | plumed_v2c (void *) |
Converts a void pointer to a plumed object. Available as of PLUMED 2.5. More... | |
int | plumed_valid (plumed p) |
Check if plumed object is valid. Available as of PLUMED 2.5. More... | |
Main plumed object.
This is an object containing a Plumed instance, which should be used in the MD engine. It should first be initialized with plumed_create(), then it communicates with the MD engine using plumed_cmd(). Finally, before the termination, it should be deallocated with plumed_finalize(). Its interface is very simple and general, and is expected not to change across plumed versions. See Reference for interfacing MD codes with PLUMED.
|
related |
Converts a C handler to a FORTRAN handler.
p | The C handler |
c | The FORTRAN handler (a char[32]) |
This function can be used to convert a plumed object created in C to a plumed handler that can be used in FORTRAN. Notice that the reference counter is not incremented. In other words, the FORTRAN object will be a weak reference. If you later finalize the C handler, the FORTRAN handler will be invalid.
#include <plumed/wrapper/Plumed.h> int main(int argc,char*argv[]){ plumed p; p=plumed_create(); char fortran_handler[32]; plumed_c2f(p,fortran_handler); printf("DEBUG: this is a string representation for the plumed handler: %s\n",fortran_handler); fortran_routine(fortran_handler); plumed_finalize(p); return 0; }
Here fortran_routine
is a routine implemented in FORTRAN that manipulates the fortran_handler.
|
related |
Converts a plumed object to a void pointer. Available as of PLUMED 2.5.
It returns a void pointer that can be converted back to a plumed object using plumed_v2c. When compiling without NDEBUG, it checks if the plumed object was properly created. Notice that an invalid object (see plumed_valid) can be converted to void* and back.
Can be used to store a reference to a plumed object without including the Plumed.h header.
|
related |
Tells p to execute a command.
If the object is not valid (see plumed_valid), this command will exit.
p | The plumed object on which command is acting |
key | The name of the command to be executed |
val | The argument. It is declared as const to allow calls like plumed_cmd(p,"A","B"), but for some choice of key it can change the content. |
Notice that within PLUMED we use a const_cast to remove any const qualifier from the second argument of plumed_cmd.
In some cases val can be omitted: just pass a NULL pointer (in C++, val is optional and can be omitted, or you can equivalently pass NULL or nullptr). The set of possible keys is the real API of the plumed library, and will be expanded with time. New commands will be added, but backward compatibility will be retained as long as possible.
|
related |
Same as plumed_cmd, but does not throw exceptions.
This function is meant to be used when errors should be handled explicitly. if an exception is raised within PLUMED, the function nothrow.handler() will be called with arguments (nothrow.ptr,code,message,opt). This allows the C++ interface to correctly rethrow exceptions, but might be used from C as well. opt can be used to pass further information (not used yet).
|
related |
Constructor.
Constructs a plumed object.
Notice that if you are linking against libplumedWrapper.a, if you are using a code patched in runtime mode, or if you are including the Plumed.c
file directly in your code, this constructor might return an invalid plumed object. In particular, this could happen if the PLUMED_KERNEL
environment variable is not set or set incorrectly. In order to detect an incorrect plumed object you might use plumed_valid() on the resulting object. Alternatively, if you use plumed_cmd() on an invalid plumed object the code will exit. Also notice that to avoid memory leaks you should call plumed_finalize() to finalize a plumed object even if it is invalid:
plumed p=plumed_create(); if(!plumed_valid(p)) { // this will happen if the PLUMED_KERNEL variable is not set correctly plumed_finalize(p); return whatever; }
\return The constructed plumed object
|
related |
Constructor from path. Available as of PLUMED 2.5.
It tries to construct a plumed object loading the kernel located at path. Notice that it could leave the resulting object in an invalid state. In order to detect an invalid plumed object you might use plumed_valid() on the resulting object. Alternatively, if you use plumed_cmd() on an invalid plumed object the code will exit.
Also notice that to avoid memory leaks you should call plumed_finalize() to finalize a plumed object even if it is invalid.
plumed p=plumed_create(path); if(!plumed_valid(p)) { // this will happen if the path argument is not set correctly plumed_finalize(p); return whatever; }
\return The constructed plumed object
|
related |
Constructor as invalid. Available as of PLUMED 2.5.
Can be used to create an object in the same state as if it was returned by plumed_create_dlopen with an incorrect path (or plumed_create using runtime binding and an incorrect PLUMED_KERNEL).
Can be used to initialize a plumed object to a well-defined state without explicitly creating it. The resulting object can be checked later with plumed_valid. Consider the following example
plumed p; p=plumed_create_invalid(); // at this point p is initialized to a well-defined (invalid) state. setenv("PLUMED_KERNEL","/path/to/kernel/libplumedKernel.so",1); plumed_finalize(p); p=plumed_create();
\return The constructed plumed object
Create a new reference to an existing object, increasing its reference count. Available as of PLUMED 2.5
Use it to increase by one the reference count of a plumed object. The resulting pointer might be identical to the one passed as an argument, but the reference count will be incremented by one. Notice that you should finalize the resulting object.
plumed p1; plumed p2; p1=plumed_create(); p2=plumed_create_reference(p1); plumed_finalize(p1); // now you can still use p2 plumed_cmd(p2,"init",NULL); plumed_finalize(p2); // now the underlying object is destroyed.
If the `p` object is invalid, also the returned object will be invalid. \param p The plumed object that will be referenced to. \return The constructed plumed object
|
related |
Create a new reference to an existing object passed as a fortran string, increasing its reference count. Available as of PLUMED 2.5.
|
related |
Create a new reference to an existing object passed as a void pointer, increasing its reference count. Available as of PLUMED 2.5.
|
related |
Converts a FORTRAN handler to a C handler.
c | The FORTRAN handler (a char[32]) |
This function can be used to convert a plumed object created in FORTRAN to a plumed handler that can be used in C. Notice that the reference counter is not incremented. In other words, the C object will be a weak reference. If you later finalize the FORTRAN handler, the C handler will be invalid.
void c_routine(char handler[32]){ plumed p; p=plumed_f2c(handler); plumed_cmd(p,"init",NULL); }
Here c_routine
is a C function that can be called from FORTRAN and interact with the provided plumed handler.
|
related |
Destructor.
It must be used for any object created using plumed_create(), even if the created object is not valid.
p | The plumed object to be deallocated |
|
related |
Tells to the global interface to execute a command.
key | The name of the command to be executed |
val | The argument. It is declared as const to allow calls like plumed_gcmd("A","B"), but for some choice of key it can change the content |
plumed_gcmd(a,b);
is equivalent to plumed_cmd(plumed_global(),a,b);
.
|
related |
Tells to the global interface to execute a command.
key | The name of the command to be executed |
safe | A safe pointer |
plumed_gcmd_safe(a,b);
is equivalent to plumed_cmd_safe(plumed_global(),a,b);
.
|
related |
Constructor for the global interface.
|
related |
Destructor for the global interface.
plumed_gfinalize(a,b);
is similar to plumed_finalize(plumed_global(),a,b);
, but not completely equivalent. In particular, plumed_gfinalize() also makes sure that the global object is reset to its initial status. After calling it, plumed_ginitialized() will thus return 0.
|
related |
Check if the global interface has been initialized.
|
related |
Retrieves an handler to the global structure.
You can use this if you work on a code that uses the global structure and you want to pass to a generic routine an handler to the same structure. E.g.
plumed p=plumed_global(); some_routine(p);
|
related |
Check if global plumed object is valid. Available as of PLUMED 2.5.
It might return zero if plumed is not available at runtime.
|
related |
Check if plumed is installed (for runtime binding).
Notice that this is equivalent to creating a dummy object and checking if it is valid.
// this: //int a=plumed_installed(); // is equivalent to this: plumed p=plumed_create(); int a=plumed_valid(p); plumed_finalize(p);
This function is mostly provided for compatibility with PLUMED 2.4, where \ref plumed_valid() was not available. Using \ref plumed_valid() is now preferred since it creates a single object instead of creating a dummy object that is then discarded. \return 1 if plumed is installed, 0 otherwise
|
related |
Returns the number of references to the underlying object. Available as of PLUMED 2.5.
|
related |
Converts a void pointer to a plumed object. Available as of PLUMED 2.5.
It returns a plumed object from a void pointer obtained with plumed_c2v. When compiling without NDEBUG, it checks if the plumed object was properly created.
Can be used to store a reference to a plumed object without including the Plumed.h header.
|
related |
Check if plumed object is valid. Available as of PLUMED 2.5.
It might return false if plumed is not available at runtime.
|
private |
Void pointer holding the real PlumedMain structure.
To maintain binary compatibility, we should not add members to this structure. As of PLUMED 2.5, in order to add new components we do not store the pointer to PlumedMain here but rather a pointer to an intermediate private structure that contains all the details.
Hosted by GitHub | 1.8.17 |