I know it’s late, but I was wondering what the community thought of this:
MOTIVATION:
With the acceptance of SE-0112, the error handling picture looks much stronger for Swift 3, but there is still one area of awkwardness remaining, in the area of returns from asynchronous methods. Specifically, many asynchronous APIs in the Cocoa framework are declared like this:
- (void)doSomethingWithFoo: (Foo *)foo completionHandler: (void (^)(Bar * _Nullable, NSError * _Nullable))completionHandler;
This will get imported into Swift as something like this:
func doSomething(foo: Foo, completionHandler: (Bar?, Error?) -> ())
The intention of this API is that either the operation will succeed, and something will be passed in the Bar parameter, and the error will be nil, or else the operation will fail, and then the error parameter will be populated while the Bar parameter is nil. However, this intention is not expressed in the API, since the syntax leaves the possibility that both parameters could be nil, or that they could both be non-nil. This forces the developer to do needless and repetitive checks against a case which in practice shouldn’t occur, as below:
doSomething(foo: foo) { bar, error in
if let bar = bar {
// handle success case
} else if let error = error {
self.handleError(error)
} else {
self.handleError(NSCocoaError.FileReadUnknownError)
}
}
This results in the dreaded “untested code.”
Note that while it is possible that the developer could simply force-unwrap error in the failure case, this leaves the programs open to crashes in the case where a misbehaved API forgets to populate the error on failure, whereas some kind of default error would be more appropriate. The do/try/catch mechanism works around this by returning a generic _NilError in cases where this occurs.
PROPOSED SOLUTION:
Since the pattern for an async API that returns an error in the Cocoa APIs is very similar to the pattern for a synchronous one, we can handle it in a very similar way. To do this, we introduce a new Result enum type. We then bridge asynchronous Cocoa APIs to return this Result type instead of optional values. This more clearly expresses to the user the intent of the API.
In addition to clarifying many Cocoa interfaces, this will provide a standard format for asynchronous APIs that return errors, opening the way for these APIs to be seamlessly integrated into future asynchronous features added to Swift 4 and beyond, in a way that could seamlessly interact with the do/try/catch feature as well.
DETAILED DESIGN:
1. We introduce a Result type, which looks like this:
enum Result<T> {
case success(T)
case error(Error)
}
2. Methods that return one parameter asynchronously with an error are bridged like this:
func doSomething(foo: Foo, completionHandler: (Result<Bar>) -> ())
and are used like this:
doSomething(foo: foo) { result in
switch result {
case let .success(bar):
// handle success
case let .error(error):
self.handleError(error)
}
}
3. Methods that return multiple parameters asynchronously with an error are bridged using a tuple:
func doSomething(foo: Foo, completionHandler: (Result<(Bar, Baz)>) -> ())
and are used like this:
doSomething(foo: foo) { result in
switch result {
case let .success(bar, baz):
// handle success
case let .error(error):
self.handleError(error)
}
}
4. Methods that return only an error and nothing else are bridged as they are currently, with the exception of bridging NSError to Error as in SE-0112:
func doSomething(foo: Foo, completionHandler: (Error?) -> ())
and are used as they currently are:
doSomething(foo: foo) { error in
if let error = error {
// handle error
} else {
// handle success
}
}
5. For the case in part 2, the bridge works much like the do/try/catch mechanism. If the first parameter is non-nil, it is returned inside the .success case. If it is nil, then the error is returned inside the .error case if it is non-nil, and otherwise _NilError is returned in the .error case.
6. For the case in part 3, in which there are multiple return values, the same pattern is followed, with the exception that we introduce a new Objective-C annotation. I am provisionally naming this annotation NS_REQUIRED_RETURN_VALUE, but the developer team can of course rename this annotation to whatever they find appropriate. All parameters annotated with NS_REQUIRED RETURN_VALUE will be required to be non-nil in order to avoid triggering the error case. Parameters not annotated with NS_REQUIRED RETURN_VALUE will be inserted into the tuple as optionals. If there are no parameters annotated with NS_REQUIRED RETURN_VALUE, the first parameter will be implicitly annotated as such. This allows asynchronous APIs to continue to return optional secondary values if needed.
Thus, the following API:
- (void)doSomethingWithFoo: (Foo *)foo completionHandler: (void (^)(Bar * _Nullable NS_REQUIRED_RETURN_VALUE, Baz * _Nullable NS_REQUIRED_RETURN_VALUE, NSError * _Nullable))completionHandler;
is bridged as:
func doSomething(foo: Foo, completionHandler: (Result<(Bar, Baz)>) -> ())
returning .success only if both the Bar and Baz parameters are non-nil, whereas this API:
- (void)doSomethingWithFoo: (Foo *)foo completionHandler: (void (^)(Bar * _Nullable NS_REQUIRED_RETURN_VALUE, Baz * _Nullable, NSError * _Nullable))completionHandler;
is bridged as:
func doSomething(foo: Foo, completionHandler: (Result<(Bar, Baz?)>) -> ())
returning .success whenever the Bar parameter is nil. An API containing no parameter annotated with NS_REQUIRED_RETURN_VALUE will be bridged the same as above.
FUTURE DIRECTIONS:
In the future, an asynchronous API returning a Result could be bridged to an async function, should those be added in the future, using the semantics of the do/try/catch mechanism. The bridging would be additive, similarly to how Objective-C properties declared via manually written accessor methods can nonetheless be accessed via the dot syntax. Thus,
func doSomething(_ completionHandler: (Result<Foo>) -> ())
could be used as if it were declared like this:
async func doSomething() throws -> Foo
and could be used like so:
async func doSomethingBigger() {
do {
let foo = try await doSomething()
// do something with foo
} catch {
// handle the error
}
}
making asynchronous APIs convenient to write indeed.
ALTERNATIVES CONSIDERED:
Leaving the somewhat ambiguous situation as is.
Charles