ar_set_preload_config

short ar_set_preload_config (short board, short item, unsigned int value);

Purpose

This routine is designed to provide protection when executing multi-threaded or multi-process applications with your CEI-x30 device.  Call this routine before calling AR_LOADSLV to update the value of a particular pre-load API operational configuration setting.  This routine should not be called subsequent to any invocation of AR_LOADSLV.

Parameters

Input

Name

Type

Description

board

short

(input) Device Number of the board to reference, (valid range is 0-15).

item

short

(input) Attribute about which to set information, currently limited to a single option, ARU_CONCURRENCY_MODE.

value

unsigned int

(input) the selected concurrency mode:

AR_CONC_NONE            no multi-thread or multi-process support (default).

AR_CONC_MULTITHRD   multi-thread concurrency mode.

AR_CONC_MULTIPROC   multi-process concurrency mode.

The default concurrency mode, AR_CONC_NONE, provides no multi-thread protection to the device and no multi-process API support.  The user application must ensure that only one thread is calling into the API at any given time, and only a single process may interface with a particular board.

If AR_CONC_MULTITHRD concurrency mode is selected, thread protection for each device access is provided internally within the API.  The user application may call into the API from multiple threads, but all threads must belong to a single process.  The main user application thread should initialize the board with a call to AR_LOADSLV before other threads attempt to call into the API.  This mode is supported on all operating systems supported by the CEI-x30 software distribution.

If AR_CONC_MULTIPROC concurrency mode is selected, thread protection is provided internally within the API and multiple processes may interface with a single board.  If any process requests multi-process mode, all other processes must also request multi-process mode.  This mode is only supported under Windows operating systems and Linux Kernel 2.6 distributions specifically supporting System V features.  In this mode, all processes must invoke AR_LOADSLV during initialization of the process and AR_CLOSE upon termination.  Failure to follow this strict requirement could result in irrecoverable errors.  Note that board setup/initialization is only executed in AR_LOADSLV if no other processes have the board open.  If another process has the board open (that is, if another process has opened the board using AR_LOADSLV but hasn't yet closed the board using AR_CLOSE), AR_LOADSLV attaches to the device without re-initializing the board or modifying board settings.  Similarly, AR_CLOSE only shuts down the board if no other processes have the board open.  If another process has the board open, AR_CLOSE detaches from the board without shutting it down.  Thus, board settings are preserved across all process invocations of AR_LOADSLV and AR_CLOSE.  Multi-process mode is only required when accessing a single board from multiple processes.  If multiple boards are installed, AR_CONC_NONE concurrency mode can be used as long as only one process interfaces with each board.

Note: The use of hardware interrupts is prohibited when multi-process operations are enabled under the Windows operating system.

Return Value

Name

Type

Description

status

short

status of the function call, with valid values of:
ARS_NORMAL               Success.                    
ARS_INVBOARD           An invalid board parameter value was provided.
ARS_INVARG               An invalid item or value parameter value was provided.
ARS_BOARD_MUTEX     Creation of the Board Lock mechanism failed.

ARS_NO_OS_SUPPORT  The item selection IS not supported with the host operating system.

References

Initialization Functions
Alphabetical Function Index
Hierarchical Function Index

CEI-x30 API Description