Object Initialization

Warning

This document is incomplete and not up-to-date; it currently describes the initialization model from Swift 1.0.

Contents

Introduction
Initializers
Memory Safety
- Three-Phase Initialization
- Initializer Inheritance Model
Objective-C Interoperability

Introduction

Object initialization is the process by which a new object is allocated, its stored properties initialized, and any additional setup tasks are performed, including allowing its superclass's to perform their own initialization. Object teardown is the reverse process, performing teardown tasks, destroying stored properties, and eventually deallocating the object.

Initializers

An initializer is responsible for the initialization of an object. Initializers are introduced with the init keyword. For example:

class A {
  var i: Int
  var s: String

  init int(i: Int) string(s: String) {
    self.i = i
    self.s = s
    completeInit()
  }

  func completeInit() { /* ... */ }
}

Here, the class A has an initializer that accepts an Int and a String, and uses them to initialize its two stored properties, then calls another method to perform other initialization tasks. The initializer can be invoked by constructing a new A object:

var a = A(int: 17, string: "Seventeen")

The allocation of the new A object is implicit in the construction syntax, and cannot be separated from the call to the initializer.

Within an initializer, all of the stored properties must be initialized (via an assignment) before self can be used in any way. For example, the following would produce a compiler error:

init int(i: Int) string(s: String) {
  completeInit() // error: variable 'self.i' used before being initialized
  self.i = i
  self.s = s
}

A stored property with an initial value declared within the class is considered to be initialized at the beginning of the initializer. For example, the following is a valid initializer:

class A2 {
  var i: Int = 17
  var s: String = "Seventeen"

  init int(i: Int) string(s: String) {
    // okay: i and s are both initialized in the class
    completeInit()
  }

  func completeInit() { /* ... */ }
}

After all stored properties have been initialized, one is free to use self in any manner.

Designated Initializers

There are two kinds of initializers in Swift: designated initializers and convenience initializers. A designated initializer is responsible for the primary initialization of an object, including the initialization of any stored properties, chaining to one of its superclass's designated initializers via a super.init call (if there is a superclass), and performing any other initialization tasks, in that order. For example, consider a subclass B of A:

class B : A {
  var d: Double

  init int(i: Int) string(s: String) {
    self.d = Double(i)            // initialize stored properties
    super.init(int: i, string: s) // chain to superclass
    completeInitForB()            // perform other tasks
  }

  func completeInitForB() { /* ... */ }
}

Consider the following construction of an object of type B:

var b = B(int: 17, string: "Seventeen")

Note

Swift differs from many other languages in that it requires one to initialize stored properties before chaining to the superclass initializer. This is part of Swift's memory safety guarantee, and is discussed further in the section on Three-Phase Initialization.

Initialization proceeds in several steps:

An object of type B is allocated by the runtime.
B's initializer initializes the stored property d to 17.0.
B's initializer chains to A's initializer.
A's initializer initialize's the stored properties i and s'.
A's initializer calls completeInit(), then returns.
B's initializer calls completeInitForB(), then returns.

A class generally has a small number of designated initializers, which act as funnel points through which the object will be initialized. All of the designated initializers for a class must be written within the class definition itself, rather than in an extension, because the complete set of designated initializers is part of the interface contract with subclasses of a class.

The other, non-designated initializers of a class are called convenience initializers, which tend to provide additional initialization capabilities that are often more convenient for common tasks.

Convenience Initializers

A convenience initializer is an initializer that provides an alternative interface to the designated initializers of a class. A convenience initializer is denoted by the return type Self in the definition. Unlike designated initializers, convenience initializers can be defined either in the class definition itself or within an extension of the class. For example:

extension A {
  init() -> Self {
    self.init(int: 17, string: "Seventeen")
  }
}

A convenience initializer cannot initialize the stored properties of the class directly, nor can it invoke a superclass initializer via super.init. Rather, it must dispatch to another initializer using self.init, which is then responsible for initializing the object. A convenience initializer is not permitted to access self (or anything that depends on self, such as one of its properties) prior to the self.init call, although it may freely access self after self.init.

Convenience initializers and designated initializers can both be used to construct objects, using the same syntax. For example, the A initializer above can be used to build a new A object without any arguments:

var a2 = A() // uses convenience initializer

Initializer Inheritance

One of the primary benefits of convenience initializers is that they can be inherited by subclasses. Initializer inheritance eliminates the need to repeat common initialization code---such as initial values of stored properties not easily written in the class itself, or common registration tasks that occur during initialization---while using the same initialization syntax. For example, this allows a B object to be constructed with no arguments by using the inherited convenience initializer defined in the previous section:

var b2 = B()

Initialization proceeds as follows:

A B object is allocated by the runtime.
A's convenience initializer init() is invoked.
A's convenience initializer dispatches to init int:string: via the self.init call. This call dynamically resolves to B's designated initializer.
B's designated initializer initializes the stored property d to 17.0.
B's designated initializer chains to A's designated initializer.
A's designated initializer initialize's the stored properties i and s'.
A's designated initializer calls completeInit(), then returns.
B's designated initializer calls completeInitForB(), then returns.
A's convenience initializer returns.

Convenience initializers are only inherited under certain circumstances. Specifically, for a given subclass to inherit the convenience initializers of its superclass, the subclass must override each of the designated initializers of its superclass. For example B provides the initializer init int:string:, which overrides A's designated initializer init int:string: because the initializer name and parameters are the same. If we had some other subclass OtherB of A that did not provide such an override, it would not inherit A's convenience initializers:

class OtherB : A {
  var d: Double

  init int(i: Int) string(s: String) double(d: Double) {
    self.d = d                    // initialize stored properties
    super.init(int: i, string: s) // chain to superclass
  }
}

var ob = OtherB()   // error: A's convenience initializer init() not inherited

Note

The requirement that a subclass override all of the designated initializers of its superclass to enable initializer inheritance is crucial to Swift's memory safety model. See Initializer Inheritance Model for more information.

Note that a subclass may have different designated initializers from its superclass. This can occur in a number of ways. For example, the subclass might override one of its superclass's designated initializers with a convenience initializer:

class YetAnotherB : A {
  var d: Double

  init int(i: Int) string(s: String) -> Self {
    self.init(int: i, string: s, double: Double(i)) // dispatch
  }

  init int(i: Int) string(s: String) double(d: Double) {
    self.d = d                    // initialize stored properties
    super.init(int: i, string: s) // chain to superclass
  }
}

var yab = YetAnotherB()   // okay: YetAnotherB overrides all of A's designated initializers

In other cases, it's possible that the convenience initializers of the superclass simply can't be made to work, because the subclass initializers require additional information provided via a parameter that isn't present in the convenience initializers of the superclass:

class PickyB : A {
  var notEasy: NoEasyDefault

  init int(i: Int) string(s: String) notEasy(NoEasyDefault) {
    self.notEasy = notEasy
    super.init(int: i, string: s) // chain to superclass
  }
}

Here, PickyB has a stored property of a type NoEasyDefault that can't easily be given a default value: it has to be provided as a parameter to one of PickyB's initializers. Therefore, PickyB takes over responsibility for its own initialization, and none of A's convenience initializers will be inherited into PickyB.

Synthesized Initializers

When a particular class does not specify any designated initializers, the implementation will synthesize initializers for the class when all of the class's stored properties have initial values in the class. The form of the synthesized initializers depends on the superclass (if present).

When a superclass is present, the compiler synthesizes a new designated initializer in the subclass for each designated initializer of the superclass. For example, consider the following class C:

class C : B {
  var title: String = "Default Title"
}

The superclass B has a single designated initializer,:

init int(i: Int) string(s: String)

Therefore, the compiler synthesizes the following designated initializer in C, which chains to the corresponding designated initializer in the superclass:

init int(i: Int) string(s: String) {
  // title is already initialized in the class C
  super.init(int: i, string: s)
}

The result of this synthesis is that all designated initializers of the superclass are (automatically) overridden in the subclass, becoming designated initializers of the subclass as well. Therefore, any convenience initializers in the superclass are also inherited, allowing the subclass (C) to be constructed with the same initializers as the superclass (B):

var c1 = C(int: 17, string: "Seventeen")
var c2 = C()

When the class has no superclass, a default initializer (with no parameters) is implicitly defined:

class D {
  var title = "Default Title"

  /* implicitly defined */
  init() { }
}

var d = D() // uses implicitly-defined default initializer

Required Initializers

Objects are generally constructed with the construction syntax T(...) used in all of the examples above, where T is the name of the type. However, it is occasionally useful to construct an object for which the actual type is not known until runtime. For example, one might have a View class that expects to be initialized with a specific set of coordinates:

struct Rect {
  var origin: (Int, Int)
  var dimensions: (Int, Int)
}

class View {
  init frame(Rect) { /* initialize view */ }
}

The actual initialization of a subclass of View would then be performed at runtime, with the actual subclass being determined via some external file that describes the user interface. The actual instantiation of the object would use a type value:

func createView(viewClass: View.Type, frame: Rect) -> View {
  return viewClass(frame: frame) // error: 'init frame:' is not 'required'
}

The code above is invalid because there is no guarantee that a given subclass of View will have an initializer init frame:, because the subclass might have taken over its own initialization (as with PickyB, above). To require that all subclasses provide a particular initializer, use the required attribute as follows:

class View {
  @required init frame(Rect) {
    /* initialize view */
  }
}

func createView(viewClass: View.Type, frame: Rect) -> View {
  return viewClass(frame: frame) // okay
}

The required attribute allows the initializer to be used to construct an object of a dynamically-determined subclass, as in the createView method. It places the (transitive) requirement on all subclasses of View to provide an initializer init frame:. For example, the following Button subclass would produce an error:

class Button : View {
  // error: 'Button' does not provide required initializer 'init frame:'.
}

The fix is to implement the required initializer in Button:

class Button : View {
  @required init frame(Rect) { // okay: satisfies requirement
    super.init(frame: frame)
  }
}

Initializers in Protocols

Initializers may be declared within a protocol. For example:

protocol DefaultInitializable {
  init()
}

Note

Initializers in protocols have not yet been implemented. Stay tuned.

A class can satisfy this requirement by providing a required initializer. For example, only the first of the two following classes conforms to its protocol:

class DefInit : DefaultInitializable {
  @required init() { }
}

class AlmostDefInit : DefaultInitializable {
  init() { } // error: initializer used for protocol conformance must be 'required'
}

The required requirement ensures that all subclasses of the class declaring conformance to the protocol will also have the initializer, so they too will conform to the protocol. This allows one to construct objects given type values of protocol type:

func createAnyDefInit(typeVal: DefaultInitializable.Type) -> DefaultInitializable {
  return typeVal()
}

De-initializers

While initializers are responsible for setting up an object's state, de-initializers are responsible for tearing down that state. Most classes don't require a de-initializer, because Swift automatically releases all stored properties and calls to the superclass's de-initializer. However, if your class has allocated a resource that is not an object (say, a Unix file descriptor) or has registered itself during initialization, one can write a de-initializer using deinit:

class FileHandle {
  var fd: Int32

  init withFileDescriptor(fd: Int32) {
    self.fd = fd
  }

  deinit {
    close(fd)
  }
}

The statements within a de-initializer (here, the call to close) execute first, then the superclass's de-initializer is called. Finally, stored properties are released and the object is deallocated.

Methods Returning `Self`

A class method can have the special return type Self, which refers to the dynamic type of self. Such a method guarantees that it will return an object with the same dynamic type as self. One of the primary uses of the Self return type is for factory methods:

extension View {
  class func createView(frame: Rect) -> Self {
    return self(frame: frame)
  }
}

Note

The return type Self fulfills the same role as Objective-C's instancetype, although Swift provides stronger type checking for these methods.

Within the body of this class method, the implicit parameter self is a value with type View.Type, i.e., it's a type value for the class View or one of its subclasses. Therefore, the restrictions are the same as for any value of type View.Type: one can call other class methods and construct new objects using required initializers of the class, among other things. The result returned from such a method must be derived from the type of Self. For example, it cannot return a value of type View, because self might refer to some subclass of View.

Instance methods can also return Self. This is typically used to allow chaining of method calls by returning Self from each method, as in the builder pattern:

class DialogBuilder {
  func setTitle(title: String) -> Self {
    // set the title
    return self;
  }

  func setBounds(frame: Rect) -> Self {
    // set the bounds
    return self;
  }
}

var builder = DialogBuilder()
                .setTitle("Hello, World!")
                .setBounds(Rect(0, 0, 640, 480))

Memory Safety

Swift aims to provide memory safety by default, and much of the design of Swift's object initialization scheme is in service of that goal. This section describes the rationale for the design based on the memory-safety goals of the language.

Three-Phase Initialization

The three-phase initialization model used by Swift's initializers ensures that all stored properties get initialized before any code can make use of self. This is important uses of self---say, calling a method on self---could end up referring to stored properties before they are initialized. Consider the following Objective-C code, where instance variables are initialized after the call to the superclass initializer:

@interface A : NSObject
- (instancetype)init;
- (void)finishInit;
@end

@implementation A
- (instancetype)init {
  self = [super init];
  if (self) {
    [self finishInit];
  }
  return self;
}
@end

@interface B : A
@end

@implementation B {
  NSString *ivar;
}

- (instancetype)init {
  self = [super init];
  if (self) {
    self->ivar = @"Default name";
  }
  return self;
}

- (void) finishInit {
  NSLog(@"ivar has the value %@\n", self->ivar);
}
@end

Notes

In Objective-C, +alloc zero-initializes all of the instance variables, which gives them predictable behavior before the init method gets to initialize them. Given that Objective-C is fairly resilient to nil objects, this default behavior eliminates (or hides) many such initialization bugs. In Swift, however, the zero-initialized state is less likely to be valid, and the memory safety goals are stronger, so zero-initialization does not suffice.

When initializing a B object, the NSLog statement will print:

ivar has the value (null)

because -[B finishInit] executes before B has had a chance to initialize its instance variables. Swift initializers avoid this issue by splitting each initializer into three phases:

1. Initialize stored properties. In this phase, the compiler verifies that self is not used except when writing to the stored properties of the current class (not its superclasses!). Additionally, this initialization directly writes to the storage of the stored properties, and does not call any setter or willSet/didSet method. In this phase, it is not possible to read any of the stored properties.

2. Call to superclass initializer, if any. As with the first step, self cannot be accessed at all.

3. Perform any additional initialization tasks, which may call methods on self, access properties, and so on.

Note that, with this scheme, self cannot be used until the original class and all of its superclasses have initialized their stored properties, closing the memory safety hole.

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

ObjectInitialization.rst

ObjectInitialization.rst

Object Initialization

Introduction

Initializers

Designated Initializers

Convenience Initializers

Initializer Inheritance

Synthesized Initializers

Required Initializers

Initializers in Protocols

De-initializers

Methods Returning `Self`

Memory Safety

Three-Phase Initialization

Initializer Inheritance Model

Objective-C Interoperability

Initializers and Init Methods

Designated and Convenience Initializers

Allocation and Deallocation

Dynamic Subclassing

Files

ObjectInitialization.rst

Latest commit

History

ObjectInitialization.rst

File metadata and controls

Object Initialization