An FS command block is stacked up in the command queue managed by the system per FS client and used to manage the priority of each FS task. It should be used for FS asynchronous functions and multithread processing. It is acceptable to use the same command block when using synchronous functions on a single thread.
There is no limit on the number of command blocks other than the upper limit of memory. Although
FSCancelCommand to be described later is available, it is not necessary to call it after a command block is
used or for those not in the queue.
Command block parameters available for developers to control are priority and user data. Priority affects the order of task execution. Use of user data is up to developers.
Each functional capability is explained below.
Call the following API to initialize the command block.
||Initialize the command block.|
After command block memory is allocated, it is necessary to initialize before actual use. User data will
be cleared, and the priority will be set to the default value (16). When sharing a command block, it is acceptable
FSInitCmdBlock again to reset these values. However, do not call it while the command is being
executed or for command blocks in the queue.
Call the following API to cancel pending commands in the command queue.
||Cancel all pending commands for the specified client in the command queue.|
||Delete the specified command block from the command queue.|
An FS function that has the canceled command block as an argument will stop processing and then
FS_STATUS_CANCELED. If the specified command is already being executed, it cannot be canceled. Also,
if it has already been executed or is not placed into the command queue, nothing will be done.
To find out whether command cancellation is valid, check the return value of the FS function that has the command block as an argument.
Whether a command has been completed or canceled, priority or user data set by the application will never be reset. Use this information as reference when sharing a command block.
FSWriteFile) stops the write process in midstream, which may leave the state incomplete during next Read (containing the latest data up to some point, and the rest is old data). To prevent unintended data from being read, consider performing the following:
The following APIs are available for the user data of a command block.
||Set the user data for the specified command.|
||Obtain the user data of the specified command.|
These APIs have no particular usage restrictions.
The following APIs are available for command block priority.
||Set the priority of the specified command.|
||Get the priority of the specified command.|
Priority must be set before placing the command into the queue.
If a command placed into the queue has higher priority than the one being executed, interrupt the active command to execute the command with higher priority.
Since Cafe SDK 2.07.03 P1, you can use the following API to get the active command for the specified client.
||Get the command block for a command that is currently being executed by the specified FS client.|
If the specified client has no active command,
NULL will return. Also, if auto error handling is
blocking APIs in case of an error, blocked commands will return.
2013/05/08 Automated cleanup pass.
2012/10/04 Initial version.