dl::IPromise Class Reference

Promise interface class. More...

#include <dlapi.h>

Public Types
enum	Status {   Idle, Executing, Complete, Error,   InvalidFuture = 0xff }

Public Member Functions
virtual void	getLastError (char *buffer, size_t &bufferSize) const =0
	Puts a human readable string into the supplied buffer containing the last known error for command the IPromise is tracking. More...
virtual EStatusCode	getAPIStatusCode () const =0
	Returns the API status code reported by the execution of the command. More...
virtual Status	getStatus () const =0
	Retrieve the status of the command the IPromise is tracking. More...
virtual Status	wait ()=0
	Wait (blocking) until the IPromise either completes, or returns an error (timing out at 10 seconds since the last known update). More...
virtual void	release ()=0
	Flags the promise for release within DLAPI. More...

Detailed Description

Promise interface class.

Device/Peripheral interface calls which complete asynchronously (e.g. query and set methods) will return a pointer to an IPromise object. Users are responsible for releasing IPromise pointers when they are done with them so that the API can manage their memory internally. A failure to release promises will result in memory leakage.

An example of how to use a promise in a blocking fashion:

 {c++}
ICamera::Info getInfo(ICameraPtr pCamera)
{
  IPromisePtr pPromise = pCamera->queryInfo();
  IPromise::Status result = pPromise->wait();
  if (result != IPromise::Complete)
  {
    char buf[512] = {0};
    size_t lng = 512;
    pPromise->getLastError(&(buf[0]), lng);
    pPromise->release(); // Mandatory!
    throw std::logic_error(&(buf[0]), lng);
  }
  pPromise->release(); // Mandatory!
  return pCamera->getInfo();
}

An example of how to use a promise in a non-blocking fashion, executing a callback function while we wait:

 {c++}
bool isPromiseDone(IPromisePtr pPromise)
{
  IPromise::Status result = pProimse->getStatus();
  if ( result == IPromise::Error )
  {
    char buf[512] = {0};
    size_t lng = 512;
    pPromise->getLastError(&(buf[0]), lng);
    pPromise->release();
    throw std::logic_error(&(buf[0]), lng);
  }
  else if ( result == IPromise::Complete )
  {
    pPromise->release();
  }
  return result == IPromise::Complete;
}

ICamera::Info getInfo(ICameraPtr pCamera, std::function<void()> fCallback)
{
  IPromisePtr pPromise = pCamera->queryInfo();
  try
  {
    while (!isPromiseDone())
    {
      // Execute fCallback while we wait
      fCallback();
    }
  }
  catch (std::exception &ex)
  {
    // Log any error messages
  }

  return pCamera->getInfo();
}

IPromise is also thread-safe, and thus could be monitored on a worker thread. You should try to avoid making multiple calls before promises have the chance to return, as the internal queuing system can get overloaded, and bog-down IO to the camera.

Member Enumeration Documentation

Status

enum dl::IPromise::Status

Enumerator
Idle	Promise has not yet begun execution.
Executing	Promise is currently being executed.
Complete	Promise completed successfully.
Error	Promise completed with an error.
InvalidFuture	Promise is uninstantiated.

        {
            Idle,      
            Executing, 
            Complete,  
            Error,     

            InvalidFuture = 0xff    
        };

Member Function Documentation

getAPIStatusCode()

virtual EStatusCode dl::IPromise::getAPIStatusCode ( ) const

pure virtual

Returns the API status code reported by the execution of the command.

Returns

API status code reported by the camera

See also

EStatusCode

This function returns a more fine-grained error code from the API when a failure is encountered. Some error codes are recoverable (such as the feature not supported), and we need to

getLastError()

virtual void dl::IPromise::getLastError ( char *  buffer, size_t &  bufferSize  ) const

pure virtual

Puts a human readable string into the supplied buffer containing the last known error for command the IPromise is tracking.

Parameters

buffer	a pointer to an array of characters that will receive the last error.
size_t	a reference to a variable which passes in the size of the supplied buffer, and updates with the length of the string returned.

This function retrieves the last error stored in this promise object. It is best to call this function only when getStatus(), or wait() returns IPromise::Error. All error strings are English text only. No localization is done within DLAPI.

getStatus()

virtual Status dl::IPromise::getStatus ( ) const

pure virtual

Retrieve the status of the command the IPromise is tracking.

Returns

IPromise::Status

See also

IPromise::Status

A non-blocking call to obtain the status of the promise's operation.

release()

virtual void dl::IPromise::release ( )

pure virtual

Flags the promise for release within DLAPI.

Signals to the API that the user is done using the promise, and it can be handled by garbage collection. This function must be called on all promises returned from the API, no exceptions. The IPromise object is no longer valid after calling this.

wait()

virtual Status dl::IPromise::wait ( )

pure virtual

Wait (blocking) until the IPromise either completes, or returns an error (timing out at 10 seconds since the last known update).

Returns

IPromise::Status

Blocking function waits for the operation to complete with a result (Success, or Error), and returns that result.

---

The documentation for this class was generated from the following file:

• C:/NightlyBuild/DL_Imaging/Aluma_Software/dlapi/src/dlapi.h