Acquisition and Streaming - Cancellation

<< Acquisition and Streaming

The Cvb::CancellationToken gives the possibility to cancel individual wait calls instead of the whole acquisition. Restarting the whole acquisition takes much longer, than to simply call wait functions again. A use case for example would be if an external stop signal is received by the application, the fastest reaction to stop the acquisition and to restart it, would be to abort the wait function with a cancellation token. The token itself can be checked if it has been canceled. In addition, on cancellation, the returned Cvb::WaitStatus will have a value of Cvb::WaitStatus::Abort.

When using a cancellation token, the following rules should be observed:

• The cancellation of the acquisition may not occur immediately and if an image is received before the cancellation is processed, a race condition may occur, and the cancellation may not be seen. It is recommended to check the cancellation token even if an image has been received to properly act on it.
• If multiple waits are cancelled at the same time through a single token, they may finish in a random order.

C++C#Python

C++

using namespace Cvb;
 
CancellationTokenSource source; // (1)
auto token = source.Token(); // (2)
 
ImagePtr image;
WaitStatus waitStatus;
NodeMapEnumerator enumerator;
std::tie(image, waitStatus, enumerator) = stream->Wait(*token); // (3)
 
// ...
 
source.Cancel(); // (4)
token->IsCanceled(); // (5)

C#

using Stemmer.Cvb;
using Stemmer.Cvb.Driver;
 
var source = new CancellationTokenSource(); // (1)
var token = source.Token(); // (2)
 
WaitStatus status;
var image = stream.Wait(out status, token)// (3)
 
// ...
 
source.Cancel(); // (4)
token.IsCanceled() // (5)

Python

import cvb
 
source = cvb.CancellationTokenSource() # (1)
token = source.token # (2)
 
image, status, node_maps = stream.wait(token) # (3)
 
# // ...
 
source.cancel() # (4)
token.is_canceled() # (5)

Note: Error handling has been omitted from the above example.

1. Create a cancellation token source object, which provides tokens and the signal to cancel.
2. Get a cancellation token.
3. Pass the cancellation token to the wait function.
4. Cancel the wait function by using the cancellation token.
5. Returns, whether or not the cancellation token has been canceled.