swift-mirror/docs/FailableInitializers.md

# Failable initializers

## Table of Contents

- [Lexicon](#lexicon)
- [Convenience initializers](#convenience-initializers)
- [Designated initializers](#designated-initializers)
- [Description of the problem](#description-of-the-problem)
- [Possible solutions](#possible-solutions)
- [Proposed solution -- pure Swift case](#proposed-solution----pure-swift-case)
- [Proposed solution -- Objective-C case](#proposed-solution----objective-c-case)
- [Implementation](#implementation)


A **failable initializer** can return early with an error, without
having initialized a new object. Examples can include initializers which
validate input arguments, or attempt to acquire a limited resource.

There are two types of failable initializers:

-   An initializer can be declared as having an optional return type, in
    which case it can signal failure by returning nil.
-   An initializer can be declared as throwing, in which case it can
    signal failure by throwing an error.

## Lexicon

Some terminology used below:

-   **deallocating** refers to freeing the memory of an object without
    running any destructors.
-   **releasing** refers to giving up a reference, which will result in
    running the destructor and deallocation of the object if this was
    the last reference.
-   A **destructor** is a Swift-generated entry point which call the
    user-defined deinitializer, then releases all stored properties.
-   A **deinitializer** is an optional user-defined entry point in a
    Swift class which handles any necessary cleanup beyond releasing
    stored properties.
-   A **slice** of an object is the set of stored properties defined in
    one particular class forming the superclass chain of the instance.


## Convenience initializers

Failing convenience initializers are the easy case, and are fully
supported now. The failure can occur either before or after the
`self.init()` delegation, and is handled as follows:

1.  A failure prior to the `self.init()` delegation is handled by
    deallocating the completely-uninitialized self value.
2.  A failure after the `self.init()` delegation is handled by releasing
    the fully-initialized self.value.

## Designated initializers

Failing designated initializers are more difficult, and are the subject
of this proposal.

Similarly to convenience initializers, designated initializers can fail
either before or after the `super.init()` delegation (or, for a root class
initializer, the first location where all stored properties become
initialized).

When failing after the `super.init()` delegation, we already have a
fully-initialized self value, so releasing the self value is sufficient.
The user-defined deinitializer, if any, is run in this case.

A failure prior to the `super.init()` delegation on the other hand will
leave us with a partially-initialized self value that must be
deallocated. We have to deinitialize any stored properties of self that
we initialized, but we do not invoke the user-defined deinitializer
method.

## Description of the problem

To illustrate, say we are constructing an instance of a class $C$, and let
$superclasses(C)$ be the sequence of superclasses, starting from $C$ and
ending at a root class $C_n$:

```math
superclasses(C) = {C, C_1, C_2, ..., C_n}
```

Suppose our failure occurs in the designated initializer for class $C_k$.
At this point, the self value looks like this:

1.  All stored properties in ${C, ..., C_(k-1)}$ have been
    initialized.
2.  Zero or more stored properties in $C_k$ have been initialized.
3.  The rest of the object ${C_(k+1), ..., C_n}$ is completely
    uninitialized.

In order to fail out of the constructor without leaking memory, we have
to destroy the initialized stored properties only without calling any
Swift deinit methods, then deallocate the object itself.

There is a further complication once we take Objective-C
interoperability into account. Objective-C classes can override `-alloc`,
to get the object from a memory pool, for example. Also, they can
override `-retain` and `-release` to implement their own reference counting.
This means that if our class has `@objc` ancestry, we have to release it
with `-release` even if it is partially initialized -- since this will
result in Swift destructors being called, they have to know to skip the
uninitialized parts of the object.

There is an issue we need to sort out, tracked by rdar://18720947.
Basically, if we haven't done the `super.init()`, is it safe to call
`-release`. The rest of this proposal assumes the answer is "yes".

## Possible solutions

One approach is to think of the `super.init()` delegation as having a
tri-state return value, instead of two-state:

1.  First failure case -- object is fully initialized
2.  Second failure case -- object is partially initialized
3.  Success

This is problematic because now the ownership conventions in the
initializer signature do not really describe the initializer's effect on
reference counts; we now that this special return value for the second
failure case, where the self value looks like it should have been
consumed but it wasn't.

It is also difficult to encode this tri-state return for throwing
initializers. One can imagine changing the try_apply and throw SIL
instructions to support returning a pair `(Error, AnyObject)` instead of a
single `Error`. But this would ripple changes throughout various SIL
analyses, and require IRGen to encode the pair return value in an
efficient way.

## Proposed solution -- pure Swift case

A simpler approach seems to be to introduce a new `partialDeinit` entry
point, referenced through a special kind of `SILDeclRef`. This entry point
is dispatched through the vtable and invoked using a standard
`class_method` sequence in SIL.

This entry point's job is to conditionally deinitialize stored
properties of the self value, without invoking the user-defined
deinitializer.

When a designated initializer for class $C_k$ fails prior to performing
the `super.init()` delegation, we emit the following code sequence:

1.  First, de-initialize any stored properties this initializer may
    have initialized.
2.  Second, invoke `partialDeinit(self, M)`, where `M` is the static
    metatype of $C_k$.

The `partialDeinit` entry point is implemented as follows:

1.  If the static self type of the entry point is not equal to `M`,
    first delegate to the superclass's `partialDeinit` entry point, then
    deinitialize all stored properties in $C_k$.
2.  If the static self type is equal to `M`, we have finished
    deinitializing the object, and we can now call a runtime function
    to deallocate it.

Note that we delegate to the superclass `partialDeinit` entry point before
doing our own deinitialization, to ensure that stored properties are
deinitialized in the reverse order in which they were initialized. This
might not matter.

Note that if even if a class does not have any failing initializers of
its own, it might delegate to a failing initializer in its superclass,
using `super.init!` or `try!`. It might be easiest to emit a
`partialDeinit` entry point for all classes, except those without any
stored properties.

## Proposed solution -- Objective-C case

As noted above, if the class has `@objc` ancestry, the interoperability
story becomes more complicated. In order to undo any custom logic
implemented in an Objective-C override of `-alloc` or `-retain`, we have
to free the partially-initialized object using `-release`.

To ensure we don't double-free any Swift stored properties, we will add
a new hidden stored property to each class that directly defines failing
initializers. The bit is set if this slice of the instance has been
initialized.

Note that unlike `partialDeinit`, if a class does not have failing
initializers, it does not need this bit, even if its initializer
delegates to a failing initializer in a superclass.

If the bit is clear, the destructor will skip the slice and not call the
user-defined `deinit` method, or delegate further up the chain. Note
that since newly-allocated Objective-C objects are zeroed out, the
initial state of this bit indicates the slice is not initialized.

The constructor will set the bit before delegating to `super.init()`.

If a destructor fails before delegating to `super.init()`, it will call
the `partialDeinit` entry point as before, but then, release the instance
instead of deallocating it.

A possible optimization would be not generate the bit if all stored
properties are POD, or retainable pointers. In the latter case, all zero
bits is a valid representation (all the `swift_retain`/`release entry`
points in the runtime check for null pointers, at least for now).
However, we do not have to do this optimization right away.

## Implementation

The bulk of this feature would be driven from DI. Right now, DI only
implements failing designated initializers in their full generality for
structs -- we already have logic for tracking which stored properties
have been initialized, but the rest of the support for the `partialDeinit`
entry point, as well as the Objective-C concerns needs to be fleshed
out.