1.6. Asynchronous Processing

Asynchronous Functions

Some Pia processes can take a long time before completing. Asynchronous versions of functions (with Async at the end of the name) have been prepared so that API calls do not block when such processes are run. Calls to asynchronous functions return immediately, but the asynchronous process continues in the background before ending at a later time. To check on the completion of an asynchronously processing function, use the corresponding IsCompleted*() functions. To get the results of asynchronous processes, use the corresponding Get*Result() functions.

Warning:

The dispatch API functions needed by an asynchronous process must be called while waiting for that process to complete. In addition, other threads must be put to sleep as necessary so that time can be allocated to the thread handling the asynchronous process.

 This is shown in the following code sample.

Code 1-5. Asynchronous Function
result = nn::pia::session::Session::GetInstance()->JoinSessionAsync(sessionSetting);
if (result.IsFailure()) {
    // Error handling.
    ...
}

// Wait for completion of asynchronous processing.
while (!nn::pia::session::Session::GetInstance()->IsCompletedJoinSession()) {
    NexDispatch();
    PiaDispatch();
    Sleep(10);
    ...
}
result = nn::pia::session::Session::GetInstance()->GetJoinSessionResult();

Canceling an Asynchronous Process

Pia also has functions for canceling some of the asynchronous processes (Cancel*Async()). Note that processing does not necessarily complete immediately upon calling a cancel function. The application must wait for the asynchronous processing to complete before the cancellation process completes.

Generally, a cancel function is not provided for functions that complete their asynchronous processing in a short amount of time. To complete processing of a function for which there is no cancel function, wait until the asynchronous processing finishes before terminating it.

Warning:

While waiting for cancel processing to complete, as when waiting for an asynchronous process to complete, the various dispatch functions required by that process must be called. Threads must also perform sleeps appropriately so that the thread handling the cancel process is allocated an appropriate amount of processing time.

 This is shown in the following code sample.

Code 1-6. Canceling an Asynchronous Process
 result = nn::pia::session::Session::GetInstance()->JoinSessionAsync(sessionSetting);
if (result.IsFailure()) {
    // Error handling.
    ...
}
 
// Wait for the completion of asynchronous processing.
while (!nn::pia::session::Session::GetInstance()->IsCompletedJoinSession()) {
    // Cancel by user input (for example).
    if (IsTriggeredCancel()) {
        nn::pia::session::Session::GetInstance()->CancelJoinSessionAsync();
        // Dispatch calls after this point enable the cancel process to proceed.
        // After the cancel process has completed, the IsCompletedJoinSession() function returns true.
    }
    NexDispatch();
    PiaDispatch();
    Sleep(10);
    ...
}
result = nn::pia::session::Session::GetInstance()->GetJoinSessionResult();