Class OpenVDS::VolumeDataRequest

class VolumeDataRequest

A VolumeDataRequest encapsulates an asynchronous request for volume data from a VDS object instance.

When created by a VolumeDataAccessManager a VolumeDataRequest will be active. The request remains active until either IsCompleted(), IsCanceled() or WaitForCompletion() returns true.

It is supported to access a VolumeDataRequest from a different thread than where it was created, but concurrent access to the same instance from multiple threads can result in race conditions.

Subclassed by OpenVDS::VolumeDataRequest_t< uint8_t >, OpenVDS::VolumeDataRequest_t< uint16_t >, OpenVDS::VolumeDataRequest_t< uint32_t >, OpenVDS::VolumeDataRequest_t< uint64_t >, OpenVDS::VolumeDataRequest_t< float >, OpenVDS::VolumeDataRequest_t< double >, OpenVDS::VolumeDataRequest_t< VALUETYPE >

Public Functions

inline VolumeDataRequest()

inline VolumeDataRequest(IVolumeDataAccessManager *manager)

inline VolumeDataRequest(IVolumeDataAccessManager *manager, void *buffer, int64_t bufferByteSize, VolumeDataFormat bufferDataType)

inline VolumeDataRequest(IVolumeDataAccessManager *manager, int64_t bufferByteSize, VolumeDataFormat bufferDataType)

inline virtual ~VolumeDataRequest()

Destructor will automatically cancel the request if it is still active.

inline void ValidateRequest()

Check if the request object is valid. Throws an InvalidOperation exception if the request object is not valid.

inline int64_t RequestID() const

Get the ID of the request.

Returns:

The ID of the request.

inline bool IsCompleted()

Check if the request completed successfully. If the request completed, the buffer now contains valid data.

Returns:

The request is active until either IsCompleted, IsCanceled or WaitForCompletion returns true.

inline bool IsCanceled()

Check if the request was canceled (e.g. the VDS was invalidated before the request was processed). If the request was canceled, the buffer does not contain valid data.

Returns:

The request is active until either IsCompleted, IsCanceled or WaitForCompletion returns true.

inline bool WaitForCompletion(int millisecondsBeforeTimeout = 0)

Wait for the VolumeDataRequest to complete successfully. If the request completed, the buffer now contains valid data.

Parameters:

millisecondsBeforeTimeout – The number of milliseconds to wait before timing out (optional). A value of 0 indicates there is no timeout and we will wait for however long it takes. Note that the request is not automatically canceled if the wait times out, you can also use this mechanism to e.g. update a progress bar while waiting. If you want to cancel the request you have to explicitly call CancelRequest() and then wait for the request to stop writing to the buffer.

Returns:

The request is active until either IsCompleted, IsCanceled or WaitForCompletion returns true. Whenever WaitForCompletion returns false you need to call IsCanceled() to know if that was because of a timeout or if the request was canceled.

inline void Cancel()

Try to cancel the request. You still have to call WaitForCompletion/IsCanceled to make sure the buffer is not being written to and to take the job out of the system. It is possible that the request has completed concurrently with the call to Cancel in which case WaitForCompletion will return true.

inline void CancelAndWaitForCompletion()

Cancel the request and wait for it to complete. This call will block until the request has completed so you can be sure the buffer is not being written to and the job is taken out of the system.

inline int GetErrorCode()

Get the error code of a request that has been cancelled.

Returns:

An error code. If the error code is 100-599 it corresponds to a HTTP status code, while -1 indicates an internal error.

inline std::string GetErrorMessage()

Get the error string of a request that has been cancelled.

Returns:

The error string.

inline float GetCompletionFactor()

Get the completion factor (between 0 and 1) of the request.

Returns:

A factor (between 0 and 1) indicating how much of the request has been completed.

inline void *Buffer() const

Get the pointer to the buffer the request is writing to.

Returns:

The pointer to the buffer the request is writing to.

inline int64_t BufferByteSize() const

Get the size of the buffer the request is writing to.

Returns:

The size of the buffer the request is writing to.

inline VolumeDataFormat BufferDataType() const

Get the volume data format of the buffer the request is writing to.

Returns:

The volume data format of the buffer the request is writing to.

template<>
struct RequestFormat<double>

Public Static Attributes

static VolumeDataFormat format = VolumeDataFormat::Format_R64

template<>
struct RequestFormat<float>

Public Static Attributes

static VolumeDataFormat format = VolumeDataFormat::Format_R32

template<>
struct RequestFormat<uint16_t>

Public Static Attributes

static VolumeDataFormat format = VolumeDataFormat::Format_U16

template<>
struct RequestFormat<uint32_t>

Public Static Attributes

static VolumeDataFormat format = VolumeDataFormat::Format_U32

template<>
struct RequestFormat<uint64_t>

Public Static Attributes

static VolumeDataFormat format = VolumeDataFormat::Format_U64

template<>
struct RequestFormat<uint8_t>

Public Static Attributes

static VolumeDataFormat format = VolumeDataFormat::Format_U8