Operation Cancellation

Functions for handling the cancellation of concurrent operations. More...

Typedefs
typedef void *	CVCANCELLATIONTOKEN
	Object to pass to abortable operations. More...
typedef void *	CVCANCELLATIONTOKENSOURCE
	Handle to send the abort signal to token registered operations. More...

Functions
cvbres_t	CVCCancellationTokenIsCanceled (CVCANCELLATIONTOKEN Token, cvbbool_t &State)
	Gets the cancellation state of the token. More...
cvbres_t	CVCCancellationTokenSourceCancel (CVCANCELLATIONTOKENSOURCE TokenSource)
	Triggers a cancellation. More...
cvbres_t	CVCCreateCancellationToken (CVCANCELLATIONTOKENSOURCE &TokenSource, CVCANCELLATIONTOKEN &Token)
	Creates cancellation token and source. More...
cvbbool_t	CVCIsCancellationToken (CVCANCELLATIONTOKEN Token)
	Checks if the specified handle is a cancellation token. More...
cvbbool_t	CVCIsCancellationTokenSource (CVCANCELLATIONTOKENSOURCE TokenSource)
	Checks if the specified handle is a cancellation token source. More...

Detailed Description

Functions for handling the cancellation of concurrent operations.

The concept of cancellation tokens improves the way the execution of parallel or concurring operations are managed. This way, the programmer has the full control of cancelling tasks from a single CVCANCELLATIONTOKENSOURCE.

• Create a token via CVCCreateCancellationToken
• Check state of a token via CVCCancellationTokenIsCanceled
• Cancel an operation via CVCCancellationTokenSourceCancel
  
  The cancellation token implementation can consist of the following steps:

1. Create the CVCANCELLATIONTOKENSOURCE and the CVCANCELLATIONTOKEN handles via CVCCreateCancellationToken. This will connect the source and the token for future cancellations.
2. Create the abortable operations
3. Trigger the cancellation via CVCCancellationTokenSourceCancel
4. CVCCancellationTokenIsCanceled gives a clue about whether the token is already canceled or not.

Typedef Documentation

CVCANCELLATIONTOKEN

CVCANCELLATIONTOKEN

Object to pass to abortable operations.

The token will assicuate a cancel operation from the source to the ongoing operation and abort this operation. A token can be reused in multiple operations at the same time, but can only be used once for cancelling an operation or a set of operations. The handle is created and connected to a source via CVCCreateCancellationToken.

See also

CVCCreateCancellationToken

CVCANCELLATIONTOKENSOURCE

CVCANCELLATIONTOKENSOURCE

Handle to send the abort signal to token registered operations.

This object is responsible for informing all tasks holding the connected token to cancel their execution. For this a function called CVCCancellationTokenSourceCancel sends a notification to all tokens.

Function Documentation

CVCCancellationTokenIsCanceled()

cvbres_t CVCCancellationTokenIsCanceled	(	CVCANCELLATIONTOKEN	Token,
		cvbbool_t &	State
	)

Gets the cancellation state of the token.

Since

1.0.0

Parameters

[in]	Token	The token object.
[out]	State	State of the cancellation, true if canceled, false otherwise #CVC_ERROR (#CVC_E_OK) on success #CVC_ERROR (#CVC_E_WRONGOBJECT) if Token is not a CVCANCELLATIONTOKEN

CVCCancellationTokenSourceCancel()

cvbres_t CVCCancellationTokenSourceCancel

(

CVCANCELLATIONTOKENSOURCE

TokenSource

)

Triggers a cancellation.

This call cancels all operations that run with the corresponding CVCANCELLATIONTOKEN handle.

Since

1.0.0

Parameters

[in]

TokenSource

The token source object. #CVC_ERROR (#CVC_E_OK) on success #CVC_ERROR (#CVC_E_WRONGOBJECT) if TokenSource is not a CVCANCELLATIONTOKENSOURCE

CVCCreateCancellationToken()

cvbres_t CVCCreateCancellationToken	(	CVCANCELLATIONTOKENSOURCE &	TokenSource,
		CVCANCELLATIONTOKEN &	Token
	)

Creates cancellation token and source.

Since

1.0.0

Parameters

[out]	TokenSource	The token source handle.
[out]	Token	The token handle.

Returns

• #CVC_ERROR (#CVC_E_OK) on success
• #CVC_ERROR (#CVC_E_ERROR) if the object could not be created.

See also

CVCCancellationTokenIsCanceled

CVCCancellationTokenSourceCancel

CVCIsCancellationTokenSource

CVCIsCancellationToken

CVCIsCancellationToken()

cvbbool_t CVCIsCancellationToken

(

CVCANCELLATIONTOKEN

Token

)

Checks if the specified handle is a cancellation token.

Since

1.0.0

Parameters

[in]

Token

A handle to be examined.

Returns

true if Handle is a cancellation token; false if not.

See also

CVCCreateCancellationToken

CVCIsCancellationTokenSource()

cvbbool_t CVCIsCancellationTokenSource

(

CVCANCELLATIONTOKENSOURCE

TokenSource

)

Checks if the specified handle is a cancellation token source.

Since

1.0.0

Parameters

[in]

TokenSource

A handle to be examined.

Returns

true if Handle is a cancellation token source; false if not.

See also

CVCCreateCancellationToken