Choosing a Synchronous or Asynchronous coding style

Many calls to the SDK can return either a synchronous or an asynchronous response. This leads to a decision on how you wish to work based on priorities. All remote communication within the Singularity Database internally takes place asynchronously. Any updates are first made to the local cache of data, then asynchronously applied to the rest of the Singularity Database outside the SDK. When the remote request completes, a callback is made to the delegate you have implemented.

Synchronous

Working synchronously allows one to immediately act on data that has been updated. This, however, means that it is possible someone else is looking at the same data without the updates you just made (inconsistency). The Singularity Database is built on the concept of eventual consistency, meaning that all SDKs viewing or holding the same object will eventually be consistent. Additionally, if a request fails, requests dependent on the success of that request, that appear complete, will be rolled back.

Asynchronous

Working asynchronously means that the main thread may continue to work while there is a separate parallel thread delegate created that will wait for the response, process the response, and optionally make any follow up processing or hand over. This means that the applications you write on top of the SDK will be event-driven instead of being triggered by a main loop. The end user experience will be a user interface that is responsive and does not freese while waiting for a server response. Working this way guarantees everything presented to the end user has been propagated to the Singularity Database and will be what is retrieved if another client communicates with the database.

Pros and cons

With this SDK the developer is provided with sets of API with both Synchronous and Asynchronous variants of the calls that may communicate with the service in the cloud.

The Synchronous calls will be easier to use, but will freeze operations waiting for the cloud to respond. For a sequential program like a report or a sensor feeding data this is probably a good choise.

For a good interactive user experience in a user interface where multiple events happens in an unpredictable order, it is probably more desirable to write asynchronously on top of the SDK.

It is possible to mix Synchronous and Asynchronous calls in the same program.

Error handling

API calls have two possible outcomes: either success or error. The Synchronous API is provided in two variants that either uses exeptions or returns a result that can be of two types: either the error information or the expected result.

In the Asynchronous API the callback delegate needs to cater for both cases: success and error.