prioSetBandwidth(3X)prioSetBandwidth(3X)NAME
prio: prioSetBandwidth, prioGetBandwidth, prioLock, prioUnlock - Priority
IO operations.
SYNOPSIS
#include <sys/prio.h>
int prioSetBandwidth (int fd, enum prioAllocateType_e mode,
bandwidth_t bytesec, pid_t *lock_holder);
int prioGetBandwidth(inf fd, bandwidth_t *read_bytesec,
bandwidth_t *write_bytesec);
int prioLock (pid_t *lock_holder);
int prioUnlock();
DESCRIPTION
prioSetBandwidth tries to allocate bandwidth: bytesec in bytes per
second on a file descriptor fd. mode specifies the allocation direction,
which can be one of PRIO_READ_ALLOCATE, PRIO_WRITE_ALLOCATE,
PRIO_READWRITE_ALLOCATE. The allocation mode must match the file opening
mode. If a read direction allocation is requested, the file must have
been opened for read; if a write direction allocation is requested, the
file must have been opened for write. Otherwise, prioSetBandwidth will
fail.
If another process holds the global lock for bandwidth allocation,
prioSetBandwidth will fail and lock_holder will have the process id of
the process which is holding the lock.
On success, the actually allocated bandwidth would be more than or equal
to the requested bandwidth because the underlying hardware manages
bandwidth allocation on cache line size transfers. Partial line transfers
requires the system to adjust upwards to meet the request.
prioGetBandwidth obtains bandwidth allocation on file descriptor fd.
read_bytesec and write_bytesec have bandwidth in bytes per second in read
and write direction, respectively.
Some applications may want to do a set of allocation/reallocation of
bandwidth without other applications' interference. A system global lock
is provided to support this multi-step reallocation. The application
acquires the lock through prioLock. The application that holds the lock
can raise or lower current allocations as well as request new allocations
without dealing with concurrent bandwidth allocations from another
application. At the end of the allocation sequence, the lock must be
released with the prioUnlock call. When an application is holding the
lock, prioSetBandwidth in other applications will fail.
Page 1
prioSetBandwidth(3X)prioSetBandwidth(3X)
When prioLock fails because another application is holding the lock,
lock_holder has the process ID of the application.
When a process that holds the lock dies for some reason before it calls
prioUnlock , the system will release the lock.
NOTE
It is not required for an application to call prioLock before it requests
bandwidth allocation.
The application should be compiled with -lprio option.
In IRIX 6.5, the Priority I/O APIs have been merged with the GRIO APIs.
As a result, the use of the Priority I/O APIs is deprecated. For
backwards compatibility, prioSetBandwidth and prioGetBandwidth are still
supported. prioLock and prioUnlock are merely stubs. No locking or
atomicity is guaranteed. Please refer to grio(5) for further details.
DIAGNOSTICS
On successful completion of all these functions, a zero is returned
indicating that the request has been granted. If the request cannot be
granted, a -1 is returned and errno is set to the appropriate value.
[ENOPKG] Bandwidth allocation is not supported on this system.
[E2BIG] Bandwidth allocation failed because not enough bandwidth is
available.
[EBADFD] File descriptor is invalid.
[EINVAL] One or more parameters are invalid.
[ENOLCK] Another application is holding the lock.
SEE ALSOprio(5), prioinfo(1), grio(5)
Page 2
