AppVenture has been updated

All articles have been rewritten and improved. You will be forwarded to the updated article.

Click here to go there directly.

Sat, 24 Oct 2015 #

The Swift Reflection API and what you can do with it

This post is also available in 🇨🇳Chinese Thanks to SwiftGG

Even though Swift stresses strong types, compile time safety, static dispatch it still offers a Reflection mechanism as part of the standard library. You may already have seen it in various blog posts or projects like here (Tuples), here (Midi Packets) or here (Core Data). Maybe you're interested in using in one of your projects, or you may want to better understand the problem domains on which reflection can be applied. This is an overview of the possibilities of the Swift Reflection API based a talk I held recently at the Macoun conference in Frankfurt, Germany.

1 API Overview

The best understanding of the topic can be achieved by having a look at the API to see what it offers us.

1.1 Mirrors

Swift's reflection capabilities are based around a struct called Mirror. You create a mirror for a particular subject and the mirror will then let you query it.

Before we do that, let's define a simple data structure that we can use as our subject.

import Foundation.NSURL

public class Store {
    let storesToDisk: Bool = true
}
public class BookmarkStore: Store {
    let itemCount: Int = 10
}
public struct Bookmark {
   enum Group {
      case Tech
      case News
   }
   private let store = {
       return BookmarkStore()
   }()
   let title: String?
   let url: NSURL
   let keywords: [String]
   let group: Group
}

let aBookmark = Bookmark(title: "Appventure", url: NSURL(string: "appventure.me")!, keywords: ["Swift", "iOS", "OSX"], group: .Tech)

1.2 Creating a Mirror

The easiest way of creating a mirror is the reflecting initializer:

public init(reflecting subject: Any)

Lets use it with our aBookmark struct:

let aMirror = Mirror(reflecting: aBookmark)
print(aMirror)
// prints : Mirror for Bookmark

So this creates a Mirror for Bookmark. As you can see, the type of the subject is Any. This is the most general type in Swift. Anything under the Swift Sun is at least of type Any 1. So this makes the mirror compatible with struct, class, enum, Tuple, Array, Dictionary, set, etc.

There are three additional initializers in the Mirror struct, however those are mostly used for circumstances where you'd want to provide your own, custom mirror. We will explain those additional initializers below when we discuss custom mirrors.

1.3 What's in a Mirror

The Mirror struct contains several types to help you identify the information you'd like to query.

The first one is the DisplayStyle enum which tells you the type of the subject:

public enum DisplayStyle {
    case Struct
    case Class
    case Enum
    case Tuple
    case Optional
    case Collection
    case Dictionary
    case Set
}

Those are the supported types of the reflection API. As we saw earlier, reflection only requires an Any type, and there're many things in the Swift standard library that are of type Any but aren't listed in the DisplayStyle enum above. What happens when you try to reflect over one of those, say a closure?

let closure = { (a: Int) -> Int in return a * 2 }
let aMirror = Mirror(reflecting: closure)

In this case, you'd get a mirror, but the DisplayStyle would be nil 2

There's also a typealias for the child elements of a Mirror:

public typealias Child = (label: String?, value: Any)

So each child consists out of an optional label and a value of type Any. Why would the label be an Optional? If you think about it, it makes sense, not all of the structures that are supported by reflection have children with names. A struct has the property's name as the label, but a Collection only has indexes, not names. Tuples are a little bit special. In Swift values in tuple could have optional labels. Doesn't matter if value in tupple is labeled or not, in reflection tuple will have labels ".0", ".1" and so on.

Next up is the AncestorRepresentation enum 3:

public enum AncestorRepresentation {
    /// Generate a default mirror for all ancestor classes.  This is the
    /// default behavior.
    case Generated
    /// Use the nearest ancestor's implementation of `customMirror()` to
    /// create a mirror for that ancestor.      
    case Customized(() -> Mirror)
    /// Suppress the representation of all ancestor classes.  The
    /// resulting `Mirror`'s `superclassMirror()` is `nil`.
    case Suppressed
}

This enum is used to define how superclasses of the reflected subject should be reflected. I.e. this is only used for subjects of type class. The default (as you can see) is that Swift generates an additional mirror for each superclass. However, if you need more flexibility here, you can use the AncestorRepresentation enum to define how superclasses are being mirrored. We will have a look at that further below.

1.4 How to use a Mirror

So we have our aMirror instance variable that reflects our aBookmark of type Bookmark subject. What do we do with it?

These are the available properties / methods on a Mirror:

  • let children: Children: The child elements of our subject
  • displayStyle: Mirror.DisplayStyle?: The display style of the subject
  • let subjectType: Any.Type : The type of the subject
  • func superclassMirror() -> Mirror?: The mirror of the subject's superclass

In the next step, we will analyze each of these.

1.4.1 displayStyle

This is easy. It will just return a case of the DisplayStyle enum. If you're trying to reflect over an unsupported type, you'll get an empty Optional back (as explained above).

print (aMirror.displayStyle)
// prints: Optional(Swift.Mirror.DisplayStyle.Struct)

1.4.2 children

This returns a AnyForwardCollection<Child> with all the children that the subject contains. Children are not limited to entries in an Array or Dictionary. All properties of a struct or class, for example, are also children returned by this property. The protocol AnyForwardCollection means that this is a collection type with indices that support forward traversal.

for case let (label?, value) in aMirror.children {
    print (label, value)
}
//prints:
//: store main.BookmarkStore
//: title Optional("Appventure")
//: url appventure.me
//: keywords ["Swift", "iOS", "OSX"]
//: group Tech

1.4.3 SubjectType

This is the type of the subject:

print(aMirror.subjectType)
//prints : Bookmark
print(Mirror(reflecting: 5).subjectType)
//prints : Int
print(Mirror(reflecting: "test").subjectType)
//prints : String
print(Mirror(reflecting: NSNull()).subjectType)
//print : NSNull

However, the Swift documentation has the following to say:

This type may differ from the subject's dynamic type when self is the superclassMirror() of another mirror.

1.4.4 SuperclassMirror

This is the mirror of the superclass of our subject. If the subject is not a class, this will be an empty Optional. If this is a class-based type, you'll get a new Mirror:

// try our struct
print(Mirror(reflecting: aBookmark).superclassMirror())
// prints: nil
// try a class
print(Mirror(reflecting: aBookmark.store).superclassMirror())
// prints: Optional(Mirror for Store)

2 Practical Example

2.1 Structs to Core Data

Imagine we're working at the newest, hot, tech startup: Books Bunny. We offer an Artificial Intelligence with a browser plugin that automatically analyses all the sites that the user visits and automatically bookmarks the relevant urls.

It's 2016, Swift is already open source, so our server backend is obviously written in Swift. Since we have millions of site visits active in our system at a time, we'd like to use structs for the analysis part of each site that a user visits. However, if our AI decides that this is worthy of a bookmark, we'd like to use CoreData to store this type in a database.

Now, we don't want to write custom serialization to Core Data code whenever we introduce a new struct. Rather, we'd like to develop this in a way so that we can utilize it for all future structs we develop.

So, how do we do that?

2.2 A Protocol

Remember, we have a struct and want to automatically convert this to NSManagedObject (Core Data).

If we want to support different structs or even types, we can implement this as a protocol and then make sure our desired types conform to it. So which functionality should our imaginary protocol offer?

  • First, it should allow us to define the name of the Core Data Entity that we want to create
  • Second, it should have a way to tell it to convert itself to an NSManagedObject

Our protocol could look something like this:

protocol StructDecoder {
    // The name of our Core Data Entity
    static var EntityName: String { get }
    // Return an NSManagedObject with our properties set
    func toCoreData(context: NSManagedObjectContext) throws -> NSManagedObject
}

The toCoreData method uses the new Swift 2.0 exception handling to throw an error, if the conversion fails. There're several possible error cases, which are outlined in the ErrorType enum below:

enum SerializationError: ErrorType {
    // We only support structs
    case StructRequired
    // The entity does not exist in the Core Data Model
    case UnknownEntity(name: String)
    // The provided type cannot be stored in core data
    case UnsupportedSubType(label: String?)
}

We have three error cases that our conversion has to look out for. The first one is that we're trying to apply it to something that is not a struct. The second is that the entity we're trying to create does not exist in our Core Data Model. The third is that we're trying to write something into Core Data which can not be stored there (i.e. an enum).

Let's create a struct and add protocol conformance:

2.3 Bookmark struct

struct Bookmark {
   let title: String
   let url: NSURL
   let pagerank: Int
   let created: NSDate
}

Next, we'd like to implement the toCoreData method.

2.4 Protocol Extension

We could, of course, write this anew for each struct, but that's a lot of work. Structs do not support inheritance, so we can't use a base class. However, we can use a protocol extension to extend to all conforming structs:

extension StructDecoder {
    func toCoreData(context: NSManagedObjectContext) throws -> NSManagedObject {
    }
}

As this extension is being applied to our conforming structs, this method will be called in the structs context. Thus, within the extension, self refers to the struct which we'd like to analyze.

So, the first step for us is to create an NSManagedObject into which we can then write the values from our Bookmark struct. How do we do that?

2.5 A Bit of Core Data

Core Data is a tad verbose, so in order to create an object, we need the following steps:

  1. Get the name of the entity which we'd like to create (as a string)
  2. Take the NSManagedObjectContext, and create an NSEntityDescription for our entity
  3. Create an NSManagedObject with this information.

When we implement this, we have:

// Get the name of the Core Data Entity
let entityName = self.dynamicType.EntityName

// Create the Entity Description
// The entity may not exist, so we're using a 'guard let' to throw 
// an error in case it does not exist in our core data model
guard let desc = NSEntityDescription.entityForName(entityName, inManagedObjectContext: context)
    else { throw UnknownEntity(name: entityName) }

// Create the NSManagedObject
let managedObject = NSManagedObject(entity: desc, insertIntoManagedObjectContext: context)

2.6 Implementing the Reflection

Next up, we'd like to use the Reflection API to read our bookmarks properties and write it into our NSManagedObject instance.

// Create a Mirror
let mirror = Mirror(reflecting: self)

// Make sure we're analyzing a struct
guard mirror.displayStyle == .Struct else { throw SerializationError.StructRequired }

We're making sure that this is indeed a struct by testing the displayStyle property.

So now we have a Mirror that allows us to read properties, and we have a NSManagedObject which we can set properties on. As the mirror offers a way to read all children, we can iterate over them and set the values. So let's do that.

for case let (label?, value) in mirror.children {
    managedObject.setValue(value, forKey: label)
}

Awesome. However, if we try to compile this, it will fail. The reason is that setValueForKey requires an object of type AnyObject?, however our children property only returns a tuple of type (String?, Any) - i.e. our value is of type Any but we need an AnyObject. To solve this, we have to test the value for AnyObject conformance. This also means that we can throw an error if we receive a property with a type that does not conform to AnyObject (such as an enum, for example).

let mirror = Mirror(reflecting: self)

guard mirror.displayStyle == .Struct 
  else { throw SerializationError.StructRequired }

for case let (label?, anyValue) in mirror.children {
    if let value = anyValue as? AnyObject {
	managedObject.setValue(child, forKey: label)
    } else {
	throw SerializationError.UnsupportedSubType(label: label)
    }
}

Now, our setValueForKey method will only be called if and only if the child is of type AnyObject.

Now, the only thing left to do is return our NSManagedObject. The complete code looks like this:

extension StructDecoder {
    func toCoreData(context: NSManagedObjectContext) throws -> NSManagedObject {
	let entityName = self.dynamicType.EntityName

	// Create the Entity Description
	guard let desc = NSEntityDescription.entityForName(entityName, inManagedObjectContext: context)
	    else { throw UnknownEntity(name: entityName) }

	// Create the NSManagedObject
	let managedObject = NSManagedObject(entity: desc, insertIntoManagedObjectContext: context)

	// Create a Mirror
	let mirror = Mirror(reflecting: self)

	// Make sure we're analyzing a struct
	guard mirror.displayStyle == .Struct else { throw SerializationError.StructRequired }

	for case let (label?, anyValue) in mirror.children {
	    if let value = anyValue as? AnyObject {
		managedObject.setValue(child, forKey: label)
	    } else {
		throw SerializationError.UnsupportedSubType(label: label)
	    }
	}

	return managedObject
    }
}

That's it. We're converting our struct to NSManagedObject.

3 Performance

So, how fast is this? Can this be used well in production? I did some testing:

Create 2000 NSManagedObjects

Native: 0.062 seconds
Reflection: 0.207 seconds

Native, here, means creating an NSManagedObject and setting the property values via setValueForKey. If you create a NSManagedObject subclass within Core Data and set the values directly on the properties (without the dynamic setValueForKey overhead) this is probably even faster.

So, as you can see, using reflection slows the whole process of creating NSManagedObjects down by about 3.5x. This is fine when you're using this for a limited amount of items, or when you don't have to care about speed. However, when you need to reflect over a huge amount of structs, this will probably kill your app's performance.

4 Custom Mirrors

As we already discussed earlier, there're other options creating a Mirror. This is useful, for example, if you need to customize just how much of your subject can be seen with a mirror. The Mirror Struct has additional initializers for this.

4.1 Collections

The first special init is tailor-made for collections:

public init<T, C : CollectionType where C.Generator.Element == Child>
  (_ subject: T, children: C, 
   displayStyle: Mirror.DisplayStyle? = default, 
   ancestorRepresentation: Mirror.AncestorRepresentation = default)

Compared to the init(reflecting:) initializer above, this one allows us to define much more details about the reflection process.

  • It only works for collections
  • We can set the subject to be reflected and the children of the subject (the collection contents)

4.2 Classes or Structs

The second can be used for a class or a struct.

public init<T>(_ subject: T, 
  children: DictionaryLiteral<String, Any>, 
  displayStyle: Mirror.DisplayStyle? = default, 
  ancestorRepresentation: Mirror.AncestorRepresentation = default)

Interesting to note, here, is that you provide the children (i.e. properties) of your subject as a DictionaryLiteral which is a bit like a dictionary only that it can be used directly as function parameters. If we implement this for our Bookmark struct, it looks like this:

extension Bookmark: CustomReflectable {
    func customMirror() -> Mirror {
	let children = DictionaryLiteral<String, Any>(dictionaryLiteral: 
	("title", self.title), ("pagerank", self.pagerank), 
	("url", self.url), ("created", self.created), 
	("keywords", self.keywords), ("group", self.group))

	return Mirror.init(Bookmark.self, children: children, 
	    displayStyle: Mirror.DisplayStyle.Struct, 
	    ancestorRepresentation:.Suppressed)
    }
}

If we do another performance measurement now, there's even a slight improvement:

Create 2000 NSManagedObjects

Native: 0.062 seconds
Reflection: 0.207 seconds
Reflection: 0.203 seconds

But hardly worth the effort, as it defeats our initial purpose of reflecting over our struct's members.

5 Use Cases

So, where does this leave us? What are good use cases for this? Obviously, if you're working a lot of NSManagedObject's, this will considerably slow down your code base. Also if you only have one or two structs, it is easier, more performant, and less magical if you simply write a serialization technique yourself with the domain knowledge of your individual struct.

Rather, the reflection technique showcased here can be used if you have many, complicated structs, and you'd like to store some of those sometimes.

Examples would be:

  • Setting Favorites
  • Storing Bookmarks
  • Staring Items
  • Keeping the last selection
  • Storing the ast open item across restarts
  • Temporary storage of items during specific processes.

Apart from that, of course, you can also use reflection for other use cases:

  • Iterate over tuples
  • Analyze classes
  • Runtime analysis of object conformance
  • Generated detailed logging / debugging information automatically (i.e. for externally generated objects)

6 Discussion

The Reflection API exists primarily as a tool for the Playgrounds. Objects conforming to the reflection API can easily be displayed in a hierarchical way in the playgrounds sidebar. Thus, the performance is not optimal. Nevertheless, this has still interesting use cases outside of playgrounds as we explained in the Use Cases chapter.

7 More Information

The source documentation of the Reflection API is very detailed. I'd encourage everyone to have a look at that as well.

Also, there's a much more exhaustive implementation of the techniques showcased here in the CoreValue project on GitHub which allows you to easily encode and decode from / to Structs to CoreData.

Footnotes:

1
In particular, Any is an empty protocol and everything implicitly conforms to this protocol
2
Or rather, an empty optional
3
I've shortened the documentation a bit

If you read this far, you should follow me (@terhechte)
on Twitter