Sensoray 2600 - Manual (Page 17)

Sensoray 2600 Programming Guide
13
Transactions
5.2.1 Thread Safety
All of the gateway transaction functions are thread safe, and it is permissible for multiple transactions to exist (and be in different
states) at the same time. For example, your application could be partitioned into multiple threads (e.g., analog I/O thread, digital
I/O thread, serial communication thread) in which each thread asynchronously begins, schedules actions into, and executes its own
private gateway transactions. To guarantee thread safety in such a case, each transaction should be started, scheduled and executed
only by the thread that “owns” that transaction. In general, a transaction object should not be shared by multiple threads.
5.3 Transaction Buffers
Each MM has fifteen internal transaction buffers which are kept in a pool. This buffer pool is shared by all comport and gateway
transactions. A transaction buffer is dynamically allocated from the pool when a MM transaction begins (i.e., upon receipt of a
packet from an Ethernet client), and when the transaction is finished (i.e., a response packet has been sent to the client), the buffer
is returned to the pool. Every client-side transaction is associated with a dedicated transaction buffer on the MM.
A maximum of fifteen transactions—in any combination of comport and/or gateway transactions—may be in progress at the same
time on one MM. For example, it is possible for a MM to process transactions on all four of its comports while simultaneously
processing up to eleven gateway transactions. This means that a single Ethernet client may run multiple threads and/or processes
in which each thread or process concurrently executes simultaneous transactions with a single MM.
Multiple simultaneous MM transactions may involve more than one Ethernet client. For example, it is permissible for two
different Ethernet clients to simultaneously execute gateway transactions on a single MM. Each of the fifteen possible
simultaneous MM transactions may be invoked by any arbitrary Ethernet client. The MM supports up to four Ethernet clients.
An error will occur on the MM if its transaction buffer pool is empty when a transaction begins. This can happen if a packet is
received from a client while the maximum possible number of simultaneous MM transactions are already in progress. In such
cases, the newest transaction will be dropped by the MM and no response will be sent to the client.
5.4 Blocking Behavior
Gateway transactions may be managed by either blocking or non-blocking functions. All comport transaction functions are
blocking operations.
In the case of a gateway transaction, execution of the calling thread is blocked by S26_SchedExecute() until a response packet is
received from the target MM. This works well if your application has one or more dedicated gateway transaction threads because
other threads can run while the transacting threads are blocked. There may be situations, however, in which it is impractical to
employ separate transaction threads. To support these cases, several middleware functions have been provided to enable
non-blocking gateway transactions.
To execute a non-blocking gateway transaction, call S26_SchedExecuteStart() instead of S26_SchedExecute() . This will
initiate the transaction (i.e., send the Ethernet command packet to the MM) but will return immediately without waiting for a
response packet.
At any convenient time after calling S26_SchedExecuteStart() , you may call S26_SchedExecuteIsResponded() to determine
whether a response packet has arrived. If no response has arrived, the application may continue on with other tasks, calling
S26_SchedExecuteIsResponded() again at any later times as needed. If and when all other tasks have been completed, the
application can call S26_SchedExecuteWait() to block until a response packet has arrived.
When the application determines that a response packet has been received, it should call S26_SchedExecuteFinish() to process
the response packet and release the transaction object’s resources.
5.5 Errors
With the exception of S26_SchedOpen() , all gateway and comport transaction functions return an enumerated error code. These
error codes are referenced by their symbolic names as defined in app2601.h . Error codes occupy the most significant three bytes
of a u32 value. Some error types return extended information in the error code’s least significant byte.