grio_reserve(3x)

NAME
     grio_reserve, grio_reserve_fd - reserve bandwidth to a GRIO managed
     filesystem

C SYNOPSIS
     #include <grio2.h>

     int grio_reserve(
             const char *path,
             grio_off_t *bytes, grio_msecs_t *msecs,
             int flags,
             grio_stream_id_t *stream_id)

     int grio_reserve_fd(
             grio_descriptor_t fd,
             grio_off_t *bytes, grio_msecs_t *msecs,
             int flags,
             grio_stream_id_t *stream_id)

     cc ... -lgrio2

PARAMETERS
     path      A path identifying the target filesystem.

     fd        An open file descriptor on the target filesystem.

     bytes, msecs
               The requested bandwidth expressed as the ratio bytes per msecs.

     flags     Additional flags modifying the characteristics of the
               reservation.

     stream_id User-allocated buffer for the returned stream ID.

DESCRIPTION
     These functions are used to reserve guaranteed rate bandwidth to or from
     a GRIO-managed filesystem. If successful they setup a GRIO stream in the
     kernel with the requested properties and return its stream ID.

     grio_reserve is used to make a filesystem-level reservation.  The target
     filesystem is identified with path which must be either the filesystem
     mount point or the device special file on which it is located. Before
     guaranteed rate I/O can be performed an open file descriptor must be
     bound to the new stream using grio_bind(3X).

     grio_reserve_fd is used to make a file-level reservation.  It takes an
     open file descriptor fd on the target filesystem. In addition to
     reserving bandwidth, the file descriptor is bound to the newly created
     stream. The file must therefore be suitable for guaranteed rate I/O and
     satisfy the normal requirements of grio_bind(3X).

     The requested bandwidth is specified as the number of bytes delivered
     every msecs milliseconds.

     msecs is referred to as the reservation interval. This value provides
     additional information to the GRIO scheduler about an application's
     ability to tolerate variation in I/O service time. For example, an
     application request of 1MB every tenth of a second suggests a tighter
     service time requirement than 100MB delivered every second, even though
     both requests describe the same average data rate.

     In the current implementation, GRIO uses this information as a hint only,
     and honors the expressed bandwidth over an implementation defined
     scheduling interval.

     The flags parameter is currently unused and should be set to 0.

     grio_release(3X) should be called when the stream is no longer required.

     The process that creates a stream with these functions is said to be the
     owning process. Any streams not already released when their owning
     process exits will be automatically released. The ownership of a GRIO
     stream is not transferable.

STREAM REFERENCES
     GRIO streams are reference counted. When created a new stream has a
     reference count of 1. This primary reference remains until the
     reservation is released using grio_release(3X) or the owning process
     exits.

     A stream persists until its reference count drops to 0. Binding a file
     descriptor using grio_bind(3X) adds a reference. Unbinding using
     grio_unbind(3X) or closing a file descriptor removes a reference. In
     flight I/O will also add references to a stream for short periods of
     time.

     It is possible, and frequently useful, for a stream to persist after it
     has been released. Refer to grio_release(3X) for further details.

NOTE
     Both grio_reserve and grio_reserve_fd are synchronous calls and may block
     while bandwidth is reallocated. This delay is referred to as the stream
     creation latency.

     In the worst case, this delay can be in the order of 1 or 2 seconds,
     although it may be significantly less depending on the configuration of a
     particular GRIO deployment.

     There are a number of strategies available for minimizing the impact of
     this behaviour including: reserving bandwidth well ahead of time,
     performing reservations in a dedicated thread, reusing a reservation
     wherever possible, or configuring ggd2 to keep a proportion of the
     available free bandwidth uncommitted using the -r option, see ggd2(1M)
     and the GRIO Version 2 Guide for more information.
DIAGNOSTICS
     On success, 0 is returned indicating that a rate guarantee has been
     granted and the stream ID has been returned in stream_id. If the desired
     rate cannot be reserved -1 is returned and errno is set to indicate the
     error.  The following error codes are defined:

     EALREADY  grio_reserve_fd: the file descriptor is already bound to
               another stream.

     EBADF     grio_reserve_fd: the file descriptor is invalid, or cannot be
               be bound to the GRIO stream.

     EINVAL    The bandwidth specification was invalid.

     EIO       The library could not communicate with ggd2.

     ENOSPC    The requested bandwidth could not be reserved.  Upon return the
               bytes and msecs parameters describe the maximum bandwidth left
               for reservation.

     EPERM     The process does not have root permissions or CAP_DEVICE_MGMT
               privilege.

FILES
     /etc/griotab

SEE ALSO
     grio2(5), grio_avail(3X), grio_bind(3X), grio_get_stream(3X),
     grio_modify(3X), grio_release(3X), grio_unbind(3X)