Command Block

Overview

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.

How to Use

Initialization

Call the following API to initialize the command block.

FSInitCmdBlock 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 to call FSInitCmdBlock again to reset these values. However, do not call it while the command is being executed or for command blocks in the queue.

Cancel a Command

Call the following API to cancel pending commands in the command queue.

FSCancelAllCommands Cancel all pending commands for the specified client in the command queue.
FSCancelCommand 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 return 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.

WARNING:
Canceling a Write Command (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:
  • Before reading and flushing the data, write again to complete.
    • By using FSGetPosFile to get the file position, you can find out where write has been canceled.
    • To restart writing from the beginning of the file, use FSSetPosFile, or reopen the file to move the file position to the top.
  • Before reading and flushing the data, perform a rollback to revert the state to before Write.
  • Do not use the cancel command on the write command.
NOTE:
An implementation caution is a restriction "to prevent reading the buffer that is being written because the system rewrites the buffer along the way". Buffers will never be rewritten after canceling the write command. After the system reverts the buffer to its original state, cancel the command.

User Data

The following APIs are available for the user data of a command block.

FSSetUserData Set the user data for the specified command.
FSGetUserData Obtain the user data of the specified command.

These APIs have no particular usage restrictions.

Priority

The following APIs are available for command block priority.

FSSetCmdPriority Set the priority of the specified command.
FSGetCmdPriority 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.

Get a Command Block

Since Cafe SDK 2.07.03 P1, you can use the following API to get the active command for the specified client.

FSGetCurrentCmdBlock 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.

Revision History

2013/05/08 Automated cleanup pass.
2012/10/04 Initial version.


CONFIDENTIAL