portals3.lyx

lustre 1.6.5 source code

\end_inset 

 for limits on values of these types.
\layout Subsection

Match Bits
\begin_inset LatexCommand \label{sec:mb-type}

\end_inset 

 
\layout Standard

The type 
\family typewriter 
ptl_match_bits_t
\family default 
 is capable of holding unsigned 64-bit integer values.
\layout Subsection

Network Interfaces
\begin_inset LatexCommand \label{sec:ni-type}

\end_inset 

 
\layout Standard

The type 
\family typewriter 
ptl_interface_t
\family default 
 is an integral type used for identifying different network interfaces.
 Users will need to consult the local documentation to determine appropriate
 values for the interfaces available.
 The special value 
\family typewriter 
PTL_IFACE_DEFAULT
\family default 
 identifies the default interface.
\layout Subsection

Identifiers
\begin_inset LatexCommand \label{sec:id-type}

\end_inset 


\layout Standard

The type 
\family typewriter 
ptl_nid_t
\family default 
 is an integral type used for representing node ids
\family typewriter 
, ptl_pid_t
\family default 
 is an integral type for representing process ids, and 
\family typewriter 
ptl_uid_t 
\family default 
is an integral type for representing user ids.
\layout Standard

The special values 
\family typewriter 
PTL_PID_ANY
\family default 
 matches any process identifier, PTL_NID_ANY matches any node identifier,
 and 
\family typewriter 
PTL_UID_ANY
\family default 
 matches any user identifier.
 See sections 
\begin_inset LatexCommand \ref{sec:meattach}

\end_inset 

 and\SpecialChar ~

\begin_inset LatexCommand \ref{sec:acentry}

\end_inset 

 for uses of these values.
\layout Subsection

Status Registers
\begin_inset LatexCommand \label{sec:stat-type}

\end_inset 


\layout Standard

Each network interface maintains an array of status registers that can be
 accessed using the 
\family typewriter 
PtlNIStatus
\family default 
 function (see Section\SpecialChar ~

\begin_inset LatexCommand \ref{sec:nistatus}

\end_inset 

).
 The type 
\family typewriter 
ptl_sr_index_t
\family default 
 defines the types of indexes that can be used to access the status registers.
 The only index defined for all implementations is 
\family typewriter 
PTL_SR_DROP_COUNT
\family default 
 which identifies the status register that counts the dropped requests for
 the interface.
 Other indexes (and registers) may be defined by the implementation.
\layout Standard

The type 
\family typewriter 
ptl_sr_value_t
\family default 
 defines the types of values held in status registers.
 This is a signed integer type.
 The size is implementation dependent, but must be at least 32 bits.
\layout Section

Initialization and Cleanup
\begin_inset LatexCommand \label{sec:init}

\end_inset 


\layout Standard

The Portals API includes a function, 
\emph on 
PtlInit
\emph default 
, to initialize the library and a function, 
\emph on 
PtlFini
\emph default 
, to cleanup after the application is done using the library.
\layout Subsection

PtlInit
\begin_inset LatexCommand \label{sec:ptlinit}

\end_inset 


\layout LyX-Code

int PtlInit( int *max_interfaces );
\layout Standard
\noindent 
The 
\emph on 
PtlInit
\emph default 
 function initializes the Portals library.
 PtlInit must be called at least once by a process before any thread makes
 a Portals function call, but may be safely called more than once.
\layout Subsubsection

Return Codes
\layout Description

PTL_OK Indicates success.
 
\layout Description

PTL_FAIL Indicates an error during initialization.
 
\layout Description

PTL_SEGV Indicates that 
\family typewriter 
max_interfaces
\family default 
 is not a legal address.
 
\layout Subsubsection

Arguments
\layout Standard


\begin_inset  Tabular
<lyxtabular version="3" rows="1" columns="3">
<features>
<column alignment="right" valignment="top" width="0pt">
<column alignment="center" valignment="top" width="0pt">
<column alignment="left" valignment="top" width="5in">
<row>
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\layout Standard


\family typewriter 
max_interfaces
\end_inset 
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\layout Standard


\series bold 
output
\end_inset 
</cell>
<cell alignment="left" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
\begin_inset Text

\layout Standard
\noindent 
On successful return, this location will hold the maximum number of interfaces
 that can be initialized.
\end_inset 
</cell>
</row>
</lyxtabular>

\end_inset 


\layout Subsection

PtlFini
\begin_inset LatexCommand \label{sec:ptlfini}

\end_inset 


\layout LyX-Code

void PtlFini( void );
\layout Standard
\noindent 
The 
\emph on 
PtlFini
\emph default 
 function cleans up after the Portals library is no longer needed by a process.
 After this function is called, calls to any of the functions defined by
 the Portal API or use of the structures set up by the Portals API will
 result in undefined behavior.
 This function should be called once and only once during termination by
 a process.
 Typically, this function will be called in the exit sequence of a process.
 Individual threads should not call PtlFini when they terminate.
\layout Section

Network Interfaces
\begin_inset LatexCommand \label{sec:ni}

\end_inset 

 
\layout Standard

The Portals API supports the use of multiple network interfaces.
 However, each interface is treated as an independent entity.
 Combining interfaces (e.g., 
\begin_inset Quotes eld
\end_inset 

bonding
\begin_inset Quotes erd
\end_inset 

 to create a higher bandwidth connection) must be implemented by the application
 or embedded in the underlying network.
 Interfaces are treated as independent entities to make it easier to cache
 information on individual network interface cards.
\layout Standard

Once initialized, each interface provides a Portal table, an access control
 table, and a collection of status registers.
 See Section\SpecialChar ~

\begin_inset LatexCommand \ref{sec:me}

\end_inset 

 for a discussion of updating Portal table entries using the 
\emph on 
PtlMEAttach
\emph default 
 function.
 See Section\SpecialChar ~

\begin_inset LatexCommand \ref{sec:ac}

\end_inset 

 for a discussion of the initialization and updating of entries in the access
 control table.
 See Section\SpecialChar ~

\begin_inset LatexCommand \ref{sec:nistatus}

\end_inset 

 for a discussion of the 
\emph on 
PtlNIStatus
\emph default 
 function which can be used to determine the value of a status register.
\layout Standard

Every other type of Portal object (e.g., memory descriptor, event queue, or
 match list entry) is associated with a specific network interface.
 The association to a network interface is established when the object is
 created and is encoded in the handle for the object.
\layout Standard

Each network interface is initialized and shutdown independently.
 The initialization routine, 
\emph on 
PtlNIInit
\emph default 
, returns a handle for an interface object which is used in all subsequent
 Portal operations.
 The 
\emph on 
PtlNIFini
\emph default 
 function is used to shutdown an interface and release any resources that
 are associated with the interface.
 Network interface handles are associated with processes, not threads.
 All threads in a process share all of the network interface handles.
\layout Standard

The Portals API also defines the 
\emph on 
PtlNIStatus
\emph default 
 function to query the status registers for a network interface, the 
\emph on 
PtlNIDist
\emph default 
 function to determine the 
\begin_inset Quotes eld
\end_inset 

distance
\begin_inset Quotes erd
\end_inset 

 to another process, and the 
\emph on 
PtlNIHandle
\emph default 
 function to determine the network interface that an object is associated
 with.
\layout Subsection

PtlNIInit
\begin_inset LatexCommand \label{sec:niinit}

\end_inset 


\layout LyX-Code

typedef struct {
\newline 
    int            max_match_entries;
\newline 
    int            max_mem_descriptors;
\newline 
    int            max_event_queues;
\newline 
    ptl_ac_index_t max_atable_index; 
\newline 
    ptl_pt_index_t max_ptable_index;
\newline 
} ptl_ni_limits_t;
\newline 

\newline 
int PtlNIInit( ptl_interface_t  interface
\newline 
               ptl_pid_t        pid,
\newline 
               ptl_ni_limits_t* desired,
\newline 
               ptl_ni_limits_t* actual,
\newline 
               ptl_handle_ni_t* handle );
\layout Standard

Values of type 
\family typewriter 
ptl_ni_limits_t
\family default 
 include the following members:
\layout Description

max_match_entries Maximum number of match entries that can be allocated
 at any one time.
\layout Description

max_mem_descriptors Maximum number of memory descriptors that can be allocated
 at any one time.
\layout Description

max_event_queues Maximum number of event queues that can be allocated at
 any one time.
\layout Description

max_atable_index Largest access control table index for this interface,
 valid indexes range from zero to 
\family typewriter 
max_atable_index
\family default 
, inclusive.
\layout Description

max_ptable_index Largest Portal table index for this interface, valid indexes
 range from zero to 
\family typewriter 
max_ptable_index
\family default 
, inclusive.
\layout Standard
\noindent 
The 
\emph on 
PtlNIInit
\emph default 
 function is used to initialized the Portals API for a network interface.
 This function must be called at least once by each process before any other
 operations that apply to the interface by any process or thread.
 For subsequent calls to 
\shape italic 
PtlNIInit
\shape default 
 from within the same process (either by different threads or the same thread),
 the desired limits will be ignored and the call will return the existing
 NI handle.
\layout Subsubsection

Return Codes
\layout Description

PTL_OK Indicates success.
 
\layout Description

PTL_NOINIT Indicates that the Portals API has not been successfully initialized.
 
\layout Description

PTL_INIT_DUP Indicates a duplicate initialization of 
\family typewriter 
interface
\family default 
.
 
\layout Description

PTL_INIT_INV Indicates that 
\family typewriter 
interface
\family default 
 is not a valid network interface.
 
\layout Description

PTL_NOSPACE Indicates that there is insufficient memory to initialize the
 interface.
 
\layout Description

PTL_INV_PROC Indicates that 
\family typewriter 
pid
\family default 
 is not a valid process id.
\layout Description

PTL_SEGV Indicates that 
\family typewriter 
actual 
\family default 
or
\family typewriter 
 handle
\family default 
 is not a legal address.
 
\layout Subsubsection

Arguments
\layout Standard


\begin_inset  Tabular
<lyxtabular version="3" rows="5" columns="3">
<features>
<column alignment="right" valignment="top" width="0pt">
<column alignment="center" valignment="top" width="0pt">
<column alignment="left" valignment="top" width="4.7in">
<row>
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\layout Standard


\family typewriter 
interface
\end_inset 
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\layout Standard


\series bold 
input
\end_inset 
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
\begin_inset Text

\layout Standard
\noindent 
Identifies the network interface to be initialized.
  (See section\SpecialChar ~

\begin_inset LatexCommand \ref{sec:ni-type}

\end_inset 

 for a discussion of  values used to identify network interfaces.)
\end_inset 
</cell>
</row>
<row>
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\layout Standard


\family typewriter 
pid
\end_inset 
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\layout Standard


\series bold 
input
\end_inset 
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
\begin_inset Text

\layout Standard
\noindent 
Identifies the desired process id (for well known process ids).
 The value 
\family typewriter 
PTL_PID_ANY
\family default 
 may be used to have the process id assigned by the underlying library.
\end_inset 
</cell>
</row>
<row>
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\layout Standard


\family typewriter 
desired
\end_inset 
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\layout Standard


\series bold 
input
\end_inset 
</cell>
<cell alignment="left" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
\begin_inset Text

\layout Standard
\noindent 
If non-NULL, points to a structure that holds the desired limits.
\end