Always Processing

Rust API Bindings: CFStringGetBytes Is Hard, Part 2

2024-01-07T00:00:00+00:00

The last post described the complexities I encountered when building Rust bindings for CFStringGetBytes. This post shares the rationale behind my design choices for the first bindings layer. This lowest level layer mitigates the four problems identified in the previous post.

I say "first bindings layer" because the method discussed in this post underlies up to four other Rust interfaces for calling CFStringGetBytes. Why so many layers, though? From the Rust API Guidelines:

Functions expose intermediate results to avoid duplicate work

Many functions that answer a question also compute interesting related data. If this data is potentially of interest to the client, consider exposing it in the API.

Therefore, in building what I thought was the most idiomatic Rust API, I exposed successively lower-level layers for more customizability (at the cost of complexity).

First, let’s review the Core Foundation C API:

String.subproj/CFString.h line 357

CFIndex CFStringGetBytes(CFStringRef theString, CFRange range, CFStringEncoding encoding, UInt8 lossByte, Boolean isExternalRepresentation, UInt8 *buffer, CFIndex maxBufLen, CFIndex *usedBufLen);

And compare it to the most direct Rust interface implemented in my crate:

src/string.rs lines 605-641

impl String {
  pub fn get_bytes_unchecked(
    &self,
    range: impl RangeBounds<usize>,
    encoding: GetBytesEncoding,
    buf: Option<&mut [u8]>,
  ) -> GetBytesResult { /* ... */ }
}

&self represents the CFStringRef pointer, which is typical for bindings of object-oriented interfaces.
The CFRange parameter equivalent is an impl RangeBounds, enabling the caller to use a Rust range expression. A caller may, for example, pass .. to specify the full range of the string.
- CFRange's fields are of type CFIndex, which is a signed type. The first post in this mini-series discussed the design choices in implementing unsigned to signed conversion.
GetBytesEncoding replaces CFStringEncoding and also subsumes lossByte and isExternalRepresentation. The following section provides more detail.
buf: Option<&mut [u8]> captures the optional UInt8 *buffer and CFIndex maxBufLen arguments. The Option type clearly expresses that a buffer is not required. If supplied, though, the slice provides the buffer’s length.
The GetBytesResult return type includes the C API’s return value (the number of UTF-16 code units converted) and the out parameter in the C API, usedBufLen.
The _unchecked suffix hints that this method has a quirk the caller must handle. The following sections elaborate on this behavior.

This method implements a check to mitigate the fourth problem identified in the previous post:

If encoding == kCFStringEncodingUTF16, isExternalRepresentation == true, and maxBufLen < 2, Core Foundation will overrun the buffer when writing the BOM. (The UTF-32 BOM write does validate the buffer’s capacity.)

Without this check, the function’s use could lead to unsoundness, so it would need the unsafe qualifier.

GetBytesEncoding

The GetBytesEncoding struct encompasses the CFStringEncoding, lossByte, and isExternalRepresentation arguments.

src/string.rs lines 126-161

pub enum GetBytesEncoding {
  CharacterSet {
    character_set: CharacterSet,

    /// **Note:** Core Foundation will process surrogate pairs as two individual lossy code
    /// points, so the number of output code points will equal the number of input code units.
    loss_byte: Option<NonZeroU8>,
  },
  Utf8,
  Utf16 {
    byte_order: GetBytesByteOrder,
  },
  Utf32 {
    byte_order: GetBytesByteOrder,
    loss_byte: Option<NonZeroU8>,
  },
}

The CharacterSet enum encompasses all the non-Unicode encodings. (The corresponding string creation function, CFStringCreateWithBytes, is quirky, too. The string construction bindings also specifically handle UTF-8, UTF-16, and UTF-32, and handle all non-Unicode representations with the CharacterSet enum.)
- The lossByte type in the bindings is an Option of NonZeroU8 to express, through the type system, that a loss byte, if used, must have a non-zero value.
- Unfortunately, the use of a comment was the only mitigation I could find for the second problem identified in the previous post:
  
  A code point encoded as a surrogate pair becomes two lossy code points for non-Unicode encodings.
The Utf8 encoding does not have a loss byte, mitigating potential unexpected behavior in reading the call site and documentation, identified in part a of the first problem in the previous post:

Even if the caller provides a lossByte, the function does not process the code unit as a lossy conversion.

The absence of a conversion fallback may imply UTF-8 cannot fail like UTF-16, which is a contributing factor to the method’s _unchecked suffix—the behavior of a straightforward call may not align with default assumptions.
Utf16 has a GetBytesByteOrder field, discussed below, which implements the isExternalRepresentation argument.
Utf32, like Utf16, also has a GetBytesByteOrder field and, similar to CharacterSet, has a loss byte to handle invalid surrogates (clarifying UTF-32 is the only Unicode target encoding that implements loss byte support, as described in part b of the first problem in the previous post).

UTF-16 and UTF-32 use 16-bit and 32-bit integer scalars, which may have big or little endian byte orders. GetBytesByteOrder enumerates the supported options.

src/string.rs lines 109-124

pub enum GetBytesByteOrder {
  BigEndian,
  HostNative {
    include_bom: bool,
  },
  LittleEndian,
}

Core Foundation only supports writing a byte order mark, or BOM (isExternalRepresentation = true), when using the host’s native byte order. This enum prevents callers from specifying unsupported combinations and, therefore, receiving unexpected results.

The combination of GetBytesEncoding::Utf8 and the implementation of isExternalRepresentation in GetBytesByteOrder combine to mitigate the third problem identified in the previous post:

isExternalRepresentation does not encode a BOM for UTF-8 despite the implication in the comment.

GetBytesResult

The function returns a struct incorporating the C API’s return value and out parameter.

src/string.rs lines 202-222

pub struct GetBytesResult {
  pub buf_len: usize,
  pub remaining: Option<Range<usize>>,
}

If buf was Some, the buf_len field contains the number of bytes written into the slice. Otherwise, it contains the number of bytes required to convert the processed range.

If the call converted the entire input range, the remaining field is None. Otherwise, it contains the portion of the input range not converted during the call. Returning a Range instead of the number of UTF-16 code units converted simplifies conversion loop implementations by providing a clear "done" signal and the range argument value for the next call.

If the caller does not provide a loss byte, any conversion (except to UTF-16) may fail. As this function is "unchecked," it’s the caller’s responsibility to check for forward progress, or it risks never terminating.

The next post will discuss the get_bytes method, which explicitly handles lossy conversions and prevents a potential infinite loop.

Rust API Bindings: CFStringGetBytes Is Hard, Part 1

2023-12-29T00:00:00+00:00

When I started building Rust API bindings for Core Foundation, I thought implementing the Debug trait with CFCopyDescription would be a great place to start, and it would help validate incremental progress in implementing the crate.

Use of CFStringCopyBytes is required to write the string value returned by CFCopyDescription to the Debug Formatter as CFStrings are canonically UTF-16 and Rust uses UTF-8, so this ended up being the first function for which I’d write Rust API bindings.

When writing API bindings, I prefer to cover 100% of the API up front. Incomplete binding layers have bitten me in the past, so I try to avoid creating any divergent behavior in a logically equivalent interface. Insufficient API coverage may also lead to a bindings layer design gap that can be difficult to close after accumulating many dependencies.

API bindings are a domain where it’s essential to go slow at first to coherently incorporate the entire API surface area into the design of the bindings to enable product development to go fast by not getting caught up fixing bindings bugs and closing bindings gaps.

In all interface design, I have two common goals:

The interface should be idiomatic—a person proficient in the language should find the naming, design patterns, integration points, etc., intuitive and familiar.
It should not be possible to represent an invalid state. In particular, assertions, preconditions, etc., are unnecessary because the compiler will reject code containing invalid states or control flow.

I had intended to discuss my Rust API design in today’s post, but I discovered a potential invalid state in the design in my final review and am still working on a fix. That works well for this blog since we can separate the problem and solution into independent posts!

CFStringGetBytes Complexity

The API doesn’t seem that complicated:

String.subproj/CFString.h lines 340-357

/* The primitive conversion routine; allows you to convert a string piece at a time
       into a fixed size buffer. Returns number of characters converted.
   Characters that cannot be converted to the specified encoding are represented
       with the byte specified by lossByte; if lossByte is 0, then lossy conversion
       is not allowed and conversion stops, returning partial results.
   Pass buffer==NULL if you don't care about the converted string (but just the convertability,
       or number of bytes required).
   maxBufLength indicates the maximum number of bytes to generate. It is ignored when buffer==NULL.
   Does not zero-terminate. If you want to create Pascal or C string, allow one extra byte at start or end.
   Setting isExternalRepresentation causes any extra bytes that would allow
       the data to be made persistent to be included; for instance, the Unicode BOM. Note that
       CFString prepends UTF encoded data with the Unicode BOM 
       when generating external representation if the target encoding allows. It's important to note that
       only UTF-8, UTF-16, and UTF-32 define the handling of the byte order mark character, and the "LE"
       and "BE" variants of UTF-16 and UTF-32 don't.
*/
CF_EXPORT
CFIndex CFStringGetBytes(CFStringRef theString, CFRange range, CFStringEncoding encoding, UInt8 lossByte, Boolean isExternalRepresentation, UInt8 *buffer, CFIndex maxBufLen, CFIndex *usedBufLen);

But, in writing tests for my bindings, I discovered the following behaviors that were not apparent to me from the comment or the documentation:

range may start or end in the middle of a surrogate pair, or the CFString may contain invalid UTF-16 (does not validate strings created from a UTF-16 buffer, and it allows the deletion of a surrogate code unit without deleting its counterpart). The handling of invalid surrogates is dependent on the encoding:
1. For UTF-8, conversion stops. Even if the caller provides a lossByte, the function does not process the code unit as a lossy conversion.
  
  Corollary: Code that assumes UTF-8 conversion cannot fail will infinitely loop if the string contains invalid UTF-16 and the loop does not validate conversion made forward progress.
2. For UTF-32, the surrogate code unit becomes a lossy conversion.
3. For all other encodings, including UTF-16, there is no observable effect.
A code point encoded as a surrogate pair becomes two lossy code points for non-Unicode encodings.
isExternalRepresentation does not encode a BOM for UTF-8 despite the implication in the comment.
If encoding == kCFStringEncodingUTF16, isExternalRepresentation == true, and maxBufLen < 2, Core Foundation will overrun the buffer when writing the BOM. (The UTF-32 BOM write does validate the buffer’s capacity.)

I didn’t see any mention of buffer alignment requirements in the documentation or code. buffer's type of UInt8 * implies CFStringGetBytes supports unaligned buffers. Such support is reasonable, for example, to facilitate callers writing bytes into a persistent format where packing may create unaligned offsets. But, as far as I can tell, the implementation relies on undefined behavior (casting the buffer pointer to a type with stricter alignment) for unaligned pointer support. Precariously but fortuitously, the instructions selected by the compiler support unaligned writes.

For the most part, these are insignificant corner cases:

Although a lot of code working with UTF-16 needs to handle surrogate pairs better, I suspect there are not many cases where a surrogate pair split occurs at the beginning or end of a range.
The primary conversion direction for non-Unicode encodings is into Unicode, so the code point inflation of surrogate pairs when converting from Unicode is likely rare.
In practice, BOMs are rarely used, especially for UTF-8.
No production code uses a buffer size of one byte.

Fortunately, a few layers of abstraction can simplify most of this complexity. Stay tuned for an overview of how I designed a Rust API to enforce correct and predictable behavior.

Rust API Bindings: Core Foundation Memory Management and Mutability

2023-12-28T00:00:00+00:00

As I’m designing Rust API bindings for Core Foundation, I want the user-facing API to match The Rust Standard Library as closely as possible, and memory management is a crucial area whose design significantly impacts the API surface. There are (at least) two critical differences between Core Foundation and The Rust Standard Library in their approach to memory management:

All Core Foundation objects are allocated on the heap and are reference counted. Generally, Rust types can be stack-allocated, heap-allocated and uniquely owned, or heap-allocated with shared ownership.
Core Foundation uses different types for immutable and mutable objects, while Rust expresses mutability through the type system.

The following summarizes my exploration in this space, my design goals for memory management, and how I achieved them.

Ad Hoc Approach

For many C APIs, wrapping a pointer in a tuple struct and implementing Drop is sufficient to provide an idiomatic Rust API for a foreign interface. Consider the following example of this approach for CFString:

struct String(*const __CFString);

impl String {
  fn len(&self) -> CFIndex {
    unsafe { CFStringGetLength(self.0) }
  }
}

impl Drop for String {
  fn drop(&mut self) {
      unsafe { CFRelease(self.0.cast()) }
  }
}

This approach is straightforward, but it is not a zero-cost abstraction. Each time the Core Foundation object pointer is required, for example, in the len method, the compiler must emit a dereference of the tuple struct &self to load the Core Foundation pointer value. This indirection is unavoidable because we must define a type to implement Drop, though it is negligible in practice.

Although Core Foundation is a C-based API, many types have logical subclasses. If we were to add Rust API bindings for CFMutableString with this approach, it would require defining a new, independent type. Adding an implementation of Deref would enable the logical subclass to gain all the methods of its logical superclass through deref coercion, and the resulting Rust API would still be reasonably idiomatic.

While this is a well-trodden path^[1], I wanted to find a design that:

Is a true zero-cost abstraction.
Shows Core Foundation objects are heap-allocated through the type system (e.g., Box).
Combines Rust’s mutable references with Core Foundation’s mutable types.

Box for Core Foundation

I started exploring the design space by building equivalents of the standard library’s Box and Arc types, knowing unique ownership (à la Box) would be part of the mutability story and that shared pointers (like Arc) are a fundamental part of programming on Apple platforms.

Through this exercise, I immediately achieved my first two design goals. Consider the following sample code illustrating the approach for CFString:

struct Box<T>(NonNull<T>);

impl<T> Deref for Box<T> {
  type Target = T;

  #[inline]
  fn deref(&self) -> &Self::Target {
    unsafe { self.0.as_ref() }
  }
}

struct String;

impl String {
  fn new() -> Box<Self> { /* ... */ }

  fn len(&self) -> CFIndex {
    let cf: *const _ = self;
    unsafe { CFStringGetLength(cf.cast()) }
  }
}

Like the approach in the previous section, a tuple struct wraps the raw Core Foundation object instance pointer. But this wrapper has three essential differences.

First, the type name, Box, signals to the reader that T is heap-allocated and that the instance T is unique.

Second, it implements Deref to T, the Rust type implementing the API bindings, which is crucial in making the abstraction zero-cost. When the box is dereferenced by the compiler, for example, to call the len method, the box returns the Core Foundation pointer value as a reference to T. The reference value (i.e., &self) is bitwise identical to the Core Foundation pointer value and can be passed directly through to the C API.

The compiler dereferences the tuple struct in each approach, so why is one approach a zero-cost abstraction while the other is not?

In the previous section, &self is a reference to the tuple struct. The compiler must load the Core Foundation pointer value from the tuple struct’s field through the reference. An illustration in C may help clarify:

struct String { const struct __CFString *s; };

CFIndex String_len(const struct String *self) {
  return CFStringGetLength(self->s);
  // dereference+member access ^^ is an abstraction cost
}

struct String s = /* ... */;
CFIndex length = String_len(&s);

In this section, &self is the pointer value. The dereferencing operation is a logical process, not a physical one, that is effectively a member access. To illustrate in C:

struct Box__CFString { const struct __CFString *v; };

CFIndex String_len(const struct String *self) {
  return CFStringGetLength((const struct __CFString *)self);
}

struct Box__CFString s = /* ... */;
CFIndex length = String_len(s.v);
//        member access here ^ is zero cost

Finally, the separation of the type bindings (e.g., String) from the memory management facility (e.g., Box) enables idiomatic, zero-cost use of references to the Core Foundation type bindings. Consider potential bindings for CFArrayGetValueAtIndex. With the approach in this section, the function binding can simply cast the pointer into a reference with the array’s lifetime.

With the approach in the previous section, the bindings for this function could:

Return a new binding instance for the value, retaining and releasing the object. The new binding instance does not have a lifetime associated with the array, so the retain is necessary to guarantee that the object lives at least as long as the binding instance. In many cases, however, the retain/release is unnecessary overhead.
Use an intermediate type to associate a lifetime with the binding instance and sidestep its retain/release, which is effectively the same as the function binding for the approach in this section but requires more ceremony to eliminate the retain/release correctly..

Arc for Core Foundation

It took more exploration and trial and error to identify an approach to achieve my third design goal of combining Rust’s mutable references with Core Foundation’s mutable types.

At some point, I asked, "Why do immutable objects need exclusive ownership?" I was eventually able to convince myself that "They don’t!" Looking back, I don’t know why this wasn’t more obvious. Rust’s documentation for its Arc type clearly states:

You cannot generally obtain a mutable reference to something inside an Arc.

With that insight, developing the guidance to identify the appropriate smart pointer type was reasonably straightforward: Is the Core Foundation object instance a mutable type uniquely owned by the raw pointer (i.e., a Create or Copy function return the pointer)? If yes, use Box; otherwise use Arc.

My implementations of Box and Arc for Core Foundation are virtually identical, with the primary difference being Box also implements DerefMut, AsMut, and BorrowMut.

The combination of reference counting and mutability in the smart pointer types^[2] fulfilled my design goals and resulted in surprisingly idiomatic Rust code.

impl String {
  fn append(&mut self, s: &String) {
    let cf: *mut _ = self;
    let s: *const _ = s;
    unsafe { CFStringAppend(cf.cast(), s.cast()) };
  }
}

fn main() {
  let mut s: Box<String> = String::new();
  s.append(cfstr!("Hello, World!"));
  println!("{s}");
}

1. The "tuple struct wrapper with Drop" is the approach used by the Servo Core Foundation bindings.

2. Although I approached this as a clean-room design, similar prior art exists. In 2014, long before I heard of Rust, GitHub user SSheldon differentiated between owned and shared references in an Objective-C smart pointer.

Rust API Bindings: Core Foundation Signed/Unsigned Conversion

2023-12-27T00:00:00+00:00

Core Foundation’s canonical index type and size type, CFIndex, is signed. Foundation’s canonical index type and size type, NSUInteger, is unsigned, and Rust’s canonical type, usize, is unsigned too.

Handling CFIndex/usize (signed/unsigned) conversion is important in crafting idiomatic Rust API bindings. Before implementing an approach for my crate, I looked at how Apple handled this problem for Core Foundation↔Foundation and Foundation↔Swift to understand how they balanced performance (an unchecked bit cast) with correctness (detect and handle a sign change).

Toll-Free Bridging Approach

Many Core Foundation and Foundation types are interchangeable. CFIndex is used throughout Core Foundation, while Foundation’s equivalent interface uses NSUInteger. I don’t have access to the Foundation source code, but in peeking at the assembly (examples below), it seems Foundation effectively uses an unchecked bit cast when converting between CFIndex and NSUInteger—the values pass through without detection of a potential sign change. So, integer values with the bit at 1 << sizeof(size_t) * 8 - 1 set to 1 will be negative in the Core Foundation interface but positive in the Foundation interface.

The only acknowledgment of the type mismatch in Apple’s documentation (as far as I’m aware) is this (slightly edited) description of the location and length fields on CFRange and NSRange:

For type compatibility with the rest of the system, LONG_MAX is the maximum value you should use for location and length.

An interesting related quirk is the difference between kCFNotFound and NSNotFound. Although many Core Foundation and Foundation types are interchangeable, the semantic "not found" value is interface-dependent. kCFNotFound is defined as -1 while NSNotFound is NSIntegerMax (i.e., the maximum value of CFIndex, LONG_MAX). So, the addressable range of failable Foundation methods returning an NSRange is effectively limited to [0, LONG_MAX).

Using a signed type in the underlying Core Foundation implementation and NSNotFound's definition as the maximum signed value inhibit Foundation from utilizing the full range of the unsigned type.

Unchecked Bit Cast Examples

-[NSString length] returns an NSUInteger, but its implementation is a simple tail call into Core Foundation’s _CFStringGetLength2, which returns a CFIndex.

CoreFoundation`-[__NSCFString length]:
  b       _CFStringGetLength2

Every method in Objective-C has two implicit arguments:

self: The pointer to the object instance
_cmd: The SEL that resolved to the method

The above tail call works because _CFStringGetLength2 has one argument, the pointer to the object instance, so the Objective-C method and the Core Foundation C function have the same ABI, and no work is required to forward the arguments. (_CFStringGetLength2 ignores the second argument.)

-[NSString getCharacters:range:], on the other hand, has to do some work before and after its call to Core Foundation’s _CFStringCheckAndGetCharacters:

The Objective-C method has four arguments (self, _cmd, buffer, and range), while the Core Foundation function has three (str, range, buffer). Removing _cmd requires moving the arguments that follow it. Also, in this case, the last two arguments are swapped between the interfaces and need to be reordered.
Generally, Core Foundation does not do bounds checking, while Foundation does. Foundation calls a Core Foundation SPI (System Programming Interface) that returns an error code if the range is out of bounds so Foundation can raise an exception.

CoreFoundation`-[__NSCFString getCharacters:range:]:
  pacibsp                         ; insert PAC into LR using SP as the modifier and key B
  stp     x20, x19, [sp, #-0x20]! ; SP -= 0x20; SP[0x00] = x20; SP[0x08] = x19
  stp     x29, x30, [sp, #0x10]   ; SP[0x10] = FP; SP[0x18] = LR;
  add     x29, sp, #0x10          ; FP = SP + 0x10 (address of {FP, LR})
  mov     x8, x2                  ; x8 = buffer (temporary)
  mov     x19, x1                 ; x19 = _cmd
  mov     x20, x0                 ; x20 = self
  mov     x1, x3                  ; x1 = range.location (arg 1, part 1/2)
  mov     x2, x4                  ; x2 = range.length   (arg 1, part 2/2)
  mov     x3, x8                  ; x3 = buffer         (arg 2)
  bl      _CFStringCheckAndGetCharacters
  cbnz    w0, raiseException      ; goto raiseException if _CFStringCheckAndGetCharacters did not return 0
  ldp     x29, x30, [sp, #0x10]   ; FP = SP[0x10]; LR = SP[0x18]
  ldp     x20, x19, [sp], #0x20   ; x20 = SP[0x00]; x19 = SP[0x08]; SP += 0x20
  retab                           ; return using PAC with SP as the modifier and key B
raiseException:
  mov     x0, x20                 ; x0 = self
  mov     x1, x19                 ; x1 = _cmd
  bl      -[__NSCFString getCharacters:range:].cold.1

Although some code is required to adapt the Foundation interface to Core Foundation, there is no validation of the range’s unsigned to signed conversion.

Swift’s Approach

For Apple’s frameworks (e.g., AppKit, Foundation, UIKit, etc.), the Swift compiler imports NSUInteger as Int. To make C and Objective-C interfaces visible to Swift code, the Swift compiler "imports" a Clang module to build a Swift module, where "import" is a Swift compiler process that constructs a Swift-native representation of the compatible declarations, definitions, and types present in the Clang module.

Normally, NSUInteger imports as UInt. But, in system modules (i.e., modules found under a directory given by an -isystem flag), Swift silently retypes NSUInteger to Int unless the NSUInteger declares the type of an enum. This retyping operation occurs during the construction of the Swift module. The compiler does not record any metadata about this change, and the operation is not visible to other parts of the compiler. Therefore, any thunks emitted by the compiler to facilitate crossing the language boundary do not check for a potential sign change.

Down the Rabbit Hole

I looked at the Swift compiler implementation to see under what conditions the change from unsigned to signed took place and how it was implemented.

Swift’s ClangImporter's shouldAllowNSUIntegerAsInt member function contains the main logic to determine if the compiler should change the type of NSUInteger to Int. It returns true if:
- The declaration is from a system module.
- And the declaration’s name does not contain Unsigned or unsigned, which is a special case to preserve NSUInteger for +[NSNumber numberWithUnsignedInteger:], -[NSNumber initWithUnsignedInteger:], and -[NSNumber unsignedIntegerValue].
There are two ways to identify a Clang module as a system module:
- Its module map has the [system] attribute.
- The compiler loaded the module map from a system directory.
  1. In this case, the loading of the module map occurs when resolving header search paths.
  2. The module inherits the IsSystem flag from the directory containing its module map.
  3. Any directory that’s not a user directory is a system directory.
  4. Clang identifies non-user directories as those belonging to one of its system directory groups.
  5. The compiler invocation arguments identify which directories belong to the system directory groups.

My Crate’s Approach

In considering various signed/unsigned conversion approaches for my Core Foundation Rust API bindings, I evaluated Foundation’s and Swift’s approach (transparent retyping) with Rust’s behavior considered undefined. Although Foundation’s and Swift’s approaches may lead to an unexpected sign change, they are not considered unsafe by Rust’s definition. The only potentially related undefined behavior is "Calling a function with the wrong call ABI," but signed-ness is not generally considered part of the C ABI.

I introduced two traits to facilitate signed/unsigned conversion:

ExpectFrom performs the signed/unsigned conversion and panics if the conversion fails. Implementations are a convenience wrapper for ::try_from(value).expect(""), which, while trivial, reduces the number of ad hoc expects in bindings code to improve readability. This trait primarily facilitates conversions from idiomatic Rust types into native Core Foundation types. It provides a user-visible signal if CFIndex cannot represent an index or size.
FromUnchecked performs the signed/unsigned conversion and assumes the result is correct, emulating the transparent retyping approach of Foundation and Swift. This trait primarily facilitates conversions from native Core Foundation types into idiomatic Rust types where it’s reasonable to assume the value is in bounds.

If a sign change goes undetected, safe Rust code will panic. Unsafe code must ensure all values are in bounds for the given domain so an undetected sign change does not impose any additional burden, assuming a sign change would cause the value to go out of bounds.

Objective-C Internals: Release

2023-10-01T00:00:00+00:00

Objective-C manages memory using a reference counting approach. This post will look at the release operation, which removes a reference count from an object instance. The previous post covered the retain implementation, which adds a reference count to an object instance. The retain and release implementations are similar because they are inverse operations. I’ll refer back to the retain post, where the discussion is similar, so this post can focus on the unique aspects of retain.

Entry Points

There are two interfaces for reference counting operations: the long-standing NSObject API and a compiler-private API used by ARC, both of which call into a core implementation. The following two subsections will examine each interface’s release implementation, and the next section will discuss the core implementation.

NSObject

Like -[NSObject retain], -[NSObject release] is trivial—it simply calls _objc_rootRelease() to release self.

runtime/NSObject.mm lines 2544-2546

- (void)release {
  _objc_rootRelease(self);
}

The term root, as discussed in the retain post, indicates the operation is occurring via a -release message received by the root class in the object’s class hierarchy.

Next, the _objc_rootRelease function, which is also trivial, calls objc_object::rootRelease().

runtime/NSObject.mm lines 1883-1889

void _objc_rootRelease(id obj) {
  ASSERT(obj);
  obj->rootRelease();
}

Finally, objc_object::rootRelease() calls an overload of rootRelease.

runtime/objc-object.h lines 729-733

bool objc_object::rootRelease() {
  return rootRelease(true, RRVariant::Fast);
}

The overload called here is the core implementation, which has two parameters:

performDealloc specifies whether the release operation should deallocate the object instance if the retain count reaches zero. The runtime always passes true for this parameter unless the _objc_rootReleaseWasZero() SPI^[1] (system programming interface for first-party use, as opposed to application programming interface for third-party use) is performing the release.
variant provides context about the call path, enabling the core implementation to elide unnecessary work. Releases performed through NSObject use RRVariant::Fast to skip the check for whether the class has a custom reference counting implementation because the operation occurring through the root class is, by definition, not custom.

Automatic Reference Counting

When ARC is enabled, the compiler performs reference counting operations through a compiler-private API added for ARC as a performance optimization (also discussed in the retain post).

runtime/NSObject.mm lines 1780-1786

void objc_release(id obj) {
  if (_objc_isTaggedPointerOrNil(obj)) return;
  return obj->release();
}

If the object pointer value references an object on the heap, derived through the same ceremony as retain, the function calls objc_object::release() to perform the release operation.

runtime/objc-object.h lines 709-716

inline void objc_object::release() {
  ASSERT(!isTaggedPointer());
  rootRelease(true, RRVariant::FastOrMsgSend);
}

This function calls the core implementation (though root in rootRelease is a misnomer at this point) with:

true for performDealloc, for the same reason discussed above in the NSObject entry point.
RRVariant::FastOrMsgSend for variant. No introspection, whether direct (see rootRelease below) or indirect (via a message send, see NSObject above), has occurred, so it’s not yet known whether the object’s class overrides any of the reference counting methods (hence the function’s name does not contain the term root).

The MsgSend part of the variant instructs the core implementation to do the introspection necessary to determine whether the object’s class overrides the reference counting methods. If it does, the core implementation performs the release operation by sending the object a -release message (which may re-enter the runtime via -[NSObject release]).

rootRelease

The objc_object::rootRelease(bool, RRVariant) function is on the larger side, so we’ll analyze it piece by piece.

runtime/objc-object.h line 744

if (slowpath(isTaggedPointer())) return (id)this;

Although the ARC entry point checks for a tagged pointer, the NSObject entry point does not. It’s not immediately apparent to me why the NSObject implementation doesn’t perform this check, but it has to happen somewhere, and in this version of the runtime, it’s here.

Next, the runtime loads the object’s isa value^[2].

runtime/objc-object.h lines 746-750

bool sideTableLocked = false;
isa_t newisa, oldisa;
oldisa = LoadExclusive(&isa().bits);

If the compiler-private API was the entry point for the release operation, the runtime must check whether the class overrides any reference counting methods^[3].

runtime/objc-object.h lines 752-764

if (variant == RRVariant::FastOrMsgSend) {
  // These checks are only meaningful for objc_release()
  // They are here so that we avoid a re-load of the isa.
  if (slowpath(oldisa.getDecodedClass(false)->hasCustomRR())) {
    ClearExclusive(&isa().bits);
    if (oldisa.getDecodedClass(false)->canCallSwiftRR()) {
      swiftRelease.load(memory_order_relaxed)((id)this);
      return true;
    }
    ((void(*)(objc_object *, SEL))objc_msgSend)(this, @selector(release));
    return true;
  }
}

If a class has a custom reference counting implementation, the runtime sends the object a -release message to fulfill the ARC-initiated release operation. Note the object may then call -[NSObject release], but this code block will not execute again as the variant will be RRVariant::Fast.

The return value of true in the message send variant is defensive. It doesn’t make sense for a class to implement its own reference counting mechanism and call the _objc_rootReleaseWasZero() SPI (the only entry point utilizing the return value). If a class has its own reference counting mechanism, then, by definition, it knows when the reference count reaches zero.

Suppose a class implementation uses the SPI with its own reference counting mechanism. In that case, the process will almost certainly crash shortly after the first release of an instance of the class—the class implementation would deallocate the instance when the SPI returns true, leaving all other objects that previously retained the instance with a dangling pointer.

Continuing to the next block.

runtime/objc-object.h lines 766-773

if (slowpath(!oldisa.nonpointer)) {
  // a Class is a Class forever, so we can perform this check once
  // outside of the CAS loop
  if (oldisa.getDecodedClass(false)->isMetaClass()) {
    ClearExclusive(&isa().bits);
    return false;
  }
}

Class objects are never deallocated and do not require reference counting. So, if the object is a class object, the function returns it without performing any further work.

Compare and Swap Loop

The compare-and-swap loop is the heart of the release implementation. It starts, perhaps unexpectedly, with a goto label. The Full Variant subsection below discusses this function’s use of goto.

runtime/objc-object.h lines 775-777

retry:
do {
  newisa = oldisa;

The loop first sets newisa to the current isa value (i.e., oldisa), which the following steps will update to reflect the decremented retain count.

Then, the loop checks if the object instance has a non-pointer isa. If it does not, the retain count is recorded in a side table^[4]. This check is performed in the loop because if this thread loses a compare-and-swap, it could be due to another thread mutating the object in a way that removed its use of a non-pointer isa.

runtime/objc-object.h lines 778-781

  if (slowpath(!newisa.nonpointer)) {
    ClearExclusive(&isa().bits);
    if (tryRetain) return sidetable_tryRetain() ? (id)this : nil;
    else return sidetable_retain(sideTableLocked);
  }

Next, the loop checks to see if it lost another race.

runtime/objc-object.h lines 782-788

  if (slowpath(newisa.isDeallocating())) {
    ClearExclusive(&isa().bits);
    if (sideTableLocked) {
      ASSERT(variant == RRVariant::Full);
      sidetable_unlock();
    }
    return false;
  }

An object may be deallocating while a thread is attempting to release it in (at least) two scenarios:

Another thread released the object, causing it to deallocate, usually due to a race condition that occurs when a process concurrently reads from and writes to a strong, nonatomic property. Everything about this scenario is undefined behavior.
Logic in -dealloc causes a release to be performed (e.g., the -dealloc implementation passes self to a clean-up routine where the ARC compiler emits a retain/release pair). This scenario is not a race condition like the case above because the release occurred on the same thread executing the deallocation.

If the _objc_rootReleaseWasZero() SPI performed the release, the return value of false indicates the caller should not initiate deallocation, as the object is already deallocating. The return value is otherwise unused by the NSObject and ARC entry points.

Finally, we get to the actual decrement.

runtime/objc-object.h lines 791-797

  // don't check newisa.fast_rr; we already called any RR overrides
  uintptr_t carry;
  newisa.bits = subc(newisa.bits, RC_ONE, 0, &carry);  // extra_rc--
  if (slowpath(carry)) {
    // don't ClearExclusive()
    goto underflow;
  }

Recall the non-pointer isa is a bit field with three variants. The value of RC_ONE is the bit that represents a retain count of one when viewing the bit field as an integer. The retain count is stored in the most significant bits of the isa, so an underflow, or carry, will occur if all of the retain count bits are zero (discussed in the following subsection). Otherwise, newisa contains the decremented retain count if no underflow occurs and is ready to be written back to the object instance.

runtime/objc-object.h line 798

} while (slowpath(!StoreReleaseExclusive(&isa().bits, &oldisa.bits, newisa.bits)));

If the value at &isa() matches the value at &oldisa, the compare-and-swap operation succeeds and writes the value of newisa to &isa(), and the loop ends.

Otherwise, the value of &isa() has changed since this thread loaded it into oldisa. The compare-and-swap operation fails and writes the new value at &isa() to &oldisa. The loop continues until the thread wins a compare-and-swap operation or another thread changes the object state to activate one of the above return paths.

After the loop ends, the runtime checks if the retain count is zero. If it is, it deallocates the object instance.

runtime/objc-object.h lines 800-801

  if (slowpath(newisa.isDeallocating()))
    goto deallocate;

Otherwise, the object has a positive retain count. If necessary, the runtime will release the side table lock. The function ends by returning false, indicating to the _objc_rootReleaseWasZero() SPI that the object should not deallocate.

runtime/objc-object.h lines 803-808

  if (variant == RRVariant::Full) {
    if (slowpath(sideTableLocked)) sidetable_unlock();
  } else {
    ASSERT(!sideTableLocked);
  }
  return false;

The Full Variant

If the retain count underflows the bits in the non-pointer isa, the runtime reverts the changes to newisa. Then, it checks whether any retain counts previously overflowed to the side table.

runtime/objc-object.h lines 810-816

underflow:
// newisa.extra_rc-- underflowed: borrow from side table or deallocate
newisa = oldisa; // abandon newisa to undo the decrement

if (slowpath(newisa.has_sidetable_rc)) {

If no retain counts overflowed to the side table, no retain counts remain, so the release deallocates the object instance, though I don’t think this can happen in practice as it would imply an over-release. Either there are retain counts in the side table, or the retain count reached zero and the above code path deallocated the object instance. In my opinion, it would be cleaner if the runtime trapped in this case, as the process will likely crash when -dealloc gets called for a second time.

If retain counts did previously overflow to the side table, the runtime checks whether this function invocation has the Fast or FastOrMsgSend variant. If so, it stops its attempt at the release operation and passes the buck to rootRelease_underflow().

runtime/objc-object.h lines 817-820

  if (variant != RRVariant::Full) {
    ClearExclusive(&isa().bits);
    return rootRelease_underflow(performDealloc);
  }

The function immediately calls back into objc_object::rootRelease(bool, RRVariant) with the Full variant.

runtime/NSObject.mm lines 1379-1383

NEVER_INLINE uintptr_t objc_object::rootRelease_underflow(bool performDealloc) {
  return rootRelease(performDealloc, RRVariant::Full);
}

I speculated in the retain post the purpose of this function is to provide a frame in stack traces to help Apple engineers troubleshoot release crashes in the runtime, as the interplay of side table locking (which uses a non-reentrant spin lock) can be challenging to reason about.

If the release count decrement underflows with the Full variant, the runtime obtains a side table lock.

runtime/objc-object.h lines 822-832

  // Transfer retain count from side table to inline storage.
  if (!sideTableLocked) {
    ClearExclusive(&isa().bits);
    sidetable_lock();
    sideTableLocked = true;
    // Need to start over to avoid a race against the nonpointer -> raw pointer transition.
    oldisa = LoadExclusive(&isa().bits);
    goto retry;
  }

Acquiring the side table lock may cause the thread to suspend, so the runtime first removes its exclusive monitor on the isa address, which is required to use the exclusive monitor correctly. From the ARM Architecture Reference Manual (emphasis mine):

The exclusives support a single outstanding exclusive access for each processor thread that is executed. … If the target address of an STREX (store exclusive) is different from the preceding LDREX (load exclusive) in the same thread of execution, behavior can be unpredictable. As a result, an LDREX/STREX pair can only be relied upon to eventually succeed if they are executed with the same address. Where a context switch… might change the thread of execution, a CLREX instruction… must be executed to avoid unwanted effects…

After obtaining the side table lock, the runtime reloads the isa value and starts the compare-and-swap loop again to perform the decrement. A reload of the isa is necessary because another thread may have changed the isa while this thread was waiting to acquire the side table lock.

Finally, if the decrement again results in an underflow, it’s safe for the runtime to load any additional retain counts from the side table.

runtime/objc-object.h lines 834-835

  // Try to remove some retain counts from the side table.
  auto borrow = sidetable_subExtraRC_nolock(RC_HALF);

sidetable_subExtraRC_nolock() returns a SidetableBorrow struct (borrow in the sense of taking the value of higher digits in a subtraction operation, not as in leasing the values from the side table), which has two fields:

borrowed: The number of retain counts taken from the side table.
remaining: The number of retain counts remaining in the side table.

The runtime first checks whether all the retain counts have been removed from the side table to perform additional bookkeeping later. Then, it checks whether the side table returned any retain counts. If the side table is empty, no retain counts remain, so the release will deallocate the object instance.

runtime/objc-object.h lines 837-839

  bool emptySideTable = borrow.remaining == 0; // we'll clear the side table if no refcounts remain there

  if (borrow.borrowed > 0) {

If the side table returned retain counts for the object instance, the runtime attempts to update the non-pointer isa with the retain counts taken from the side table.

runtime/objc-object.h lines 840-846

    // Side table retain count decreased.
    // Try to add them to the inline count.
    bool didTransitionToDeallocating = false;
    newisa.extra_rc = borrow.borrowed - 1;  // redo the original decrement too
    newisa.has_sidetable_rc = !emptySideTable;

    bool stored = StoreReleaseExclusive(&isa().bits, &oldisa.bits, newisa.bits);

The borrow.borrowed field contains the retain counts taken from the side table. The runtime subtracts one from the count (recall this is the code path for an underflow, so the release accounting has not yet occurred) and stores the value in the non-pointer isa's extra_rc field. It then updates the has_sidetable_rc bit to reflect whether the side table still has overflowed retain counts for the object instance.

It then attempts to store the new isa value. The store may fail, which is handled by the next code block.

runtime/objc-object.h lines 848-863

    if (!stored && oldisa.nonpointer) {
      // Inline update failed.
      // Try it again right now. This prevents livelock on LL/SC architectures
      // where the side table access itself may have dropped the reservation.
      uintptr_t overflow;
      newisa.bits = addc(oldisa.bits, RC_ONE * (borrow.borrowed-1), 0, &overflow);
      newisa.has_sidetable_rc = !emptySideTable;
      if (!overflow) {
        stored = StoreReleaseExclusive(&isa().bits, &oldisa.bits, newisa.bits);
        if (stored) {
          didTransitionToDeallocating = newisa.isDeallocating();
        }
      }
    }
  }

If placing the retain counts taken from the side table into the non-pointer isa fails, the runtime immediately tries again. The runtime’s StoreReleaseExclusive() function performs the load exclusive operation if the store exclusive fails, so oldisa is the most recent value. After subtracting one for this release operation, it adds the retain counts taken from the side table, updates the bit tracking if the object instance has retain counts in the side table, and then attempts to store the updated isa again. This retry is likely less than 32 instructions (meeting ARM’s recommendation; see aside below) and is more likely to succeed than the general path.

If the store is successful, the runtime sets didTransitionToDeallocating to true if the retain count has reached zero. But this can never happen in practice, as adding RC_HALF - 1 retain counts to the non-pointer isa just succeeded.

"LL/SC" in the comment refers to Load-Linked and Store-Conditional instructions, the general purpose name for the AArch64 lxdr (load exclusive) and stxr (store exclusive) instructions. Exclusive refers to ARM’s exclusive monitor synchronization primitive and does not imply anything about execution behavior (i.e., nothing prevents other processors or cores from reading from or writing to the address).

The store instruction can fail in several circumstances:

Another processor or core has written to the address range associated with the most recent load exclusive operation.
A context switch occurred between the load exclusive and store exclusive operation (e.g., interrupt, thread preemption), and the handler routine cleared the exclusive monitor.
A subroutine performed another load exclusive/store exclusive operation, invalidating the previous load exclusive operation.

When the comment mentions the side table access may have dropped the reservation, it could be due to any of the points above.

ARM recommends 128 byte limit between the load exclusive and store exclusive instructions to minimize the chances a context switch clears the monitor during the operation. I haven’t measured the number of machine instructions here, but I’d be willing to bet there are more than 32 instructions between the load and store in the main loop.

I could only contrive one scenario where a live lock may occur: one thread continuously retains and releases the object, causing many writes to the isa, thus inhibiting a successful store exclusive operation on the thread dealing with the underflow. A retain/release loop could perform many iterations in the time required for a side table lookup, so without a fast path, the release operation may never finish.

If another thread performed one or more retains, no live lock would occur, as this thread should be able to decrement from that count. Or, if another thread performed one or more releases, no live lock would occur as one thread would win the race to acquire the side table lock.

If the retry did not succeed (e.g., adding RC_HALF - 1 retain counts overflowed), the runtime aborts this transaction by clearing the exclusive monitor, putting the retain counts back into the side table, and reloading the non-pointer isa before jumping back to the start of the compare-and-swap loop. It does, however, still hold the side table lock.

runtime/objc-object.h lines 865-872

  if (!stored) {
      // Inline update failed. Put the retains back in the side table.
      ClearExclusive(&isa().bits);
      sidetable_addExtraRC_nolock(borrow.borrowed);
      oldisa = LoadExclusive(&isa().bits);
      goto retry;
  }

If either of the store attempts succeeds, and the side table does not have any additional retain counts for the object instance, the runtime removes the entry for the object instance from the side table.

runtime/objc-object.h lines 874-876

  // Decrement successful after borrowing from side table.
  if (emptySideTable)
      sidetable_clearExtraRC_nolock();

Finally, if necessary, the runtime releases its side table lock and returns false to indicate the retain count did not reach zero (which is only used by the _objc_rootReleaseWasZero() SPI). The retain count cannot reach zero on this path (see above), so the release operation ends here after a successful side table update.

runtime/objc-object.h lines 878-882

  if (!didTransitionToDeallocating) {
    if (slowpath(sideTableLocked)) sidetable_unlock();
    return false;
  }
}

Otherwise, execution continues to the deallocation logic.

Deallocate

If the retain count reaches zero (or underflows and the object instance is not storing retain counts in a side table), the runtime deallocates^[5] the object.

runtime/objc-object.h lines 888-901

deallocate:
// Really deallocate.
ASSERT(newisa.isDeallocating());
ASSERT(isa().isDeallocating());

if (slowpath(sideTableLocked)) sidetable_unlock();

__c11_atomic_thread_fence(__ATOMIC_ACQUIRE);

if (performDealloc) {
  ((void(*)(objc_object *, SEL))objc_msgSend)(this, @selector(dealloc));
}
return true;

First, the runtime releases the side table lock, if necessary.

Next, it has an acquire fence. I presume this is a atomic-fence synchronization, but it’s not clear to me what release operation this fence synchronizes with. The only potentially contentious read after the fence is of the isa in the message send a few lines down, but this thread just set the isa.

I would expect writes to the isa from another thread to be undefined behavior because the retain count is zero. Such a write, though, could change the class, which would be visible to this thread because of the fence. So, as far as I can tell, the fence’s only potential effect is on the message send in quite rare and bizarre circumstances.

The fence is probably an artifact from a previous implementation that is no longer relevant, a last minute change to "fix" a memory ordering problem just before a release, an unnecessary addition, or am I misunderstanding the behavior.

Then, finally, if the release didn’t occur through the _objc_rootReleaseWasZero() SPI, a -dealloc message is sent to the object.

The release operation ends by returning true, indicating the retain count has reached zero, which is ignored by every caller except the _objc_rootReleaseWasZero() SPI.

Epilogue

When I decided to cover retain and release separately, I thought the release post would be significantly shorter than retain, but it’s 20% longer!

When the retain count overflows, the runtime keeps half of the count in the non-pointer isa and then adds half to the side table. It can quickly perform the critical write to the non-pointer isa and follow up with the expensive write to the side table. In contrast, when the retain count underflows, the runtime must take retain counts from the side table to gain the information necessary to perform the critical write to the non-pointer isa. The expensive read between the exclusive load and store increases the probability that the store may fail, which creates a unique corner case the release operation must handle. Writing is a great way to learn.

With that lesson learned, I have my fingers crossed that the next post on autorelease will be more straightforward!

1. The SPI returns true if the release results in a retain count of zero, enabling system frameworks implementing root classes to perform clean up work before deallocating the root class instance. Safari 10.1 (circa March 2017) added a use of the SPI, though the change was later reverted in Safari 11.1.

2. The rootRetain section in the retain post briefly discusses the runtime’s LoadExclusive function.

3. The rootRetain section in the retain post has a detailed discussion on the message send logic and its use of Objective-C runtime functions.

4. A future post will discuss the implementation of the retain count side table.

5. A future post will discuss object deallocation in more detail.

Objective-C Internals: Retain

2023-07-22T00:00:00+00:00

Background

OS X 10.7 and iOS 5 introduced Automatic Reference Counting, or ARC, to improve Objective-C programmer productivity by eliminating boilerplate code and reducing the surface area for reference counting bugs (leaks and over-releases).

Before ARC, the -[NSObject retain], -[NSObject release]^[1], and -[NSObject autorelease]^[2] methods were the exclusive interface to manage object reference counts. And, until OS X 10.8 and iOS 6, the NSObject implementation was part of Foundation, not the Objective-C runtime.

The designers of ARC identified a key requirement to improve the likelihood of the feature’s success, learning from Apple’s ill-fated attempt to add garbage collection to Objective-C: Automatic Reference Counting must transparently interoperate with manual reference counting in the same process without requiring recompilation of existing code (e.g., a third-party binary-only library).

In the early days of macOS, it wasn’t unheard of for some objects to override the reference counting methods^[3] to use their own implementation, often for performance reasons. ARC had to support transparent interoperability with these custom reference counting implementations to deliver on the aforementioned requirement.

Entry Points

There are two interfaces for reference counting operations: the long-standing NSObject API and a compiler-private API used by ARC, both of which call into a core implementation. The following two subsections will examine each interface’s retain implementation, and the next section will discuss the core implementation.

NSObject

The -[NSObject retain] implementation^[4] is trivial—it simply calls _objc_rootRetain to retain self.

runtime/NSObject.mm lines 2502-2504

- (id)retain {
  return _objc_rootRetain(self);
}

The term root indicates the root class in the object’s class hierarchy received the -retain message. Therefore, the class does not override -retain or the override calls the superclass method, so the retain operation is guaranteed to use the runtime’s implementation. (As we’ll see in the following section, not all entry points have this guarantee.)

Next, the _objc_rootRetain function, which is also trivial, calls objc_object::rootRetain().

runtime/NSObject.mm lines 1875-1881

id _objc_rootRetain(id obj) {
  ASSERT(obj);
  return obj->rootRetain();
}

The existence of this function is a historical artifact. In the first implementation of ARC, this function was the retain implementation, but it persisted through various refactors in subsequent releases that made it unnecessary. The only other caller of this function is the legacy Object class, which is implemented in Objective-C++, so it could call objc_object::rootRetain() directly.

Finally, objc_object::rootRetain() calls an overload of rootRetain.

runtime/objc-object.h lines 607-611

id objc_object::rootRetain() {
  return rootRetain(false, RRVariant::Fast);
}

The overload called here is the core implementation, which has two parameters:

tryRetain enables support to load weak references^[5]. The argument is false because a weak reference cannot exercise this code path. (The runtime must first load an object from a weak reference before the object can receive a message, and, by definition, the object reference obtained through the load operation is strong.)
variant provides context about the call path, enabling the core implementation to elide unnecessary work. Retains performed through NSObject use RRVariant::Fast to skip the check for whether the class has a custom reference counting implementation because performing the operation through the root class is, by definition, not custom.

Automatic Reference Counting

When ARC is enabled, the compiler performs reference counting operations through a compiler-private API added for ARC as a performance optimization. The API allows reference counting operations to call directly into the Objective-C runtime and skip the overhead of sending a message.

runtime/NSObject.mm lines 1772-1777

id objc_retain(id obj) {
  if (_objc_isTaggedPointerOrNil(obj)) return obj;
  return obj->retain();
}

The function first checks the object pointer value and returns immediately if it does not reference an object on the heap, which may occur in two cases:

The pointer nil. Sending a message to nil is legal, so this optimization of -[NSObject retain] must also support nil pointers.
The pointer is a tagged pointer. A tagged pointer is an implementation detail of the Objective-C runtime not visible to the compiler, so the compiler can not eliminate the retain operation. Tagged pointers do not participate in reference counting (there is no heap allocation to track), so there’s no need to proceed.

If the object pointer value references an object on the heap, the function calls objc_object::retain() to perform the retain operation.

runtime/objc-object.h lines 589-596

inline id objc_object::retain() {
  ASSERT(!isTaggedPointer());
  return rootRetain(false, RRVariant::FastOrMsgSend);
}

This function calls the core implementation (though root in rootRetain is a misnomer at this point) with:

false for tryRetain, for the same reason discussed above in the NSObject entry point.
RRVariant::FastOrMsgSend for variant. No introspection, whether direct (see rootRetain below) or indirect (via a message send, see NSObject above), has occurred, so it’s not yet known whether the object’s class overrides any of the reference counting methods (hence the function’s name does not contain the term root).

The MsgSend part of the variant instructs the core implementation to do the introspection necessary to determine whether the object’s class overrides the reference counting methods. If it does, the core implementation performs the retain operation by sending the object a -retain message (which may re-enter the runtime via -[NSObject retain]).

rootRetain

The objc_object::rootRetain(bool, RRVariant) function is on the larger side, so we’ll analyze it piece by piece.

runtime/objc-object.h line 622

if (slowpath(isTaggedPointer())) return (id)this;

Next, the runtime loads the object’s isa value.

runtime/objc-object.h lines 624-630

bool sideTableLocked = false;
bool transcribeToSideTable = false;
isa_t oldisa = LoadExclusive(&isa().bits);
isa_t newisa;

The isa stores the object’s retain count on all modern Apple platforms. The Objective-C runtime uses ARM’s exclusive monitor synchronization primitive to manage concurrency on the arm64 architecture, which is where the LoadExclusive function gets its name. On all other architectures, including arm64e, the Objective-C runtime uses C11 atomics. (I’m unsure whether arm64 or arm64e is the outlier case here or why.)

If the compiler-private API was the entry point for the retain operation, the runtime must check whether the class overrides any of the reference counting methods.

runtime/objc-object.h lines 632-642

if (variant == RRVariant::FastOrMsgSend) {
  // These checks are only meaningful for objc_retain()
  // They are here so that we avoid a re-load of the isa.
  if (slowpath(oldisa.getDecodedClass(false)->hasCustomRR())) {
    ClearExclusive(&isa().bits);
    if (oldisa.getDecodedClass(false)->canCallSwiftRR()) {
      return swiftRetain.load(memory_order_relaxed)((id)this);
    }
    return ((id(*)(objc_object *, SEL))objc_msgSend)(this, @selector(retain));
  }
}

Custom referencing counting implementations are rare, so the runtime uses its slowpath() macro to hint to the CPU’s branch prediction unit this path is unlikely to run. getDecodedClass() returns the object’s Class object, which has a flag indicating whether the class overrides any reference counting methods. This quick check provides the necessary class introspection for the ARC entry point to support custom reference counting implementations with minimal overhead.

The term decoded in getDecodedClass() likely refers to extracting the class object pointer from the non-pointer isa. The specifics of this function depend on the target architecture:

arm64_32: The Apple Watch ABI uses 32-bit pointers, so its non-pointer isa stores an index into a table with the class object (there aren’t enough bits to store extra data with a pointer value).
- If the isa is not a pointer, the function calls classForIndex() to get the class object from the table.
- Otherwise, if the isa is a pointer, it’s a pointer to the class object, so the function returns the isa bits as-is.
On all other target architectures, the function is an alias for getClass(), which returns the class object by masking out the non-pointer bits from the isa value.
- arm64e: If isa pointer authentication is enabled, the function extracts the class object pointer value using a mask computed by the compiler. However, the function skips authentication because the caller passes false for authenticate. The documented rationale for not authenticating is that authentication occurs as part objc_msgSend, so additional authentications aren’t needed.
- Otherwise, the function extracts the class object pointer value using a static mask definition.

If a class has a custom reference counting implementation, the runtime sends the object a -retain message to fulfill the ARC-initiated retain operation. Note the object may then call -[NSObject retain], but this code block will not execute again as the variant will be RRVariant::Fast.

Pure Swift classes (i.e., classes not derived from NSObject) derive from the SwiftObject class (only on Apple platforms) for Objective-C compatibility. Swift uses its own reference counting system, so SwiftObject implements the reference counting methods to support bridging pure Swift objects to Objective-C. As an optimization for this case, the Objective-C runtime calls the Swift runtime’s swift_retain() function directly^[6] (vs. retaining the object via a message send).

Continuing to the next block.

runtime/objc-object.h lines 644-651

if (slowpath(!oldisa.nonpointer)) {
  // a Class is a Class forever, so we can perform this check once
  // outside of the CAS loop
  if (oldisa.getDecodedClass(false)->isMetaClass()) {
    ClearExclusive(&isa().bits);
    return (id)this;
  }
}

Class objects are never deallocated and do not require reference counting. So, if the object is a class object, the function returns it without performing any further work.

Compare and Swap Loop

The compare-and-swap loop is the heart of the retain implementation. It starts by (re-)initializing the loop’s start state.

runtime/objc-object.h lines 654-655

do {
  transcribeToSideTable = false;
  newisa = oldisa;

It sets newisa to the current isa value (i.e., oldisa), which the loop will update to reflect the incremented retain count. The following subsection will look at the use of transcribeToSideTable.

runtime/objc-object.h lines 656-660

  if (slowpath(!newisa.nonpointer)) {
    ClearExclusive(&isa().bits);
    if (tryRetain) return sidetable_tryRetain() ? (id)this : nil;
    else return sidetable_retain(sideTableLocked);
  }

First, the loop checks if the object instance has a non-pointer isa. If it does not, the retain count is recorded in a side table^[7]. This check is performed in the loop because if this thread loses a compare-and-swap, it could be due to another thread mutating the object in a way that removed its use of a non-pointer isa.

Next, the loop checks to see if it lost another race.

runtime/objc-object.h lines 661-673

  // don't check newisa.fast_rr; we already called any RR overrides
  if (slowpath(newisa.isDeallocating())) {
    ClearExclusive(&isa().bits);
    if (sideTableLocked) {
      ASSERT(variant == RRVariant::Full);
      sidetable_unlock();
    }
    if (slowpath(tryRetain)) {
      return nil;
    } else {
      return (id)this;
    }
  }

An object may be deallocating while a thread is attempting to retain it in (at least) three scenarios:

tryRetain is true, and this thread lost the race to load the weak object before it started deallocation. The function returns nil, indicating it could not obtain a strong reference. In this scenario, the caller, objc_loadWeakRetained(), holds a lock to the weak reference side table, preventing the object from being freed, so the read of the isa from the object pointer is defined behavior.
Another thread released the object, causing it to deallocate, usually due to a race condition that occurs when a process concurrently reads from and writes to a strong, nonatomic property. Everything about this scenario is undefined behavior. The function returns self to fulfill the -retain contract, but it will become a dangling pointer, almost certainly resulting in a crash in the thread’s near future. Hitting this code path in a race condition is "lucky." In practice, the isa bits read through the dangling pointer could have sent this function in any number of directions resulting in unpredictable effects.
Logic in -dealloc causes a retain to be performed (e.g., the -dealloc implementation passes self to a clean-up routine where the ARC compiler emits a retain/release pair). This scenario is not a race condition like the two cases above because the retain occurred on the same thread executing the deallocation. However, this scenario can lead to undefined behavior if the function performing the retain requires the object instance to survive its call scope (e.g., storing self in a strong property of another object) because the pointer will become danging when deallocation completes.

Finally, we get to the actual increment.

runtime/objc-object.h lines 674-675

  uintptr_t carry;
  newisa.bits = addc(newisa.bits, RC_ONE, 0, &carry);  // extra_rc++

Recall the non-pointer isa is a bit field with three variants. The value of RC_ONE is the bit that represents a retain count of one when viewing the bit field as an integer. The retain count is stored in the most significant bits of the isa, so an overflow, or carry, will occur if all of the retain count bits are in use (discussed in the following subsection). newisa contains the incremented retain count if no overflow occurs and is ready to be written back to the object instance.

runtime/objc-object.h line 691

} while (slowpath(!StoreExclusive(&isa().bits, &oldisa.bits, newisa.bits)));

If the value at &isa() matches the value at &oldisa, the compare-and-swap operation succeeds and writes the value of newisa to &isa(), and the loop ends.

The Full Variant

If the retain count overflows the bits in the non-pointer isa, the runtime will use a side table to store part of the retain count.

runtime/objc-object.h lines 677-690

  if (slowpath(carry)) {
    // newisa.extra_rc++ overflowed
    if (variant != RRVariant::Full) {
      ClearExclusive(&isa().bits);
      return rootRetain_overflow(tryRetain);
    }
    // Leave half of the retain counts inline and
    // prepare to copy the other half to the side table.
    if (!tryRetain && !sideTableLocked) sidetable_lock();
    sideTableLocked = true;
    transcribeToSideTable = true;
    newisa.extra_rc = RC_HALF;
    newisa.has_sidetable_rc = true;
  }

If this function invocation uses the Fast or FastOrMsgSend variant, it stops its attempt of the retain operation and passes the buck to rootRetain_overflow().

runtime/objc-object.h lines 1372-1376

NEVER_INLINE id objc_object::rootRetain_overflow(bool tryRetain) {
  return rootRetain(tryRetain, RRVariant::Full);
}

I assume the purpose of this function is to provide a frame in stack traces to help Apple engineers troubleshoot retain crashes in the runtime, as the interplay of side table locking (which uses a non-reentrant spin lock) can be challenging to reason about.

If the retain count overflows in rootRetain with the Full variant, the implementation sends half of the retain count value to a side table and keeps the other half in the non-pointer isa. The retain count is divided in half to minimize the number of side table accesses (requiring fewer CPU instructions and fewer lock acquisitions). If the implementation sent only the overflow bits to the side table, reference counting operations at the overflow boundary value could become a performance drag on the system.

runtime/objc-object.h lines 693-700

  if (variant == RRVariant::Full) {
    if (slowpath(transcribeToSideTable)) {
      // Copy the other half of the retain counts to the side table.
      sidetable_addExtraRC_nolock(RC_HALF);
    }
    if (slowpath(!tryRetain && sideTableLocked)) sidetable_unlock();
  }

The side table is updated after the compare-and-swap succeeds because another thread may win the race in moving the overflow retain count to the side table. The compare-and-swap loop acquires a lock to the side table, which prevents a race condition if another thread also attempts to read from or write to the side table.

Return self

After the compare-and-swap succeeds and, if necessary, the side table is updated, the retain operation is complete.

runtime/objc-object.h line 693-700

return (id)this;

The last step is to return self^[8] to fulfill the -[NSObject retain contract]:

As a convenience, retain returns self because it may be used in nested expressions.

Retain has evolved into a highly optimized operation since the first release of Mac OS X over 20 years ago. The same is true for release, autorelease, and dealloc, which we’ll see soon.

1. This post is long, so I decided to discuss release in the next post.

2. Autorelease is a purely additive feature built on release. I’ll discuss its implementation in a future post, given it’s not part of the core retain/release operations.

3. The Objective-C runtime considers the retain, release, autorelease, _tryRetain, _isDeallocating, retainCount, allowsWeakReference, and retainWeakReference selectors to be part of the reference counting method family. If a class overrides any of these methods, the Objective-C runtime classifies the class as having a custom reference counting implementation.

4. The implementation of NSObject moved into the Objective-C runtime in OS X 10.8 and iOS 6 to support the introduction of os_object, which enabled GCD and XPC types to participate in ARC and to work with Foundation collections. Before this move, its implementation in Foundation was likely the same.

5. Exploring the implementation of weak references is on the backlog of upcoming posts.

6. The Swift runtime depends on the Objective-C runtime, creating a reverse dependency. The Objective-C runtime resolves this by dynamically loading the swift_retain symbol from libswiftCore.dylib.

7. A future post will discuss the implementation of the retain count side table.

8. Apple started using Objective-C++ to implement the Objective-C runtime in OS X 10.7 and iOS 5, but it wasn’t until OS X 10.9 and iOS 7 that Apple used Objective-C++ to implement the object type itself. A future post will explore this approach and show how this and self are the same.

Home Lab: The Accidental System

2023-06-11T00:00:00+00:00

Over the years, I accumulated various systems, devices, and services in responding to an immediate need. However, I didn’t have a holistic, coherent plan, and the responsive, ad hoc approach created unnecessary churn, especially for the WiFi hardware. In the following sections, I’ll describe each notable investment and its motivating event, organized chronologically, to show how I accidentally stumbled into building a home lab.

Evolution of the Home Lab

Network, Version 1

I moved into a new townhouse in September 2014 and brought the only infra I had at the time: an AirPort Extreme^[1]. I installed it in the wiring enclosure on the third floor, which kept it and the cable modem out of sight. However, the install location (at the end of both the horizontal and vertical footprints of the home) and placement (in a metal box) are both sub-optimal choices for whole-house coverage, so I added a wired AirPort Express 802.11n (2nd Generation) access point on the first floor.

I didn’t have many leaf nodes in my network topology at the time (a phone, a laptop, a work laptop, an Apple TV, and probably a few others), so this setup worked well enough for a few years. (I don’t consider the leaf nodes part of the home lab, so I’ll keep any mention brief to stay on point.)

Network, Version 1.1

I had gained a few new housemates by the summer of 2017, and the questionable WiFi system needed to be improved. However, I didn’t understand the problem, nor was I familiar with contemporary solutions, so I replaced the AirPort Extreme with an AirPort Extreme 802.11ac, which somewhat improved WiFi coverage. We also connected a few devices via Ethernet to mitigate some unresolved issues, bringing overall home network connectivity to "good enough."

NAS, Version 1

With more people living in the home and less space to store things, I looked at what I could discard. I had too many hard drives, so I decided to buy a network-attached storage (NAS) device to:

Consolidate into a single device. I had 4 USB 2.0 drives, 1 FireWire 400/800 drive, 2 USB 3.0 drives, and 1 Thunderbolt 2 drive. Apple went all-in on USB-C/Thunderbolt 3 in 2016, so the clock was ticking on my ability to connect some of the drive enclosures. I was particularly concerned about the FireWire enclosure, which not only had an obsolete connector but also had two disks in a RAID 0 configuration with my most precious data, and I was not confident this would be readable by another enclosure if that were to become necessary^[2].
Improve hardware failure resiliency. I’ve had two hard drives fail while in use. One did not have any backups, and that was very painful. I thought I was safe for a while as the drive was new, but it failed within three months of purchase. The other drive failure was a backup drive, which I replaced without additional trouble.
Make the data accessible. I didn’t have a desk at home, so mounting a drive required putting it somewhere stable (all the drives were spinning disks), finding the correct power adapter and data cable, and plugging everything in. While workable for occasional use, a network mount is far easier to attach and usable anywhere in the home.

At the time, I thought of network-attached storage as just storage available via a network mount, so I wondered why so many NAS devices had a wide range of processor and RAM specs. Instead of taking time to resolve that confusion, I just bought the lowest spec’d device I could find with good reviews, the Synology DS216+II, and installed two 10 TB 7200 RPM Deskstar NAS hard drives, the largest supported capacity, in a RAID 1 configuration.

The Synology gained more responsibilities over time (which it handled well despite being so woefully under-spec’d), and the hardware is still running strong.

Network, Version 2

In the summer of 2018, we tried to set up a projector with an Apple TV on the rooftop deck, but the WiFi coverage needed improvement, and there was no Ethernet wiring nearby. Apple had officially discontinued its AirPort product line, so I decided to replace the AirPort products with a new system. I installed eero Pros (2nd Generation) where Ethernet was available and added an eero Beacon next to the rooftop deck door. Finally, WiFi coverage was excellent throughout the house and rooftop deck!

Network, Version 2.1

A few months into working from home in the summer of 2020, I was fortunate enough to have CenturyLink Fiber Internet installed the first day it was available. A 940 Mbps symmetrical connection was a massive improvement over the 50/10 Mbps Xfinity Cable Internet and $20/month less expensive!

I had previously moved to a new house and its modem/router setup differed from the townhouse: a media cabinet housed the cable modem and an eero Pro, and the eero Pro had an Ethernet connection to the wiring enclosure with a switch to connect the other access points in the house.

The Fiber Internet connection ran into the wiring cabinet from the exterior connection point, necessitating a new router placement. I thought about getting an additional eero Pro for the wiring cabinet but didn’t want to spend that much money on a router when CenturyLink provided an Actiontec C3000A for free. And I wanted to avoid installing a WiFi access point in a metal box again, especially since it was close to access points in more ideal positions.

So, I went with the path of least resistance: I used the Actiontec C3000A as the router in the wiring cabinet and reconfigured the eero Pro in the media cabinet to be just an access point.

Mac Hosts, Version 1

Apple announced its transition from Intel CPUs to Apple Silicon in the summer of 2020. I picked up a Mac mini (2018) to ensure I had an Intel Mac for testing purposes that would last through the tail end of the Intel Mac install base. And I also got a Mac mini (M1, 2020) to have an entry-level, first-generation Apple Silicon Mac for testing.

NAS, Version 1.1

In late 2020, I added two more services to the Synology, so it was no longer just network-attached storage.

We use HomeKit a lot but had a few devices that were not HomeKit compatible. After learning about Synology’s Docker support, I installed a Homebridge container and had the non-compatible devices working with HomeKit in an evening.

Before moving to Seattle, I had digitized many years of home video. Now with sufficient uplink bandwidth, and after recovering the files from the disks in the FireWire enclosure, I wanted to make the footage easily watchable by family (and at home). I experimented with Synology Video Station, which worked, but the experience was clunky. So, I tried Plex. While it was more work to set up, it was more accessible to everyone, which is why I chose it for serving video from the Synology.

Lab, Version 1

I had a hard time finding a good location for the Synology. It required Ethernet connectivity but also needed protection from accidental impact. The only location meeting those requirements was the media cabinet for the TV. But, this wasn’t an ideal location because the Synology created background noise, affecting the use of the room and watching TV.

After some consideration, I purchased a wall mount rack to install in the mechanical room. I chose a wall mount to protect the electronics from flooding by keeping them away from the floor and chose a rack for additional protection from accidental impact (vs., e.g., a shelf). The mechanical room doesn’t have Ethernet, but I was able to run a line from a nearby port in the adjacent room.

I would not recommend this approach. The rack transferred the noise from the Synology into the wall into the adjacent room (though, in this case, it was less disruptive). And the rack I chose does not have sufficient depth to support some rack mount servers.

NAS, Version 1.2

I almost omitted this section because it’s embarrassing. I did not have a regular backup of my primary computer and didn’t enable Time Machine support on the Synology until September 2021, nearly four years after I purchased it 🤦‍♂️.

Lab, Version 1.1

When we have high winds, heavy precipitation, or receive a lot of snow, we sometimes experience small power fluctuations or outages. In the late fall and early winter of 2021, we had many such events, and I was worried this might damage or corrupt the disks in the Synology. I purchased a CyberPower 1500VA/900W Uninterruptible Power Supply (UPS) to ensure future fluctuations would not affect the Synology, and to ensure the Synology would have time to shut down during an outage safely.

Network, Version 2.2

By early 2022, I was experiencing a high disruption rate in my work VPN connection. I don’t know if the Actiontec C3000A router had an increased failure rate, if my home network traffic had increased beyond the router’s capabilities, or if the problem had always existed but had become more noticeable.

As most hypotheses pointed at the router, I did not attempt to root cause the issue and replaced it with a Ubiquiti EdgeRouter 12. The results were fantastic—there was a notable increase in network throughput and no interrupted connections.

NAS, Version 1.3

Many companies are exploring calendar management and sharing solutions, but address books and contacts get less attention. I have some use cases for contact sharing, so I installed Synology Contacts to see how well it could support my needs. It does work well in limited scenarios, and I am using it for now, but I’m also looking for a more sophisticated solution.

NAS, Version 1.4

I use NetNewsWire to follow many feeds and blogs. Unfortunately, I’ve been unable to get iCloud syncing to work for unknown reasons. I wanted to sync feeds and read state across devices, so during the holiday break in December 2022, I set up a FreshRSS container on the Synology and migrated my feeds to the self-hosted service. Using NetNewsWire as my primary client and FressRSS as the backend has worked quite well.

Summary

Over the course of 8+ years, my home computing infrastructure grew from a naïve router/WiFi access point installation to an eclectic mix of hardware supporting a half dozen services. By the end of April 2023, my home lab consisted of the following:

Hardware:

CyberPower 1500VA/900W UPS
ECHOGEAR 10U Network Rack
Three eero Pros (2nd Generation) and one eero Beacon
Synology DS216+II with two 10 TB 7200 RPM Deskstar NAS hard drives
Mac mini (2018)
Mac mini (M1, 2020)
Ubiquiti EdgeRouter 12

Services:

During that time, as requirements changed, I decommissioned and replaced the following hardware:

1. I no longer have my first AirPort Extreme device and, perhaps unsurprisingly, cannot recall its model. The only thing I know for sure was that it was the short, square box and, therefore, not the sixth generation. I’m pretty sure it had gigabit Ethernet because I was annoyed the AirPort Express did not. I maybe vaguely recall it did not support a guest network and only implemented the 802.11n draft specification, which, if correct, identifies it as the AirPort Extreme 802.11n (2nd Generation).

2. Unfortunately, my suspicions were correct. The enclosure failed before I could transfer the data, and I could not mount the stripe set using a different enclosure or software RAID. Luckily, I successfully reverse-engineered the striping scheme and reconstructed the volume manually, which I’ll post about in the future.

Objective-C Internals: Associated References

2023-06-05T00:00:00+00:00

I remember eagerly awaiting the day we changed the minimum deployment target in what would become Microsoft Office 2016 for Mac to Mac OS X 10.6^[1]. Snow Leopard introduced a lot of new APIs, including Grand Central Dispatch and blocks. But, I was most excited to start using Objective-C Associative References to replace some terrible code.

The Old Way

Objective-C’s greatest strength (and weakness) is its dynamic method binding. Virtually all major third-party apps (ab)use this feature to fill a functionality gap or mitigate app/system architecture impedance mismatches.

The ability to tie an object’s lifetime to the lifetime of an object instantiated and controlled by a third party (i.e., Apple) was one such functionality gap. Before the runtime provided this feature, an app could implement this functionality by, in part, pre-patching the implementation of -[NSObject dealloc]. The following code sample shows how a third party may have implemented Associative References using this approach.

#import 
#import 

static OSSpinLock s_lock;               // for main side table
static NSMapTable *s_associatedObjects; // main side table
static IMP s_NSObject_dealloc;          // original implementation

void APAssociatedObjectSet(id object, id association) {
  id previousAssociation = nil;

  // retain does not require the lock, so do it outside of the
  // lock to minimize time spent holding the lock
  [association retain];

  OSSpinLockLock(&s_lock);
  previousAssociation = [s_associatedObjects objectForKey:object];
  if (association != nil) {
    [s_associatedObjects setObject:association forKey:object];
  } else {
    [s_associatedObjects removeObjectForKey:object];
  }
  OSSpinLockUnlock(&s_lock);

  // release outside of the lock in case this is the last
  // release, as the dealloc implementation acquires the lock
  [previousAssociation release];
}

id APAssociatedObjectGet(id object) {
  OSSpinLockLock(&s_lock);
  id association = [s_associatedObjects objectForKey:object];
  // retain the associated object to ensure it's not deallocated
  // while in use by the caller in case another thread changes the
  // associated object between now and then
  [association retain];
  OSSpinLockUnlock(&s_lock);

  return [association autorelease];
}

static void APAssociatedObject_dealloc(id self, SEL _cmd) {
  // release any associated object and remove the side table entry
  APAssociatedObjectSet(self, nil);
  (*s_NSObject_dealloc)(self, _cmd);
}

void APAssociatedObjectInitialize(void) {
  s_lock = OS_SPINLOCK_INIT;
  // The key is weak to prevent the object from becoming immortal.
  // The value is weak to explicitly control the retain count to
  // prevent dealloc reentrancy deadlocks.
  s_associatedObjects=[NSMapTable mapTableWithWeakToWeakObjects];

  // Pre-patch -[NSObject dealloc] to clean up s_associatedObjects
  Method m = class_getInstanceMethod([NSObject class],
                                     @selector(dealloc));
  s_NSObject_dealloc = method_getImplementation(m);
  method_setImplementation(m, (IMP)&APAssociatedObject_dealloc);
}

Although the implementation is only 59 lines, including white space and comments, there are a few things I want to call out:

This implementation supports 0 or 1 object associations but could support an arbitrary number of associations, like objc_setAssociatedObject(), with minor revisions. Alternatively, the client could use an NSMutableDictionary to associate an arbitrary number of objects.
Every -dealloc needs to acquire a lock to perform bookkeeping (in addition to the runtime and allocator lock acquisition(s)). We saw in a previous post that the runtime has a fast deallocation path for object instances that do not have an associated reference (in addition to other criteria), enabling it to avoid locking overhead for most cases.
Removing an association may cause the associated object to deallocate, which, in turn, may cause its associated objects to deallocate. So, the implementation must avoid recursion while holding the lock, as OSSpinLock is not reentrant.
Pre-patching -dealloc on the class of the object gaining an association is not a viable approach for two reasons:
1. A class hierarchy may have multiple patches. For example, after setting an associated object on an NSObject and another on NSView, all NSView instances, including subclasses, call into the patch twice during deallocation. An implementation could handle this case but at the cost of additional complexity.
2. Calling into the correct -dealloc from the patch becomes more challenging. Continuing with the above example, if an NSTableView is deallocating, how does the patch know whether it should call the -[NSView dealloc] implementation or the -[NSObject dealloc] implementation? (The class identity of self is always NSTableView.) A significant amount of bookkeeping would be required to track where an object is in its dealloc chain and to handle additional deallocations that occur as part of its deallocation.
Objective-C Automatic Reference Counting (ARC) didn’t debut until OS X 10.7 Lion. So I want to highlight two things that are no longer relevant to the modern Objective-C programmer:
- The retain and autorelease calls in APAssociatedObjectGet() guarantee the returned object lives through the current autorelease scope. Without this, another thread may cause the object to deallocate between its retrieval from the map table and its return to the caller.
- The use of weak in the map table’s mapTableWithWeakToWeakObjects factory method does not have ARC’s zeroing weak reference semantics. Instead, it’s the equivalent of ARC’s unsafe_unretained.
APAssociatedObjectInitialize() could have an __attribute__((constructor)) to initialize the feature before main() is called. I left that out as major apps usually have a sophisticated initialization system that would call this function.

Next, let’s see how Apple’s Objective-C runtime implements this feature.

The Apple Way

The above third-party implementation and commentary align shockingly well with Apple’s implementation. (I say shocking because I wrote it before looking up Apple’s implementation^[2].)

First, let’s look at objc_setAssociatedObject(), which simply calls _object_set_associative_reference().

runtime/objc-references.mm lines 170-219

DisguisedPtr<objc_object> disguised{(objc_object *)object};
ObjcAssociation association{policy, value};

// retain the new value (if any) outside the lock.
association.acquireValue();

bool isFirstAssociation = false;
{
  AssociationsManager manager;
  AssociationsHashMap &associations(manager.get());

  if (value) {
    auto refs_result = associations.try_emplace(disguised, ObjectAssociationMap{});
    if (refs_result.second) {
      /* it's the first association we make */
      isFirstAssociation = true;
    }

    /* establish or replace the association */
    auto &refs = refs_result.first->second;
    auto result = refs.try_emplace(key, std::move(association));
    if (!result.second) {
      association.swap(result.first->second);
    }
  } else {
    auto refs_it = associations.find(disguised);
    if (refs_it != associations.end()) {
      auto &refs = refs_it->second;
      auto it = refs.find(key);
      if (it != refs.end()) {
        association.swap(it->second);
        refs.erase(it);
        if (refs.size() == 0) {
          associations.erase(refs_it);
        }
      }
    }
  }
}

if (isFirstAssociation)
  object->setHasAssociatedObjects();

// release the old value (outside of the lock).
association.releaseHeldValue();

Given the alignment with the previous section, I’ll simply highlight key similarities and differences relative to my implementation.

DisguisedPtr is used to inhibit heap tracing in tools like leaks.
The ObjcAssociation helper object implements the association policy (storage with assign, retain, or copy semantics, and whether reads are atomic or nonatomic).
The AssociationsManager is an RAII convenience object to lock and unlock the associations spinlock (now an unfair lock).
Object associations are stored using a hash map (specifically LLVM’s DenseMap). A top-level hash map maps object pointers to an associations hash map, which maps keys to ObjcAssociations (the object and its retain policy).
Associating a nil value removes any previously associated object.
When an object gains its first association, the runtime updates its state to turn off the fast deallocation path.
The release of any previously associated object takes place outside of the lock.

Like the setter, objc_getAssociatedObject() simply calls _object_get_associative_reference(). The get path is straightforward, so there’s nothing for me to comment on! 🙊

Apple’s implementation provides a curious function, objc_removeAssociatedObjects(). I’m honestly not sure why this is a public API—the comment in runtime.h advises against using it (and for a good reason):

The main purpose of this function is to make it easy to return an object to a "pristine state”. You should not use this function for general removal of associations from objects, since it also removes associations that other clients may have added to the object. Typically you should use objc_setAssociatedObject with a nil value to clear an association.

Like the getter and setter functions, objc_removeAssociatedObjects() calls _object_remove_associations(). But, this internal function takes one additional parameter: bool deallocating, which is false when called by objc_removeAssociatedObjects(). This internal function has only one other caller, objc_destructInstance(), which, unsurprisingly, passes true for deallocating.

So, what does the deallocating flag do? A comment in the function explains its purpose:

If we are not deallocating, then SYSTEM_OBJECT associations are preserved.

Apple has an internal policy flag, OBJC_ASSOCIATION_SYSTEM_OBJECT, which prevents its associated objects from being removed by objc_removeAssociatedObjects(). You can shoot yourself in the foot using this function, but Apple will prevent you from violating their assumptions.

I suspect this is why the association key has a type of void *: pointer keys are hard to identify in Apple’s frameworks and subsequently (ab)use in third party-apps vs., for example, string keys which are easy-ish to find and use (e.g., NSNotificationName).

Tagged Pointer Objects

What happens when setting an associated object on a tagged pointer object? The effect is the same as assigning the object to a global variable with the same storage policy: the object remains until a new value is assigned. So, setting an associated object on a tagged pointer object will effectively leak the associated object.

The associated object implementation has no code paths to handle tagged pointers (not even to log a warning in the console). So, the runtime stores the tagged pointer in the associations hash map where it lives indefinitely because tagged pointer objects never deallocate.

Another side effect of tagged pointer objects is that they effectively intern all values. While some types like NSNumber are known to implement some form of interning, NSString did not have such behavior. But, the NSString tagged pointer code path is aggressive enough that localized strings loaded from disk may yield a tagged pointer object! Thus, any code setting associated objects on types of NSString may find associated objects stomping on each other if the string instances are tagged pointer objects instead of discrete instances.

Although the use of tagged pointer objects is considered an internal implementation detail, take a look at the classes that use tagged pointers and avoid using associated objects with any objects with those types.

A Closer Look At assign Storage

In writing the post, I realized I’ve been misusing this API for over a decade 🤦‍♂️. The comment next to the OBJC_ASSOCIATION_ASSIGN policy says:

Specifies a weak reference to the associated object.

As mentioned in The Old Way section, before ARC, the term weak is equivalent to ARC’s unsafe_unretained; this flag does not use ARC zeroing weak reference semantics. Take a look through the implementation for any use of weak. There isn’t any!

I have a lot of grepping and code reviewing to do this week…

Conclusion

A third-party implementation of Associated References can nearly match what Apple can do with a first-party implementation, with the main first-party advantage being the availability of a fast deallocation path for objects without associated objects. New runtime optimizations (i.e., tagged pointer objects) may cause unexpected behavior for code associating objects with objects whose uniqueness and lifetime may change across OS versions. And, historical context is essential—the assumptions underlying documentation may change over time, warping its meaning.

1. By the time Office 2016 launched, macOS 10.12 Sierra was the current release. So, following the n-2 pattern, Office’s minimum deployment target was OS X 10.10 Yosemite.

2. I did make one revision after reading through Apple’s implementation, which was to perform the associated object’s retain outside of the lock.

Site Refresh

2023-05-30T00:00:00+00:00

The new post hiatus was unintentional—an inordinate amount of time was spent designing the new theme and improving the functionality of the site.

I have not done design work in my career (perhaps implied by the topics I choose to write about), so updating the visuals to something that doesn’t make your eyes bleed took many, many attempts. I think it landed in a good place and am very appreciative of the feedback received along the way.

In addition to the new layout, theme, and art, version 3 of the site also features:

Brief summaries of each post
Rich post links (title, summary, and image)
A By Line in posts, which includes the author and estimated read time in addition to the publish date
More CSS breakpoints for improved screen utilization
An All Posts page to index blog content
Series, which collects related posts into a single page index, starting with Objective-C Internals

I also added a site changelog to document the new features, updates, and ~~churn~~ fixes. There’s a surprising number of corner cases for something as simple as this…

Now, back to posting arcane technical articles! 😁

Objective-C Internals: Tagged Pointer Objects

2023-03-19T00:00:00+00:00

Tagged pointer objects is a private feature of the Objective-C runtime that Apple uses to optimize some core Foundation classes (pun intended).

What is a tagged pointer?

Most memory allocators guarantee a minimum alignment for each allocation. For example, malloc() on Apple’s platforms guarantees an alignment that "can be used for any data type, including AltiVec- and SSE-related types."

In practice, all allocations are 16-byte aligned, so the bottom four bits of any pointer are always zero. Sometimes it is advantageous to use this fact and store additional information in those bits (which requires updating all uses of the pointer value to handle the extra bits correctly). When unused bits in a pointer store additional information, the pointer is often referred to as tagged.

The isa pointer in Objective-C objects may be tagged, the details of which were discussed in the Non-Pointer isa section of The Many Uses of isa post earlier in this series.

Tagged Pointer Objects

Tagged pointer objects in Objective-C are a special type of object pointer. If the object pointer is tagged, the data held by the class instance represented by the tagged pointer is encoded entirely into the pointer value itself. No heap allocation occurs.

Eliminating the heap allocation can significantly reduce the cost of, for example, an NSArray of NSNumbers. An NSNumber allocated on the heap uses a minimum of 16 bytes (since the allocation is 16-byte aligned) plus the 8 bytes for its pointer. However, an NSNumber encoded into a tagged pointer uses only the 8 bytes for its pointer, saving both memory and time by not calling the allocator.

Tag Identity

The bit used to identify a pointer as tagged varies by platform. objc-internal.h provides a convenience function to the runtime implementation that identifies whether a pointer is tagged. macOS and Catalyst apps on Intel processors use bit 0 to identify a tagged pointer object, and everything else uses bit 63.

#if __arm64__
  // ARM64 uses a new tagged pointer scheme...
# define _OBJC_TAG_MASK (1UL<<63)
#elif (TARGET_OS_OSX || TARGET_OS_MACCATALYST) && __x86_64__
  // 64-bit Mac - tag bit is LSB
# define _OBJC_TAG_MASK 1UL
#else
  // Everything else - tag bit is MSB
# define _OBJC_TAG_MASK (1UL<<63)
#endif

static inline bool
_objc_isTaggedPointer(const void *ptr) {
  return ((uintptr_t)ptr & _OBJC_TAG_MASK) == _OBJC_TAG_MASK;
}

Eliminating the heap allocation to store the object’s value also eliminates the storage for the isa pointer. So, the tagged pointer object scheme reserves some bits to identify the object’s class.

At the time of this writing, the Objective-C runtime has two schemes to reserve class identity bits: one reserves 3 bits for objects with 60-bit payloads, and the other reserves 11 bits for objects with 52-bit payloads.

Up to 7 class types can use the 60-bit payload variant (with the eighth type being a special case to identify the 52-bit payload variant). And up to 256 class types can use the 52-bit payload variant. objc-internal.h has an enum that provides some symbolic identity for various class identity bit values.

When the runtime requires the isa pointer for an object, it calls objc_object::getIsa()^[1] (defined in objc-object.h), which returns the isa instance variable for objects allocated on the heap and the isa pointer stored in one of the tag class arrays for tagged pointer objects.

inline Class
objc_object::getIsa() {
  if (fastpath(!isTaggedPointer())) return ISA(/*authenticated*/true);

  extern objc_class OBJC_CLASS_$___NSUnrecognizedTaggedPointer;
  uintptr_t slot, ptr = (uintptr_t)this;
  Class cls;

  slot = (ptr >> _OBJC_TAG_SLOT_SHIFT) & _OBJC_TAG_SLOT_MASK;
  cls = objc_tag_classes[slot];
  if (slowpath(cls == (Class)&OBJC_CLASS_$___NSUnrecognizedTaggedPointer)) {
      slot = (ptr >> _OBJC_TAG_EXT_SLOT_SHIFT) & _OBJC_TAG_EXT_SLOT_MASK;
      cls = objc_tag_ext_classes[slot];
  }
  return cls;
}

When system frameworks initialize at the start of a process, they call _objc_registerTaggedPointerClass() to set the Class object for the given tag value. We can observe this by adding a symbolic breakpoint for that function and print its arguments when called:

(lldb) reg re x0 x1
      x0 = 0x0000000000000003
      x1 = 0x0000000203a994f0  (void *)0x0000000203a99518: __NSCFNumber

Anatomy of a Message Send

Any code that operates on the pointer value must specifically handle tagged pointers, as unconditionally dereferencing the pointer will almost certainly result in a runtime crash.

The first step in objc_msgSend() checks for a tagged pointer to determine how to load the object’s isa pointer to find its class’s methods, similar to the objc_object:getIsa() implementation above. After the isa pointer is loaded, whether or not the pointer is tagged is immaterial to the remainder of the message send logic.

When an Objective-C class that supports tagged pointer objects receives a message, it must check whether its self pointer is tagged and handle that case appropriately. The following is my disassembly of -[NSNumber integerValue] to show, in part, how NSNumber tagged pointers work (per my interpretation of the disassembly of the following functions on macOS 12.6.2 for arm64).

@implementation __NSCFNumber
- (NSInteger)integerValue {
  return [self longValue];
}

- (long)longValue {
  long longValue;
  CFNumberGetValue((__bridge CFNumberRef)self, kCFNumberSInt64Type, &longValue);
  return longValue;
}
@end

Boolean CFNumberGetValue(CFNumberRef number, CFNumberType theType, void *valuePtr) {
  if (_objc_isTaggedPointer(number)) {
    if (_objc_getTaggedPointerTag(number) == OBJC_TAG_NSNumber) {
      long localMemory;
      valuePtr = valuePtr ?: (void *)&localMemory;

      uintptr_t value = _objc_getTaggedPointerValue(number);
      uintptr_t shift = (value & 0x08) ? 0x4 : 0x6;

      CFNumberType type = __CFNumberTypeTable[theType].canonicalType;
      if (type <= kCFNumberFloat64Type) {
        value = value >> shift;

        switch (type) {
        case kCFNumberSInt8Type:
          *(uint8_t *)valuePtr = (uint8_t)value;
          break;
        case kCFNumberSInt16Type:
          *(uint16_t *)valuePtr = (uint16_t)value;
          break;
        case kCFNumberSInt32Type:
          *(uint32_t *)valuePtr = (uint32_t)value;
          break;
        case kCFNumberSInt64Type:
          *(uint64_t *)valuePtr = (uint64_t)value;
          break;
        case kCFNumberFloat32Type:
          *(float *)valuePtr = (float)value;
          break;
        case kCFNumberFloat64Type:
          *(double *)valuePtr = (double)value;
          break;
        }
        return true;
      } else {
        return __CFNumberGetValueCompat(number, theType, valuePtr);
      }
    } else {
      theType = __CFNumberTypeTable[theType].canonicalType;
      return [(__bridge id)number _getValue:valuePtr forType:theType];
    }
  } else {
    // ...
  }
}

I’ll share a few comments and observations about the manually decompiled code above:

The private __NSCFNumber subclass (in this code path) doesn’t operate on the value of self and therefore does not need to handle the tagged pointer case. The -integerValue method acts as an alias for the longValue method, which calls into CoreFoundation to do the heavy lifting. Given CFNumberRef and NSNumber * are toll-free bridged, it makes sense to see that one type is a wrapper of the other.
Apple’s implementation of CFNumber almost certainly includes objc-internal.h for access to functions that simplify working with tagged pointer objects.
It seems that either 4 or 6 bits of the payload act as bitflags for other CFNumber features, but whatever functionality that may be is not used by this function.
The __CFNumberTypeTable maps the public-facing type values to the corresponding fixed size type, simplifying the value extraction logic.
Apple has a private type, kCFNumberSInt128Type, not handled by the switch statement, so the call to __CFNumberGetValueCompat() is necessary for that case.
Floating point numbers with a non-zero fractional value do not use the tagged pointer object optimization, given the logic in the switch statement does not handle that scenario.
I am intrigued by the call to -_getValue:forType:. It implies another private subclass uses the tag pointer object optimization, but I didn’t trace through the various code paths to attempt to identify it.

1. The use of C++ to implement the Objective-C runtime is pretty clever, in my opinion. I’ll discuss the mechanics of how that works in a future post.