3.2.4.3 Rules for Handling Synchronous and Asynchronous Tasks

  • Article

A number of protocol messages require the server to execute configuration tasks on the storage objects (for example, delete partition or create volume).

Tasks can be either synchronous or asynchronous. For a synchronous task, the server MUST wait for the task to complete with either success or failure before returning a response to the client. For an asynchronous task, the server SHOULD return a response to the client before the task completes.

This is the list of methods that MAY be implemented asynchronously:<17>

  • IVolumeClient::CreatePartitionAssignAndFormat

  • IVolumeClient3::CreatePartitionAssignAndFormat

  • IVolumeClient::CreatePartitionAssignAndFormatEx

  • IVolumeClient3::CreatePartitionAssignAndFormatEx

  • IVolumeClient::Format

  • IVolumeClient3::Format

  • IVolumeClient::CreateVolumeAssignAndFormat

  • IVolumeClient3::CreateVolumeAssignAndFormat

  • IVolumeClient::CreateVolumeAssignAndFormatEx

  • IVolumeClient3::CreateVolumeAssignAndFormatEx

  • IVolumeClient::ImportDiskGroup

  • IVolumeClient3::ImportDiskGroup

  • IVolumeClient::UninitializeDisk

  • IVolumeClient3::UninitializeDisk

  • IVolumeClient::ReConnectDisk

  • IVolumeClient3::ReConnectDisk

All the other methods MUST be implemented synchronously.

For the asynchronous methods, the server MUST send periodic notifications to the client after returning the initial response to inform the client about the status and progress of the task. The time interval for these periodic notifications SHOULD be based on two objectives:

  • Not flooding the client with unnecessary notifications.

  • Providing pertinent information about the ongoing status of the task.<18>

The protocol messages that require the server to execute configuration tasks receive an output parameter named tinfo of type TASK_INFO.

To process synchronous tasks, the server MUST follow these rules:

  1. The server MUST fill the tinfo output parameter:

    • Generate a unique identifier for the task and place it in tinfo.id.

    • Set tinfo.status to the appropriate value of the enumeration REQSTATUS, denoting the success or failure of the task.

    • Set all other fields to 0, unless otherwise specified.

  2. The server MUST return the tinfo structure in the response to the client.

  3. The server MUST NOT add a new task object to the list of tasks currently running on the server.

For all synchronous method calls that have a TASK_INFO structure as an output parameter, the server MUST perform the following extra step (the only methods that do not have to carry out this step are IVolumeClient::CreatePartition, IVolumeClient3::CreatePartition, IVolumeClient::DeletePartition, IVolumeClient3::DeletePartition, IVolumeClient::WriteSignature, IVolumeClient3::InitializeDiskStyle, IVolumeClient::MarkActivePartition, IVolumeClient3::MarkActivePartition, IVolumeClient::Eject IVolumeClient3::Eject, IVolumeClient::FTDeleteVolume, IVolumeClient3::FTDeleteVolume, IVolumeClient::FTBreakMirror, IVolumeClient3::FTBreakMirror, IVolumeClient::FTResyncMirror, IVolumeClient3::FTResyncMirror, IVolumeClient::FTRegenerateParityStripe, IVolumeClient3::FTRegenerateParityStripe, IVolumeClient::FTReplaceMirrorPartition, IVolumeClient3::FTReplaceMirrorPartition, IVolumeClient::FTReplaceParityStripePartition, IVolumeClient3::FTReplaceParityStripePartition, IVolumeClient::AssignDriveLetter, IVolumeClient3::AssignDriveLetter, IVolumeClient::FreeDriveLetter, IVolumeClient3::FreeDriveLetter, IVolumeClient::Format, IVolumeClient3::Format, IVolumeClient::GetEncapsulateDiskInfo, IVolumeClient3::GetEncapsulateDiskInfoEx, IVolumeClient::EnumTasks, IVolumeClient3::EnumTasks, IVolumeClient3::GetTaskDetail, and IVolumeClient::GetTaskDetail):

  • Send a task completion notification to the client using the IDMNotify::ObjectsChanged message. The notification MUST be of type DMNOTIFY_TASK_INFO and action LDMACTION_MODIFIED. The status field of the TASK_INFO structure MUST be set to the appropriate value of the enumeration REQSTATUS denoting the success or failure of the task.

Note Subsections found under Protocol Message Details (section 3.2.4.4) explicitly call out any synchronous tasks that require sending task completion notifications.

To process asynchronous tasks, the server MUST follow these rules:

  1. The server MUST fill the tinfo output parameter:

    • Generate a unique identifier (UID) for the task and place it in tinfo.id.

    • Set tinfo.status to REQ_STARTED.

    • Set the rest of the fields to 0, unless otherwise specified.

  2. The server MUST return the tinfo structure in the initial response to the client.

  3. The server MUST add a new task object to the list of tasks currently running on the server.

  4. Periodically, the server MUST send progress notifications to the clients by using the IDMNotify::ObjectsChanged message. The notifications MUST be of type DMNOTIFY_TASK_INFO and action LDMACTION_MODIFIED. The percentComplete field of the TASK_INFO structure MUST be set to accurately provide information on the progress of the operation.

  5. When the task finishes with either success or failure, the server MUST send a final notification to the clients by using the IDMNotify::ObjectsChanged message. The notification MUST be of type DMNOTIFY_TASK_INFO and action LDMACTION_MODIFIED. The status field of the TASK_INFO structure MUST be set to the appropriate value of the enumeration REQSTATUS denoting the success or failure of the task.

  6. When the task is finished, the task object MUST be deleted from the list of tasks that are currently running on the server.