MACSio  0.9
Multi-purpose, Application-Centric, Scalable I/O Proxy App
 All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Macros Modules Pages
Template

A simple MIF Plugin Template. More...

Functions

static int process_args (int argi, int argc, char *argv[])
 Process command-line arguments specific to this plugin. More...
 
static void * CreateMyFile (const char *fname, const char *nsname, void *userData)
 CreateFile MIF Callback. More...
 
static void * OpenMyFile (const char *fname, const char *nsname, MACSIO_MIF_ioFlags_t ioFlags, void *userData)
 OpenFile MIF Callback. More...
 
static void CloseMyFile (void *file, void *userData)
 CloseFile MIF Callback. More...
 
static json_objectwrite_mesh_part (FILE *myFile, char const *fileName, json_object *part_obj)
 Write a single mesh part to a MIF file. More...
 
static void main_dump (int argi, int argc, char **argv, json_object *main_obj, int dumpn, double dumpt)
 Main MIF dump implementation for this plugin. More...
 
static int register_this_interface ()
 Method to register this plugin with MACSio main. More...
 

Variables

static char const * iface_name = "miftmpl"
 
static char const * iface_ext = "json"
 
static int json_as_html = 0
 
static int my_opt_one
 
static int my_opt_two
 
static char * my_opt_three_string
 
static float my_opt_three_float
 
static int const dummy = register_this_interface()
 Dummy initializer to trigger register_this_interface by the loader. More...
 

Detailed Description

A simple MIF Plugin Template.

Writing a new plugin for MACSio involves a mininum of two new files in the plugins directory. One is the C or C++ source code for the plugin. The other is a .make file that includes various plugin-specific variable definitions and logic to decode library dependencies that effect.

We'll describe the structure and content of the .make using a generic plugin identified by the moniker plgn. In any plugin's .make file, all the variable names should be prepended with the plugin's name except for these three (examples below).

PLUGIN_OBJECTS += $(PLGN_SOURCES:.c=.o)
PLUGIN_LDFLAGS += $(PLGN_LDFLAGS)
PLUGIN_LIST += plgn

The first variable is the BUILD_ORDER variable. This variable is used to sort the order in which plugin object files as well as their dependent libraries appear on the link line when linking the MACSio main executable. The numerical value assigned to the BUILD_ORDER variable is a floating point number. Smaller numbers appear earlier on the link line. If plugin A depends on libraries that are also used by plugin B, then plugin A should be assigned a BUILD_ORDER value that is larger than plugin B.

PLGN_BUILD_ORDER = 1.7

The next variables in the .make file define the version number, tarfile and URL for zero or more dependent libraries used by the plugin.

PLGN_VERSION = 1.8.11
PLGN_FILE = plgn-$(PLGN_VERSION).tar.gz
PLGN_URL = http://www.greatplugins.org/ftp/PLGN/releases/$(PLGN_FILE)

In addition, for each third party library a plugin uses, it is assumed there is an associated home variable that specifies a top-level directory underneath which lives include and lib directories for the library's header files and library files respectively. If you have a package that does not conform to this standard installation structure, the work-around is to use symlinks or explicit copies to create some proxy home directory for the library that is structured in the way MACSio's Makefiles need it. So, for our generic plugin, there is a PLGN_HOME variable that defines where the library is installed. Note that this variable is then typically defined in the config-site file.

The next section of the makefile is the conditional logic necessary to decide if the plugin can be built based on whether its depndent library(s), if any, are defined.

ifneq ($(PLGN_HOME),)
PLGN_LDFLAGS = -L$(PLGN_HOME)/lib -lplgn
PLGN_CFLAGS = -I$(PLGN_HOME)/include
PLGN_SOURCES = macsio_plgn.c
PLGN_LDFLAGS += -lz -lm
PLUGIN_OBJECTS += $(PLGN_SOURCES:.c=.o)
PLUGIN_LDFLAGS += $(PLGN_LDFLAGS)
PLUGIN_LIST += plgn
endif

The next section of the .make file indicates how to make the plugin object file.

macsio_plgn.o: ../plugins/macsio_plgn.c
$(CXX) -c $(PLGN_CFLAGS) $(MACSIO_CFLAGS) $(CFLAGS) ../plugins/macsio_plgn.c

The final section of the .make file defines some pre-defined targets which having to do with obtaining the third party library(s) associated with the plugin.

$(PLGN_FILE):
$(DLCMD) $(PLGN_FILE) $(PLGN_URL)
list-tpls-plgn:
@echo "$(PLGN_FILE) ($(PLGN_URL))"
download-tpls-plgn: $(PLGN_FILE)

The miftmpl plugin is intended to serve as a template for how to create a basic MIF-mode plugin for MACSio. This template code does indeed actually function correctly as a MACSio plugin. It does so by writing MACSio's internal JSON objects repesenting each mesh part as ascii strings to the individual files.

Each processor in a MIF group serializes each JSON object representing a mesh part to an ascii string. Then, each of these strings is appended to the end of the file. For each such string, the plugin maintains knowledge of the mesh part's ID, the filename it was written to and the offset within the file.

The filenames, offsets and mesh part IDs are then written out as a separate JSON object to a root or master file. Currently, there is no plugin in VisIt to read these files and display them. But, this example code does help to outline the basic work to write a MIF plugin.

In practice, this plugin could have simply written the entire JSON object from each processor to its MIF group's file. However, in doing that, the resulting file would not "know" such things as how many mesh parts there are or where a given mesh part is located in the file set. So, we wind up writing JSON objects for each part individually so that we can keep track of where they all are in the fileset.

Some of the aspects of this plugin code exist here only to serve as an example in writing a MIF plugin and are non-essential to the proper operation of this plugin.

MACSio uses a static load approach to its plugins. The MACSio main executable must be linked with all the plugins it expects to use.

In writing any MACSio plugin (MIF or SIF) be sure to declare all of your plugin's symbols (functions, local variables, etc.) as static. Each plugin is being linked into MACSio's main and any symbols that are not static file scope will wind up appearing in and therefore being vulnerable too global namespace collisions. The plugin's main interface methods to MACSio are handled via registration of a set of function pointers.

Function Documentation

static int process_args ( int  argi,
int  argc,
char *  argv[] 
)
static

Process command-line arguments specific to this plugin.

Uses MACSIO_CLARGS_ProcessCmdline() to do its work.

This example plugin is implemented to route command line arguments to memory locations (e.g. static variables) here in the plugin. Alternatively, a plugin can choose to route the results of MACSIO_CLARGS_ProcessCmdline() to a JSON object. MACSio's main is implemented that way.

Parameters
[in]argiArgument index of first argument that is specific to this plugin
[in]argcargc as passed into main
[in]argvargv as passed into main

Definition at line 196 of file macsio_miftmpl.c.

static void* CreateMyFile ( const char *  fname,
const char *  nsname,
void *  userData 
)
static

CreateFile MIF Callback.

This implments the MACSIO_MIF_CreateFile callback needed for a MIF mode plugin.

Returns
A void pointer to the plugin-specific file handle
Parameters
[in]fnameName of the MIF file to create
[in]nsnameName of the namespace within the file for caller should use.
[in]userDataOptional plugin-specific user-defined data

Definition at line 233 of file macsio_miftmpl.c.

static void* OpenMyFile ( const char *  fname,
const char *  nsname,
MACSIO_MIF_ioFlags_t  ioFlags,
void *  userData 
)
static

OpenFile MIF Callback.

This implments the MACSIO_MIF_OpenFile callback needed for a MIF mode plugin.

Returns
A void pointer to the plugin-specific file handle
Parameters
[in]fnameName of the MIF file to open
[in]nsnameName of the namespace within the file caller should use
[in]ioFlagsVarious flags indicating behavior/options
[in]userDataOptional plugin-specific user-defined data

Definition at line 250 of file macsio_miftmpl.c.

static void CloseMyFile ( void *  file,
void *  userData 
)
static

CloseFile MIF Callback.

This implments the MACSIO_CloseFile callback needed for a MIF mode plugin.

Parameters
[in]fileA void pointer to the plugin specific file handle
[in]userDataOptional plugin specific user-defined data

Definition at line 266 of file macsio_miftmpl.c.

static json_object* write_mesh_part ( FILE *  myFile,
char const *  fileName,
json_object part_obj 
)
static

Write a single mesh part to a MIF file.

All this method does is serialize the JSON object for the given mesh part to an ASCII string and then appends/writes that string at the end of the current file.

After serializing the object to an ASCII string and writing it to the file, the memory for the ASCII string is released by json_object_free_printbuf().

Returns
A tiny JSON object holding the name of the file, the offset at which the JSON object for this part was written in the file and the part's ID.
Parameters
[in]myFileThe file handle being used in a MIF dump
[in]fileNameName of the MIF file
[in]part_objThe json object representing this mesh part

Definition at line 287 of file macsio_miftmpl.c.

static void main_dump ( int  argi,
int  argc,
char **  argv,
json_object main_obj,
int  dumpn,
double  dumpt 
)
static

Main MIF dump implementation for this plugin.

This is the function MACSio main calls to do the actual dump of data with this plugin.

It uses MACSIO_MIF twice; once for the main dump and a second time to create the root (or master) file. However, in the second use, the file count is set to 1. That means that the root file is effectively written using serial (e.g. non-parallel) I/O.

It is a useful exercise to ask how we might improve the implementation here to avoid writing the root file using serial I/O.

Parameters
[in]argiCommand-line argument index at which first plugin-specific arg appears
[in]argcargc from main
[in]argvargv from main
[in]main_objThe main json object representing all data to be dumped
[in]dumpnThe number/index of this dump. Each dump in a sequence gets a unique, monotone increasing index starting from 0
[in]dumptThe time to be associated with this dump (like a simulation's time)

Definition at line 324 of file macsio_miftmpl.c.

static int register_this_interface ( )
static

Method to register this plugin with MACSio main.

Due to its use to initialize a file-scope, static const variable, this function winds up being called at load time (e.g. before main is even called).

Its purpose is to add key information about this plugin to MACSio's global interface table.

Definition at line 442 of file macsio_miftmpl.c.

Variable Documentation

char const* iface_name = "miftmpl"
static

Name of the interface this plugin uses

Definition at line 177 of file macsio_miftmpl.c.

char const* iface_ext = "json"
static

Default file extension for files generated by this plugin

Definition at line 178 of file macsio_miftmpl.c.

int json_as_html = 0
static

Use HTML output instead of raw ascii

Definition at line 179 of file macsio_miftmpl.c.

int my_opt_one
static

Example of a static scope, plugin-specific variable to be set in process_args to control plugin behavior

Definition at line 180 of file macsio_miftmpl.c.

int my_opt_two
static

Another example variable to control plugin behavior

Definition at line 182 of file macsio_miftmpl.c.

char* my_opt_three_string
static

Another example variable to control plugin behavior

Definition at line 183 of file macsio_miftmpl.c.

float my_opt_three_float
static

Another example variable to control plugin behavior

Definition at line 184 of file macsio_miftmpl.c.

int const dummy = register_this_interface()
static

Dummy initializer to trigger register_this_interface by the loader.

This one statement is the only statement requiring compilation by a C++ compiler. That is because it involves initialization and non constant expressions (a function call in this case). This function call is guaranteed to occur during initialization (that is before even 'main' is called) and so will have the effect of populating the iface_map array merely by virtue of the fact that this code is linked with a main.

Definition at line 473 of file macsio_miftmpl.c.