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.
Page 1
grio_reserve(3X)grio_reserve(3X)
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.
Page 2
grio_reserve(3X)grio_reserve(3X)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 ALSOgrio2(5), grio_avail(3X), grio_bind(3X), grio_get_stream(3X),
grio_modify(3X), grio_release(3X), grio_unbind(3X)
Page 3
