Examples¶
There are several examples available on ways to use UnifyFS. These examples build into static and GOTCHA versions (pure POSIX versions coming soon) and are also used as a form of intregraton testing.
Examples Locations¶
The example programs can be found in two locations, where UnifyFS is built and where UnifyFS is installed.
Install Location¶
Upon installation of UnifyFS, the example programs are installed into the install/libexec folder.
Installed with Spack¶
The Spack installation location of UnifyFS can be found with the command
spack location -i unifyfs
.
To easily navigate to this location and find the examples, do:
$ spack cd -i unifyfs
$ cd libexec
Installed without Spack¶
The autotools installation of UnifyFS will place the example programs in the
libexec/ directory of the path provided to --prefix=/path/to/install
during
the configure step of building and installing.
Build Location¶
Built with Spack¶
The Spack build location of UnifyFS (on a successful install) only exists when
--keep-stage
in included during installation or if the build fails. This
location can be found with the command spack location unifyfs
.
To navigate to the location of the static and POSIX examples, do:
$ spack install --keep-stage unifyfs
$ spack cd unifyfs
$ cd spack-build/examples/src
The GOTCHA examples are one directory deeper in spack-build/examples/src/.libs.
Note
If you installed UnifyFS with any variants, in order to navigate to the
build directory you must include these variants in the spack cd
command. E.g.:
spack cd unifyfs+hdf5 ^hdf5~mpi
Built without Spack¶
The autotools build of UnifyFS will place the static and POSIX example programs in the examples/src directory and the GOTCHA example programs in the examples/src/.libs directory of your build directory.
Running the Examples¶
In order to run any of the example programs you first need to start the UnifyFS server daemon on the nodes in the job allocation. To do this, see Starting & Stopping in a Job.
Each example takes multiple arguments and so each has its own --help
option
to aid in this process.
[prompt]$ ./write-static --help
Usage: write-static [options...]
Available options:
-a, --appid=<id> use given application id
(default: 0)
-A, --aio use asynchronous I/O instead of read|write
(default: off)
-b, --blocksize=<bytes> I/O block size
(default: 16 MiB)
-c, --chunksize=<bytes> I/O chunk size for each operation
(default: 1 MiB)
-d, --debug for debugging, wait for input (at rank 0) at start
(default: off)
-f, --file=<filename> target file name (or path) under mountpoint
(default: 'testfile')
-k, --check check data contents upon read
(default: off)
-L, --listio use lio_listio instead of read|write
(default: off)
-m, --mount=<mountpoint> use <mountpoint> for unifyfs
(default: /unifyfs)
-M, --mapio use mmap instead of read|write
(default: off)
-n, --nblocks=<count> count of blocks each process will read|write
(default: 32)
-p, --pattern=<pattern> 'n1' (N-to-1 shared file) or 'nn' (N-to-N file per process)
(default: 'n1')
-P, --prdwr use pread|pwrite instead of read|write
(default: off)
-S, --stdio use fread|fwrite instead of read|write
(default: off)
-U, --disable-unifyfs do not use UnifyFS
(default: enable UnifyFS)
-v, --verbose print verbose information
(default: off)
-V, --vecio use readv|writev instead of read|write
(default: off)
-x, --shuffle read different data than written
(default: off)
One form of running this example could be:
$ srun -N4 -n4 write-static -m /myMountPoint -f myTestFile