Promise object

.html ›› .html ›› .html ›› .html ››
Parent Previous Next

Promise object

A Promise is an object designed for monitoring asynchronous operations and their eventual outcomes, whether they result in success or failure


A Promise can exist in one of the following states:


Once a Promise has resolved to either "Success" or "Failed," its state becomes sealed along with its associated data or error message, and it remains immutable.

Tracking a promise

When dealing with a function that returns a Promise object, you have the flexibility to either monitor or disregard its eventual outcome. If the success or failure of the asynchronous operation doesn't impact your code, you can simply ignore the Promise object.


If you need to capture the result of an asynchronous operation, you can engage with the Promise object using one of the following styles:

"Await" style for tracking promises:

This style simplifies the code, but it is limited to use within coroutines.


Reminder: Coroutines are computer program execution lines that can be suspended and resumed. 
All Firecast events run inside coroutines, and you can initiate a new one using the Async.execute function.


Example 1 (using a variable to hold the Promise object):

local promise = Dialogs.asyncOpenFile("Select a image", "image/*");

local selectedFiles = await(promise);  

showMessage(selectedFiles[1].name);


Example 2 (without using a variable to hold the Promise object):

local selectedFiles = await(Dialogs.asyncOpenFile("Select a image", "image/*"));

showMessage(selectedFiles[1].name); 


Example 3 (using the sugar "await" method that Promises objects have):

local selectedFiles = Dialogs.asyncOpenFile("Select a image", "image/*"):await();

showMessage(selectedFiles[1].name); 


Please refer to the await function documentation for more details.

"Event" style for tracking promises:

This style works both inside and outside of coroutines but can make your code less readable if used excessively.

Invoke the "thenDo" and/or "onError" methods that all Promise objects have. The functionality of these methods is clarified below.


Example 1 (using a variable to hold the Promise object):

local promise = Dialogs.asyncOpenFile("Select a image", "image/*");

 

promise:thenDo(

    function(selectedFiles)

        -- the argument "selectedFiles" receives the success data of the promise      

        showMessage(selectedFiles[1].name);

end);


Example 2 (without using a variable to hold the Promise object):

Dialogs.asyncOpenFile("Select a image", "image/*"):thenDo(

    function(selectedFiles)

        -- the argument "selectedFiles" receives the success data of the promise

        showMessage(selectedFiles[1].name);

    end);

       

Object characteristics

Methods

Método

Descrição

promise:await()

This method is employed to synchronize with the resolution of the Promise, allowing your code to pause until the asynchronous operation concludes.


The promise:await() method is functionally equivalent to await(promise). 


For detailed information, please consult the documentation for the await function.

promise:pawait()

This method is employed to synchronize with the resolution of the Promise, allowing your code to pause until the asynchronous operation concludes.


The promise:pawait() method is functionally equivalent to pawait(promise)


For detailed information, please consult the documentation for the pawait function.

promise:thenDo(successCallback)
or
promise:onSuccess(successCallback)

Set a continuation callback function that will be called when the Promise resolves to success.


Arguments:

  • successCallback - A function that will be called when the Promise resolves to success. The first argument of the callback function will receive the associated success data.


Return:

  • A new Promise object that will be resolved asynchronously with the execution of the successCallback. This new promise can be used to chain promises handling.


Remarks:

  • If the Promise is already in a success state, the successCallback will be called as soon as possible


Example:

  1. local promise = Firecast.asyncOpenUserNDB("name");
  2.  
  3. promise:thenDo(
  4.     function(node)
  5.         -- This function will be called when the Promise is resolved
             -- successfully. The first argument, "node", contains the
  6.        -- Promise success data, which in this case is an opened
  7.        -- nodeDatabse
  8.     end);

promise:thenDo(successCallback, failureCallback)

Set continuation callback functions that will be called when the Promise resolves to success or failure.


Arguments:

  • successCallback - A function that will be called if the Promise resolves to success. The first argument of the callback function will receive the associated success data
  • failureCallback - A function that will be called if the Promise resolves to failure. The first argument of the callback function will receive the error message.


Return:

  • A new Promise object that will be resolved asynchronously with the execution of either the successCallback or failureCallback. This new promise can be used to chain promises handling.


Remarks:

  • This will monitor the Promise for both success and failure states at the same time
  • If the Promise is already in a success state, the successCallback will be called as soon as possible. 
  • If the Promise is already in a failure state, the failureCallback will be called as soon as possible
  • If the “successCallback” is called, “failureCallback” will never be called and vice versa.


Example:


  1. local promise = Firecast.asyncOpenUserNDB("name");
  2.  
  3. promise:thenDo(
  4.     function(node)
  5.         -- This function will be called when/if the 
  6.         -- Promise is resolved successfully. The first argument, 
  7.         -- "node", contains the Promise success data, 
  8.         -- which in this case is an opened nodeDatabase
  9.     end,
  10.     
  11.     function(errorMsg)
  12.         -- This function will be called when/if the 
  13.         -- Promise is resolved to failure. The first argument, 
  14.         -- "errorMsg", contains the associated error message,
  15.         -- which in this case is the message explaining why
  16.         -- it was not possible to open the nodeDatabase
  17.     end);

promise:thenFinally(callback)

Set a continuation callback function that will be called when the Promise resolves, whether to success or failure.


Arguments:

  • callback - A function that will be called when the Promise resolves, regardless of the outcome. This function receives no parameters and will handle both success and failure cases.


Return:

  • A new Promise object that will be resolved asynchronously with the execution of the callback. This new promise can be used to chain promises handling.


Remarks:

  • Typically, this method is used to establish a finalization continuation that must be executed regardless of the promise outcome.
  • This will monitor the Promise for both success and failure states at the same time
  • If the Promise is already in a success state, the callback will be called as soon as possible. 
  • If the Promise is already in a failure state, the callback will be called as soon as possible
  • The callback will be called only once.

promise:thenResolve(promiseResolution)

Set a delegation that will resolve the provided PromiseResolution object with the same outcome (success or failure) as the original promise.


Arguments:


Return:

  • A new Promise object that will be resolved asynchronously along with the delegation. This new promise can be used to chain promises handling.


Remarks:

  • If the promise is already resolved, the PromiseResolution will be resolved as soon as possible.

promise:onError(failureCallback)

Set a continuation callback function that will be called when the Promise resolves to failure.


Arguments:

  • failureCallback - A function that will be called if the Promise resolves to failure. The first argument of the callback function will receive the error message.


Return:

  • A new Promise object that will be resolved asynchronously with the execution of failureCallback. This new promise can be used to chain promises handling.


Remarks:

  • If the Promise is already in a failure state, the failureCallback will be called as soon as possible


Example:


  1. local promise = Firecast.asyncOpenUserNDB("name");
  2.  
  3. promise:onError(
  4.     function(errorMsg)
  5.         -- This function will be called when/if the 
  6.         -- Promise is resolved to failure. The first argument, 
  7.         -- "errorMsg", contains the associated error message,
  8.         -- which in this case is the message explaining why
  9.         -- it was not possible to open the nodeDatabase
  10.     end);

Created with the Personal Edition of HelpNDoc: Qt Help documentation made easy