Tribblix: manual page: dat_ia

DAT_IA_OPEN(3DAT) Direct Access Transport Library Functions

NAME

dat_ia_open - open an Interface Adapter (IA)

SYNOPSIS

cc [ flag... ] file... -ldat [ library... ]
#include <dat/udat.h>

DAT_RETURN
dat_ia_open (
IN const DAT_NAME_PTR ia_name_ptr,
IN DAT_COUNT async_evd_min_qlen,
INOUT DAT_EVD_HANDLE *async_evd_handle,
OUT DAT_IA_HANDLE *ia_handle
)

PARAMETERS

ia_name_ptr
Symbolic name for the IA to be opened. The name
should be defined by the Provider registration.

If the name is prefixed by the string
RO_AWARE_, then the prefix is removed prior to
being passed down and the existence of the
prefix indicates that the application has been
coded to correctly deal with relaxed ordering
constraints. If the prefix is not present and
the platform on which the application is
running is utilizing relaxed ordering, the open
will fail with DAT_INVALID_PARAMETER (with
DAT_SUBTYPE_STATUS of DAT_INVALID_RO_COOKIE).
This setting also affects dat_lmr_create(3DAT).

async_evd_min_qlen
Minimum length of the Asynchronous Event
Dispatcher queue.

async_evd_handle
Pointer to a handle for an Event Dispatcher for
asynchronous events generated by the IA. This
parameter can be DAT_EVD_ASYNC_EXISTS to
indicate that there is already EVD for
asynchronous events for this Interface Adapter
or DAT_HANDLE_NULL for a Provider to generate
EVD for it.

ia_handle
Handle for an open instance of a DAT IA. This
handle is used with other functions to specify
a particular instance of the IA.

DESCRIPTION

The dat_ia_open() function opens an IA by creating an IA instance.
Multiple instances (opens) of an IA can exist.

The value of DAT_HANDLE_NULL for async_evd_handle (*async_evd_handle
== DAT_HANDLE_NULL) indicates that the default Event Dispatcher is
created with the requested async_evd_min_qlen. The async_evd_handle
returns the handle of the created Asynchronous Event Dispatcher. The
first Consumer that opens an IA must use DAT_HANDLE_NULL because no
EVD can yet exist for the requested ia_name_ptr.

The Asynchronous Event Dispatcher (async_evd_handle) is created with
no CNO (DAT_HANDLE_NULL). Consumers can change these values using
dat_evd_modify_cno(3DAT). The Consumer can modify parameters of the
Event Dispatcher using dat_evd_resize(3DAT) and dat_evd_modify_cno().

The Provider is required to provide a queue size at least equal to
async_evd_min_qlen, but is free to provide a larger queue size or
dynamically enlarge the queue when needed. The Consumer can determine
the actual queue size by querying the created Event Dispatcher
instance.

If async_evd_handle is not DAT_HANDLE_NULL, the Provider does not
create an Event Dispatcher for an asynchronous event and the Provider
ignores the async_evd_min_qlen value. The async_evd_handle value
passed in by the Consumer must be an asynchronous Event Dispatcher
created for the same Provider (ia_name_ptr). The Provider does not
have to check for the validity of the Consumer passed in
async_evd_handle. It is the Consumer responsibility to guarantee that
async_evd_handle is valid and for this Provider. How the
async_evd_handle is passed between DAT Consumers is out of scope of
the DAT specification. If the Provider determines that the Consumer-
provided async_evd_handle is invalid, the operation fails and returns
DAT_INVALID_HANDLE. The async_evd_handle remains unchanged, so the
returned async_evd_handle is the same the Consumer passed in. All
asynchronous notifications for the open instance of the IA are
directed by the Provider to the Consumer passed in Asynchronous Event
Dispatcher specified by async_evd_handle.

Consumer can specify the value of DAT_EVD_ASYNC_EXISTS to indicate
that there exists an event dispatcher somewhere else on the host, in
user or kernel space, for asynchronous event notifications. It is up
to the Consumer to ensure that this event dispatcher is unique and
unambiguous. A special handle may be returned for the Asynchronous
Event Dispatcher for this scenario, DAT_EVD_OUT_OF_SCOPE, to indicate
that there is a default Event Dispatcher assigned for this Interface
Adapter, but that it is not in a scope where this Consumer may
directly invoke it.

The Asynchronous Event Dispatcher is an Object of both the Provider
and IA. Each Asynchronous Event Dispatcher bound to an IA instance
is notified of all asynchronous events, such that binding multiple
Asynchronous Event Dispatchers degrades performance by duplicating
asynchronous event notifications for all Asynchronous Event
Dispatchers. Also, transport and memory resources can be consumed per
Event Dispatcher bound to an IA

As with all Event Dispatchers, the Consumer is responsible for
synchronizing access to the event queue.

Valid IA names are obtained from dat_registry_list_providers(3DAT).

RETURN VALUES

DAT_SUCCESS
The operation was successful.

DAT_INSUFFICIENT_RESOURCES
The operation failed due to resource
limitations.

DAT_INVALID_PARAMETER
Invalid parameter.

DAT_PROVIDER_NOT_FOUND
The specified provider was not
registered in the registry.

DAT_INVALID_HANDLE
Invalid DAT handle; async_evd_handle is
invalid.

USAGE

The dat_ia_open() function is the root method for the Provider, and,
thus, all Objects. It is the root handle through which the Consumer
obtains all other DAT handles. When the Consumer closes its handle,
all its DAT Objects are released.

The dat_ia_open() function is the workhorse method that provides an
IA instance. It can also initialize the Provider library or do any
other registry-specific functions.

The dat_ia_open() function creates a unique handle for the IA to the
Consumer. All further DAT Objects created for this Consumer reference
this handle as their owner.

The dat_ia_open() function can use a reference count for the Provider
Library to ensure that the Provider Library cannot be removed when it
is in use by a DAT Consumer.

ATTRIBUTES