[Development] async operation error guidance

[Tony Van Eerd]

Most of BlackBerry's APIs are async.
We are looking at moving some of these APIs into Qt.
Just as one  example, WiFi Direct.

I have been attempting to come up with some solid guidelines of how to deal with errors on async operations.

Some things to consider:

- the initial request may fail. ie

	WifiDirect::connectToDevice(someparams);

this could fail immediately if wifi is not on or various other reasons.  So does it return an error:

	ConnectError connectToDevice(SomeParams someparams);

or should even the immediate error be made async? 

It could also fail later, as it is mostly asynchronous. Or it could succeed with a result. ie

	Q_SIGNAL void deviceConntected(SomeDevice device);
	Q_SIGNAL void deviceConnectionFailed(SomeOtherConnectError error);

or one signal:

	Q_SIGNAL void deviceConnectionResult(SomeDevice device, ConnectionResult result);


Also consider that there are multiple async operations, not just 'connectToDevice'.  There is scan, startSession, etc.

Should there be a single error() covering everything?  Or one per task? Or a way to link the error back to the task?

	RequestId startSession();
	RequestId startScan();

	Q_SIGNAL void error(RequestId requestId, BigSetOfErrorEnums error, QString errorStringAsWellMaybe);



And there are a bunch more considerations. ie:

- "Error" vs "Result"  (I dislike Error::NoError, prefer Result::Success)
- Is "finished()" OK if it didn't _complete_ (successfully) or should it be... "ended()" or some better word?
- etc etc etc

For a "tl;dr" version, see the attached doc.

Thoughts greatly appreciated,
Tony

---------------------------------------------------------------------
This transmission (including any attachments) may contain confidential information, privileged material (including material protected by the solicitor-client or other applicable privileges), or constitute non-public information. Any use of this information by anyone other than the intended recipient is prohibited. If you have received this transmission in error, please immediately reply to the sender and delete this information from your system. Use, dissemination, distribution, or reproduction of this transmission by unintended recipients is not authorized and may be unlawful.
-------------- next part --------------
A non-text attachment was scrubbed...
Name: HowToReturnErrors.pdf
Type: application/pdf
Size: 40128 bytes
Desc: HowToReturnErrors.pdf
URL: <http://lists.qt-project.org/pipermail/development/attachments/20131105/8dfde3fb/attachment.pdf>