Description
This manual connection member function requests 'read' access from the connected store. If there is a readable buffer available then it is claimed and its address returned. If there are no buffers available (they are all currently opened for write or update), then the call will block in accordance with the specified timeout, and then return TRUE if one becomes available within the timeout constraint; or FALSE if it does not. Before reading this topic, we would recommend familiarity with Manual Connections and Arbitrated Stores.
Prototype
Uns OpenRead( Int key,
Uns rule,
Uns timeout );
Parameters
key
This parameter can be used as a means of filtering reads and updates. If a writer and/or updater specifies a key then it is associated with the buffer instance. Readers and/or updaters that specify a key and a rule will only be granted access to data that satisfies their specified constraint. See Store Keys and Rules.
rule
This parameter can be used by readers and updaters as a means of filtering out data of interest (see Store Keys and Rules).
timeout
This parameter determines whether the connection will poll or block (see Connection Timeout). In this case it can only be set to poll (CLP_POLL) or block (CLP_WAIT). Millisecond timeouts are not supported. Since arbitrated stores are only usually held open for short periods this attribute is usually set to block.
Return Value
This function returns logical TRUE if the store is successfully opened for 'read' within the timeout period; or FALSE otherwise.
Notes
This member function is overloaded and in the case of 'mapped' connections, the translator will also produce a call that requires no arguments. In that case the arguments will be set to those that were set by the connection's attributes (see Manual Connections).
Reads are only allowed if they are permitted by the connection's access constraints (see Manual Connections).
All read and update accesses will block until the store has been initialized by a 'write'. Typically, stores are initialized from circuit/method initialization code during startup and prior to execution (see Entering Harness Code).
Writers and updaters take precedence over readers. If a write or update request is issued to a store, and there are no free buffers then the oldest buffer (earliest written to or updated) becomes the target buffer for writes/updates. If there are no uncontended buffers, and there are writers/updaters waiting, then subsequent read requests will block.