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

See attributes(5) for descriptions of the following attributes:

See Also

dat_evd_modify_cno(3DAT), dat_evd_resize(3DAT), dat_ia_close(3DAT), dat_registry_list_providers(3DAT), libdat(3LIB), attributes(5)