I haven’t written a Cocoa with Love article in 4 and a half years. What’s been happening? Is there anything new in Cocoa?

“Everything”, you say? Excellent! I should have plenty of new code to share.

But not in this article.

Previously on Cocoa with Love…

Cocoa with Love started as a place for me to write down some fun hacks I used for doing mischievous things in Cocoa – mostly abusing the Objective-C runtime. It’s fun to do things generally considered undocumented or impossible and Objective-C’s highly introspectible runtime let the devious programmer do much by hijacking other people’s code and subverting it. Of course, these sorts of actions are little more than cute tricks with few real use cases (they’re too risky, too high maintenance and there’s usually a non-devious way to achieve the same effect). I branched out in a number of different directions and even tried writing some articles about designing better apps, I primarily demonstrated a “business as usual” approach to app development and I’m not really happy with the overall result.

I’ve looked back through most of my old articles and many contain code that no longer compiles or code that’s completely superseded by newer APIs. Still more contain out-of-date information or worse: offer advice and opinions I no longer endorse.

I’m not planning to take the old articles down – people do still read them – but I’m not going to update or maintain them either. I’ve put a prominent “Reader beware” disclaimer on all of them to highlight that they should be viewed with appropriate caution. They’re doomed to become less relevant as Cocoa development continues to move towards Swift and away from Objective-C and that’s fine by me. I’d rather take the opportunity afforded by Swift and start fresh.

A new theme

Switching from Objective-C to Swift will be an obvious change as I return to Cocoa with Love but it’s not the only change. I’ve wanted to return to Cocoa with Love since before Swift’s announcement (it’s a long delayed 2014 New Year’s Resolution of mine) to try writing articles that loosely fit into a broad, overarching theme: writing maintainable Cocoa apps.

I realize that as a topic, “writing maintainable Cocoa apps” sounds like a good choice for boring people into a coma. Despite the banal connotations, maintenance is truly the hardest problem in app development and minimizing maintenance costs is a good way to make everything else in programming feel better.

The importance of maintenance is due to the fact that an app is never “done”. In most modern desktop and mobile spaces, update cycles for operating systems, devices – even device categories – are annual or faster. There is always a change that requires a corresponding update. At the same time, your app has its own update cycle because you want to advance its feature set. Sadly, the fundamental architecture of modern user-applications does not gracefully endure multiple refreshes. A typical codebase will grow progressively harder to maintain until after 2 to 3 years, you’re barely maintaining existing features, let alone adding new ones. If you can afford to double your developer resources, you’ll need to completely rewrite or thoroughly refactor otherwise the only option is app abandonment.

This situation is horrible: we invest months or years into projects and throw that work away on a regular basis.

A significant portion of this problem is due to the same code maintenance issues that affect all programming. Any programming project – not just user-applications – can suffer loss of momentum over successive releases due to haphazard implementation, poor original designs, difficulties refactoring code and other forms of “code rot”.

But the manifestation of maintenance difficulties affecting user-apps is particularly acute. Even fair implementations of adequately designed apps can rapidly grow unreasonably difficult to add features or update for new technologies and OS versions. User-applications, as a programming domain, have a high concentration of traits that most programming tries to avoid for the exact reason that they are difficult to maintain. Most prominent of these traits are:

• apps are inherently stateful
• controllers naturally subsume other components increasing coupling and fragility
• efforts to combat coupling lead to excessive layers of abstraction rather than cleaner code
• apps include many timing dependent behaviors including callbacks, asynchrony, animation and user events
• apps are heavily reliant on OS provided APIs, taking many things out of your direct control
• apps are difficult to test automatically

The cumulative result is that app programming, while not a technically difficult field, tends to create fragile webs of code that are highly interdependent along a number of different axes leading to programs that are easy enough to design initially but surprisingly time-consuming and expensive to maintain and update.

We need to write code that is resilient against regular code maintenance issues and at the same time, address the problems that undermine app maintenance in particular. Unless we do, every program we write is just another soon-to-be-abandoned app.

How do we improve “maintainability”?

If you’re savvy enough to reading this blog, then you’re doubtless aware that there are plenty of ideas around – technologies, frameworks, design patterns and programming techniques – that aim to limit the various negative traits that I listed as contributing to maintenance problems for user-applications.

• Some are applications of basic programming theory
• Some are lessons to avoid misusing development tools
• Some are as simple as better coding practices
• Some try to limit problems through evolved design patterns
• Some try to detect problems sooner through better testing approaches
• Some involve changing conventional thinking about errors, data, time or state
• Some involve pure functional, dataflow, declarative or other programming paradigms
• Some are frameworks that encapsulate a difficult trait throughout your program
• Some are frameworks that entirely replace the native application frameworks with alternatives

However, it’s interesting to consider though, that despite the number of techniques claiming to limit maintenance problems, none are universally considered essential for app development. Swift language notwithstanding, mainstream Cocoa app development is not dramatically different to NeXTSTEP development 20 years ago. Which leaves open the question: how many of these techniques – if any – actually succeed at their goals?

Conclusion

My aim with the “Swift era” of Cocoa with Love will be to look at different approaches to make app programming suck less. If we program with fewer runtime errors and our new features are easier to add, we’ll have more fun – even if “maintainability” sounds like a dull word.

For my first proper article since returning to Cocoa with Love, I want to talk about “partial functions” (functions with preconditions).

It’s an unusual topic for an app programming blog since, outside of API design or Design by Contract, preconditions are not widely discussed. This isn’t because our functions are precondition-free. Instead, it’s because we tend to test applications in such a narrow way that we never consider the entire range of values that can be passed to our functions. Our functions may have lots of implicit preconditions (including dependencies on broader program state) that we’ve never considered or that we never document (so are easy to violate during subsequent changes).

Ultimately, consideration of preconditions and how to avoid partial functions is the consideration of whether our programs work reliably across the whole range of possible scenarios.

Background: type requirements versus runtime expectations

Every function has two categories of requirements:

1. Type requirements: a function must accept arguments and return a result as specified by its type signature. The compiler enforces the type requirements, ensuring both caller and function meet the requirements.
2. Runtime expectations: a description of what the function will achieve by its conclusion. Ensuring runtime expectations are met is the role of the function’s programmer (and testing).

What happens when these two categories of requirements conflict?

Let’s consider a function that converts an Int to a Bool (those are the type requirements). Rather than use the C rule of 0 is false and anything else is true, this function will be strict: 0 is false and only 1 may be converted to true (that’s the runtime expectation).

functoBool(x:Int)->Bool{ifx==0{returnfalse}elseifx==1{returntrue}}

This function satisfies the runtime expectations: 0 becomes false and 1 becomes true but the compiler will highlight the closing } character with the error message:

Missing return in a function expected to return ‘Bool’

The compiler knows that we haven’t handled every possible value of x and the function can skip over the two if conditions and reach the end without returning a value (a violation of type requirements).

We could change the function to handle every possible value of x:

functoBool(x:Int)->Bool{ifx==0{returnfalse}returntrue}

but now we’re converting values like -1 to true in violation of the runtime expectations.

This is a conflict between type requirements and runtime expectations.

Background: preconditions

The conflict occurs because the runtime expectations imply an additional requirement that is not part of the type requirements. We call this additional requirement a precondition. In our simple toBool example, the precondition is that the value of x must be 0 or 1.

That’s simple enough to say but there’s a problem: the precondition isn’t known to the compiler so it is possible to accidentally violate the precondition at runtime. What should a function do if the precondition is not met?

The only safe option is to trigger a fatal error (abort the program).

This might not sound “safe” but it’s the only approach that prevents something potentially worse. If a function fails to meet runtime expectations and actually returns, this means anything dependent on the function is now in an indeterminate state. Once the program is in an indeterminate state, any branch could go the wrong way, any action could be wrong. Maybe toBool was trying to answer the question “Do you want to delete everything on your hard disk?” Maybe toBool was trying to determine if the program should exit a loop but now it’s stuck in the loop, allocating more memory until the whole computer grinds to a halt.

We also want to abort the program because it draws attention to the exact location where the programming error occurred – rather than forcing us to look at subsequent symptoms and try to trace the symptoms back to where the program went awry. A fatal error simplifies debugging and ensures that when an error occurs, it’s likely to be caught and reported.

Background: preconditions in Swift

So we need to enforce the precondition by triggering a fatal error if it is not satisfied. Swift has a function named precondition which, unsurprisingly, does exactly that: tests a condition and triggers a fatal error if the condition is false. Our function then becomes:

functoBool(x:Int)->Bool{precondition(x==0||x==1,"This function can only convert 0 or 1 to Bool")ifx==0{returnfalse}/* x == 1 */returntrue}

Terminology note: I’ll refer to the precondition function for most of this article (since its role is unambiguous) but numerous other functions may be similarly used to directly (or indirectly, though a child funcion) trigger a fatal error including assert, assertionFailure, precondition, preconditionFailure, fatalError or other standard library functions that use “trap” intrinsics like Builtin.int_trap or Builtin.condfail.

Now, all of this might seem a little obstinate. I’ve deliberately chosen type requirements and runtime expectations that conflict and I’ve refused to change either, forcing the use of precondition. You might think no one would ever design a function this way of that you’d never use a function like this.

The reality is that nearly every Swift program uses this type of function indirectly through Swift standard library functions that contain similar precondition checks. Most common in Swift are the Array subcript operator (which has a precondition that the index be in-bounds), the force-unwrap operator ! on the Swift Optional type (which has a precondition that self be non-nil), any use of the ImplicitlyUnwrappedOptional type (which similarly has a precondition that self be non-nil) and the default integer operators and conversions (which trigger fatal errors on overflow).

There’s another kind of precondition you may have in your code: functions that may misbehave, non-fatally, when certain implicit, unchecked requirements are not met. This is an extremely difficult point to keep under control but you need to consider whether any of your functions have implicit, unchecked requirements and add precondition checks to document the requirements and ensure that you don’t accidentally violate them in the future.

Partial functions

A precondition is used to enforce the requirement that a function may be invoked only for a partial subset of the total set of values that would be valid according to the function’s type signature. That leads us to the mathematical term “partial function”.

The next paragraph is going to be math jargon. It’s important to use the correct terminology. It’s not so bad; hold your breath if you’d like.

In mathematics, a partial function is a function constructed to map values from a domain (set of possible input values) to a codomain (set of possible output values) where the function is undefined (no appropriate mapping exists) for one or more values in the input domain. The subset of inputs values where the partial function is actually defined is called the domain of definition. Functions that are defined for all possible inputs are called total functions.

A simple example of a partial function in mathematics is division. A mathematical function that divides 5 by any real number:

is undefined for x = 0 because there is no sensible way to divide by zero in typical mathematics.

If implemented in Swift, due to the “undefined” case, we use precondition to enforce the requirement that the function may be invoked only within the “domain of definition”:

funcdivideFiveBy(x:Real)->Real{precondition(x!=0)return5/x}

Hidden partial functions

Now there isn’t a Real type in the Swift standard library. We do have Double but Swift’s Double doesn’t actually work this way (see “Change the behavior” below). However, Swift does work this way if we swap Int for Real:

funcdivideFiveBy(x:Int)->Int{return5/x}

Where did the precondition go? It’s still there. We don’t need to write precondition because it’s part of the / operator. The infix / operator for Int uses “checked” division in Swift (implemented in the standard library as _overflowChecked) so it will trigger a fatal error if it is invoked with 0 as its second argument. This occurs because the Int type in Swift, as with ℝ (reals) in the math example above, has no sensible way to handle division by zero.

The following is another example of a partial function because it may trigger a fatal error based on the value of parameter someArrayIndex:

funcsomeArrayFunction(someArrayIndex:Int)->Element{returnmyArray[someArrayIndex]}

And so is this, since it may trigger a fatal error based on the state of self:

structsomeStructWithAnOptionalMember{varoptionalSomeType:SomeType?funcaccessor()->SomeType{returnoptionalSomeType!}}

The problem with partial functions

How did I know that the infix / operator for Int uses “checked” division in Swift and will cause a fatal error if it is invoked with 0 as its second argument?

The only way to know is to check the documentation. The Swift Programming Language describes the requirements of division as:

arithmetic operators in Swift do not overflow by default. Overflow behavior is trapped and reported as an error.

It’s up to the reader to either know (or experiment and find out) that this means that the division operator will write a failure message to standard out and abort the program if you ever pass 0 as the second argument to integer division.

This makes partial functions terrifyingly dependent on documentation and testing (two areas worryingly prone to lapses):

1. A partial function’s requirements must be clearly documented
2. Users of the function must read and understand the documentation
3. Tests must exercise a wide range to confirm usage remains correctly inside required bounds in all cases

Let’s assume points 1 and 2 are satisfied (or at least noticed during debugging). We still need to satisfy point 3.

Unfortunately: debugging and testing are unlikely to check all scenarios in a non-trivial program. Debugging and testing excel at validating specific scenarios but unless your tests are extremely thorough, it’s likely your users will be able to get one of your functions into a state you never tested. If your program uses partial functions, this leaves you expsed to potential runtime failure.

Avoid partial functions and use total functions instead

Partial functions should be avoided because:

• they have requirements that the compiler cannot verify
• they can pass your testing but still cause fatal errors after deployment if different data is encountered

Let me be clear: it is not the checking of preconditions that should be avoided. Absolutely, if your function has preconditions, you should check them immediately or face rendering your program “indeterminate”.

The problem is the existence of preconditions.

A function is partial if it has preconditions. We want to design our functions as “total functions” that have no preconditions. This means that we need a sensible result for every possible input value.

Let’s revisting the mathematical function that divides 5 by any real number. Previously we defined it as a partial function that was undefined for x = 0. Let’s write it as a total function:

To explain this in a more programmer-friendly way: we’ve changed the type signature of the function. Instead of accepting any “Real” as an input, I’ve defined a new type X that can be any value in the Reals except zero. Now, the function is defined for every possible value in X and the function is a total function.

A rough equivalent in Swift would be:

structNonZeroInt{letvalue:Intinit?(fromInt:Int){guardfromInt!=0else{returnnil}value=fromInt}}funcdivideFiveBy(x:NonZeroInt)->Int{return5/x.value}

The runtime requirement in divideFiveBy is gone and instead we have a new type, NonZeroInt that satisfies the requirement at compile-time.

You might be able to see why I mentioned, above, that it’s important to think about precondition as subtracting values from the total set of valid values according to the type signature. We can avoid a precondition by defining a new type where those precondition-excluded-values are avoided by design in the new type.

Failable construction, non-failable usage

In the previous example, we created a new type, NonZeroInt, but the constructor for this new type can fail (return a nil instead of a value). In some sense, we’ve simply taken the burden of ensuring correctness from the call location of divideFiveBy and put it somewhere else. However, this change has helped for two reasons:

1. the compiler will ensure that we check the NonZeroInt?(fromInt:) return result
2. we’re validating the value at its construction, not when it is used

The first point stops the function being a partial function but the second point is just as interesting.

Ideally, we shouldn’t construct NonZeroInt from an Int immediately before passing into divideFiveBy, instead we should never have the Int at all; the NonZeroInt should be constructed at the source. Maybe the source is a settings file, maybe the source is user-input, maybe the source is a network connection; in any case, as soon as the value comes into existence, we immediately know if it’s valid or invalid. In the invalid case, we can report the input as the source of the problem. This is a huge improvement over carrying an invalid 0 value Int for an unknown time until it is finally passed to the function divideFiveBy which has no idea about the origin of its parameters.

Think about the path of data through your program as a pipeline: if your data won’t fit through the whole pipeline, reject it at the start rather than letting it cause problems in the middle. Ideally, construction should be the only scenario that can fail and every use case should be a “total function”.

Other approaches for avoiding partial functions

Avoiding a partial function involves making the type requirements and the runtime expectations agree.

Defining a new, more specific type that encapsulates the runtime expectations’ complete requirements for the data is the conceptually best approach to addressing the problem. As I explained, it pushes any checks on data back to the construction point which is the best place to handle error conditions.

However, there are plenty of cases where it’s not the most practical option:

• it may be algorithmically difficult to determine the constraints for the data ahead-of-time
• you might not have access at construction-time to state information required to check validity
• maybe you don’t have control over the design of earlier stages in the data pipeline
• maybe you construct data in a lot of places but only use it in one place so it’s simpler to change the usage location instead of the construction location

Fortunately, there are plenty of other options.

Change the return type

The simplest solution to making any partial function into a total function is to change the type signature to include room in the return type to communicate a failure condition. Instead of needing to trigger a fatal error, we can communicate the condition back to the caller and the caller can choose how to handle the result.

Swift’s Optional is ideal for this as we can show with our toBool function:

functoBool(x:Int)->Bool?{switchx{case0:returnfalsecase1:returntruedefault:nil}}

An example of this in the Swift standard library is the subscript operator on Dictionary. Unlike the subscript on Array, the Dictionary version returns an Element?. This means that you are allowed to look up a key that doesn’t exist.

I personally like to use the following extension on CollectionType to allow this type of Optional returning access for Array or other CollectionTypes:

extensionCollectionType{/// Returns the element at the specified index iff it is within bounds, otherwise nil.publicfuncat(index:Index)->Generator.Element?{returnindices.contains(index)?self[index]:nil}}

The name at in this case is borrowed from a function in C++ that accesses the value if it exists or throws an exception if it does not. A Swift throws function would be closer to the C++ implementation but returning an Optional is more in line with the pattern established by Dictionary and is syntactically tighter for this use-case.

However, using Swift’s error handling mechanism is also a valid way of making a function total, if you’d prefer it:

enumArtithmeticError{caseDivideByZero}funcdivideFiveBy(x:Int)throws->Int{switchx{case0:throwArtithmeticError.DivideByZerodefault:return5/x}}

In Objective-C, exceptions were (usually) used to indicate unrecoverable situations (i.e. partial functions). However, Swift errors are meant to be caught; in fact they must be caught. Therefore throwing an error in Swift is really just offering a different return type – semantically similar to returning an Optional despite the syntactic differences.

Change the behavior

Depending on context, it might make sense to change the runtime expectations so that every input is mapped to a valid output. This is

As I mentioned in the beginning, if we had used the C language’s definition of a Bool (anything that isn’t zero is true) then our toBool function would never have needed a precondition.

We can also change the behavior of the divideFiveBy function to do something not-entirely-accurate but which may be valid, depending on expected usage:

funcdivideFiveBy(x:Int)->Int{switchx{case0:returnInt.maxdefault:return5/x}}

This mirrors the Swift standard library’s division operator for Double:

funcdivideFiveBy(x:Double)->Double{return5/x}

Unlike the version from Int to Int, this function is a total function, not a partial function.

The / operator for Double will return Double.infinity (IEEE 754 “positive infinity”) if invoked with x == 0 which isn’t really true in a mathematical sense but is sufficient that you can work out what happened. Of course, the problem with this type of behavior change is that it might obscure the “basically an error” status of the result (for example: you should be handling the zero denominator rather than attempting to scale a drawing by “+infinity”).

Keep dependent components together

A common reason for partial functions is that you’re using two pieces of data that need to agree with each other (like an Array and a subscript index) but you create and store them separately so they are not naturally kept in agreement – they might even be created separately and could be out of agreement from their construction.

We can avoid preconditions on separate data being in sync by holding the required data in a single data structure that ensures the requirement.

The following alternative approach to indexes into an Array ensures the index remains valid at all times by keeping a reference to the Array and preventing transformations to the index that would make it invalid.

enumAlwaysValidArrayIndexError:ErrorType{caseNoAcceptableIndex}structAlwaysValidArrayIndex<T>{// Store the indexvarindex:Int// Together with the arrayletarray:Array<T>// Construction gives the first index in the array (or throws if the array is empty)init(firstIndexInArraya:Array<T>)throws{guard!a.isEmptyelse{throwAlwaysValidArrayIndexError.NoAcceptableIndex}array=aindex=array.startIndex}// Only allow the index to be advanced if there's somewhere to advancemutatingfuncadvance()throws{guardarray.count>indexelse{throwAlwaysValidArrayIndexError.NoAcceptableIndex}index+=1}// We can deference using the index alone since the array is held internallyfuncelementAtIndex()->T{returnarray[index]}}

This might seem like a strange thing to do but it’s similar to how Swift String indexes advance safely. With a StringString.CharacterView.Index, you’re required to construct the index from a String.startIndex and the index stores the string’s internal _StringCore storage with it so that it can iterate correctly over the Unicode grapheme clusters, keeping the index valid.

Minor aside/complaint about how Swift String indexes work

Sadly, despite storing the _StringCore internally and therefore being able to ensure validity at all times, String indexes let you hit fatal errors by advancing past the end (rather than a more graceful nil) and even worse: don’t themselves access characters but instead need to be passed back into the subscript on a String. This second problem lets the String.CharacterView.Index and String be out-of-sync again (since you can use an index from one String on a different String), leading to potential fatal errors (for out-of-range accesses) or invalid Unicode as produced by this example where an index from “Unrelated string” is used to access an invalid offset in an Emoji string:

print("👿👿"["Unrelated string".startIndex.advancedBy(1)])// Output will not be the 'n' in "Unrelated" or the second "Imp" Emoji.// Instead we get the Unicode invalid character marker '�'.

I hope these problems are addressed in future changes to the Swift standard library (even a basic precondition failure when using indexes with the wrong string would be preferrable).

Change the design

A final way to avoid partial functions is to avoid design patterns where they are common. This means: use the library functions and features that are total functions. If we restrict our programming to total functions then our functions are more likely to be total functions too.

Easy examples include using for x in, map and filter to perform most of the needed work on an Array without using the subscript. Similarly as an alternative to Optional’s force unwrap, you can always use if let, switch and flatMap and avoid any potential fatal errors.

What are the reasons for writing partial functions?

I’ve used a lot of words to say “partial functions are bad”. I also shown multiple ways to avoid them.

Why do partial functions exist at all? There’s a few reasons. I don’t agree with them all.

Aesthetics

The biggest reason for partial functions is aesthetics: the interface designer didn’t really want to define a new type, return an Optional or declare a function as throws.

To illustrate this claim, there’s a number of partial functions in the Swift standard library that are designed to look like traditional operators from C while transparently adding safety checks where memory unsafe behavior could have occurred in C. This includes Array subscripts, ImplicitlyUnwrappedOptional and overflowable arithmetic; these are designed to look like their C equivalents while applying runtime checks internally. There’s a historical/social expectation: people expect an array index to return a non-Optional. People expect that they can forcibly unwrap Optional if they want. People don’t want the syntactic overhead of dealing with overflows for most arithmetic.

The choice to use precondition rather than return an Optional (or another alternative) is risky and crash prone but that’s how humans work sometimes.

Internal functions with simple conditions

Preconditions involving multiple values being in-sync or methods on an object being invoked in a given order take additional work to avoid. For our internal functions – where we are the only people who need to learn and obey any preconditions – the amount of work to avoid the precondition might not be worth the effort, particularly if the precondition is simple and obvious and we’re sure we won’t accidentally violate it.

Just make certain to use precondition to explicitly check, rather than run the risk of accidentally violating the precondition later.

Method overrides

If an overrideable method is required by the superclass to do something (e.g. invoke super), we often need to rely on precondition or other similar tests to ensure the requirement occurs.

This is really a limitation of how object-oriented programming composes interfaces: subclasses are fully in control and the superclass only receives control when the subclass yields it. If the superclass wants to place requirements on the subclass, it can only do that checking the requirement after-the-fact (a “postcondition” but technically still implemented using precondition).

Effectively unreachable code paths

The actual conditions required to reach some code paths are so convoluted that they’re basically unreachable. This sometimes occurs when checking the results of functions: we feel obliged to check all error results but we might not be able to design a test case to actually reach the failure path. Rather than write a recovery attempter that we can’t test, we may place a preconditionFailure or a fatalError in the path to confirm out belief that the branch is unreachable.

Examples where this is appropriate include handling memory allocation failure return paths from certain C functions. On a modern system, a memory allocation failure is usually impossible (the OS will kill the process before malloc fails) so writing code to test and handle this situation is a poor use of our time.

Forced correctness

In some cases interface designers want haphazard users of their functions to see failures. There’s an argument that programming defensively against careless users of your function encourages poor programming and prevents users understanding what they’re doing wrong; instead, we should force bad programmers to confront their mistakes.

I think this argument is more valid in languages like C where returning an int error condition is frequently ignored by the user so a fatal error is more attention grabbing. In Swift, I think this approach is inappropriate. Users can’t ignore Optional or throws in Swift and will learn their mistakes from a returned “invalid argument” ErrorType just as well as they’d learn from a precondition failure – in fact, better, since users might not be aware of the existence of possible precondition failures but the syntactic overhead for throws is unavoidable so it’s possible that a never-before-seen failure will still be handled correctly at runtime.

Truly haphazard programmers are likely to handle Optional and throws results by using force-unwrap or try! in Swift so they’re going to see fatal errors anyway.

Logic tests

The assert function is commonly used to test “soft” postconditions (where a false result is not a critical failure) and other program logic.

If you’re unaware, assert works like precondition in Debug builds (compiled with ‘-Onone’) but does nothing in Release builds (compiled with ‘-O’). This split behavior complicates the practical implications but ultimately assert is still used to fatally test conditions in Debug builds so its usage in a function is still equivalent to a partial function.

Ultimately, assert treads a weird line between a precondition that isn’t properly tested in Release builds (leaving you open to indeterminate behavior) and a logic test that should be in your testing code and not in your regular code.

I personally think assert is a good idea only when a precondition is too computationally onorous to run at Release. In all other cases, you should be using precondition (because you really do want the condition to be true) or you should move the testing into your test code (because it’s not truly a precondition and you’re just validating behavior in a specific case).

Conclusion

A function with one or more preconditions is a partial function (valid for only a subset of the values implied by the type signature). Each precondition represents a potential programmer error you can make when using the partial function. Unlike type requirements (where programmer errors get caught at compile time) precondition programmer errors manifest as a fatal errors at runtime.

Fatal errors are obviously bad and you can avoid them by avoiding partial functions.

Do not avoid a partial function by failing to check preconditions. Boldface for a reason: that’s worse than a crash. Failing to check preconditions results in indeterminate behavior that can let misbehavior propagate, potentially leading to “worst case” scenarios. It also impedes debugging and allows misbehaviors to persist rather than being quickly caught. If your function has requirements, check them!

Instead, we can avoid partial functions by fixing our design to eliminate preconditions.

Preconditions are required only because there are values permitted by the type requirements that cannot meet the runtime expectations. If you fix the type requirements (choose input types where every value can meet the runtime expectations) or change the runtime expectations (to handle every value in the type requirements) there’s no need for preconditions.

This can be as simple as returning an Optional instead of a simple value. Or defining an input type that validates requirements on construction (returning nil if the requirements can’t be met). Given Swift’s syntactically efficient conditional unwrapping operators and error handling capabilities, the cost of handling lots of these types of conditionals is quite low so partial functions should be a very rare thing.

Despite all this, partial functions do exist. There are some narrow cases where they are necessary and some other situations where they’re commonly used. And due to their use in the Swift standard library, almost all Swift programs use partial functions in some form so you need to be aware of them.

For these reasons, you might even decide to create partial functions of your own. In the next post, I’ll look at testing partial functions by catching precondition failures so you can ensure any partial functions you create will trigger fatal errors correctly as expected.

In the previous post, I discussed “partial functions” and advised against them. As stated in that article though, there are situations where partial functions are necessary or expected. If you’re going to write a partial function, you need to test it and that means testing a precondition failure occurs when the requirement is violated.

One problem: precondition failures crash the xctest harness making testing annoying. In this article, I’m going to show a Mach exception handler that catches these crashes and rewrites the application’s state as though an Objective-C exception was raised instead, making precondition failures testable.

Background

A precondition failure is implemented in the Swift standard library as a Builtin.int_trap() which is ultimately compiled as a ud2 instruction on i386/x86-64 platforms. This instruction exists for the sole purpose of triggering an “invalid opcode” which will be caught by the operating system, leading to a Mach EXC_BAD_INSTRUCTION exception at runtime.

Using only Swift language and standard library features, there’s no way to recover from a precondition failure.

Traditional approaches to this type of situation involve running the code in a child process and monitoring crashes from the parent or using build configurations to swap the fatal error with something more catchable.

Mach exception handlers provide a different approach. With a Mach exception handler the operating system gives us a chance to respond to the Mach exception and we can use that chance to rewrite our application’s history as though the ud2 instruction never happened.

Tests first

What we need is a function named catchBadInstruction that satisfies the following test:

functestCatchBadInstruction(){#if arch(x86_64)// Test catching an assertion failurevarreachedPoint1=falsevarreachedPoint2=falseletexception1:BadInstructionException?=catchBadInstruction{// Must invoke this blockreachedPoint1=true// Fatal error raisedprecondition(false,"EXC_BAD_INSTRUCTION raised here")// Exception must be thrown so that this point is never reachedreachedPoint2=true}// We must get a valid BadInstructionExceptionXCTAssert(exception1!=nil)XCTAssert(reachedPoint1)XCTAssert(!reachedPoint2)// Test without catching an assertion failurevarreachedPoint3=falseletexception2:BadInstructionException?=catchBadInstruction{// Must invoke this blockreachedPoint3=true}// We must not get a BadInstructionException without an assertionXCTAssert(reachedPoint3)XCTAssert(exception2==nil)#endif}

The catchBadInstruction function runs the closure passed to it. If any Mach EXC_BAD_INSTRUCTION exceptions occur, this function catches the Mach exception, creates an instance of BadInstructionException (a subclass of NSException), raises that exception at the point where the EXC_BAD_INSTRUCTION occurred and then catches the BadInstructionException outside the child closure. The BadInstructionException raised, if any, is returned.

This catchBadInstruction function will catch any of the Swift fatal error aborts, including assert, assertionFailure, precondition, preconditionFailure, fatalError. By catching these failures, we can test that functions required to raise assertions for particular combinations of inputs are being applied correctly.

This code will also catch other unrelated sources of Mach EXC_BAD_INSTRUCTION exceptions but they’re extremely rare unless your binary is corrupted (not a serious possibility in the testing scenarios to which this code should be limited).

A list of serious caveats

I have tagged this article with the tag ‘hacks’. I intend this tag to communicate that the code in this post does some clever things but the result is well outside the bounds of what safe, maintainable programs should do. Let me be clear: there’s no good reason to run this code in your deployment builds. This code is intended for testing, exclusively.

One of the simplest things this code does is also the least usable in a deployed program: throwing and catching an Objective-C exception over your Swift code. Even in Objective-C, exceptions are usually unsafe unless you’re extremely careful. The situation is worse in Swift since we can no longer ask the compiler to generate exception-safe automatic reference counting. A few memory leaks will almost certainly occur and other code may misbehave due to interrupted side effects or partial construction. It’s up to you to minimize these problems if they surround precondition failures that you need to test. Under test conditions, this is usually a manageable problem.

Installing multiple Mach exception handlers may create complications. I’ve not tested multiple, nested or otherwise conflicting Mach exception handlers and I’m not convinced the exception handler will play well with other handlers installed on the same thread. This is all outside the “testing, exclusively” use-case so just don’t do it.

There’s also something you might have noticed in the test code: it will only run on arch(x86_64). The code will run in the iOS/watchOS/tvOS simulators and natively on the Mac but it will not run on iOS/watchOS/tvOS devices. This is because the API for catching Mach exceptions is not public in these SDKs. Landon Fuller mentioned in 2013 that he had filed a radar with Apple requesting the required interfaces on iOS but nothing has come of it. I can only assume this isn’t going to change.

If you’re using open source Swift on Linux, Mach exceptions and the Objective-C runtime aren’t available. The code in this post will not work. You could probably do something similar with a POSIX SIGILL signal handler and setjmp/longjmp.

Trying to write a Mach exception handler

Writing this code was considerably harder for me than it ideally should have been. For whatever reason, Apple don’t document Mach exception handling. They don’t conceal its existence and the “mach_exc.defs” file is public API on OS X but there’s nothing in the Xcode documentation reference, man pages or on Apple’s website beyond the definitions file itself.

Making matters worse, the examples and documentation you can easily find on third-party web sites are usually for the 32-bit version of Mach exceptions which uses slightly different functions and requires slightly different parameters. When you do find examples of 64-bit Mach exception handling (like that in plcrashreporter, lldb or gdb) it’s normally catching exceptions for the whole program rather than a specific thread or for catching from another process.

I eventually got through it with a basic trial-and-error approach but it was really slow going due to the ease of writing code that appeared to succeed but did nothing useful because the mach_port_t was configured using flags only valid in 32-bit.

There’s no simple C interface for processing Mach messages. Instead, you get a “MiG” (Mach Interface Generator) file and you’re expected to generate a C interface from that. Interface generators are normally used when it’s possible to generate interfaces for multiple languages. Okay, so can I generate a Swift interface? No, you can only generate a C interface. So why do I need to generate the interface at all? Why isn’t the implementation in a library with a basic C interface provided? I don’t know.

Then the generated interface expects to call into C functions in your code with specific type signatures. Here we run into a Swift limitation: Swift (as of version 2.1) can’t expose a function matching a C type signature. You can pass around @convention(c) pointers to your Swift functions but you can’t publicly expose headers to those same functions. The autogenerated “[ProductName]-Swift.h” file for letting Objective-C call into Swift only exposes your public Objective-C classes (free functions are not exposed). The end result is that it’s just easiest to call into Swift via Objective-C.

I wanted to write as much of the Mach message handling in Swift as possible but I’ve had to implement the actual callback interface in an Objective-C file and call the Swift handler function from there. There’s also some Objective-C code use to catch exceptions.

The Mach exception handler: rewriting history

There’s a lot of different parts to the code but the core of it happens inside the Mach exception handler. The exception handler gives us the “state” (registers and stack) for the thread where the exception occurs. The thread is suspended at this point, so we’re allowed to play around with the state. This is what we do:

// Read the old thread statevarstate=UnsafePointer<x86_thread_state64_t>(old_state).memory// 1. Decrement the stack pointerstate.__rsp-=__uint64_t(sizeof(Int))// 2. Save the old Instruction Pointer to the stack.UnsafeMutablePointer<__uint64_t>(bitPattern:UInt(state.__rsp)).memory=state.__rip// 3. Set the Instruction Pointer to the new function's addressvarf:@convention(c)()->()=raiseBadInstructionExceptionwithUnsafePointer(&f){state.__rip=UnsafePointer<__uint64_t>($0).memory}// Write the new thread stateUnsafeMutablePointer<x86_thread_state64_t>(new_state).memory=statenew_stateCnt.memory=x86_THREAD_STATE64_COUNT

The three numbered steps are the equivalent of an assembly language call instruction. We’ve changed the state of the thread to look like the last code run was not the ud2 instruction that raised the EXC_BAD_INSTRUCTION but was instead a call to our raiseBadInstructionException function. Therefore, when the thread resumes it will run:

privatefuncraiseBadInstructionException(){BadInstructionException().raise()}

which is a straightforward throw of an NSException subclass.

Setting up a Mach exception handler

The other code I wanted to highlight was the setup of the Mach exception handler. There are two reasons for this:

1. Documentation and useful examples for the required functions were really difficult to find, so I’d like to publish it here for visibility.
2. This was some of the first Swift 2 code I ever wrote and I went crazy with Swift’s defer, try, guard, throw and catch; I’m not sure if the result is brilliant or ridiculous but at least there’s no possibility of a goto fail error here.

I’ve commented each step in the code so you should just be able to read the comments to see what the code does. Pay close attention to the order that the steps are numbered, remember: defer statements are executed in the reverse order to their setup.

Here goes:

funccatchBadInstruction(block:()->())->BadInstructionException?{varcontext=exceptionContext()varresult:BadInstructionException?=nildo{varhandlerThread:pthread_t=nildefer{// 8. Wait for the thread to terminate *if* we actually made it to the creation point// The mach port should be destroyed *before* calling pthread_join to avoid a deadlock.ifhandlerThread!=nil{pthread_join(handlerThread,nil)}}trykernCheck{// 1. Create the mach portmach_port_allocate(mach_task_self_,MACH_PORT_RIGHT_RECEIVE,&context.currentExceptionPort)}defer{// 7. Cleanup the mach portmach_port_destroy(mach_task_self_,context.currentExceptionPort)}trykernCheck{// 2. Configure the mach portmach_port_insert_right(mach_task_self_,context.currentExceptionPort,context.currentExceptionPort,MACH_MSG_TYPE_MAKE_SEND)}trykernCheck{// 3. Apply the mach port as the handler for this threadthread_swap_exception_ports(mach_thread_self(),EXC_MASK_BAD_INSTRUCTION,context.currentExceptionPort,Int32(bitPattern:UInt32(EXCEPTION_STATE)|MACH_EXCEPTION_CODES),x86_THREAD_STATE64,&context.masks.value.0,&context.count,&context.ports.value.0,&context.behaviors.value.0,&context.flavors.value.0)}defer{// 6. Unapply the mach portthread_swap_exception_ports(mach_thread_self(),EXC_MASK_BAD_INSTRUCTION,0,EXCEPTION_DEFAULT,THREAD_STATE_NONE,&context.masks.value.0,&context.count,&context.ports.value.0,&context.behaviors.value.0,&context.flavors.value.0)}trywithUnsafeMutablePointer(&context){cthrowsin// 4. Create the threadguardpthread_create(&handlerThread,nil,machMessageHandler,c)==0else{throwPthreadError.Any}// 5. Run the blockresult=BadInstructionException.catchException(block)}}catch{// Should never be reached but this is testing code, don't try to recover, just abortfatalError("Mach port error: \(error)")}returnresult}

The kernCheck function is just a little helper to grab the result code from a Mach function and if it’s an error, convert to a Swift ErrorType and throw. It’s equivalent to the sort of macro that might be used for this type of error code checking in C.

The catchBadInstruction function sets everything up but it’s the machMessageHandler function (spawned by the pthread_create call at step 4) that sits around and waits to see if a Mach message will be received. It looks like this:

privatefuncmachMessageHandler(arg:UnsafeMutablePointer<Void>)->UnsafeMutablePointer<Void>{letcontext=UnsafeMutablePointer<ExceptionContext>(arg).memoryvarrequest=request_mach_exception_raise_t()varreply=reply_mach_exception_raise_state_t()do{// Request the next mach message from the portrequest.Head.msgh_local_port=context.currentExceptionPortrequest.Head.msgh_size=UInt32(sizeofValue(request))trykernCheck{withUnsafeMutablePointer(&request){mach_msg(UnsafeMutablePointer<mach_msg_header_t>($0),MACH_RCV_MSG|MACH_RCV_INTERRUPT,0,request.Head.msgh_size,context.currentExceptionPort,0,UInt32(MACH_PORT_NULL))}}// Prepare the reply structurereply.Head.msgh_bits=MACH_MSGH_BITS(MACH_MSGH_BITS_REMOTE(request.Head.msgh_bits),0)reply.Head.msgh_local_port=UInt32(MACH_PORT_NULL)reply.Head.msgh_remote_port=request.Head.msgh_remote_portreply.Head.msgh_size=UInt32(sizeofValue(reply))reply.NDR=NDR_record// Use the MiG generated server to invoke our handler for the request and fill in// the rest of the reply structureguardwithUnsafeMutablePointers(&request,&reply,{mach_exc_server(UnsafeMutablePointer<mach_msg_header_t>($0),UnsafeMutablePointer<mach_msg_header_t>($1))})!=0else{throwMachExcServer.Any}// Send the replytrykernCheck{withUnsafeMutablePointer(&reply){mach_msg(UnsafeMutablePointer<mach_msg_header_t>($0),MACH_SEND_MSG,reply.Head.msgh_size,0,UInt32(MACH_PORT_NULL),0,UInt32(MACH_PORT_NULL))}}}catchleterrorasNSErrorwhere(error.domain==NSMachErrorDomain&&(error.code==Int(MACH_RCV_PORT_CHANGED)||error.code==Int(MACH_RCV_INVALID_NAME))){// Port was already closed before we started or closed while we were listening.// This means the block completed without raising an EXC_BAD_INSTRUCTION. Not a problem.}catch{// Should never be reached but this is testing code, don't try to recover, just abortfatalError("Mach message error: \(error)")}returnnil}

Usage

The project containing this code is available on github: mattgallagher/CwlPreconditionTesting.

The Readme.md file file contains some additional usage instructions but the short version is:

1. git clone https://github.com/mattgallagher/CwlPreconditionTesting.git
2. drag the “CwlPreconditionTesting.xcodeproj” file into your project’s file tree in Xcode
3. go to your testing target’s Build Phase settings and under “Target Dependencies” press the “+” button and select the relevant “CwlPreconditionTesting” target (“_iOS” or “_OSX”, depending on your testing target’s SDK)
4. write import CwlPreconditionTesting at the top of any test file where you want to use catchBadInstruction (Swift should handle the linkage automatically when you do this)
5. use the catchBadInstruction function as shown in the CwlCatchBadInstructionTests.swift tests file

Conclusion

CwlPreconditionTesting.catchBadInstruction can catch Swift precondition failures so we can accurately test partial functions. I think it’s likely that the Mach exception handler shown in this article contains the highest percentage of Swift used in any Mach exception handler ever written (although I doubt there’s much Swift competition in this area).

This post completes my “Return to Cocoa with Love and Be Completely Self-Contradictory” trilogy:

• Part 1: Move away from fun hacks on Cocoa with Love
• Part 2: Don’t use partial functions
• Part 3: Let’s test partial functions using fun hacks!

I’m being flippant, of course, since this omits the context: the respective problem domains. In these three articles, the respective problem domains are:

1. deployed apps
2. programming interface design
3. programming interface testing

I hope that it’s apparent that key statements in each of these articles has very different relative importance within different problem domains in programming. I also hope it’s apparent that economics and other considerations will always get in the way of good app implementations and good API designs. Sometimes we have to cover our asses with good testing.

Swift is a memory safe language so that means no undefined memory bugs, right? Not quite. Swift often needs to interact with C and C remains memory unsafe. To further complicate matters, C and Swift have different models of how memory works, leading to some subtle situations that would have been totally safe in C becoming unsafe in Swift.

In this article, I’ll look at a class of memory safety bug that occurred multiple times while I was writing the previous article. This particular bug occurs only in Release builds and can occur even when your code has no occurrence of the word “unsafe” anywhere in it.

An example

The following example shows an Objective-C test that creates a C string from an Objective-C string, copies the C string using strcpy and converts back to Objective-C, testing that the result is the same as the original.

-(void)testProblem{NSString*source=@"Hi, all!";constchar*cs=[sourcecStringUsingEncoding:NSUTF8StringEncoding];charstring1[10]={0};charstring2[10]={cs[0],cs[1],cs[2],cs[3],cs[4],cs[5],cs[6],cs[7],0,0};strcpy(&string1[0],&string2[0]);NSString*destination=[NSStringstringWithUTF8String:string1];XCTAssert([destinationisEqualToString:source]);}

There are some minor quirks in how I’ve written this but it is totally valid C/Objective-C and the XCTAssert check succeeds. Let’s recreate it as accurately as possible in Swift:

functestProblem(){typealiasTenCChars=(CChar,CChar,CChar,CChar,CChar,CChar,CChar,CChar,CChar,CChar)letsource="Hi, all!"letcs=source.cStringUsingEncoding(NSUTF8StringEncoding)!varstring1=TenCChars(0,0,0,0,0,0,0,0,0,0)varstring2=TenCChars(cs[0],cs[1],cs[2],cs[3],cs[4],cs[5],cs[6],cs[7],0,0)strcpy(&string1.0,&string2.0)letdestination=String.fromCString(&string1.0)!XCTAssert(destination==source)}

Swift is doing exactly what the Objective-C code does. The word “unsafe” does not appear anywhere in the code. The code compiles and works correctly in Debug. In Release, there is a memory safety problem and the XCTAssert fails. The problem is particularly subtle: change the order of string1 and string2 and you’ll still have memory unsafety but the test will pass.

Can you see the problem?

C’s memory model

The source of the problem is a difference in memory model between C and Swift.

In C’s memory model:

1. every variable has an address
2. every field in a structure can be reached by offsetting a pointer from another field in the structure

Despite being part of C’s memory model, these points are not necessarily true – particularly after optimization. Variables in registers don’t have addresses. Variables, fields and whole structures may be omitted if they are unused.

But the optimizer in C is required to maintain the illusion of the memory model. Maintaining this illusion requires something very specific:

If you take the address of any field of a struct then the compiler must ensure the entire struct – and any parent struct that contains it – is allocated in an addressable location and fields may not be reordered or omitted.

So when we write:

strcpy(&string1[0],&string2[0]);

in C, we are forcing the compiler to ensure that the entire string1 and string2 arrays are addressable and complete. They cannot be registers, they cannot be truncated, they cannot be eliminated.

Maintaining the C memory model has a cost – the optimizer becomes limited in what it can do. Potentially unnecessary stack allocations have a performance overhead relative to register allocations or elimination.

Swift’s memory model

In Swift’s memory model:

1. variables don’t necessarily have addresses except inside a scope that creates an address
2. a pointer to one field of a tuple or struct offers zero knowledge about siblings or parents

You can create an UnsafeMutablePointer to a variable in Swift but Swift may need to copy that variable to the stack specifically for the UnsafeMutablePointer creation and may immediately remove it from the stack afterwards.

Specifically for this article:

you cannot create a pointer to a field within a tuple or struct and then use that pointer to access sibling or parent fields in the same tuple or struct.

That is the simple answer to what’s gone wrong in the Swift version: we tried to use a pointer to the first element of a tuple to read and write to the whole tuple. Creating a pointer to the first element of a larger structure and using that as a proxy for the whole structure is common in C and C++ but it’s simply not allowed in Swift.

A destructuring optimization pass

The optimization pass that causes the problem in this article occurs in the SILSROA optimization pass in the Swift compiler. It is applied during the runSILOptimizationPasses function in Passes.cpp. This SROA (scalar replacement of aggregates) optimization destructures structs and tuples that are only used for their component fields (never used in their entirety). This lets the separate fields of the struct be moved around and optimized separately – as though they were separately declared variables.

For the example in this article, after destructuring the tuple the Swift compiler realizes that – according to the rules of the Swift memory model – only the zeroth field of the string1 and string2 tuples are ever read so the initialization of the remaining fields is marked as a “dead store” and the dead fields 1-9 are omitted from the function entirely (never allocated on the stack).

The result is that strcpy, when it advances the pointer past the first element, overwrites whatever is on the stack past string1. I’ve organized the variables so that the source of the copy (string2) is immediately overwritten – causing an obvious and testable problem – but depending on how your variables on the stack are organized, you might not overwrite anything important, making this a very difficult bug to spot.

The fix

The solution isn’t particularly difficult: if we need the entire structure then we must use the entire structure. To do this, replace the line:

strcpy(&string1.0,&string2.0)

with

withUnsafeMutablePointers(&string1,&string2){strcpy(UnsafeMutablePointer<CChar>($0),UnsafePointer<CChar>($1))}

Swift can infer the <CChar> generic parameter, I’ve just included it for clarity.

This code makes its pointers from the entire string1 and string2 tuples (not just the zeroth elements). This guarantees the entire tuple remains intact. Once inside the withUnsafeMutablePointers scope, we can recast the pointer to UnsafeMutablePointer<CChar> to satisfy the strcpy function signature.

How does this relate to the previous article?

Let’s look at the real-world examples from the previous article where this bug caused problems. The following code snippets from CwlCatchBadInstruction.swift all show examples of needing to create pointers carefully to avoid this problem.

guardwithUnsafeMutablePointers(&request,&reply,{mach_exc_server(UnsafeMutablePointer($0),UnsafeMutablePointer($1))})!=0else{throwMachExcServer.Any}

This was the example that first drew my attention to the problem. In this example, request and reply are large structures for receiving and storing Mach exception messages but the mach_exc_server function only takes a pointer to their first field. In C, you’d simply pass &request.Head, &reply.Head but in Swift, we need to correctly scope the pointer to the entire structure or every field past Head will be invalid; the reply won’t be created correctly and the Mach exception handler stops doing its job.

trykernCheck{withUnsafeMutablePointers(&context.masks,&context.ports,&context.behaviors){(m,p,b)inwithUnsafeMutablePointer(&context.flavors){// 3. Apply the mach port as the handler for this threadthread_swap_exception_ports(mach_thread_self(),EXC_MASK_BAD_INSTRUCTION,context.currentExceptionPort,Int32(bitPattern:UInt32(EXCEPTION_STATE)|MACH_EXCEPTION_CODES),x86_THREAD_STATE64,UnsafeMutablePointer<exception_mask_t>(m),&context.count,UnsafeMutablePointer<mach_port_t>(p),UnsafeMutablePointer<exception_behavior_t>(b),UnsafeMutablePointer<thread_state_flavor_t>($0))}}}

In this great, ugly behemoth, 4 generic structs wrapping 14-element tuples (context.masks, context.ports, context.behaviors and context.flavors) need to be passed to the function. In the original code that I posted for the previous article, I passed these tuples to the function by creating pointers to the zeroth elements (e.g. &context.masks.value.0). The code worked without problem (since the unspecialized nature of the generic structs prevented the SROA optimization) but the code was likely to fail if I ever turned on whole-module optimization (which could specialize the generic structs). Oops.

Since there’s no withUnsafeMutablePointers function that creates 4 pointers, we need to create the pointers in two nested layers. And Swift’s type inference refuses to infer the types of the UnsafeMutablePointer generic parameters so they’ve all been written in full. Yuck.

Conclusion

This article is really just an aside, commenting on an interesting quirk from the previous article. The lesson that we need to properly scope all pointer access in Swift is a straightforward one but it’s important to understand that it can be very subtle; practically invisible. Any unsafe pointer – including an implicitly created one – can result in unsafe memory usage if the user of the pointer tries to access memory outside the scope of the pointer’s creation.

Debugging tasks with complex or asynchronous control flow can be difficult since it renders useless one of the most important debugging tools we have: the debugger stack trace. To overcome this, we can have our tasks capture their own stack traces in debug builds to aid debugging by reconstructing the path that long-running task objects take through the program.

This article will also share my own custom code for creating and symbolicating stack traces that’s a little faster and more flexible than the existing code for doing this in Swift.

Introduction

One of the best ways to analyze a program for the source of an error is a debugger stack trace.

Imagine we create a task object in function (1), then we pass the task object into another function (2), which then passes the task object into a third function (3) which represents the end of the task. In this example, path the object takes through the program and the call stack are the same thing:

If, by the end of function (3), we don’t have the expected result, we can set a breakpoint at the end of function (3) and the stack trace in the debugger will show functions (2) and (1) ahead of function (3) on the stack. We’ll know the path our task took through functions between creation and completion. If the task is processed purely as a series of nested calls, then the debugger stack trace at the deepest point will capture the entire history of the task and reconstructing the control flow is as simple as reading this stack trace.

Unfortunately, many tasks are not so simple. Objects are not just passed into functions but also returned from functions, eliminating their source frames from the call stack in the process. Objects are also passed between threads, eliminating all prior steps in their lifetime from the call stack.

Imagine our simple three step path for the object instead looked like this:

In this diagram, function (2) calls function (1) where the task object is created. Function (1) then returns the task object to function (2) which then asynchronously passes the object to function (3).

Function (1) is lost from the stack trace as soon as it returns to function (2) then function (2) is also lost from the stack trace when function (3) is invoked asynchronously. When we find a problem at the end of function (3), we’ve lost the history of control flow for the object through our program.

How can we maintain enough information about our computation to perform useful reactive analysis at step (3) under these circumstances?

We could use a log file

Traditionally, we address this type of control flow tracking problem with a log file. We log the construction of the task object, we log when we hand the object from one thread to another and we log its conclusion. By reading through the log file, we can see what events occurred and when.

The biggest problem with a log file though is controlling the amount of information it contains. A log file is usually program-wide and records events from all tasks in a single location. If multiple tasks are occurring simultaneously, they will be interleaved in the log file. If you have many tasks in your program, the log can become unreasonably difficult to read.

Another problem with log files is that they’re only as helpful as the information you choose to write – they don’t implicitly gather information. Good logging requires a non-zero amount of time to write a good log message.

Finally, logging only captures information from the current scope. This makes logging information far less helpful in reusable code where you’re more likely to be interested in the call site than the reusable callee.

A journal of stack traces instead

Instead of using log files to track asynchronous tasks, I prefer to use a structure that I call a “task journal”. It’s not a complicated data structure. Here’s an example:

#if DEBUGvartaskJournal:[[UInt]]=[callStackReturnAddresses()]#endif

Its an array of stack traces, where a stack trace is simply an array of return addresses (UInt) that we can use to reconstruct functions and offsets within those functions at a later time.

Relative to a log file for tracking control flow, this task journal has the following advantages:

1. it stays out of the way until you need it (it’s not blasted into a common location)
2. it’s unique for the task (remains readable, even when multiple tasks are occurring at once)
3. it captures information about callers, making it useful in reusable classes

The initial stack trace (as captured by callStackReturnAddresses) is added on initialization of the taskJournal and when your task reaches an interesting sequence point (conditional branch, interface boundary or other handover point), you append a stack trace.

Coming from a log files, it’s natural to think you might need to include a message with the stack trace but the message is usually “I am here”, something that is already implicit in the stack trace.

This doesn’t mean you shouldn’t store additional metadata with tasks – information like “this task was created with parameters X, Y and Z” or “task received error message E” is very helpful – but it should usually be stored in a custom format for your task context. The key purpose of the task journal is to have metadata that doesn’t require any custom formatting, structures or messages – you just add sequence points when you want.

Capturing the stack trace

Now, I’ve written callStackReturnAddresses in the examples above to capture the current stack trace. There isn’t a free function with that name in Swift or Cocoa.

There is a class function with that name on NSThread, so we could write:

vartaskJournal:[[UInt]]=[NSThread.callStackReturnAddresses()]

Unfortunately, neither NSThread, nor any other class in Foundation, exposes a way to easily convert addresses to symbols at a later time when needed.

There is an alternative function on NSThread:

lettrace=NSThread.callStackSymbols()

which immediately converts the return addresses to symbols but that’s really too time consuming to attach to our main task machinery (we only want to convert to symbols after an error occurs, not on our critical path where we may need to capture hundreds or thousands of stack traces per second).

For performance reasons then, we need to stick to basic return addresses and we’ll need to convert them to symbols ourselves with the C function dladdr. At a minimum: NSThread.callStackReturnAddresses isn’t going to be a complete solution.

But I have another issue with the NSThread implementation: you can’t skip over the top couple of stack frames and you can’t limit the number of captured frames. With NSThread.callStackReturnAddresses, you must always capture the whole stack and then crop the result down to the information you actually need – which forces reallocates and wastes time.

We’d have a bit more flexibility if we could use the C function backtrace but in Swift, we can’t. The backtrace function comes from the “execinfo.h” header and is implemented as part of libSystem on OS X and iOS (which all Swift programs link against) but for whatever reason, the “execinfo.h” contents are not exposed to Swift programs.

Rolling my own

While the functionality of NSThread.callStackReturnAddresses is probably enough for most people, I was dissatisfied enough that I bothered to re-implement it in Swift with the features I wanted:

/// Traverses the frames on current stack and gathers the return addresses for traversed stack frames as an array of UInt./// - parameter skip: number of stack frames to skip over before copying return addresses to the result array./// - parameter maximumAddresses: limit on the number of return addresses to return (default is `Int.max`)/// - returns: The array of return addresses on the current stack within the skip/maximumAddresses bounds.@inline(never)publicfunccallStackReturnAddresses(skipskip:UInt=0,maximumAddresses:Int=Int.max)->[UInt]

To support the function, I also wrote:

/// When applied to the output of callStackReturnAddresses, produces identical output to the execinfo function "backtrace_symbols" or NSThread.callStackSymbols/// - parameter addresses: an array of memory addresses, generally as produced by `callStackReturnAddresses`/// - returns: an array of formatted, symbolicated stack frame descriptions.publicfuncsymbolsForCallStackAddresses(addresses:[UInt])->[String]

which can take the [UInt] and produce call stack symbols in an identical format to NSThread.callStackSymbols() but in an on-demand fashion.

A simple example using these functions

I have a class that I sometimes use called DeferredWork. This object wraps a closure that is deferred to run at a later date. The class has a strict usage requirement: the work must be run at some point before the DeferredWork object is deleted but it is not automatically run; it must be done manually.

A simplified version of the class looks like this (NOTE: this code assumes DEBUG is defined in debug builds):

classDeferredWork{letwork:()->Void#if DEBUG// The task journal captures the stack trace on constructionvartaskJournal:[[UInt]]=[callStackReturnAddresses()]vardidRun=false#endifinit(work:()->Void){self.work=work}funcrun(){work()#if DEBUGdidRun=true#endif}funcrecordHandover(){#if DEBUG// We can append additional stack traces whenever we wish.// For DeferredWork, this is intended to be done on ownership changes.taskJournal.append(callStackReturnAddresses())#endif}#if DEBUGdeinit{if!didRun{// A "didn't run" condition at this point constitutes a failure.// We symbolicate and format the stack traces and trigger a fatal error.lettraces=taskJournal.map{symbolsForCallStackAddresses($0).joinWithSeparator("\n")}preconditionFailure("Failed to perform work deferred at location:\n"+traces.joinWithSeparator("\n\nWith handover at:\n"))}}#endif}

To explain how this works: when the DeferredWork class is created, it takes ownership of the work closure and agrees to run this closure at a later time. The location of the construction is saved as the first element in the taskJournal.

If the DeferredWork is handed over to another owner, the recordHandover function can be manually invoked, recording the change in ownership.

Ultimately, if there is a problem – for this class a “problem” is a failure to invoke run before deinit– we know where the work closure came from we know the chain of custody that brought it to the current location and we can rapidly track down the precise location where the failure to run occurred.

Let’s look at how this solves the problematic three-step control flow I showed above:

DeferredWork.init is function (1). The recordHandover function should be called immediately before the asynchronous call at the end of function (2). The deinit function is invoked at the end of function (3) when the DeferredWork object falls out of scope. If the run function is not called at any time during function (2) or function (3) then we can immediately see the path the object took through our program and decide where we’ve made our mistake.

Implementation of callStackReturnAddresses

As with all code, I’d prefer to implement everything in Swift but Swift lacks an equivalent of to the gcc/clang builtin function __builtin_frame_address which is critical for locating the current stack frame. I’ve written a C function named frame_address that returns __builtin_frame_address(1) and exposed this function to Swift in the bridging header.

Using this function, the internals of callStackReturnAddresses are very simple. I store the result from frame_address in a struct named StackFrame (which is nothing more than few functions wrapped around a uintptr_t that stores the result from frame_address)

letframe=StackFrame(address:frame_address())

Traversing through a stack is as simple as dereferencing the frame pointer (since the value at the frame pointer is the address of the previous frame):

letnextFrameAddress=UnsafeMutablePointer<uintptr_t>(bitPattern:frame.address).memory

Getting return addresses from each frame is also easy since it is stored immediately after the frame pointer in each frame:

letreturnAddress=UnsafeMutablePointer<uintptr_t>(bitPattern:frame.address).advancedBy(1).memory

So we just do this repeatedly through the stack until we exceed the stack bounds.

The resulting callStackReturnAddresses function is about twice as fast as NSThread.callStackReturnAddresses on the basic tests I’ve tried (roughly 2 million invocations per second per core on my Mac versus 1 million invocations per second for NSThread.callStackReturnAddresses). It’s easily fast enough to gather lots of data in Debug builds – even for fairly intensive computational paths.

Usage

The project containing this code is available on github: mattgallagher/CwlUtils.

1. In a subdirectory of your project’s directory, run git clone https://github.com/mattgallagher/CwlUtils.git
2. Drag the “CwlUtils.xcodeproj” file into your own project’s file tree in Xcode
3. Click on your project in the file tree to access project settings and click on the target to which you want to add CwlUtils.
4. Click on the “Build Phases” tab and under “Target Dependencies” click “+” and add the CwlUtils_OSX or CwlUtils_iOS target as appropriate for your target’s platform.
5. Still on “Build Phases”, if you don’t already have a “Copy Files” build phase with a “Destination: Frameworks”, add one. In this build phase, add “CwlUtils.framework”. NOTE: there will be two frameworks in the list with the same name (one is OS X and the other is iOS). The “CwlUtils.framework” will appear above the corresponding CwlUtils OS X or iOS testing target.

Note about step (1): it is not required to create the checkout inside your project’s directory but if you check the code out in a shared location and then open it in multiple parent projects simultaneously, Xcode will complain – it’s usually easier to create a new copy inside each of your projects.

Packaging note

This and the next few code posts I write are going to be part of a single framework, CwlUtils. To be blunt, I’m not really happy with this monolithic framework approach. Ideally, much of the code I’m hoping to produce would be separate, isolated classes that would be pulled together, on-demand, by a dependency manager. However, the existing third-party solutions for dependency management in Swift don’t work elegantly in this scenario (not entirely their fault since static linking and transparent Xcode integration are not possible).

I’ll definitely revisit this when the official Swift Package Manager is shipped as part of Xcode but at the moment, a dependency-free, monolithic framework is it. If you’re only interested in a small piece of code that I’ve written, you’ll need to extract it for yourself.

Conclusion

I’ve talked about ease and benefits of recording stack traces for ongoing tasks to aid debugging. Tracking down why a result is incorrect after asynchronous invocations or other complex control flows can be completely impractical without this information so it’s a good technique to keep in mind.

In the previous article, I looked at gathering stack traces to record what your own process is doing. In debug analysis, though, information about what a process has done is only half the picture: we often need to know about the environment in which the process ran to understand why the process has behaved a certain way.

In this article, I’ll look at gathering a narrow set of basic information about the host system for the purpose of debug analysis. System information can be obtained through a number of different APIs, each with their own advantages, disadvantages and idiosyncracies but I’ll be focussing on a core function available across OS X and iOS: sysctl. The function itself is cumbersome and full of classic C quirks so I’ll also share a Swift wrapper for sysctl to make it slightly less irksome.

Introduction

As with the previous article, this article concerns debug analysis. Specifically, analyzing information about what has happened after a problem occurs to try and determine what led to the problem. This time, instead of capturing information about our own actions, I want to look at capturing information about the host system.

To illustrate what I mean, let’s look at what’s in a typical Mac OS X diagnostic report. We can look at any of the “.diag” files in the “/Library/Logs/DiagnosticReports” folder. A typical dianostic report on my computer contains:

1. The date
2. Name and version information for program that was running when the report was created
3. Specific details about what error or condition triggered the report
4. A stack trace for the program that was running
5. The following information about the host computer…

OS Version:      Mac OS X 10.11.3 (Build 15D21)
Architecture:    x86_64
Hardware model:  MacPro4,1
Active cpus:     8

This is the host information I want to gather.

NSProcessInfo and UIDevice

Let’s look and see if we can gather this information from any common Cocoa location.

The Foundation singleton NSProcessInfo.processInfo() has properties operatingSystemVersionString and activeProcessorCount which could give:

OS Version:      Version 10.11.3 (Build 15D21)
Active cpus:     8

the iOS-only singleton UIDevice.currentDevice() also has systemName and model which would let you amend that to:

OS Version:      iPhone OS Version 9.2.1 (Build 13D20)
Hardware model:  iPhone
Active cpus:     2

Unfortunately though, “iPhone” is not a very helpful model description (this ran on my iPhone 6s which has a true model name of “iPhone8,1”).

The “Hardware model”, as listed in common diagnostic reports, is not available through Objective-C/Swift APIs. For this information, we need to look elsewhere.

uname

Cocoa classes don’t really help us get the hardware model. Instead, let’s turn to a C function named uname. Calling uname function fills in a struct named utsname with the following values:

sysname = "Darwin"
nodename = "Matt-Gallaghers-iPhone"
release = "15.0.0"
version = "Darwin Kernel Version 15.0.0: Wed Dec  9 22:19:38 PST 2015; root:xnu-3248.31.3~2/RELEASE_ARM64_S8000"
machine = "iPhone8,1"

We have the full model name. We can combine this with information from NSProcessInfo and we have all the basic information we need, right?

Let’s try the same thing on a “MacPro4,1” running Mac OS X…

sysname = "Darwin"
nodename = "MacPro.local"
release = "15.3.0"
version = "Darwin Kernel Version 15.3.0: Thu Dec 10 18:40:58 PST 2015; root:xnu-3248.30.4~1/RELEASE_X86_64"
machine = "x86_64"

The model name is gone, replaced instead by the CPU family. So we can’t get the “Hardware model” on the Mac using uname.

Looking for the source

Why is uname inconsistent between platforms? What’s happening?

Let’s look at where uname gets its information and see what’s going on. We can view the source code for uname on opensource.apple.com.

The machine field is filled in by the following code:

mib[0]=CTL_HW;mib[1]=HW_MACHINE;len=sizeof(name->machine);if(sysctl(mib,2,&name->machine,&len,NULL,0)==-1)rval=-1;

So uname isn’t the source of the information. The value actually comes from another function named sysctl.

Of course, sysctl isn’t the source either. Following that rabbit hole all the way down gives:

1. sysctl gets its information from different OID handlers
2. sysctl_hw_generic handles the information for most of the CTL_HW OIDs, including HW_MACHINE.
3. PEGetMachineName handles the HW_MACHINE OID.
4. Depending on CPU, one of the IOPlatformExpert::getMachineName implementations (essentially a driver for the CPU) will return the machine name.

The value is hardcoded into the getMachineName function so this is the true source, although it’s largely irrelevant to us since the sysctl API remains the final layer that we can easily access.

Does this answer why uname is inconsistent between OS X and iOS? Let’s have a look at the output from sysctl on these platforms:

That “N71mAP” value is the iPhone’s CPU model – not completely the same as “x86_64” for an Intel W3520 but similar. So it looks like the inconsistency is due to HW_MACHINE and HW_MODEL results from sysctl getting swapped around – without access to the source code, I don’t if this is a mistake or a deliberate decision (it looks like an accidental mixup) but in any case, the iOS behavior has remained steady since the iOS platform was released.

With this knowledge, we can finally get a “Hardware model” value by using sysctl to get the HW_MODEL for OS X and HW_MACHINE for iOS systems.

What else can sysctl do?

For my own purposes, I rarely go much deeper; basic machine and model information is enough to satisfy the diagnostic information needs for which I employ sysctl. However, the HW_MODEL and HW_MACHINE values that I’ve focussed on in this article are only a small fraction of a huge range of values you can get from sysctl.

You can see almost all of these values on OS X by running sysctl -A on the command line. More than 1000 keys and values will be shown.

I say “almost” though because a few keys are not shown. Curiously, there’s a handful of values that are hidden from this list by default, including HW_MODEL and HW_MACHINE. To get the full list of values, you can download the source to the sysctl command line tool and on line 992, change the final 0 argument passed to show_var to 1. Running the result gives a few dozen extra values you can query.

On iOS, there are a couple hundred fewer sysctl values available (806 on my iPhone versus 1098 on my Mac) with many of the missing values omitted from the hardware – CTL_HW– section. While this is annoying, fortunately most of the relevant traits of an iOS system (CPU type, capabilities and clock rate) are locked to the model so it’s not a major catastrophe. In any case, be wary of the fact that sysctl on iOS may return errors (specifically, a POSIX error 2) for many values that are valid on OS X.

Improving sysctl’s interface with a nested set of wrappers

The sysctl function itself is not incredibly complicated but it is a little ugly in Swift:

publicfuncsysctl(name:UnsafeMutablePointer<Int32>,namelen:u_int,oldp:UnsafeMutablePointer<Void>,oldlenp:UnsafeMutablePointer<Int>,newp:UnsafeMutablePointer<Void>,newlenp:Int)->Int32

You pass a C array of Int32 which uniquely identifies the value you’re after and you pass a buffer via oldp that’s oldlenp long and the value will be written there (I’m going to completely ignore using sysctl to set values since it’s very rare to do that in an app).

The reason why sysctl feels so cumbersome in Swift is:

• Creating an array of Int32 and passing that by pointer for the first parameter is a nuisance in Swift
• You basically need to call sysctl twice: once with oldp equal to nil to get the size required for the result buffer and then a second time with a properly allocated buffer.
• The result is returned as an untyped buffer of bytes which you then need to interpret correctly.
• There are a few different ways in which failure can occur and we want to reduce these different ways to idiomatic Swift errors or preconditions.

For these reasons, I use a wrapper around sysctl which has the following interface:

publicfuncsysctl(levels:[Int32])throws->[Int8]

This lets you write let modelAsArrayOfChar = sysctl([CTL_HW, HW_MODEL]) to get the hardware model as an array of Int8.

Of course, a [Int8] isn’t particularly useful so I call this function from inside subsequent functions that further refine the process:

publicfuncsysctlString(levels:Int32...)throws->String

This function lets you pass in the levels as a comma separated list and converts the result to a regular Swift String so we can get the model as a string in a single line: let modelString = try sysctlAsString(CTL_HW, HW_MODEL).

An alternative overload lets you use the sysctl names instead of Int32 identifiers:

publicfuncsysctlString(name:String)throws->String

for which we’d write let modelString = try sysctlAsString("hw.model").

There’s still more that we can do: we can eliminate the try, entirely. Risking fatal errors should always be kept to a minimum but for core sysctl values, the error code path is effectively unreachable (see ‘Effectively unreachable code paths’ in Partial Functions in Swift, Part1) so forcing “no error” with try! is a valid approach for these code values.

This then leads to the final wrapper around these functions, a static struct exposing the core values, without error handling:

publicstructSysctl{publicstaticvarmodel:String}

For these convenience vars on this Sysctl struct, I’ve taken the opportunity to swap HW_MACHINE and HW_MODEL results on iOS so that its behavior is more in line with OS X. The result is that you can use Sysctl.model to get the “Hardware model” on either OS X or iOS.

Usage

The project containing this sysctl wrapper is available on github: mattgallagher/CwlUtils.

The CwlSysctl.swift file is fully self-contained so you can just copy the file, if that’s all you need. Otherwise, the ReadMe.md file for the project contains detailed information on cloning the whole repository and adding the framework it produes to your own projects.

Conclusion

The sysctl function is a fundamental kernel/machine information tool on OS X and iOS. There’s more information about network interfaces in SystemConfiguration and there’s more about attached hardware devices in the IOKit registry, but these locations don’t hold all of the same information that sysctl offers (and IOKit isn’t available on iOS anyway).

Despite the fundamental nature of this function, its clumsy interface often leaves it as an API of last resort behind Foundation classes and simpler C functions. I hope I’ve shown that if you’re interested in a description of the host’s “Hardware model”, it should be first choice.

The opening sentence of “The Swift Programming Language” chapter on “Error Handling” briefly refers to “error conditions” but beyond that, there’s no definition of what an error is, the conditions that would give rise to one or why it would require special handling.

It’s not a problem unique to “The Swift Programming Language”; search for “error” on the web and you’ll realize it is difficult to find a clear definition of this kind of error that isn’t a discussion about error representations. Error representations are just value types so they’re not ultimately very interesting. They may be returned along separate return paths to non-errors or they may be combined with non-error types into composite entities like “sum” types – but they are still just values.

To better manage errors and test the functions that involve them, we need to look at what makes errors (not just their representations) unique. I’ll give a universal definition of an “error” and look at an increasing series of complications common to errors (“unexpected”, “composite”, “non-pure”, “external”) that make them much worse than typical values and look at the implications this has on testing and subsequent handling.

Figure 1: a pure function

To begin, let’s look at a function that doesn’t produce an error or require any error handling.

This is the structure of a basic “pure” function. If you’re unfamiliar with functional programming technology:

A pure function is one whose behavior depends only on its input arguments (the only data it reads must be read from its arguments) and doesn’t change program state (only temporary local variables and the “return” value may be written)

The function pre-processes arguments (the “prepare” step in the diagram), maps the input values onto output values in accordance with expected behavior (the “evaluate” step) and then packages and sends the output to the caller (the “return” step).

An example in Swift:

funcmultiplyU32toU64(a:UInt32,b:UInt32)->UInt64{let(x,y)=(UInt64(a),UInt64(b))letresult=x*yreturnresult}

In this function, the first line is the “prepare” step (processing the arguments into the desired format), the second line is the “evaluate” step (performs the logic of the function) and the third line is the “return” step (sending the results of the “evaluate” step to the caller).

By design, this function has the same semantics (logical behavior) for all possible inputs. Due to the increase from 32 to 64 bits, there is no possibility of overflow and there is no other way to trigger a special valued output in this function; any two Int32 values will produce an Int64 that is the multiplicative product of the two.

Figure 2: a piecewise function

This diagram represents another “pure” function. In some respects, it is simply a “zoom in” on the previous diagram – the “prepare” step has expanded into “check” and “partition” steps. The “evaluate” step has expanded into two possible “evaluate” steps (“A” and “B”) but otherwise, it’s the same overall structure.

The difference is that now, we have two different control-flow paths for the function, based on an analysis of the input.

An example in Swift:

funcmultiplyU32toU32(a:UInt32,b:UInt32)->UInt32?{letresult:UInt32?iflog2(Double(a))+log2(Double(b))<32{result=a*b}else{result=nil}returnresult}

This version of the multiply function guards against overflow by pre-checking the inputs and returning nil if it multiplication would overflow and only performing the multiplication if it would be safe.

The two different control-flow paths are reflected in the result which is a “sum” type – an Optional which may be either nil or a UInt32.

A sum type is a composite or algebraic type where instances must conform to one type from a set of possible types. In Swift, this is usually implemented as an enum, like Optional.

Errors are expectation failures

The multiplyU32toU32 function’s behavioral expectation is that it will apply a multiplication and return the result. However, the function has a code path and a return type that bypass that functionality entirely.

Depending on the value of input arguments, this function may fail to meet behavioral expectations. This leads us to the missing definition of an error:

An error represents a failure to meet expectations (of arguments, state or other input) where those expectations are a predicate to meeting behavioral expectations (of the statement, function or program).

There are different kinds of error. I’ve previously discussed fatal errors which are failures of the programmer to meet expectations where the program chooses to abort rather than allow the behavioral expectations to fail.

In this article, we’re looking at non-fatal errors. They still represent an expectation failure that prevents the typical behavioral expectations of the function being met however, instead of an abort, the function avoids returning its expected result and instead, a different value (which doesn’t depend on the failed expectation) is returned.

Implications of errors

It’s a seemingly minor note but we don’t generally expect we will fail to meet our expectations.

While the multiplyU32toU32 function has similar structure to the following function:

funcabsoluteValue(a:Int)->Int{letresult:Intifa<0{result=-a}else{result=a}returnresult}

The difference is that with absoluteValue, we expect we’ll need to test both paths equally.

When we call something an “error”, we’re expecting to avoid the error wherever possible. For this reason, there’s an instinct to leave the error path relatively untested – we don’t expect it to occur as often. Even if this asymmetry of usage is true, it creates a higher risk for the less tested path.

It should be clear that testing the internals of both multiplyU32toU32 and absoluteValue should follow the same pattern: both branches should be equally exercised by tests. The only reason you should apply less rigorous testing to a path is if its implementation is much simpler.

Usage frequency should not be used to dictate testing thoroughness (unless the expected frequency is “never”, in which case: maybe the path shouldn’t exist at all).

Impact of a composite type on the caller

Any composite type – like a sum type or an ad hoc equivalent that uses mutually exclusive separate values or even single scalars where different ranges reserved for communicating different behaviors – requires that the caller separate the different components and handle each appropriately. This requires either control flow constructs or functions that are aware of the nature of the composite.

Returning a sum type increases the complexity for the caller. Efficient language constructs and functions that are aware-by-design of the sum type will mitigate some of this complexity increase but a sum type will never be as simple as a continuous scalar type.

Swift has numerous language and library features for handling “sum” types (e.g. switch and if let) but this handling has a syntactic and mental overhead compared to non-sum type handling. There are other approaches that further reduce syntactic overhead by enclosing the actual handling inside the function (e.g. conditional unwrapping and flatMap) but even when the syntax is efficient, we must still consider the multiple behaviors that may be involves.

Figure 3: a non-pure function

We’ve looked at “pure errors” but the majority of errors in imperative programming results from “non-pure” inputs.

To see what that means, let’s start with an error-free, non-pure function:

Structurally, it’s not much different to a pure function. The “prepare” is now a “fetch” stage – implying an action to bring data in from outside – but the purpose is the same: get the required arguments for the function. The difference is in the details:

funcsecondsSince(previous:NSDate)->Double{letcurrent=NSDate()letresult=current.timeIntervalSinceDate(previous)returnresult}

Like the multiply32to64 function under “Figure 1”, this function is an operation on two values. In this case however, while one of the operands (previous) is a function parameter, the other (current) pulls its value from the system clock inside the NSDate constructor. Since the clock is not a parameter to the function, this function is “non-pure”.

Non-pure statements

Technically a function is only non-pure by extension. Non-pure is really the property of a single statement. Most of the secondsSince function is pure and it is only the fetching of the current date:

letcurrent=NSDate()

that is non-pure. The diagram for “non-pure” could have been just the “fetch” step and nothing more. However, “non-pure” as a concept is not particularly interesting, it is the effect that non-pure dependencies have on our program that we want to consider – which is why it’s important to always look at what follows any “fetch” or “send”.

Impact of non-pure functions on testing

Non-pure statements have implications for thread-safety, repeatability and determinism but in many cases, the biggest difficulty with non-pure functions is that they’re difficult to test.

In typical testing, we invoke a function with known arguments and test the result to ensure the function worked. With non-pure functions, controlling the arguments doesn’t control the function.

In the “non-pure” function diagram, how do we test the “evaluate” step is working correctly if we don’t know the exact value constructed during the “fetch” step?

We either need access to the other dependencies (sometimes singletons or other global state within our program can be pre-configured) or we need to be loose enough with our testing that guesses about the result will be true. In both cases, it adds complexity and reduces the robustness of testing.

Alternately, we can move dependencies to the other side of the function interface (a process called “dependency injection”) which can stop the function being non-pure but adds interface complexity and (since it adds an additional layer of indirection) can impede performance.

Figure 4: a non-pure error

I’ve looked at “pure errors” and “non-pure functions”; no surprises that the next step is a non-pure error:

In most respects, it is a combination of a “pure error” and a “non-pure function”. There’s a “sum” return type, two paths through the function and a dependency that isn’t part of the invocation arguments.

Here’s a simple example:

varsettings=Dictionary<String,String>()funcformattedName()->String?{letresult:String?ifletfirstName=settings["firstName"],secondName=settings["secondName"]{result="\(secondName), \(firstName)"}else{result=nil}returnresult}

Like the multiplyU32toU32 function, above, which checked an expectation and returned an error value of nil when the expectation was not met, this function checks that the “firstName” and “secondName” keys are present in the settings and returns nil when they’re not.

This example isn’t very intimidating. The dependency is local (just a global variable in the same file) so its access can be viewed and controlled easily. It’s unlikely to return nil in surprising ways.

External state

The most difficult to manage errors are those that depend on “external” state.

External state, in this case, is state that doesn’t reside within your own process. It may mutate independently of your program, it may have behavior that is not fully declared and even when the behavior is broadly understood, the full complexity may be far beyond what a simple app wants to manage.

Consider the following function:

funcsizeOfFile(path:String)throws->Int{letattributes=tryNSFileManager.defaultManager().attributesOfItemAtPath(path)letresult=(attributes[NSFileSize]as?Int)??0returnresult}

This function attempts to get the size of a file at the specified path. It’s not a complicated idea. Looking at this function, consider the following questions:

• How many ways can an attempt to get the attributes of a file fail?
• The attributesOfItemAtPath documentation simply states that attributes will be present – does it mean all attributes?
• Is it possible that NSFileSize will be missing from the attributes?
• Is returning 0 a sensible result (correct interpretation when NSFileSize is missing) or would a missing NSFileSize convey a different meaning?

Unless you have access to the Foundation source code and the source code of the filesystem, you might not be able to answer any of these questions. Errors due to external state are a nightmare because there aren’t clear answers. You can guess about likely errors and scenarios but it’s almost impossible to know.

Conclusion

It shouldn’t be as difficult to find a definition for “error” as it is. It’s not a complicated concept: an error is a failed expectation, of an input or another dependency, that leads to a failure to deliver on behavioral expectations.

It’s the common traits of an error that make them so difficult to manage:

• composite (requiring handling of multiple possibilities)
• unexpected (skewing testing and design considerations)
• non-pure (dramatically increasing difficulty of testing)
• external (preventing control or clear definition)

I’ve attempted to keep the contents of this article as simple as possible, focussing on definitions and the implicit difficulties but avoiding significant discussion about error handling or how to manage difficulties.

I hope to refer back to this article in the future as I go through the different approaches used to manage errors, test error-prone functions, handle non-pure functions, handle externalities, reduce and hide complexity in error handling and use higher level abstractions to work with composite types in the same way as normal types.

In Swift, a class type is allocated on the heap, uses reference counting to track its lifetime and can perform cleanup behaviors when it is deleted. By contrast, a struct is not separately allocated on the heap, does not use reference counting and cannot perform cleanup behaviors.

Right?

In reality all of these traits “heap”, “reference counting” and “cleanup behaviors” can be true of struct types too. Be careful though: out-of-character behaviors are a good way to cause problems. I’m going to show how a struct can end up with some of the traits you might associate with a class and show how this can be a source of memory leaks, errant behavior and compiler crashes.

WARNING: this post presents a number of anti-patterns (things you really shouldn’t do). The purpose of this article is to highlight some subtle dangers with structs and closure capture. The best way to avoid these dangers is to steer well clear of them unless you’re comfortable that you understand the risks.

Class fields in a struct

While a struct doesn’t usually have any deinit behavior, values of struct type are required (like all other values in Swift) to correctly maintain reference counts for their contents. Any reference counted field within the struct must have its reference counts correctly incremented and decremented as they are added to the struct and when they are removed, or when the struct is deleted.

We can exploit the fact that reference counted fields are decremented when a struct falls out of scope to attach behaviors to the struct as though it had a deinit method. To do this, we can use an OnDelete class:

publicfinalclassOnDelete{varclosure:()->Voidpublicinit(_c:()->Void){closure=c}deinit{closure()}}

and then use the OnDelete class as follows:

structDeletionLogger{letod=OnDelete{print("DeletionLogger deleted")}}letdl=DeletionLogger()print("Not deleted, yet")withExtendedLifetime(dl){}

which will output:

Not deleted, yet
DeletionLogger deleted

When the DeletionLogger is deleted (after the completion of the withExtendedLifetime function which keeps it alive past the preceeding print statement), then the OnDelete closure is run.

Trying to access a struct from a closure

So far, there’s nothing too strange. An OnDelete object can perform a function at cleanup time for a struct, a little like a deinit method. But while it might appear to mimic the deinit behavior of a class, an OnDelete closure is unable to do the most important thing a deinit method can do: operate on the fields of the struct.

Despite some obvious reasons why it’s a bad idea, let’s try to access the struct anyway and see what goes wrong. We’ll use a simple struct that contains an Int value and we’ll try to output the value of the Int when the OnDelete closure runs.

structCounter{letcount=0letod=OnDelete{print("Counter value is \(count)")}}

We can’t do this (error: Instance member 'count' cannot be used on type 'SomeStruct'). That’s not so strange though: we wouldn’t be allowed to do that, even on a class since you’re not allowed to access other fields from an initializer like that.

Let’s initialize the struct properly and then try to capture one of its fields.

structCounter{letcount=0varod:OnDelete?=nilinit(){od=OnDelete{print("Counter value is \(self.count)")}}}

The compiler throws a segmentation fault in Swift 2.2 and a fatal error in Swift Development Snapshot 2016-03-24.

Excellent! I’m having fun already.

Of course, I could avoid all compiler problems by doing this:

structCounter{varcount:Intletod:OnDeleteinit(){letc=0count=cod=OnDelete{print("Counter value is \(c)")}}}

or the seldom-seen capture list which, in this case, is equivalent:

structCounter{varcount=0letod:OnDelete?init(){od=OnDelete{[count]inprint("Counter value is \(count)")}}}

but neither of these options actually let us access the struct itself; both these options capture an immutable copy of the count field but we want access to the up-to-date mutable count.

structCounter{varcount=0varod:OnDelete?init(){od=OnDelete{print("Counter value is \(self.count)")}}}

Hooray! That’s better. Everything is mutable and shared. We’ve captured the count variable and there are no compiler crashes.

We should ship this code since it clearly works, doesn’t it?

Completely loopy

It clearly doesn’t work. If we run the code the same way as before:

letc=Counter()print("Not deleted, yet")withExtendedLifetime(c){}

the only output we get is:

Not deleted, yet

The OnDelete closure is not getting invoked. Why?

Looking at the SIL (Swift Intermediate Language, as returned by swiftc -emit-sil), it’s clear that capturing self in the OnDelete closure prevents self from being optimized to the stack. This means that instead of using alloc_stack, the self variable is allocated using alloc_box:

%1 = alloc_box $Counter, var, name "self", argno 1 // users: %2, %20, %22, %29

and the OnDelete closure retains this alloc_box.

Why is this a problem? It’s a reference counted loop:

• closure retains the boxed version of Counter→ the boxed version of Counter retains OnDelete→ OnDelete retains closure

With this loop created, our OnDelete object is never deallocated and never invokes its closure.

Can we break the loop?

If Counter was a class, we would capture it using a [weak self] closure and avoid the reference counted loop that way. However, since Counter is a struct, attempting to do that is an error. No luck there.

Can we break the loop manually, after construction, by setting the od field to nil?

varc=Counter()c.od=nil

Nope. Still doesn’t work. Why not?

When the Counter.init function returns, the alloc_box it creates is copied to the stack. This means that the version OnDelete has retained is different from this version we can accces. The version OnDelete has is now inaccessible.

We’ve created an unbreakable loop.

As Joe Groff highlights in this thread on Twitter, Swift evolution change SE-0035 should prevent this problem by limiting inout capture (the kind of capture used in the Counter.init method) to @noescape closures (which would prevent capture by OnDelete’s escaping closure).

Copies bad, shared references good?

So the problem is that a different copy of self is returned by the Counter.init method than the version we capture during the method. What we need is to make the returned and retained versions the same.

Let’s avoid doing anything in an init method and instead set things up in static function instead.

structCounter{varcount=0varod:OnDelete?=nilstaticfuncconstruct()->Counter{varc=Counter()c.od=OnDelete{print("Value loop break is \(c.count)")}returnc}}varc=Counter.construct()c.count+=1c.od=nil

Nope: we still have the same problem. We’ve got a captured version of Counter, permanently embedded in OnDelete, that’s different to the returned version.

Let’s change that static method…

structCounter{varcount=0varod:OnDelete?=nilstaticfuncconstruct()->()->(){varc=Counter()c.od=OnDelete{print("Value loop break is \(c.count)")}return{c.count+=1c.od=nil}}}varloopBreaker=Counter.construct()loopBreaker()

The output is now:

Counter value is 1

This finally works, and we can see the state change from the loopBreaker closure is correctly affecting the result printed in the OnDelete closure.

Now that we’re no longer returning the Counter instance, we’ve stopped making a separate copy of it. There is only one copy of the Counter instance and that’s the alloc_box version shared by the two closures. We have a referenced counted struct on the heap and an OnDelete method that can access the fields of the struct at cleanup time.

Some perspective

The code technically “works” but the result is a mess. We have a reference counted loop that we need to manually break, we can only access the Counter type through closures set up in the construct function and for a single underlying instance we now have four heap allocations (the closure in OnDelete, the OnDelete object itself, the boxed allocation of the c variable and the loopBreaker closure).

If you haven’t realized by now… this has all been a big waste of time.

We could just have made the Counter a class in the first place, keeping the number of heap allocations to 1.

classCounter{varcount=0deinit{print("Counter value is \(count)")}}

Long story short: if you need access to the same mutable data from different scopes, a struct probably isn’t a great choice.

Conclusion

Closure capture is something we just write and assume the compiler will do what is required. However, capturing mutable values has a few, subtly different semantics, that may need to be understood to avoid problems. This is complicated by a couple minor design issues that we’re still waiting on Swift 3 to fix.

Remember to consider the possibility of reference counted loops when capturing struct values with class fields. You can’t weakly capture a struct so if a reference counted loop occurs, you’ll need to break the loop another way.

In any case, most of this article has looked at a completely stupid idea: trying to make a struct capture itself. Don’t do that. Capturing, like other reference counting structures, should be an acyclic graph. If you find yourself trying to make loops, it’s probably because you should be using class types with weak links from child to parent.

Finally, there are some good reasons to use an OnDelete class (I’ll be using one in the next article) but don’t start thinking it works like a deinit method – it’s predominantly for side effects (state outside the scope to which it’s attached).

The always entertaining Erica Sadun wrote an article on her blog yesterday about code indentation styles, titled “Swift Style: Are you a 4-denter?”. There was a flurry of replies on Twitter as others playfully chimed in.

While I love trolling and human misery as much as the next person, I’m always saddened when I see these discussions – not because I have a deeply vested interest in tabs over spaces or one indentation width over another – but because the existence of the argument reminds me of the fact that after more than 50 years of indented code, nothing has been done to fix the technology limitations that cause these debates.

Ignoring hypothetical technology changes to eliminate the problem, there does exist a best-practice approach on the topic of code formatting that maximizes maintainability. But I’ll give you a hint: if you’re trying to fix things on the left edge of the line, you’re looking in the wrong spot.

A quick rhetorical question…

Have a look at the following code:

funchelloWorld(){print("Hello world")}

Question: when I typed this text, did I type Unix linefeeds \n, classic Mac carriage returns \r or Windows carriage return linefeeds \r\n?

Obviously, I didn’t type anything of the sort. I hit the “return” key and my text editor did whatever was required to take me to the start of the next line.

Here is how I feel about the encoding of layout commands:

The encoding of layout commands is the responsibility of the text editor program, not the user. The fact that users are perpetually embroiled in debates about the underlying encoding is a failure between text editing programs and text formats to negotiate parameters without user intervention.

Document formats could eliminate the debate entirely

If you’re given a text document without any context, detecting the document type and the character encoding are unsolvable problems. You can use heuristics to guess but these fail regularly.

Consider an XML document declaration:

<?xml version="1.0" encoding="UTF-8"?>

XML documents clearly state their type and encoding, eliminating ambiguity and making the unsolvable problem of determining document type and text encoding into a trivially easy task.

Now, imagine if it was standard for Swift documents to start with a comment like this:

/*swift tabwidth="4" prefertabs="true"*/

This shouldn’t be such a strange thing to see: something equvalent is probably buried in your .vimrc or Xcode settings. The problem is that this information is attached to your editor, not the document. This information needs to be carried along with the document.

If common code editors supported this type of “document declaration” comment, there wouldn’t need to be a tabs versus spaces debate. The mere presence of this line would be enough for a text editor to correctly interpret any combination of tab and space characters at the start of a line and ensure any newly added indentations are correctly encoded.

Tabs versus spaces

But like I said before: in more than 50 years, no one in a position to fix the problem has done anything. I don’t anticipate change.

So given the existing constraints what do we do to keep editing and maintenance costs to a minimum? Tabs or spaces?

From a code maintenance point-of-view, it doesn’t really matter: you will need to vigilantly enforce your standard, no matter what standard you choose.

Both spaces and tabs require that all editors of a document coordinate on which standard they’re going to use. But tabs and spaces are both invisible by default which leads to mistakes. That’s the reason why hostility exists: it’s not because one is superior to another, it’s because anyone who uses a different standard to you is a potential looming threat to your coding standard.

Frankly, compilers should detect inconsistent indentation styles and emit warnings. That would help far more than any debate over choice of standard.

But detecting indentation is complicated by files where lines don’t always start on a whole number of indents…

Non-indent formatting

There’s a related issue to indentation that requires separate discussion: horizontal alignment of text in ways other than indentation.

Non-indent formatting is one of the biggest reasons why many people choose spaces over tabs. For a range of reasons, tabs are more prone to problems when used as part of non-indent formatting.

Here’s my take on the issue though: you should never use non-indent formatting in your code, regardless of your choice of tabs or spaces for indentation encoding. This advice has little to do with tabs versus spaces though and more to do with the belief that time spent formatting code is time wasted and it creates an unncessary code maintenance headache.

I use the following rule and I suggest it for all people free to choose their own coding standards:

Indent code but never horizontally align code in any other way. After indentation, never put 2 spaces together (except inside a comment block or string literal) and never use a tab character at all.

Your editor may be set up to “smart indent” or otherwise facilitate certain kinds of non-indent formatting but I assure you, there’s still a non-zero effort involved in maintaing the aesthetic. It’s much harder to coordinate this type of styling across a team than tabs/spaces settings. And it simply doesn’t help readability enough to be worth the effort.

Hard wrapping and parameter alignment

Let’s look at some code to see what I’m talking about. Here’s some code from Swift’s GenEnum.cpp:

voidstoreExtraInhabitant(IRGenFunction&IGF,llvm::Value*index,Addressdest,SILTypeT)constoverride{auto&C=IGF.IGM.getLLVMContext();autopayloadTy=llvm::IntegerType::get(C,cast<FixedTypeInfo>(TI)->getFixedSize().getValueInBits());dest=IGF.Builder.CreateBitCast(dest,payloadTy->getPointerTo());index=IGF.Builder.CreateZExtOrTrunc(index,payloadTy);index=IGF.Builder.CreateAdd(index,llvm::ConstantInt::get(payloadTy,ElementsWithNoPayload.size()));IGF.Builder.CreateStore(index,dest);}

Clearly, this file is authored with a standard that requires parameters are horizontally aligned when they’re put on new lines. Is it really time well spent? The alignment plays poorly with the 80 character line width and many of the aligned parameters aren’t actually aligned – they just hang in the middle of the line for no apparent reason until you realize they’ve bumped up against the right margin of the window and been pushed partially leftwards.

Let’s look at this same code with no formatting other than indentation:

voidstoreExtraInhabitant(IRGenFunction&IGF,llvm::Value*index,Addressdest,SILTypeT)constoverride{auto&C=IGF.IGM.getLLVMContext();autopayloadTy=llvm::IntegerType::get(C,cast<FixedTypeInfo>(TI)->getFixedSize().getValueInBits());dest=IGF.Builder.CreateBitCast(dest,payloadTy->getPointerTo());index=IGF.Builder.CreateZExtOrTrunc(index,payloadTy);index=IGF.Builder.CreateAdd(index,llvm::ConstantInt::get(payloadTy,ElementsWithNoPayload.size()));IGF.Builder.CreateStore(index,dest);}

I’ve cheated slightly: I moved the opening brace to its own line and increased the indentation to 3 spaces. Both changes are to offset the increased density from eliminating non-indent formatting.

But despite my scurrilous cheating ways, I think there’s an objective truth here: the extensive formatting effort in the first example doesn’t make it substantially easier to read. In fact, I personally I find the more consistent indentation in the second example (the lack of formatting) makes it easier to read.

Even if you find the second example harder to read, you need to ask yourself: how much easier? Because the second example comes with a very big advantage: in Xcode (or Vim and other editors), soft line wrapping with indentation can be automatic and completely eliminates any need to ever hard format code.

Relying on soft wrapping in your editor can take a little acclimatization (many developers have hard-wrapping techniques drilled into them) but this one approach alone can save dozens of hours of time per year as every edit, re-edit or refactor to a hard-wrapped line wastes a few seconds of your time.

Column formatting

Maybe it was cruel to use C++ as an example: it’s ugly from the beginning. Let’s start with something that looks pretty. The following code is from ffmpeg’s mpjpegdec.c:

staticconstAVClassmpjpeg_demuxer_class={.class_name="MPJPEG demuxer",.item_name=av_default_item_name,.option=mpjpeg_options,.version=LIBAVUTIL_VERSION_INT,};

Two columns! It looks pretty! It’s contextually appropriate for the declarative structure!

But are you really saving time? Separating the two columns helps you locate the right column more quickly but that’s not really very important.

staticconstAVClassmpjpeg_demuxer_class={.class_name="MPJPEG demuxer",.item_name=av_default_item_name,.option=mpjpeg_options,.version=LIBAVUTIL_VERSION_INT,};

Removing formatting has made the code uglier.

But you can still find the keys at a glance, with almost the same speed. The right column doesn’t pop out and it doesn’t look like a pretty formatted table but there was no time wasted in lining up columns and no need for formatting maintenance.

Is your time really well spent by aligning columns?

Conclusion

We shouldn’t need to care about tabs versus spaces – it should be coordinated between the document and the editor with no possibility for mistakes.

Sadly, that’s not how things work.

Compilers should emit warnings about inconsistent indentation used within a given file so we aren’t perpetually forced to police invisible characters.

Sadly, that’s not how things work, either.

Due to the failures of our tools to address the issue, we’re stuck with ongoing work to enforce whatever indentation standard we choose.

You can look at my code on Github and discover how I typically encode my indents. I do have a standard and I do keep to it but unless you choose to push changes to one of my projects, you shouldn’t care.

Far more interesting example to follow is how I handle whitespace elsewhere on the line: a \t character will never appear anywhere except in an indent and two or more space characters will only appear in indents, comment blocks or string literals. This avoids a whole host of problems and combined with the fact that I use soft-wrapping where possible, saves a noticeable amount of time in editing and refactoring code.

The best approach for presenting error conditions to the user is to integrate feedback into the user interface about the condition that the error indicates. This could be changing an icon, colors, adding status text or otherwise changing the state of a user interface element.

This “best approach” requires that we understand the error condition and plan for it in advance.

What if we’re still implementing the app and haven’t had time to exhaustively discover possible error conditions and plan for them? What about technically possible error conditions that we cannot trigger in our own testing making planning impractical? What about error conditions that should never occur if everything is well behaved but are still semantically possible?

We need a base level tier of error handling and reporting to the user. This base level must be very low overhead (so we can add it use it without much thought during development) and while it must report an error to the user, it is primarily intended to gather diagnostic information so the source of the error condition can be understood and facilitate fixes and other maintenance.

Introduction

First, some quick terminology:

1. an error condition is a failed conditional check that results in a function skipping its usual functionality and instead returning an nominated error value.
2. an error is a value used to report that an error condition occurred and normal functionality was skipped
3. error handling is code that looks for errors and performs different actions based on the presence of those errors
4. error reporting communicates an error result from a user task to the user

In my previous article, “Errors: unexpected, composite, non-pure, external” I focussed on the first two points and discussed how, from the perspective of the function that creates the error, the error always represents an “unexpected” condition.

In this article, I’m focussing on the latter two points. It’s important to realize that, from the perspective of handling and reporting code, errors might not be entirely unexpected.

Certainly in some cases, an “error” result from one function may represent the preferred result for the receiver (an expected error). In other cases, error handling may deal with errors by choosing a different path that satisfies requirements another way, so the error is never communicated to the user (error recovery). In most other scenarios, even if the error is not “preferred”, then at least we know how to handle the error (an anticipated error) and specialized feedback is presented to the user in a way that is aesthetically appropriate.

In most programs of reasonable complexity, there are likely to be paths through the program – even if they are rare or theoretical – where an error receives no custom handling. This means: no custom text, no custom code paths based on the error type, just bulk acknowledgement of an unanticipated error and an abort of the task in progress.

Reliable, maintainable programming requires that we always have an approach for errors, even these unanticipated errors, so that the error is routed through our error handling and reported to the user. Given that this type of error potentially represents programmer oversight, it’s important that this error include helpful diagnostic information so fixes or other maintenance can occur if required.

Mediocre error handling and reporting

Let’s look at a basic user task. In this case, an @IBAction method on a view controller (as triggered by a button press). The user action then starts a processing task which may trigger an error condition.

// An action on a view controller, triggered by a button press@IBActionfuncsomeUserAction1(sender:AnyObject){someProcessingTask1("/invalid/path")}// A processing task in the data modelfuncsomeProcessingTask1(path:String){do{letdata=tryNSData(contentsOfFile:path,options:.DataReadingMappedIfSafe)processData(data)}catchleterrorasNSError{showAlert(error)}}// A utility function (part of neither data model nor user interface)funcshowAlert(error:NSError){#if os(OSX)NSAlert(error:error).runModal()#elseletalert=UIAlertController(title:error.localizedDescription,message:error.localizedFailureReason,preferredStyle:UIAlertControllerStyle.Alert)alert.addAction(UIAlertAction(title:NSLocalizedString("OK",comment:""),style:UIAlertActionStyle.Default,handler:nil))UIApplication.sharedApplication().windows[0].rootViewController!.presentViewController(alert,animated:true,completion:nil)#endif}

If you look about, you’ll see roughly this pattern repeated in many projects. It’s the result of not wanting to think about error handling but feeling obliged to put something into the catch block.

At least this approach does something in the event of an error. That makes this approach a step up from the typical Objective-C error handling (pass nil for the NSError ** parameter and ignore the problem entirely) or an empty catch block (which is the equivalent in Swift).

But despite appearing to handle the error, this approach can have some potentially serious problems.

Non-unique error information

On its own, the error dialog produced by the previous code may be helpful or it may be useless.

If a user reports that they’re seeing this error dialog in your program, do you have enough information to work out what’s happening and potentially fix the problem?

This error message tells us a given file couldn’t be found but it doesn’t tell us why we’re trying to open a non-existent file. Did we process the path incorrectly? Have we missed a step before getting here? How did the program get to this point? What has gone wrong to trigger this event?

If the only information we have is the error message it’s difficult to properly diagnose many situations. We have a problem that needs to be fixed but we either need to rely on intuition to find the problem or we need to reproduce the problem again in the debugger. The information we are given in this error message alone is insufficient.

For a “file not found” error like this, the default error message is more helpful than usual since the exact missing file is named (although the full path is omitted). Other errors typically have far more opaque default error messages that might be used generically across a range of different circumstances. Errors like “The file could not be played.”, “The operation couldn’t be completed.” are so broad as to be useless. And if you’re unlucky enough to get a POSIX error code, it could have been generated by lots of different functions for lots of different reasons – they are not unique.

Always propagate errors

But the amount of information reported isn’t the biggest problem. The biggest problem is presenting the error at the site where it occurs, rather than the site that triggered the overarching task. We need to propagate the error back to its origin in the someUserAction1 function, rather than trying to handling it in the middle of the task.

Without error propagation:

• the user-interface may get stuck in a mid-task state
• earlier stages in the task can’t attempt a retry or recover
• we’re forcing the task’s presentation of the error, rather than giving the user interface controller that triggered the action a the chance to present errors in a more integrated way

In Objective-C, propagating errors was really annoying (layer, after layer passing NSError** parameters). I personally avoided this where possible – storing the error in a state structure somewhere and instead propagating BOOL through the stack. This approach had numerous problems (shared state is a maintenance headache) but Objective-C’s idiomatic error handling was just miserable.

Swift’s throws keyword is one of the best features of the language. You may need to paint a lot of functions with the throws attribute (especially if you need to throw from deep inside a hierarchy) but it makes your interfaces honest.

What do we want?

Let’s look at a better approach…

// An action on a view controller, triggered by a button press@IBActionfuncsomeUserAction2(sender:AnyObject){do{trysomeProcessingTask2("/invalid/path")}catchleteasNSError{self.presentError(e)}}// A processing task in the data modelfuncsomeProcessingTask2(path:String)throws{tryrethrowUnanticipated{letdata=tryNSData(contentsOfFile:path,options:.DataReadingMappedIfSafe)processData(data)}}

Why is this better?

Error propagation improvements

The most significant difference is that the function responsible for starting the user action – someUserAction2– is now the function responsible for presenting feedback. The highest priority in a user interface is to give feedback to the user’s actions; this control flow lets the user action that triggers the task be responsible for the display of the result.

Moving the presentation to the view controller in this way removes all view code from the model. In the first example, the data model was performing a view action (presenting user-interface feedback). This is a theoretical win for separation of concerns.

The function presentError part of Cocoa on Mac OS X but isn’t usually part of iOS. I’ve provided an implementation on UIViewController to make this work. Even if you don’t choose to use presentError, it remains a good idea to pass your errors through a relevant controller associated with your view hierarchy. This gives you the ability to use custom presentation for errors at a later time by overriding the presentation method.

Diagnostic improvements

Now, I haven’t just let the error thrown by NSData propagate directly. That would be possible and it would work but the error dialog would be the same “default” error I showed in the “mediocre” example, above. In a situation where you know the cause of the error and you know that the localizedDescription for this error fully describes it to the user, then this type of simple error reporting may be sufficient, however, this article focusses on errors that we haven’t anticipated and we don’t know if the localizedDescription will be helpful at all.

We want more information to ensure easy problem diagnosis. The rethrowUnanticipated wrapper function adds an UnanticipatedErrorRecoveryAttempter to the userInfo dictionary of the error and the dialog becomes:

and clicking the “Copy details” button places the following text on the clipboard:

CwlUtils_OSXHarness/1, x86_64/MacPro4,1, Version 10.11.4 (Build 15E65), en, fr

The file “path” couldn’t be opened because there is no such file.
The error occurred at line 61 of the CwlUtils_OSXHarness/AppDelegate.swift file in the program's code.

NSCocoaErrorDomain: 260. [NSFilePath: /invalid/path, NSLocalizedDescription: The file “path” couldn’t be opened because there is no such file., NSUnderlyingError: Error Domain=NSPOSIXErrorDomain Code=2 "No such file or directory"]

1   CwlUtils_OSXHarness                 0x000000010000241c _TFC19CwlUtils_OSXHarness11AppDelegate19someProcessingTask2fzSST_ + 412
2   CwlUtils_OSXHarness                 0x00000001000025c2 _TFC19CwlUtils_OSXHarness11AppDelegate15someUserAction2fPs9AnyObject_T_ + 114
3   CwlUtils_OSXHarness                 0x0000000100002716 _TToFC19CwlUtils_OSXHarness11AppDelegate15someUserAction2fPs9AnyObject_T_ + 54
4   libsystem_trace.dylib               0x00007fff9caa107a _os_activity_initiate + 75
5   AppKit                              0x00007fff8c9ace89 -[NSApplication sendAction:to:from:] + 460
6   AppKit                              0x00007fff8c9befde -[NSControl sendAction:to:] + 86
7   AppKit                              0x00007fff8c9bef08 __26-[NSCell _sendActionFrom:]_block_invoke + 131
8   libsystem_trace.dylib               0x00007fff9caa107a _os_activity_initiate + 75
9   AppKit                              0x00007fff8c9bee65 -[NSCell _sendActionFrom:] + 144
10  libsystem_trace.dylib               0x00007fff9caa107a _os_activity_initiate + 75
11  AppKit                              0x00007fff8c9bd48a -[NSCell trackMouse:inRect:ofView:untilMouseUp:] + 2693
12  AppKit                              0x00007fff8ca05fd0 -[NSButtonCell trackMouse:inRect:ofView:untilMouseUp:] + 744
13  AppKit                              0x00007fff8c9bbbb4 -[NSControl mouseDown:] + 669
14  AppKit                              0x00007fff8cf10469 -[NSWindow _handleMouseDownEvent:isDelayedEvent:] + 6322
15  AppKit                              0x00007fff8cf1144d -[NSWindow _reallySendEvent:isDelayedEvent:] + 212
16  AppKit                              0x00007fff8c95063d -[NSWindow sendEvent:] + 517
17  AppKit                              0x00007fff8c8d0b3c -[NSApplication sendEvent:] + 2540
18  AppKit                              0x00007fff8c737ef6 -[NSApplication run] + 796
19  AppKit                              0x00007fff8c70146c NSApplicationMain + 1176
20  CwlUtils_OSXHarness                 0x0000000100002984 main + 84
21  libdyld.dylib                       0x00007fff982a45ad start + 1
22  ???                                 0x0000000000000003 0x0 + 3

How is it done?

No significant work happens in the rethrowUnanticipated function. It’s just a convenience wrapper that looks like this:

publicfuncrethrowUnanticipated<T>(@noescapef:()throws->T)throws->T{do{returntryf()}catch{throwerror.withUnanticipatedErrorRecoveryAttempter()}}

In situations where you want to selectively handle different error types or create your own errors, you would call withUnanticipatedErrorRecoveryAttempter on your error directly instead of using this convenience wrapper.

In any case, it’s withUnanticipatedErrorRecoveryAttempter that’s important. It converts the ErrorType to an NSError (if it wasn’t one already) and adds keys to the userInfo dictionary so that the error can participate in Cocoa’s error recovery system.

The mechanics of presentError and NSRecoveryAttempterErrorKey are fairly straightforward and you can read about them in Apple’s ‘Recover From Errors’ documentation. Obviously, in this case, we’re not strictly “recovering” from an error, we’re just attaching diagnostic information.

Let’s look then at how we attach all this information.

extensionErrorType{publicfuncwithUnanticipatedErrorRecoveryAttempter(file:String=#file,line:Int=#line)->NSError{// We want to preserve the "userInfo" dictionary, so we avoid "self as NSError"// if we can (since it creates a new NSError that doesn't preserve the userInfo).// Instead, we cast *via* NSObject.lete=((selfas?NSObject)as?NSError)??(selfasNSError)varuserInfo:[NSObject:AnyObject]=e.userInfo// Move any existing NSLocalizedRecoverySuggestionErrorKey to a new key (we want// to replace it but don't want to lose potentially useful information)ifletpreviousSuggestion=userInfo[NSLocalizedRecoverySuggestionErrorKey]{userInfo[UnanticipatedErrorRecoveryAttempter.PreviousRecoverySuggestionKey]=previousSuggestion}// Attach a new NSLocalizedRecoverySuggestionErrorKey and our recovery attempter// and optionsletdirectory=((fileasNSString).stringByDeletingLastPathComponentasNSString).lastPathComponentletfilename=(fileasNSString).lastPathComponentletsuggestion=NSString(format:NSLocalizedString("The error occurred at line %ld of the %@/%@ file in the program's code.",comment:""),line,directory,filename)userInfo[NSLocalizedRecoverySuggestionErrorKey]=suggestionuserInfo[NSLocalizedRecoveryOptionsErrorKey]=UnanticipatedErrorRecoveryAttempter.localizedRecoveryOptions()userInfo[NSRecoveryAttempterErrorKey]=UnanticipatedErrorRecoveryAttempter()// Attach the call stackuserInfo[UnanticipatedErrorRecoveryAttempter.ReturnAddressesKey]=callStackReturnAddresses()returnNSError(domain:e.domain,code:e.code,userInfo:userInfo)}}

Getting a little mileage out of my own code, this uses callStackReturnAddresses and symbolsForCallStackAddresses from Tracing tasks with stack traces in Swift.

When the error this function returns is passed to presentError it will use the NSRecoveryAttempterErrorKey added to the userInfo dictionary.

This UnanticipatedErrorRecoveryAttempter provides implementations for the NSErrorRecoveryAttempting methods and uses them to put an OK and Copy details button in the presentError dialog and when the Copy details button is pressed, generates a string to put on the generalPasteboard using the following function:

privatefuncextendedErrorInformation(error:NSError)->String{varuserInfo=error.userInfo// Fetch and format diagnostic information for displayletcallStackSymbols=(userInfo[ErrorTypeReturnAddressesKey]as?[UInt]).map{symbolsForCallStackAddresses($0).joinWithSeparator("\n")}??NSLocalizedString("(Call stack unavailable)",comment:"")letlocalizedDescription=error.localizedDescriptionletlocalizedRecoverySuggestion=error.localizedRecoverySuggestion??""letapplicationName=(NSBundle.mainBundle().infoDictionary?[kCFBundleNameKeyasString]as?String)??NSProcessInfo.processInfo().processNameletapplicationVersion=(NSBundle.mainBundle().infoDictionary?[kCFBundleVersionKeyasString]as?String)??NSLocalizedString("(App version unavailable)",comment:"")letlocales=NSLocale.preferredLanguages().joinWithSeparator(", ")letmachineInfo="\(Sysctl.machine)/\(Sysctl.model), \(NSProcessInfo.processInfo().operatingSystemVersionString)"// Remove already handled keys from the userInfo.userInfo.removeValueForKey(NSLocalizedDescriptionKey)userInfo.removeValueForKey(NSLocalizedRecoverySuggestionErrorKey)userInfo.removeValueForKey(NSLocalizedRecoveryOptionsErrorKey)userInfo.removeValueForKey(NSRecoveryAttempterErrorKey)userInfo.removeValueForKey(ErrorTypeRecoveryAttemptCheckKey)userInfo.removeValueForKey(ErrorTypeReturnAddressesKey)return"\(applicationName)/\(applicationVersion), \(machineInfo), \(locales)\n\n\(localizedDescription)\n\(localizedRecoverySuggestion)\n\n\(error.domain): \(error.code). \(userInfo)\n\n\(callStackSymbols)"}

This includes “machine” and “model” information, generated as described in my earlier article Gathering system information in Swift with sysctl.

Usage

The code presented in this article is part of the CwlUnanticipatedError.swift file in my CwlUtils project on Github.

The ReadMe.md file for the project contains detailed information on cloning the whole repository and adding the framework it produes to your own projects.

If you want to play with the example error handling code used in this article, it is part of the “CwlUtils_OSXHarness” and “CwlUtils_iOSHarness” targets which each produce a basic app with some buttons to trigger errors.

Conclusion

This article discussed two key points:

1. The importance of propagating errors all the way back to their origin
2. Using an error that embeds an NSErrorRecoveryAttempting implementation for diagnostic purposes

Combined with some wrapper functions, Swift’s error handling and Cocoa’s error reporting capabilities, these two techniques provide a solid base level of error management that you can start to use, even at a hastily implemented prototype stage, and iteratively replace with better error handling and reporting as needed.

In a fully-tested program, this type of error reporting is not what the user should see. The presence of line numbers and mention of the “program’s code” is a cue to any mildy savvy user that this dialog is diagnostic tool, not a deliberate feature. While the user may be able to use the information contained to resolve the problem on their own, they are hinted to provide the information under the “Copy details” button through appropriate support channels if the problem persists.

I rewrote the C++ implementation of Swift’s Demangle.cpp in Swift. My reimplementation is completely standalone and can be dropped directly into any Swift project.

On its own though, that isn’t necessarily very interesting. Demangling Swift names isn’t a very common task – most Swift/Cocoa reflection functions will return an already demangled name. You usually have to go through C functions to get a mangled name in the first place.

To make it interesting, I turned the exercise into an opportunity to compare C++ and Swift – to see if Swift could be used as a C++ replacement for relatively low level tasks like a recursive descent parser. Would C++ do things with preprocessor macros or templates and metaprogramming that can’t be recreated in Swift, leading to cumbersome workarounds? Would Swift turn out to have critical performance problems?

And if I could clear all the technical hurdles, could I improve on the C++ implementation by making it more “Swifty”? What would idiomatic Swift look like for this type of work?

As an aside to the whole language comparison, the ScalarScanner that I implemented as part of the parser is available separately and might be useful if you’re looking for an alternative to using NSScanner, NSRegularExpression or other tools poorly suited to character-by-character parsing.

A specific style of C++

I’m going to compare my opinion of what idiomatic Swift is to the style of C++ found in Demangle.cpp from the Swift project.

I’m going to refer to things that C++ does but I really mean: the style of C++ used in Demangle.cpp. Of course, there are lots of different ways of writing C++ and the C++ on display in Demangle.cpp is a very narrow subset. Demangle.cpp uses a particular, minimalist, conservative style. I will discuss some possible pragmatic reasons why Demangle.cpp is so minimalist but for now, please keep in mind: I’m not saying C++ can’t do things differently but that a mainstream C++ compiler project from experienced, professional developers chooses to do things this way.

A Swift UnicodeScalar scanner

Starting at the beginning, the most important tool for writing a recursive descent parser is a scanner (character, string and other token reader) for traversing the input data.

Demangle.cpp defines its own scanner class named NameSource for traversing data provided by an LLVM StringRef.

classNameSource{StringRefText;public:NameSource(StringReftext);boolhasAtLeast(size_tlen);boolisEmpty();explicitoperatorbool();charpeek();charnext();boolnextIf(charc);boolnextIf(StringRefstr);StringRefslice(size_tlen);StringRefstr();voidadvanceOffset(size_tlen);StringRefgetString();boolreadUntil(charc,std::string&result);};

We need something with similar functionality. The obvious choice for this in Cocoa is usually NSScanner (or a subclass) but for a number of reasons, NSScanner isn’t really the right tool for this type of job. In particular: it doesn’t read single characters, it doesn’t peek, you can’t inline Objective-C method invocations and it doesn’t use Swift error handling.

So I wrote ScalarScannerto behave like a Swift version of NameSource:

publicstructScalarScanner<C:CollectionType,TwhereC.Generator.Element==UnicodeScalar,C.Index:BidirectionalIndexType,C.Index:Comparable>{letscalars:Cvarindex:C.Index/// Entirely for user usepublicvarcontext:Tpublicinit(scalars:C,context:T)publicinit(string:String,context:T)publicmutatingfuncmatchString(value:String)throwspublicmutatingfuncmatchScalar(value:UnicodeScalar)throwspublicmutatingfuncreadUntil(scalar:UnicodeScalar)throws->Stringpublicmutatingfuncskip(count:Int=default)throwspublicmutatingfuncbacktrack(count:Int=default)throwspublicmutatingfuncremainder()->StringpublicmutatingfuncconditionalString(value:String)->BoolpublicmutatingfuncconditionalScalar(value:UnicodeScalar)->BoolpublicfuncrequirePeek()throws->UnicodeScalarpublicfuncpeek(ahead:Int=default)->UnicodeScalar?publicmutatingfuncreadScalar()throws->UnicodeScalarpublicmutatingfuncreadInt()throws->IntpublicmutatingfuncreadScalars(count:Int)throws->StringpublicfuncunexpectedError()->CwlDemangle.ScalarScannerError// Any `NSCharacterSet`-like functionality could be applied using thesepublicmutatingfuncskipWhileTrue(@noescapef:UnicodeScalar->Bool)publicmutatingfuncreadWhileTrue(@noescapef:UnicodeScalar->Bool)->String}

From the first line, we can see a difference between the Swift and C++ versions. Swift has a standard set of protocols and constraints for defining data providers, so it makes sense to use them. C++ could use a template parameter to define the data provider but since C++ lacks an equivalent to Swift’s protocol constraints and lacks a corresponding set of standard behaviors, the mulitple constraints for the data provider would be a confusing black box thrust upon any user of NameSource– likely manifesting in weird errors in internal headers if any requirements were not met.

Unless there’s a strong need for abstraction in C++, it’s not worth the effort. Meanwhile, in Swift, there’s no reason to make collections, sequences and other common providers concrete.

This has immediate reuse benefits for Swift. This ScalarScanner can read equally from Array<UnicodeScalar> or from a String.UnicodeScalarView and is completely reusable in any Swift project. Meanwhile NameSource os completely dependent on LLVM’s StringRef and would need to be rewritten to be used with a different data provider.

Translation is boring

I translated about 4200 lines of C++ into about 2800 lines of Swift in roughly 5 hours. All that typing, copying, regex replacing and glancing between code files is as mind numbing as you’d expect.

The answer to my question about whether there would be any difficulties is: there were no major hurdles at all. Demangle.cpp is a very clear, simple, easy to translate file.

Later, because I’m a glutton for punishment, I spent another few hours refactoring to make things a little more “Swifty” and get the line count down under 2100.

Biggest difference between Swift and C++: error handling

The initial implementation – even before any refactoring to make the code more “Swifty” – included Swift error handling instead of the C++ approach of returning a nullptr instead of a NodePointer on error. Swift error handling is such an obvious inclusion that it doesn’t require a second pass or a rethink, even during a relatively mindless translation task.

You can see how simple it is to switch from nullptr results to Swift error handling from the first line of the parser:

C++:

if(!Mangled.nextIf("_T"))returnnullptr;

Swift:

tryscanner.matchString("_T")

The difference between these two approaches is profound.

Most importantly, there are significant benefits for reliability. When Tony Hoare’s called null his “billion dollar mistake”, he was referring to the likelihood of bugs when a potentially null result is not checked for null. Looking at the Git history for Demangle.cpp reveals this happening on more than one occasion – and this doesn’t include bugs that may have been fixed prior to committing. Using nullptr to indicate failure has a real-world maintenance cost.

Also of potential benefit for maintenance: the Swift approach includes contextual information. All errors thrown by the parser include the index where the parsed failed and brief information about the type of token that couldn’t be read. If something goes wrong, there’s at least some information about why the failure occurred.

But the most visible difference in adopting Swift error handling is a significant reduction in code size. Switching to Swift error handling immediately eliminated 149 return nullptr early exit lines from the C++ version. Furthermore, Swift can happily exit from a function in the middle of an expression when a parse attempt fails instead of needing to break expressions into multiple pieces either side of early exits.

For example, the following C++:

#define DEMANGLE_CHILD_OR_RETURN(PARENT, CHILD_KIND) do { \
   auto _node = demangle##CHILD_KIND();                  \
   if (!_node) return nullptr;                           \
   (PARENT)->addChild(std::move(_node));                 \
} while (false)autometaclass=NodeFactory::create(Node::Kind::Metaclass);DEMANGLE_CHILD_OR_RETURN(metaclass,Type);returnmetaclass;

Is reduced down to:

returnSwiftName(kind:.Metaclass,children:[trydemangleType(&scanner)])

Swift is happy to run demangleType and exit before proceeding with construction of the Array or SwiftName.

C++ exceptions versus Swift error handling

C++ could have used exceptions to improve syntactic efficiency and achieve some of the same effects as Swift error handling. Why rely on error prone nullptr to communicate results in Demangle.cpp?

Many large C++ projects – Swift included – are compiled with C++ exceptions entirely disabled. Why deliberately remove a potentially useful feature from the language? The Swift developers answer this question when considering error handling options for Swift:

C++ aspires to making out-of-memory a recoverable condition, and so allocation can throw […] Since constructors are called pervasively and implicitly, it makes sense for the default rule to be that all functions can throw […] Different error sites occur with a different set of cleanups active, and there are a large number of such sites. In fact, prior to C++11, compilers were forced to assume by default that destructor calls could throw, so cleanups actually created more error sites. This all adds up to a significant code-size penalty for exceptions, even in projects which don’t directly use them and which have no interest in recovering from out-of-memory conditions.

C++ exceptions bloat the entire project – even if you only use them sparingly. The code size increase alone can start to slow your program. Then, if you actually throw an exception, the stack unwinding is between 4 and 100 times slower than simply returning a value from a the function (depending on compiler and host details). And you have to maintain rigorous RAII discipline or risk leaking memory. And you have to be careful to avoid exceptions in destructors.

Exceptions are not well-loved.

Conditionals and switch statements

The majority of any recursive descent parser is conditional logic based on the token encountered. Accordingly, the C++ parser is filled with functions that look like this:

if(Mangled.nextIf('M')){if(Mangled.nextIf('P')){autopattern=NodeFactory::create(Node::Kind::GenericTypeMetadataPattern);DEMANGLE_CHILD_OR_RETURN(pattern,Type);returnpattern;}if(Mangled.nextIf('a')){autoaccessor=NodeFactory::create(Node::Kind::TypeMetadataAccessFunction);DEMANGLE_CHILD_OR_RETURN(accessor,Type);returnaccessor;}// ... and so on}

The control flow here shows two tiers of conditionals, checking for 'M' at the top level and 'P' and 'a' at the second.

With Swift switch statements, we can check both tiers of conditionals simultaneously:

switch(tryscanner.readScalar(),tryscanner.readScalar()){case("M","P"):returnSwiftName(kind:.GenericTypeMetadataPattern,children:[trydemangleType(&scanner)])case("M","a"):returnSwiftName(kind:.TypeMetadataAccessFunction,children:[trydemangleType(&scanner)])// ... and so on}

Technically, C++ could pack two chars into a uint16_t and switch on that, just like I have done in Swift. With macros, you could probably make the case label vaguely readable. The point is really that this wouldn’t be idiomatic C++ so you’d need to weigh the syntactic benefit against the familiarity shock.

Let’s look at some non-idiomatic C++ and see how that usually goes. The following exerpt from Demangle.cpp is an implementation of a two tier conditional construct in C++:

enumclassImplConventionContext{Callee,Parameter,Result};StringRefdemangleImplConvention(ImplConventionContextctxt){#define CASE(CHAR, FOR_CALLEE, FOR_PARAMETER, FOR_RESULT)            \
  if (Mangled.nextIf(CHAR)) {                                      \
    switch (ctxt) {                                                \
    case ImplConventionContext::Callee: return (FOR_CALLEE);       \
    case ImplConventionContext::Parameter: return (FOR_PARAMETER); \
    case ImplConventionContext::Result: return (FOR_RESULT);       \
    }                                                              \
    unreachable("bad context");                               \
  }autoNothing=StringRef();CASE('a',Nothing,Nothing,"@autoreleased")CASE('d',"@callee_unowned","@unowned","@unowned")CASE('D',Nothing,Nothing,"@unowned_inner_pointer")CASE('g',"@callee_guaranteed","@guaranteed",Nothing)CASE('e',Nothing,"@deallocating",Nothing)CASE('i',Nothing,"@in","@out")CASE('l',Nothing,"@inout",Nothing)CASE('o',"@callee_owned","@owned","@owned")returnNothing;#undef CASE}

This was the trickiest construct from Demangle.cpp to translate into Swift because it’s so unconventional. It was an effort to work out, given possible values of ctxt on input, what were the possible results from the function.

That’s the result of doing something non-idiomatic in any language: it can take a little time to get your head around what it’s trying to do. Basically, it tries to consume the char in the left column of each CASE and if it succeeds, it will return the result from the second, third or fourth column, as determined by the ctxt parameter passed into the function.

Now, the demangleImplConvention function is used from two locations: demangleImplCalleeConvention and demangleImplParameterOrResult. The former always invokes demangleImplConvention with ctxt equal to ImplConventionContext::Callee and the latter goes through the following logic to determine the ctxt parameter:

autogetContext=[](Node::Kindkind)->ImplConventionContext{if(kind==Node::Kind::ImplParameter)returnImplConventionContext::Parameter;elseif(kind==Node::Kind::ImplResult||kind==Node::Kind::ImplErrorResult)returnImplConventionContext::Result;elseunreachable("unexpected node kind");};autoconvention=demangleImplConvention(getContext(kind));if(convention.empty())returnnullptr;

The relevant point is that the ImplConventionContext enum used as input to demangleImplConvention is largely pointless. The getContext closure maps Node::Kind::ImplParameter onto ImplConventionContext::Parameter and Node::Kind::ImplResult/Node::Kind::ImplErrorResult onto ImplConventionContext::Result. We might as well eliminating the existence of the ImplConventionContext type, using Node::Kind instead and then both of the previous two C++ code blocks reduce to the following Swift switch statment:

funcdemangleImplConvention(inoutscanner:ScalarScanner<[SwiftName]>,kind:SwiftName.Kind)throws->String{switch(tryscanner.readScalar(),(kind==.ImplErrorResult?.ImplResult:kind)){case("a",.ImplResult):return"@autoreleased"case("d",.ImplConvention):return"@callee_unowned"case("d",.ImplParameter):fallthroughcase("d",.ImplResult):return"@unowned"case("D",.ImplResult):return"@unowned_inner_pointer"case("g",.ImplConvention):return"@callee_guaranteed"case("g",.ImplParameter):return"@guaranteed"case("e",.ImplParameter):return"@deallocating"case("i",.ImplParameter):return"@in"case("i",.ImplResult):return"@out"case("l",.ImplParameter):return"@inout"case("o",.ImplConvention):return"@callee_owned"case("o",.ImplParameter):fallthroughcase("o",.ImplResult):return"@owned"case("t",_):return"@convention(thin)"default:throwscanner.unexpectedError()}}

This shows the advantage of a two value switch being idiomatic in Swift: compared to the strange series of #define, if and switch constructions in C++, this is clear, simple and readable. If you have a look, you’ll notice that the different columns from the C++ statement have become different rows in this example – it’s a two dimensional switch but the elements are still presented in a single column. (The appearance of a “t” case is not an accident; it’s an additional case rolled in from the demangleImplCalleeConvention call site.)

When we use a simple switch like this, it’s not just clearer to the programmer. It’s also clearer to the compiler. In the Swift case, you’d get warned by the compiler if you accidentally had two duplicate cases. You’re not going to get a warning about this in the C++ code… which is how the “D” case was accidentally labelled “d” for 2 years in the Swift compiler until I created a pull request to fix the problem while writing this article.

Aggregate processing

Thus far, I’ve been looking at code changes in the parser but Demangle.cpp actually includes two different parts:

• the parser (which reads a mangled string into a tree of nodes) and
• the printer (that serializes the node tree back to an unmangled string).

Swift error handling and switch statements were a big help in the parser but they don’t offer much to the printer. The print function is already a single massive switch statement and it doesn’t need to return any error results.

Let’s look at a typical case from the NodePrinter::print function in C++:

caseNode::Kind::TupleElement:if(pointer->getNumChildren()==1){NodePointertype=pointer->getChild(0);print(type);}elseif(pointer->getNumChildren()==2){NodePointerid=pointer->getChild(0);NodePointertype=pointer->getChild(1);print(id);print(type);}return;

On my first pass, I wasn’t able to think of anything helpful and the SwiftName.print I wrote ended up looking very similar to the C++.

case.TupleElement:ifchildren.count==1{children[0].print(&output)}elseifchildren.count==2{children[0].print(&output)children[1].print(&output)}

In my code, the SwiftName prints itself, rather than requiring a separate NodePrinter class, so the actual output stream is passed as the first parameter (named output here and it’s a Swift.OutputStreamType). Other than that difference, the code is structurally identical.

How do you make this more “Swifty”?

Finally, I concluded that idiomatic Swift implies processing collections – in this case, the children array – in a different way. Idiomatic Swift collection processing implies:

• Avoid accessing elements by index.
• Act on the collection unconditionally (conditionals should be inside your operators, not around them).
• Don’t loop over or manually enumerate collection contents (act declaratively on the whole collection).

That lead me to this:

case.TupleElement:output.write(children.slice(0..<2)){output,childinchild.print(&output)}

Unlike the typical slice subscript in Swift, e.g. children[0..<2], this version that I’m using limits the slice range to the valid indices of the collection. This means there’s no need to check the size of the collection before creating the slice which enables unconditional behavior and reduces possibility of programming errors leading to fatal errors.

Obviously, this isn’t the typical write function on OutputStreamType but is instead a new overload which iterates over a sequence and runs a render closure to actually write to the OutputStreamType– in this case, that means recursing into the next level of the SwiftName.print

Now, it might not be clear why I’ve chosen to implement this as a function on OutputStreamType instead of simply running a forEach over the children. The answer is that this approach allows the OutputStreamType to insert prefixes, separators, suffixes or other labels into the stream between iterations of the loop making comma separated lists a simple task.

For example, the following C++:

caseNode::Kind::ProtocolConformance:{NodePointerchild0=pointer->getChild(0);NodePointerchild1=pointer->getChild(1);NodePointerchild2=pointer->getChild(2);print(child0);Printer<<" : ";print(child1);Printer<<" in ";print(child2);return;}

becomes:

case.ProtocolConformance:output.write(children.slice(0..<3),labels:[nil," : "," in "]){$1.print(&$0)}

Not all cases in the print function are this simple. In Demangle.cpp, many involve iteration over part of the children, terminated by different conditions, where rendering isn’t a simple recursive call to printing the child within.

An example of one of the tricker cases is DependentGenericSignature:

caseNode::Kind::DependentGenericSignature:{Printer<<'<';unsigneddepth=0;unsignednumChildren=pointer->getNumChildren();for(;depth<numChildren&&pointer->getChild(depth)->getKind()==Node::Kind::DependentGenericParamCount;++depth){if(depth!=0)Printer<<"><";unsignedcount=pointer->getChild(depth)->getIndex();for(unsignedindex=0;index<count;++index){if(index!=0)Printer<<", ";Printer<<archetypeName(index,depth);}}if(depth!=numChildren){Printer<<" where ";for(unsignedi=depth;i<numChildren;++i){if(i>depth)Printer<<", ";print(pointer->getChild(i));}}Printer<<'>';return;}

The logic here is difficult to dramatically simplify but if the operators you use to act on your collections aren’t composable (in particular, able to wrap recursively around each other), then you probably haven’t designed them correctly.

The nested loops over children from the C++ example are expressed as nested calls to OutputStreamType.write and the loop condition on the outer loop is expressed as a filter on the input sequence.

case.DependentGenericSignature:letfilteredChildren=children.lazy.filter{$0.kind==.DependentGenericParamCount}.enumerate()varlastDepth=0output.write(filteredChildren,prefix:"<",separator:"><"){o,tinlastDepth=t.indexo.write(0..<t.element.indexFromContents(),separator:", "){$0.write(archetypeName($1,UInt32(t.index)))}}letprefix=(lastDepth+1<children.endIndex)?" where ":""lets=children[(lastDepth+1)..<children.endIndex]output.write(s,prefix:prefix,separator:", ",suffix:">"){$1.print(&$0)}

No loops, no conditionals (except for a ternary operator), no direct accesses by index and the collection is processed by aggregrate statements (in two parts but that’s fine).

Why does pragmatic C++ avoid abstraction?

The abstractions I used to improve the printing could easily be implemented in C++. But despite the standard library including a <functional> header (its included in Demangle.cpp although I’m not exactly sure where it’s used), C++ is not typically used in a functional fashion.

Part of the problem, as I’ve already discussed, is that a lack of protocols and contraints in C++ makes actions on different kinds of collection difficult. Accidentally providing a type that doesn’t meet the requirements of a template parameter and getting an esoteric error buried deep inside a header you didn’t write is frustrating and slow to resolve.

But there’s more to it than that. If you look though large codebases like llvm and Swift, you’ll see that they are very spartan. While Demangle.cpp contains a few minor C++11 niceities, in general, most of the code could have been written in the late 1990s. Most types have no template parameters. Most iteration is done using manual indexes. There’s no “map”, “reduce”, “filter” or other aggregate processing. And there’s no significant library of reusable functionality either – Demangle.cpp is part of a large compiler project but it has to implement its own token scanner.

Why does “best practice” in C++ often involve writing C++ like it’s C?

I’m often reminded of one of C++’s founding principles: you should only pay for those features that you use. The unfortunate corollary is that you’re forced to pay for everything you use.

C++’s compilation model requires substantial header includes and the more features you use, the slower and more painful compilation becomes. Templates must appear in the include path, rather than a separate compilation unit, adding significant complexity for every feature.

The end result is that large C++ projects work better when each file keeps to itself and minimizes includes.

I hope these problems don’t end up affecting Swift. In general, it feels like there’s less resistance in Swift towards using language features and abstractions because less baggage is brought along. No need for headers or declaring before usage. Swift uses easier-to-reason about generics rather than templates, Swift protocols rather than templates again and Swift thankfully uses nothing rather than metaprogramming. Additionally, the fact that reference counting, algebraic types and optionals are all part of the language, rather than bolted on using library features makes abstractions cleaner, less leaky and simpler.

A quick comparison of performance

I don’t want to over emphasise the importance of performance here, since I’m fairly sure Demangle.cpp wasn’t written with performance as a primary consideration and neither was my Swift implementation. But I was curious anyway and I’m sure other people would be, also.

I extracted the full set of mangled strings from Apple’s manglings.txt test file and ran both a parse and print to string 10,000 times in a loop. For Apple’s Demangle.cpp version (C++), the loop was:

for(llvm::StringRefname:names){for(inti=0;i<10000;++i){swift::Demangle::NodePointerpointer=swift::demangle_wrappers::demangleSymbolAsNode(name);std::stringstring=swift::Demangle::nodeToString(pointer,options);}}

For my own CwlDemangle.cpp, the loop was:

// NOTE: `input` here is `Array<UnicodeScalar>`, not `String`, to avoid conversion costs inside the loop.forinputininputs{for_in0..<10_000{_=(try?demangleSwiftName(input).description)??input.reduce(""){return$0+String($1)}}}

I built the C++ code with the Swift project’s build script with the “ReleaseAssert” settings (which is -O2, I think) and Swift at -O.

The C++ version took 21.202s and the Swift version took 17.110s (Swift was about 20% faster).

Please don’t take this to mean that Swift is 20% faster than C++. That’s not what these numbers mean at all. In fact, at a glance it appears that all these numbers show is that the C++ version used a separately allocated pointer for each NodePointer but the corresponding SwiftName in the Swift version is just a plain struct. Yes, the C++ needs the separate allocation to avoid a copy-constructor on Node when used with std::vector but an optimized copy constructor (or an alternative to std::vector) could be easily used if performance was a serious issue.

Let’s take a quick look at the top 10 “Time Profiler” results with “Invert call tree” selected:

C++

    Running Time    Self (ms)  Symbol Name
3766.0ms   17.2%    3766.0     szone_free_definite_size
1830.0ms    8.4%    1830.0     szone_malloc_should_clear
1741.0ms    7.9%    1741.0     tiny_malloc_from_free_list
1607.0ms    7.3%    1607.0     std::__1::__shared_weak_count::__release_shared()
1422.0ms    6.5%    1422.0     _os_lock_spin_lock
1232.0ms    5.6%    1232.0     tiny_free_list_add_ptr
1147.0ms    5.2%    1147.0     szone_size
1079.0ms    4.9%    1079.0     tiny_free_list_remove_ptr
876.0ms     4.0%     876.0     std::__1::__shared_weak_count::__add_shared()
679.0ms     3.1%     679.0     get_tiny_free_size

Swift

    Running Time    Self (ms)  Symbol Name
2115.0ms   12.3%    2115.0     _swift_release_(swift::HeapObject*)
1557.0ms    9.0%    1557.0     _swift_retain_(swift::HeapObject*)
1159.0ms    6.7%    1159.0     szone_free_definite_size
771.0ms     4.5%     771.0     szone_malloc_should_clear
770.0ms     4.5%     770.0     tiny_free_list_add_ptr
769.0ms     4.4%     769.0     _StringCore._claimCapacity(Int, minElementWidth : Int) -> (Int, COpaquePointer)
716.0ms     4.1%     716.0     tiny_malloc_from_free_list
645.0ms     3.7%     645.0     szone_size
569.0ms     3.3%     569.0     _os_lock_spin_lock
568.0ms     3.3%     568.0     _os_lock_handoff_lock

Bluntly: neither case is particularly optimized. These numbers represent roughly 100,000 names parsed and printed per second but optimized versions of these parsers would be an order of magnitude faster and these memory allocation, deallocation and reference counting calls would barely feature.

Despite C++ coming in slower, I would expect it to be easier to eliminate reference counting and dynamic string and array storage from C++. The reason is that these features are largely opt-in in C++ but opt-out in Swift. A couple days optimizing both codebases would probably see the performance lead swing the other way as the time spent in _swift_release_ and _swift_retain_ would be much harder to eliminate (not impossible, just harder) than the other calls in these lists.

In any case, I think it’s obvious that for parsers of this nature, C++ and Swift are “similar enough” in performance.

Some minor points against Swift

The reason retains and releases are difficult to eliminate in Swift is that there’s no “unique pointer” (all reference types are shared pointers). But retains and releases are usually triggered implicitly depending on the @owned or @guaranteed nature of function parameters (attributes you might not know about unless you’ve read Swift’s Calling Convention carefully). Dancing around implicit rules like this can vary from difficult to impossible. It would be good to get some help in Instruments for locating lines of code that trigger retains and release and report why they are occurring (the variables and the rules involved) since reading the assembly and trying to connect it back to the Swift code is slow and error prone.

Changing topic from performance to safety, my implementation includes the methods: Array.at and Array.slice. These extensions to Array include non-fatal bounds checks on Array accesses. With Swift’s emphasis on safety in other cases, I’m surprised that this functionality is not part of the standard library. I feel like I need to include these in every project.

Another place where the Swift standard library could add a little more functionality is with UnicodeScalar. Converting between ASCII numerals stored in UnicodeScalar and UInt32 is a real pain. Being explicit is fine but since UnicodeScalaris a UInt32 under the hood, it would be nice if the two could be used more naturally together for integer arithmetic so I don’t feel like need to unwrap and rewrap the UnicodeScalar twice in every expression.

It would also be nice to have an ASCIILiteralType in Swift (or something else for constructing UInt8 from a string literal). The absence of such a type is the biggest reason I opted to use UnicodeScalar as my underlying element type, even though the code only ever processes UTF8 code units and is therefore wasting 25 bits of storage out of every 32. It doesn’t obviously impact performance here but if the source data was multiple kilobytes instead of a few dozen bytes, it might cause a bigger problem.

Finally, despite having an OptionSetType for managing bitfields, defining their values is still a nuisance in Swift. It would be nice to have an enum that could constrain values to powers of two by default (while allowing certain cases to have non-power-of-two values for multi-value masks) and could work together with OptionSetType to provide values/names for bits in the set.

Usage

The ScalarScanner presented in this article is contained in the CwlScalarScanner.swift file in my CwlUtils project on Github.

The implementation is fully self-contained, so you can just copy the file if you wish.

Otherwise, the ReadMe.md file for the project contains detailed information on cloning the whole repository and adding the framework it produces to your own projects but the file is fully self-contained so you can just download the “CwlScalarScanner.swift” file on its own and add it to an existing project, if you wish.

The CwlDemangle implementation presented in this article is contained in the CwlDemangle.swift file in my CwlDemangle project on Github.

LICENSE NOTE: I usually release my code under an ISC-style license (an Expat/MIT-style license equivalent which I prefer for its simple, readable phrasing) but since the CwlDemangle.swift code is derived from Apple’s Demangle.cpp, I have released it under the same Apache-License 2.0 with runtime exception.

The implementation is fully self-contained, so you can just copy the file if you wish. The whole repository contains full tests for the demangle implementation (tests for ScalarScanner are in the CwlUtils repository, above).

Conclusion

Swift worked pretty well for writing a recursive descent parser. I expected performance gotchas in Swift compared to C++ but it worked out better than expected. I expected some C++ constructs, abstractions or library features that wouldn’t translate easily to Swift but it turns out such things are generally avoided in C++.

By adding Swift error handling, some multi-dimensional switch statements and some more functional abstractions over collections, I was able to produce code in Swift that passes all the same tests as the C++ version, has less possibility of unchecked nullptr crashes and array index issues, produces significantly better errors on parse failures, is less than half the number of lines and is nearly 20% faster.

None of this should be seen an attack on the Swift developers or their code quality. Quite the opposite: Demangle.cpp’s conservative, simple style is very easy to read, was very easy to adapt and has a universality to it that would make it legible to developers familiar with any C-influenced language. The code sometimes looks more like C than C++ but there are pragmatic reasons why that might result in a better experience in large codebases. I also suspect my more-densely packed, hastily written Swift code would be a little harder for outsiders to follow.

And, of course, it’s the Swift developers who developed the tools in Swift that I’m using to iteratively improve upon the tools that are used to develop Swift.

Um, what?

Appendix: why reimplement Demangle.cpp?

In general, no Swift API will give you a mangled name but if you interrogate your process through C APIs (or anything that isn’t Swift or Cocoa), you’ll see names that look like this:

_TFC19CwlUtils_OSXHarness11AppDelegate15someUserAction2fPs9AnyObject_T_   

This particular name is taken from the stack trace shown in the previous article. This name ultimately comes from the C dl_info function (called as part of the symbolsForCallStackAddresses function I introduced in Tracking tasks with stack traces in Swift) which is not Swift name aware.

The demangled form of the name is:

CwlUtils_OSXHarness.AppDelegate.someUserAction2 (Swift.AnyObject) -> ()

The demangled name is far more readable. Where possible, I’d prefer to read the demangled name.

It’s easily possible to demangle this on the command-line. Assuming Xcode is installed, then the following will do it:

MacPro:~ matt$ xcrun swift-demangle _TFC19CwlUtils_OSXHarness11AppDelegate15someUserAction2fPs9AnyObject_T_
_TFC19CwlUtils_OSXHarness11AppDelegate15someUserAction2fPs9AnyObject_T_ ---> CwlUtils_OSXHarness.AppDelegate.someUserAction2 (Swift.AnyObject) -> ()

but this requires that a recent version of Xcode is installed on the target machine and you want to launch a whole process just to demangle a single name – neither are necessarily true on an end-user device.

Now, the Swift standard library kinda sorta contains a function to perform name demangling. The non-public function stdlib_demangleName exists in the standard library. Search your compiled programs and this identifier likely appears in all of them. Unfortunately, this function is non-public. Why? My guess is that you’re not supposed to encounter a mangled name if you’re acting in an idiomatically Swift way and the Swift developers are worried about backwards/forwards compatibility issues as the Swift mangled name grammar changes from version to version.

In any case, if we want name demangling, we need to do it ourselves. How complicated could it be?

The full grammar for mangled Swift names appears at the bottom of The Swift ABI document. It’s roughly 10 screens in my browser just for the BNF grammar – it’s not exactly complex but it’s sizeable.

Faced with the prospect of implementing a 2000 line parser and serializer from scratch, I balked and instead decided to translate the Swift Demangle.cpp from C++ into Swift. This required a lot of typing but much less thinking than coding from scratch.

Why not simply use the Swift C++ version with a C wrapper, just like stdlib_demangleName does in the Swift standard library? For a few reasons, but mostly: I wanted to see what it was like to write a parser in Swift.

What’s the best general purpose random number generating algorithm available?

In this article I’ll present a RandomGenerator protocol use it to implement 8 different random number generating algorithms. Implementations will include wrapers around Mac/iOS built-in algorithms, my own implementations in Swift of some popular algorithms and some corresponding C implementations for comparison. The implementations of the RandomGenerator protocol all seed from /dev/random by default, can generate data of arbitrary size (although I’ll focus on 64-bit integer generation) and offer conversion to Double (preserving up to 52-bits of randomness in the significand).

As an aside, my Swift implementation of the Mersenne Twister ended up 20% faster than the official mt19937-64.c implementation. Curious to understand what I had done, I ended up “fixing” the C version to be just as fast as the Swift version. Yes, it’s true: with a little tuning, C can be just as fast as Swift.

Welcome to C with love.

Use case

My primary use for random numbers is in fuzz testing; deliberately sending mixed and garbled inputs to my functions (to look for data handling errors) or running large numbers of threads with different timing offsets and data sizes (to look for timing or thread-safety bugs).

It’s difficult to know exactly what performance or quality I require from random numbers in this scenario – most “good quality” options would probably suffice – but what I do require is:

• no shared global data (since I run multiple tests in parallel)
• the ability to set the initial seed (since I want to reproduce bugs when I find them)

Historically, I’ve used a C implementation of the Mersenne Twister. I don’t have any particular problems with it but the algorithm is nearing its 20th birthday so I was curious to see what else was around.

Built-in sources of randomness on Mac and iOS

The C standard library on the Mac and iOS contains a few different functions for random number generation:

1. rand()
2. random()
3. [d|e|j|l|m]rand48() et al
4. arc4random()
5. /dev/random

/dev/random

If you need cryptographically secure random numbers, the only option you should consider is /dev/random.

On some OSes, /dev/random can block waiting for random bits to accumulate from hardware entropy sources (so you may be encouraged to use /dev/urandom instead) but on Mac and iOS, both /dev/random and /dev/urandom are identical and use the Yarrow algorithm in conjunction with bits accumulated from hardware entropy sources to generate non-blocking data.

The problem is that reading from /dev/random is slow. In my testing, it is between 100 and 1000 times slower than other generators and uses additional system resources on top of the userspace resources of typical random number generators.

The end result is that /dev/random, while useful for setting initial values, is a poor choice for a general-use random number generator.

Linear congruential generators

The rand, random and the various rand48 functions are all variations of linear congruential generator. This means that invocation mutates the internal state according to the following equation: