Appendix B: Extension Interface

Moab supports an extension interface that allows external libraries to be linked to the Moab server. This interface provides these libraries with full access to and control over all Moab objects and data. It also allows this library the ability to use or override most major Moab functions.

The purpose of this library is to allow the development and use of extension modules, or plug-ins, similar to those available for Web browsers.

Writing a Task Distribution Plug-in for Moab

Before submitting a job, Moab identifies a node or set of nodes on which the job can run. Then, Moab uses a function to distribute tasks among the selected node(s). Moab has several built-in task distribution functions, but it also allows you to create your own if you prefer. To create your own task distribution function, review the following instructions.

Moab comes packaged with a header file named mapi.h that contains the interface information needed to compile a plug-in. Moab also includes four static libraries that contain the actual function implementations needed in the link stage of creating a plug-in. The following are the four static libraries:

libmoab.a
libcmoab.a
librmrmi.a
libmcom.a

When moab loads a task distribution function, it will look for a function named DistributeTasks that fulfills the following C interface:

int DistributeTasks(mjob_t *,mrm_t *,mnalloc_t *, mnode_t **, int)

The table below describes the parameters of DistributeTasks in detail:

#	Parameter	Role	Description
1	mjob_t *	Input parameter	The job for whom the tasks are being distributed. This parameter can be safely ignored for now.
2	mrm_t *		The resource manager the job has been assigned to. This parameter can be safely ignored for now.
3	mnalloc_t *		An array of node-task mappings of type mnalloc_t. Each element in the array contains a member N that represents a node and a member TC representing the number of tasks that have been allocated on that node for the job. The array is terminated with an mnalloc_t struct that has a null N value.
4	mnode_t **	Output parameter	The array that will contain the task distribution the function generates. Each entry in the array represents one task for the entry. Nodes can be entered multiple times to specify multiple tasks for that node. The array should be null-terminated.
5	int	Defines mnode_t **	Defines the array size of the fourth parameter. This value should always be large enough to allocate enough tasks for the job.

The function should return the macro SUCCESS if it successfully distributes its given tasks. If not, it should return the macro FAILURE.

DistributeTasks should take the task-mapping information stored in the node list passed in as the third parameter and should assign nodes to the output array passed in as the fourth parameter. The order in which the nodes are assigned specifies the task distribution order that Moab will use.

When the file is written, it can be compiled on Linux with gcc as shown below. The flags denoting paths to mapi.h and Moab's static libraries can be omitted if they have been installed in a standard location that your compiler is already aware of.

#compile stage
  gcc -Wall -I [path to moab-public.h] -g -fPIC -c [source file] -o [object file name]

#link stage
  gcc -shared -L [path to moab static libraries] -o libMTaskDist.so [object file name] -lmoab -lcmoab -lmcom -lminit -lmrmi

The preceding process creates the shared library that can then be copied to $MOABHOMEDIR/plugins/ and used by Moab.

Hooking a Task Distribution Plug-in into Moab

Hooking an already-created plug-in into Moab requires two steps:

Move or copy the plug-in to $MOABHOMEDIR/plugins/libMTaskDist.so.
Configure Moab to use the plug-in via the TASKDISTRIBUTIONPOLICY moab.cfg parameter or via msub as an extension attribute.

Moab expects to find the shared library with the DistributeTasks function at $MOABHOMEDIR/plugins/libMTaskDist.so. If Moab finds such a file at startup it will attempt to load the file and find the function. Once loaded, Moab can be configured to use the plug-in by default or on a per-job basis. You can specify a TASKDISTRIBUTIONPOLICY of LOCAL in the moab.cfg file to make Moab use the plug-in by default. The plug-in can also be requested for a particular job through msub as follows:

msub -W x=taskdistpolicy=local

Moab retrieves the stored library from $MOABHOMEDIR/plugins/libMTaskDist.so and relies on the DistributeTasks function for instructions that you specified during initial configuration for task distribution.

Searches Moab documentation only