# The Swift Runtime

This document describes the ABI interface to the Swift runtime, which provides
the following core functionality for Swift programs:

- memory management, including allocation and reference counting;
- the runtime type system, including dynamic casting, generic instantiation,
  and protocol conformance registration;

It is intended to describe only the runtime interface that compiler-generated
code should conform to, not details of how things are implemented.

The final runtime interface is currently a work-in-progress; it is a goal of
Swift 3 to stabilize it. This document attempts to describe both the current
state of the runtime and the intended endpoint of the stable interface.
Changes that are intended to be made before stabilization are marked with
**ABI TODO**. Entry points that only exist on Darwin platforms with
ObjC interop, and
information that only pertains to ObjC interop, are marked **ObjC-only**.

## Deprecated entry points

Entry points in this section are intended to be removed or internalized before
ABI stabilization.

### Exported C++ symbols 

**ABI TODO**: Any exported C++ symbols are implementation details that are not
intended to be part of the stable runtime interface.

### swift\_ClassMirror\_count
### swift\_ClassMirror\_quickLookObject
### swift\_ClassMirror\_subscript
### swift\_EnumMirror\_caseName
### swift\_EnumMirror\_count
### swift\_EnumMirror\_subscript
### swift\_MagicMirrorData\_objcValue
### swift\_MagicMirrorData\_objcValueType
### swift\_MagicMirrorData\_summary
### swift\_MagicMirrorData\_value
### swift\_MagicMirrorData\_valueType
### swift\_ObjCMirror\_count
### swift\_ObjCMirror\_subscript
### swift\_StructMirror\_count
### swift\_StructMirror\_subscript
### swift\_TupleMirror\_count
### swift\_TupleMirror\_subscript
### swift\_reflectAny

**ABI TODO**: These functions are implementation details of the standard
library `reflect` interface. They will be superseded by a low-level
runtime reflection API.

### swift\_stdlib\_demangleName

```
@convention(thin) (string: UnsafePointer<UInt8>,
                   length: UInt,
                   @out String) -> ()
```

Given a pointer to a Swift mangled symbol name as a byte string of `length`
characters, returns the demangled name as a `Swift.String`.

**ABI TODO**: Decouple from the standard library `Swift.String` implementation.
Rename with a non-`stdlib` naming scheme.

## Memory allocation

### TODO

```
000000000001cb30 T _swift_allocBox
000000000001c990 T _swift_allocObject
000000000001ca60 T _swift_bufferAllocate
000000000001ca70 T _swift_bufferAllocateOnStack
000000000001ca80 T _swift_bufferDeallocateFromStack
000000000001ca90 T _swift_bufferHeaderSize
000000000001cd30 T _swift_deallocBox
000000000001d490 T _swift_deallocClassInstance
000000000001cd60 T _swift_deallocObject
000000000001d4c0 T _swift_deallocPartialClassInstance
000000000001d400 T _swift_rootObjCDealloc
000000000001c960 T _swift_slowAlloc
000000000001c980 T _swift_slowDealloc
000000000001ce10 T _swift_projectBox
000000000001ca00 T _swift_initStackObject
```

## Reference counting

### TODO

```
0000000000027ba0 T _swift_bridgeObjectRelease
0000000000027c50 T _swift_bridgeObjectRelease_n
0000000000027b50 T _swift_bridgeObjectRetain
0000000000027be0 T _swift_bridgeObjectRetain_n
000000000001ce70 T _swift_release
000000000001cee0 T _swift_release_n
000000000001ce30 T _swift_retain
000000000001ce50 T _swift_retain_n
000000000001d140 T _swift_tryPin
000000000001d240 T _swift_tryRetain
0000000000027b10 T _swift_unknownRelease
0000000000027a70 T _swift_unknownRelease_n
0000000000027ad0 T _swift_unknownRetain
0000000000027a10 T _swift_unknownRetain_n
0000000000027d50 T _swift_unknownUnownedAssign
00000000000280a0 T _swift_unknownUnownedCopyAssign
0000000000027fd0 T _swift_unknownUnownedCopyInit
0000000000027ed0 T _swift_unknownUnownedDestroy
0000000000027cb0 T _swift_unknownUnownedInit
0000000000027f20 T _swift_unknownUnownedLoadStrong
00000000000281f0 T _swift_unknownUnownedTakeAssign
0000000000028070 T _swift_unknownUnownedTakeInit
0000000000027f70 T _swift_unknownUnownedTakeStrong
00000000000282b0 T _swift_unknownWeakAssign
0000000000028560 T _swift_unknownWeakCopyAssign
00000000000284e0 T _swift_unknownWeakCopyInit
00000000000283e0 T _swift_unknownWeakDestroy
0000000000028270 T _swift_unknownWeakInit
0000000000028420 T _swift_unknownWeakLoadStrong
0000000000028610 T _swift_unknownWeakTakeAssign
0000000000028520 T _swift_unknownWeakTakeInit
0000000000028470 T _swift_unknownWeakTakeStrong
000000000001d3c0 T _swift_unownedCheck
000000000001cfb0 T _swift_unownedRelease
000000000001d0a0 T _swift_unownedRelease_n
000000000001cf70 T _swift_unownedRetain
000000000001cf60 T _swift_unownedRetainCount
000000000001d2b0 T _swift_unownedRetainStrong
000000000001d310 T _swift_unownedRetainStrongAndRelease
000000000001d060 T _swift_unownedRetain_n
000000000001d1b0 T _swift_unpin
000000000001ca20 T _swift_verifyEndOfLifetime
000000000001d680 T _swift_weakAssign
000000000001d830 T _swift_weakCopyAssign
000000000001d790 T _swift_weakCopyInit
000000000001d770 T _swift_weakDestroy
000000000001d640 T _swift_weakInit
000000000001d6d0 T _swift_weakLoadStrong
000000000001d8b0 T _swift_weakTakeAssign
000000000001d800 T _swift_weakTakeInit
000000000001d710 T _swift_weakTakeStrong
000000000002afe0 T _swift_isUniquelyReferencedNonObjC
000000000002af50 T _swift_isUniquelyReferencedNonObjC_nonNull
000000000002b060 T _swift_isUniquelyReferencedNonObjC_nonNull_bridgeObject
000000000002b200 T _swift_isUniquelyReferencedOrPinnedNonObjC_nonNull
000000000002b130 T _swift_isUniquelyReferencedOrPinnedNonObjC_nonNull_bridgeObject
000000000002b2f0 T _swift_isUniquelyReferencedOrPinned_native
000000000002b290 T _swift_isUniquelyReferencedOrPinned_nonNull_native
000000000002af00 T _swift_isUniquelyReferenced_native
000000000002aea0 T _swift_isUniquelyReferenced_nonNull_native
000000000001d280 T _swift_isDeallocating
```

**ABI TODO**: `_unsynchronized` r/r entry points

## Error objects

The `ErrorType` existential type uses a special single-word, reference-
counted representation.

**ObjC-only**: The representation is internal to the runtime in order
to provide efficient bridging with the platform `NSError` and `CFError`
implementations. On non-ObjC platforms this bridging is unnecessary, and
the error object interface could be made more fragile.

To preserve the encapsulation of the ErrorType representation, and
allow for future representation optimizations, the runtime provides
special entry points for allocating, projecting, and reference
counting error values.


```
00000000000268e0 T _swift_allocError
0000000000026d50 T _swift_bridgeErrorTypeToNSError
0000000000026900 T _swift_deallocError
0000000000027120 T _swift_errorRelease
0000000000027100 T _swift_errorRetain
0000000000026b80 T _swift_getErrorValue
```

**ABI TODO**: `_unsynchronized` r/r entry points

**ABI TODO**: `_n` r/r entry points

## Initialization

### swift_once

```
@convention(thin) (Builtin.RawPointer, @convention(thin) () -> ()) -> ()
```

Used to lazily initialize global variables. The first parameter must
point to a word-sized memory location that was initialized to zero at
process start. It is undefined behavior to reference memory that has
been initialized to something other than zero or written to by anything other
than `swift_once` in the current process's lifetime. The function referenced by
the second parameter will have been run exactly once in the time between
process start and the function returns.

## Dynamic casting

```
0000000000001470 T _swift_dynamicCast
0000000000000a60 T _swift_dynamicCastClass
0000000000000ae0 T _swift_dynamicCastClassUnconditional
0000000000028750 T _swift_dynamicCastForeignClass
000000000002ae20 T _swift_dynamicCastForeignClassMetatype
000000000002ae30 T _swift_dynamicCastForeignClassMetatypeUnconditional
0000000000028760 T _swift_dynamicCastForeignClassUnconditional
00000000000011c0 T _swift_dynamicCastMetatype
0000000000000cf0 T _swift_dynamicCastMetatypeToObjectConditional
0000000000000d20 T _swift_dynamicCastMetatypeToObjectUnconditional
00000000000012e0 T _swift_dynamicCastMetatypeUnconditional
00000000000286c0 T _swift_dynamicCastObjCClass
0000000000028bd0 T _swift_dynamicCastObjCClassMetatype
0000000000028c00 T _swift_dynamicCastObjCClassMetatypeUnconditional
0000000000028700 T _swift_dynamicCastObjCClassUnconditional
0000000000028af0 T _swift_dynamicCastObjCProtocolConditional
0000000000028a50 T _swift_dynamicCastObjCProtocolUnconditional
0000000000028960 T _swift_dynamicCastTypeToObjCProtocolConditional
00000000000287d0 T _swift_dynamicCastTypeToObjCProtocolUnconditional
0000000000000de0 T _swift_dynamicCastUnknownClass
0000000000000fd0 T _swift_dynamicCastUnknownClassUnconditional
```

## Debugging

```
0000000000027140 T _swift_willThrow
```

## Objective-C Bridging

**ObjC-only**.

**ABI TODO**: Decouple from the runtime as much as possible. Much of this
should be implementable in the standard library now.

```
0000000000003b60 T _swift_bridgeNonVerbatimFromObjectiveC
0000000000003c80 T _swift_bridgeNonVerbatimFromObjectiveCConditional
00000000000037e0 T _swift_bridgeNonVerbatimToObjectiveC
00000000000039c0 T _swift_getBridgedNonVerbatimObjectiveCType
0000000000003d90 T _swift_isBridgedNonVerbatimToObjectiveC
```

## Code generation

Certain common code paths are implemented in the runtime as a code size
optimization.

```
0000000000023a40 T _swift_assignExistentialWithCopy
000000000001dbf0 T _swift_copyPOD
000000000001c560 T _swift_getEnumCaseMultiPayload
000000000001be60 T _swift_getEnumCaseSinglePayload
000000000001c400 T _swift_storeEnumTagMultiPayload
000000000001bf90 T _swift_storeEnumTagSinglePayload
```

## Type metadata lookup

These functions look up metadata for types that potentially require runtime
instantiation or initialization, including structural types, generics, classes,
and metadata for imported C and Objective-C types.

**ABI TODO**: Instantiation APIs under flux as part of resilience work. For
nominal types, `getGenericMetadata` is likely to become an implementation
detail used to implement resilient per-type metadata accessor functions.

```
0000000000023230 T _swift_getExistentialMetatypeMetadata
0000000000023630 T _swift_getExistentialTypeMetadata
0000000000023b90 T _swift_getForeignTypeMetadata
000000000001ef30 T _swift_getFunctionTypeMetadata
000000000001eed0 T _swift_getFunctionTypeMetadata1
000000000001f1f0 T _swift_getFunctionTypeMetadata2
000000000001f250 T _swift_getFunctionTypeMetadata3
000000000001e940 T _swift_getGenericMetadata
000000000001e9c0 T _swift_getGenericMetadata1
000000000001ea60 T _swift_getGenericMetadata2
000000000001eb00 T _swift_getGenericMetadata3
000000000001eba0 T _swift_getGenericMetadata4
0000000000022fd0 T _swift_getMetatypeMetadata
000000000001ec50 T _swift_getObjCClassMetadata
000000000001e6b0 T _swift_getResilientMetadata
0000000000022260 T _swift_getTupleTypeMetadata
00000000000225a0 T _swift_getTupleTypeMetadata2
00000000000225d0 T _swift_getTupleTypeMetadata3
0000000000028bc0 T _swift_getInitializedObjCClass
```

**ABI TODO**: Fast entry points for `getExistential*TypeMetadata1-3`. Static
metadata for `Any` and `AnyObject` is probably worth considering too.

## Type metadata initialization

Calls to these entry points are emitted when instantiating type metadata at
runtime.

**ABI TODO**: Initialization APIs under flux as part of resilience work.

```
000000000001e3e0 T _swift_allocateGenericClassMetadata
000000000001e620 T _swift_allocateGenericValueMetadata
0000000000022be0 T _swift_initClassMetadata_UniversalStrategy
000000000001c100 T _swift_initEnumMetadataMultiPayload
000000000001bd60 T _swift_initEnumValueWitnessTableSinglePayload
0000000000022a20 T _swift_initStructMetadata_UniversalStrategy
0000000000024230 T _swift_initializeSuperclass
0000000000028b60 T _swift_instantiateObjCClass
```

## Metatypes

```
0000000000000b60 T _swift_getDynamicType
0000000000022fb0 T _swift_getObjectType
00000000000006f0 T _swift_getTypeName
00000000000040c0 T _swift_isClassType
0000000000003f50 T _swift_isClassOrObjCExistentialType
0000000000004130 T _swift_isOptionalType
00000000000279f0 T _swift_objc_class_usesNativeSwiftReferenceCounting
000000000002b340 T _swift_objc_class_unknownGetInstanceExtents
000000000002b350 T _swift_class_getInstanceExtents
0000000000004080 T _swift_class_getSuperclass
```

**ABI TODO**: getTypeByName entry point.

**ABI TODO**: Should have a `getTypeKind` entry point with well-defined enum
constants to supersede `swift_is*Type`.

**ABI TODO**: Rename class metadata queries with a consistent naming scheme.

## Protocol conformance lookup

```
0000000000002ef0 T _swift_registerProtocolConformances
0000000000003060 T _swift_conformsToProtocol
```

## Error reporting

```
000000000001c7d0 T _swift_reportError
000000000001c940 T _swift_deletedMethodError
```

## Standard metadata

The Swift runtime exports standard metadata objects for `Builtin` types
as well as standard value witness tables that can be freely adopted by
types with common layout attributes. Note that, unlike public-facing types,
the runtime does not guarantee a 1:1 mapping of Builtin types to metadata
objects, and will reuse metadata objects to represent builtins with the same
layout characteristics.

```
000000000004faa8 S __TMBB
000000000004fab8 S __TMBO
000000000004f9f8 S __TMBb
000000000004f9c8 S __TMBi128_
000000000004f998 S __TMBi16_
000000000004f9d8 S __TMBi256_
000000000004f9a8 S __TMBi32_
000000000004f9b8 S __TMBi64_
000000000004f988 S __TMBi8_
000000000004f9e8 S __TMBo
000000000004fac8 S __TMT_
000000000004f568 S __TWVBO
000000000004f4b0 S __TWVBb
000000000004f0a8 S __TWVBi128_
000000000004eec8 S __TWVBi16_
000000000004f148 S __TWVBi256_
000000000004ef68 S __TWVBi32_
000000000004f008 S __TWVBi64_
000000000004ee28 S __TWVBi8_
000000000004f1e8 S __TWVBo
000000000004f778 S __TWVFT_T_
000000000004f3f8 S __TWVMBo
000000000004f8e8 S __TWVT_
000000000004f830 S __TWVXfT_T_
000000000004f620 S __TWVXoBO
000000000004f2a0 S __TWVXoBo
000000000004f6d8 S __TWVXwGSqBO_
000000000004f358 S __TWVXwGSqBo_
```

## Tasks

- Moving to per-type instantiation functions instead of using
  `getGenericMetadata` directly

- `swift_objc_` naming convention for ObjC

- Alternative ABIs for retain/release

- Unsynchronized retain/release

- Nonnull retain/release

- Decouple dynamic casting, bridging, and reflection from the standard library