sf gowno
Author: Magdalena Nieplocha

##

##
Shared Files Library

The Shared Files (SF) library implements logically-shared temporary files for parallel SPMD (single-program-multiple-data) applications. Any process can read and write at arbitrary location in a file independently of other processes. Shared files must be created and destroyed collectively. To optimize performance of the library, user can provide hints on:

- soft limit, and
- hard limit for the file size.

The SF read and write operations are asynchronous/nonblocking and require a wait operation to complete.

Due to the FORTRAN data type limitations, in order to facilitate access to files >2GB the file size, request size and offset arguments use double precision data types.

All SF routines return an error code. The "0" value means success, other values correspond to error codes.

##

## sf_create

    integer sf_create(fname, size_hard_limit, size_soft_limit, req_size, handle)
            fname            -- meta-file name
            size_hard_limit  -- max file size in bytes not to be exceeded (a hint)
            size_soft_limit  -- estimated file size (a hint)
            req_size         -- size of  a typical request (a hint)
            handle           -- returned handle to the created file

Creates shared file using name and path specified in fname as a template.
req_size specifies size of a typical request (-1. means "don't know").

Creates shared file using name and path specified in fname as a template.
req_size specifies size of a typical request (-1. means "don't know").

It is a collective operation.

## sf_write

    integer sf_write(handle, offset, bytes, buffer, request_id)
            handle           -- file handle returned from sf_create   [in]
            offset           -- location in file (from the beginning)
                                where data should be written to       [in]
            buffer           -- local array to put the data           [in]
            bytes            -- number of bytes to read               [in]
            request_id       -- id identifying asynchronous operation [out]

Asynchronous write operation. Writes number of bytes to the file identified by handle at location offset.Operation is guaranteed to be complete when sf_wait called with request_id argument returns.

##

## sf_read

    integer sf_read(handle, offset, bytes, buffer, request_id)
            handle           -- file handle returned from sf_create   [in]
            offset           -- location in file (from the beginning)
                                where data should be read from        [in]
            buffer           -- local array to put the data           [in]
            bytes            -- number of bytes to read               [in]
            request_id       -- id identifying asynchronous operation [out]

Asynchronous read operation. Reads number of bytes to the file identified by handle at location offset.Operation is guaranteed to be complete when sf_wait called with request_id argument returns.

##

## sf_wait

    integer sf_wait(request_id)
            request_id       -- id identifying asynchronous operation [in/out]

Blocks the calling process until I/O operation associated with request_id completes.
Invalidates request_id.

## sf_waitall

    integer sf_waitall(list, num)
            list(num)        -- array of ids for asynchronous operations [in/out]
            num              -- number of entries in list                [in]

Blocks the calling process until all of the num I/O operations associated with ids
specified in list complete. Invalidates (modifies) ids on the list.

##

## sf_destroy

    integer sf_destroy(handle)
            handle           -- file handle returned from sf_create      [in]

Destroys the shared file associated with handle. It is a collective operation.