|
||||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
public interface Action
Actions represent asynchronous processes handled by an underlying action engine which encapsulating action verbs, submission states, and cached input and output parameters. Particular drivers implement the action interface, providing by convention blocking action verbs, getters, and setters.
The simplest and most common way to use a device action is through its blocking action verbs. Blocking action verbs appear to act as any other function by using the input parameters to prepare the action, submitting it to the action engine, blocking until the action engine completes the action, and returning any meaningful results. Examples of blocking action verbs are read, write, toggle, send, receive, and so on.
Getters and setters MUST access only the cached input and output parameters for the action. The particular device action defines which getters correspond to input parameters or output values or both, and which are valid before submission or after completion or both.
By convention, setters SHOULD always return a "this" pointer to the action. A device action MAY provide particular setters that directly or indirectly correspond to the blocking action verbs. Using this convention, advanced user code may asynchronously invoke a device action.
For example, imagine a device called BlockReader that implements Action to allows for block read operations, which may take some time to complete. The BlockReader interface may look something like this:
interface BlockReader extends Action { public int read( byte[] buffer, int offset, int length ); public BlockReadDevice setRead( byte[] buffer, int offset, int length ); public int getNumRead(); }
Given an instance of a BlockReader called block_reader, user code may directly call the blocking action verb read for synchronous reads, like this:
byte[] buffer = new byte[200]; int num_read = block_reader.read( buffer, 0, buffer.length ); // here buffer has num_read valid bytes
Alternatively, advanced users may create more complex code to call setRead to perform asynchronous operations, like this:
byte[] buffer = new byte[200]; block_reader.setRead( buffer, 0, buffer.length ).submit(); // ... do something else ... if( block_reader.block(250).isDone() ) { // Here, within 250ms of calling block(250), block_reader has completed // and buffer has valid bytes. Find out how many. int num_read = block_reader.getNumRead(); } else { // Here, after at least 250ms, block_reader is not yet complete and buffer // has an indeterminate number of valid bytes, if any. The result of // getNumRead is undefined here. }
Field Summary | |
---|---|
static byte |
DONE
Done action state. |
static byte |
ERROR
DoneError action state. |
static byte |
IDLE
Idle action state. |
static byte |
PENDING
Pending action state. |
Method Summary | |
---|---|
Action |
block()
Block an indefinite amount of time until this Action is no longer pending. |
Action |
block(int timeoutMilli)
Block a defined amount of time or until the Action is no longer pending. |
Action |
cancel()
Cancel this Action if PENDING. |
byte |
getActionState()
Get the current state of this Action: IDLE, PENDING, DONE, or ERROR. |
boolean |
isDone()
Return true is this Action is DONE. |
Action |
submit()
Submit this Action for processing by the action engine. |
Field Detail |
---|
static final byte IDLE
static final byte PENDING
static final byte DONE
static final byte ERROR
Method Detail |
---|
Action submit()
Action block() throws ActionException
ActionException
Action block(int timeoutMilli) throws ActionException
timeoutMilli
- the maximum number of milliseconds to block
ActionException
Action cancel()
byte getActionState()
boolean isDone() throws ActionException
ActionException
|
||||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |