.TH array_sessions 5
.SH NAME
\f3array_sessions\f1 \- introduction to array sessions
.SH DESCRIPTION
An array session is a group of processes all related to each other by a
single unique identifier, the  \f3array session handle\f1.
The processes
don't necessarily have to belong to the same parent-child chain, and
don't even have to be running on the same system.
However, the default
is for a child process to inherit the array session handle of its
parent, so in the average case the processes in an array session are
parents/siblings/children of each other and reside on the same system.
An array session is considered to be active from the time it is first
created until the last process that is a member of it exits.
.PP
The goal of an array session is to correlate all the processes that
belong conceptually to the same login session or batch job, even if
those processes are running on several separate machines in an array.
Then, with the help of external software, the array session can
potentially be treated as a single unit for the purposes of accounting,
checkpoint/restart, job control, etc.
.PP
A process can create a new array session and place itself in it by
using the \f2newarraysess\fP(2) call.
Ordinarily, this would only be
done programs like login or rshd, which are effectively logging a user
into the system, and programs like batch queue systems or cron, which
are running jobs on behalf of another user.
A new array session is
assigned an array session handle that is unique to the current system
only.
If the process is actually part of an existing array session on
another system (e.g.\& the process is part of a single job running
across more than one node in an array) it can change the handle of its
array session to that of its "parent" on the remote system using the
\f2setash\fP(2) call.
The parent's array session handle would
presumably be unique across the entire array, although it would be the
parent's responsibility to arrange for that.
The range of values that
the kernel will assign as array session handles is configurable so
that it would be possible to design a server to provide array-unique
handles.
.PP
An array session is \f2not\f1
the same thing as a POSIX session, though the two concepts are similar
on a single system.
One important characteristic of a
POSIX session is that all of the processes included within it share a
single controlling terminal.
That distinction does not exist for array
sessions: processes from two different array sessions might both be
using the same controlling terminal (e.g.\& by way of the newproj
command) or contrarily two processes in the same array session might
have two different controlling terminals (e.g.\& when running on
different systems).
However, in the simple case of a local login with
no remote interactions an array session and a POSIX session would
include the same set of processes.
.SH SERVICE PROVIDER INFORMATION
Associated with every array session is a block of data known as the
\f3service provider information\f1.
It is typically used to tag the array session
with certain identifying information for accounting or statistical
purposes.
For example, a batch queuing system might store information about the
queue name and job initiator in this area.
The service provider information is reported as part of the
array session accounting data when the array session finally terminates.
.PP
The amount of storage available to an array session for holding
service provider information can vary from 0 to 1024 bytes, though
the most common lengths are 64 (the system default) or 128 bytes.
If no specific action has been taken to associate service provider
information with an array session, then the default system service
provider information will be associated with the array session instead.
.PP
The \f2xactl\fP(1m) program or the \f2arsop\fP(2) and \f2arsctl\fP(2)
system calls can be used to query or modify the contents or size of the
system default service provider information or the service provider
information of a particular array session.
A user must generally be privileged to make any modifications.
Although the format of the service provider information is not enforced
by IRIX, there are two recommended formats defined in 
/usr/include/sys/extacct.h:
"format 1" (defined by the structure \f3acct_spi_t\f1) is for
systems that use 64 bytes of service provider information, and "format 2"
(defined by the structure \f3acct_spi_2_t\f1) is for systems that
use 128 bytes of service provider information.
Only format 1 service provider information is supported on systems
running IRIX 6.4 or earlier.
.PP
The system default service provider information is 64 bytes in length
and is always cleared to zeroes
when the system is initially started.
If desired, the default size can be changed for boot-time array sessions
by modifying the \f3spilen\f1 kernel variable using \f2systune\fP(1m).
.SH SEE ALSO
getash(2),
getspinfo(2),
newarraysess(2),
setash(2),
setspinfo(2),
extacct(5),
projects(5).