Integrate the UnifyFS API

This section describes how to use the UnifyFS API in an application.

Transparent Mount Caveat

MPI applications that take advantage of the transparent mounting feature (through configuring with --enable-mpi-mount or with +auto-mount through Spack) do not need to be modified in any way in order to use UnifyFS. Move on to the Link with the UnifyFS library section next as this step can be skipped.

Attention

Fortran Compatibility

unifyfs_mount and unifyfs_unmount are usable with GFortran. There is a known ifort_issue with the Intel Fortran compiler as well as an xlf_issue with the IBM Fortran compiler. Other Fortran compilers are currently unknown.

If using fortran, when installing UnifyFS with Spack, include the +fortran variant, or configure UnifyFS with the --enable-fortran option if building manually.

---

Include the UnifyFS Header

In C or C++ applications, include unifyfs.h. See writeread.c for a full example.

C

#include <unifyfs.h>

In Fortran applications, include unifyfsf.h. See writeread.f90 for a full example.

Fortran

include 'unifyfsf.h'

Mounting

UnifyFS implements a file system in user space, which the system has no knowledge about. The UnifyFS library intecepts and handles I/O calls whose path matches a prefix that is defined by the user. Calls corresponding to matching paths are handled by UnifyFS and all other calls are forwarded to the original I/O routine.

To use UnifyFS, the application must register the path that the UnifyFS library should intercept by making a call to unifyfs_mount. This must be done once on each client process, and it must be done before the client process attempts to access any UnifyFS files.

For instance, to use UnifyFS on all path prefixes that begin with /unifyfs this would require a:

C

int rc = unifyfs_mount("/unifyfs", rank, rank_num);

Fortran

call UNIFYFS_MOUNT('/unifyfs', rank, size, ierr);

Here, /unifyfs is the path prefix for UnifyFS to intercept. The rank parameter specifies the MPI rank of the calling process. The size parameter specifies the number of MPI ranks in the user job.

Unmounting

When the application is done using UnifyFS, it should call unifyfs_unmount.

C

unifyfs_unmount();

Fortran

call UNIFYFS_UNMOUNT(ierr);