Skip to content

Commit acbdfef

Browse files
rauhulrauhul
authored
Remove stale embedded swift documentation (swiftlang#82395)
Update in-tree markdown files with links to the new Embedded Swift documentation home.
1 parent 9b9db58 commit acbdfef

File tree

7 files changed

+9
-751
lines changed

7 files changed

+9
-751
lines changed

‎docs/EmbeddedSwift/ABI.md‎

Lines changed: 1 addition & 56 deletions
Original file line numberDiff line numberDiff line change
@@ -1,58 +1,3 @@
11
# Embedded Swift -- ABI
22

3-
**⚠️ Embedded Swift is experimental. This document might be out of date with latest development.**
4-
5-
**‼️ Use the latest downloadable 'Trunk Development' snapshot from swift.org to use Embedded Swift. Public releases of Swift do not yet support Embedded Swift.**
6-
7-
For an introduction and motivation into Embedded Swift, please see "[A Vision for Embedded Swift](https://github.com/swiftlang/swift-evolution/blob/main/visions/embedded-swift.md)", a Swift Evolution document highlighting the main goals and approaches.
8-
9-
## ABI stability
10-
11-
The ABI of code generated by Embedded Swift is not currently stable. For a concrete compiler version, it will be consistent, but do not mix code built with different compiler versions.
12-
13-
Similarly, do not mix Embedded Swift code with full Swift code, as the ABIs are different. Details are described in the following sections.
14-
15-
## Symbol mangling under Embedded Swift
16-
17-
Since Swift 5.0, the stable ABI mangling schema uses the `$s` prefix on all Swift symbols. Because Embedded Swift's ABI differs from the stable ABI, and furthermore because it's not expected to be stable, Embedded Swift uses a `$e` mangling prefix. The logic and structure of the mangling stays the same, the only difference is the prefix.
18-
19-
## Calling convention of Embedded Swift
20-
21-
As of today, Embedded Swift has identical calling convention to full Swift. However, this does not need to continue in the future, and there should not be expectations that the ABI of Embedded Swift is compatible with full Swift.
22-
23-
The compiler respects the ABIs and calling conventions of C and C++ when interoperating with code in those languages. Calling C/C++ functions from Embedded Swift code is supported, and similarly exporting Swift code via `@_extern`, `@_cdecl` or `@_expose` will match the right calling conventions that C/C++ expects.
24-
25-
## Metadata ABI of Embedded Swift
26-
27-
Embedded Swift eliminates almost all metadata compared to full Swift. However, class and existential metadata are still used, because those serve as vtables and witness tables for dynamic dispatch of methods to implement runtime polymorphism with classes and existentials.
28-
29-
### Class Metadata ABI
30-
31-
The layout of Embedded Swift's class metadata is *different* from full Swift:
32-
33-
- The **super pointer** pointing to the class metadata record for the superclass is stored at **offset 0**. If the class is a root class, it is null.
34-
- The **destructor pointer** is stored at **offset 1**. This function is invoked by Swift's deallocator when the class instance is destroyed.
35-
- The **ivar destroyer** is stored at **offset 2**. This function is invoked to destroy instance members when creation of the object is cancelled (e.g. in a failable initializer).
36-
- Lastly, the **vtable** is stored at **offset 3**: For each Swift class in the class's inheritance hierarchy, in order starting
37-
from the root class and working down to the most derived class, the function pointers to the implementation of every method of the class in declaration order in stored.
38-
39-
### Witness Tables ABI
40-
41-
The layout of Embedded Swift's witness tables is *different* from full Swift:
42-
43-
- The first word is always a null pointer (TODO: it can be eliminated)
44-
- The following words are witness table entries which can be one of the following:
45-
- A method witness: a pointer to the witness function.
46-
- An associated conformance witness: a pointer to the witness table of the associated conformance
47-
48-
Note that witness tables in Embedded Swift do not contain associated type entries.
49-
50-
Witness functions are always specialized for concrete types. This also means that parameters and return values are passed directly (if possible).
51-
52-
## Heap object layout in Embedded Swift
53-
54-
Heap objects have the following layout in Embedded Swift:
55-
56-
- The **isa pointer** (pointer to the class metadata) is stored at **offset 0**.
57-
- The **refcount** is stored inline at **offset 1**.
58-
- Normal stored properties follow.
3+
Embedded Swift documentation has moved to: [Swift.org](https://docs.swift.org/embedded/documentation/embedded).

‎docs/EmbeddedSwift/EmbeddedSwiftStatus.md‎

Lines changed: 1 addition & 75 deletions
Original file line numberDiff line numberDiff line change
@@ -1,77 +1,3 @@
11
# Embedded Swift -- Status
22

3-
**⚠️ Embedded Swift is experimental. This document might be out of date with latest development.**
4-
5-
**‼️ Use the latest downloadable 'Trunk Development' snapshot from swift.org to use Embedded Swift. Public releases of Swift do not yet support Embedded Swift.**
6-
7-
For an introduction and motivation into Embedded Swift, please see "[A Vision for Embedded Swift](https://github.com/swiftlang/swift-evolution/blob/main/visions/embedded-swift.md)", a Swift Evolution document highlighting the main goals and approaches.
8-
9-
## Embedded Swift Language Features
10-
11-
| **Language Feature** | **Currently Supported In Embedded Swift** |
12-
|-------------------------------------------------------|------------------------------------------------------------------------------------|
13-
| *Anything not listed below* | Yes |
14-
| Library Evolution (resilience) | No, intentionally unsupported long-term |
15-
| Objective-C interoperability | No, intentionally unsupported long-term |
16-
| Non-WMO builds | No, intentionally unsupported long-term (WMO should be used) |
17-
| Existentials (values of protocol types) | Only class-bound existentials (for protocols derived from AnyObject) are supported |
18-
| Any | No, currently disallowed |
19-
| AnyObject | Yes |
20-
| Metatypes | No, currently only allowed as unused arguments (type hints) |
21-
| Untyped throwing | No, intentionally unsupported long-term (typed throwing should be used instead) |
22-
| Weak references, unowned references | No |
23-
| Non-final generic class methods | No, intentionally unsupported long-term, see <[Embedded Swift -- Non-final generic methods](NonFinalGenericMethods.md)>|
24-
| Parameter packs (variadic generics) | No, not yet supported |
25-
26-
## Embedded Standard Library Breakdown
27-
28-
This status table describes which of the following standard library features can be used in Embedded Swift:
29-
30-
| **Swift Standard Library Feature** | **Currently Supported In Embedded Swift?** |
31-
|------------------------------------------------------------|-----------------------------------------------------|
32-
| Array (dynamic heap-allocated container) | Yes |
33-
| Array slices | Yes |
34-
| assert, precondition, fatalError | Partial, only StaticStrings can be used as a failure message |
35-
| Bool, Integer types, Float types | Yes |
36-
| Codable, Encodable, Decodable | No |
37-
| Collection + related protocols | Yes |
38-
| Collection algorithms (sort, reverse) | Yes |
39-
| CustomStringConvertible, CustomDebugStringConvertible | Yes, except those that require reflection (e.g. Array's .description) |
40-
| Dictionary (dynamic heap-allocated container) | Yes |
41-
| Floating-point conversion to string | No |
42-
| Floating-point parsing | No |
43-
| FixedWidthInteger + related protocols | Yes |
44-
| Hashable, Equatable, Comparable protocols | Yes |
45-
| InputStream, OutputStream | No |
46-
| Integer conversion to string | Yes |
47-
| Integer parsing | Yes |
48-
| KeyPaths | Partial (only compile-time constant key paths to stored properties supported, only usable in MemoryLayout and UnsafePointer APIs) |
49-
| Lazy collections | Yes |
50-
| ManagedBuffer | Yes |
51-
| Mirror (runtime reflection) | No, intentionally unsupported long-term |
52-
| Objective-C bridging | No, intentionally unsupported long-term |
53-
| Optional | Yes |
54-
| print / debugPrint | Partial (only String, string interpolation, StaticStrings, integers, pointers and booleans, and custom types that are CustomStringConvertible) |
55-
| Range, ClosedRange, Stride | Yes |
56-
| Result | Yes |
57-
| Set (dynamic heap-allocated container) | Yes |
58-
| SIMD types | Yes |
59-
| StaticString | Yes |
60-
| String (dynamic) | Yes |
61-
| String interpolations | Partial (only strings, integers, booleans, and custom types that are CustomStringConvertible can be interpolated) |
62-
| Unicode | Yes |
63-
| Unsafe\[Mutable\]\[Raw\]\[Buffer\]Pointer | Yes |
64-
| VarArgs | No |
65-
66-
## Non-stdlib Features
67-
68-
This status table describes which of the following Swift features can be used in Embedded Swift:
69-
70-
| **Swift Feature** | **Currently Supported In Embedded Swift?** |
71-
|------------------------------------------------------------|-----------------------------------------------------|
72-
| Synchronization module | Partial (only Atomic types, no Mutex) |
73-
| Swift Concurrency | Partial, experimental (basics of actors and tasks work in single-threaded concurrency mode) |
74-
| C interop | Yes |
75-
| C++ interop | Yes |
76-
| ObjC interop | No, intentionally unsupported long-term |
77-
| Library Evolution | No, intentionally unsupported long-term |
3+
Embedded Swift documentation has moved to: [Swift.org](https://docs.swift.org/embedded/documentation/embedded).

‎docs/EmbeddedSwift/Existentials.md‎

Lines changed: 1 addition & 106 deletions
Original file line numberDiff line numberDiff line change
@@ -1,108 +1,3 @@
11
# Embedded Swift -- Existentials
22

3-
**⚠️ Embedded Swift is experimental. This document might be out of date with latest development.**
4-
5-
**‼️ Use the latest downloadable 'Trunk Development' snapshot from swift.org to use Embedded Swift. Public releases of Swift do not yet support Embedded Swift.**
6-
7-
For an introduction and motivation into Embedded Swift, please see "[A Vision for Embedded Swift](https://github.com/swiftlang/swift-evolution/blob/main/visions/embedded-swift.md)", a Swift Evolution document highlighting the main goals and approaches.
8-
9-
## Background
10-
11-
Existentials (also known as "any" types) in Swift are a way to express a type-erased value, where the actual type is not known statically, and at runtime it can be any type that conforms to the specified protocol. Because the possible types can vary in size, the representation of such a value is an "existential container" and the actual represented value is stored either inline (when it fits) or indirectly as a pointer to a heap allocation. There are also multiple concrete representations of the existential container that are optimized for different constraints (e.g. for class-bound existentials, the value does not make sense to ever store inline, so the size of the container is matched to hold exactly one pointer).
12-
13-
Existentials are restricted in Embedded Swift in multiple ways, for multiple reasons:
14-
15-
- Value existentials are not allowed. This prevents the optimization barriers and heap allocation indirections that come with those existentials in regular Swift.
16-
- Class-bound protocols can be used as an existential. This still circumvents the often undesired behavior of existentials where they allocate (and deallocate) storage on the heap for the inner value if it cannot fit in the inline buffer, because class references are always refcounted and references are shared.
17-
- Unbounded generic methods cannot be called through an existential.
18-
19-
## Class-bound existentials
20-
21-
Embedded Swift allows and supports class-bound existentials:
22-
23-
```swift
24-
procotol ClassBoundProtocol: AnyObject { // ✅, this means any type that wants to conform to ClassBoundProtocol must be a class type
25-
func foo()
26-
}
27-
28-
class Base: ClassBoundProtocol { ... }
29-
class Derived: Base { ... } // also conforms to ClassBoundProtocol
30-
class Other: ClassBoundProtocol { ... }
31-
32-
let existential: any ClassBoundProtocol = ... // ✅
33-
existential.foo() // ✅
34-
```
35-
36-
Note that protocols that are not class-bound cannot form existentials (in Embedded Swift):
37-
38-
```swift
39-
let existential: any Equatable = ... // ❌
40-
41-
class MyClass: Equatable { ... }
42-
let existential: any Equatable = MyClass // ❌, not enough that the actual type is a class, the protocol itself must be class-bound
43-
```
44-
45-
Class-bound existentials in Embedded Swift allow the "is" and "as!" / "as?" operators:
46-
47-
```swift
48-
let existential: any ClassBoundProtocol = ...
49-
if existential is Base { ... } // ✅
50-
guard let concrete = existential as? Derived else { ... } // ✅
51-
let concrete = existential as! Derived // ✅, and will trap at runtime if a different type is inside the existential
52-
```
53-
54-
## Restrictions on class-bound existentials
55-
56-
Class-bound existentials in Embedded Swift do come with some restrictions compared to class-bound existentials in regular Swift:
57-
58-
- You cannot use an existential to call a unbounded generic method from the protocol. This is described in depth in [Embedded Swift -- Non-final generic methods](NonFinalGenericMethods.md). For example:
59-
```swift
60-
protocol ClassBoundProtocol: AnyObject {
61-
func foo<T>(t: T)
62-
}
63-
64-
let ex: any ClassBoundProtocol = ... // ✅
65-
ex.foo(t: 42) // ❌
66-
```
67-
68-
- You cannot use an existential composition of a class-bound protocol with a non-class-bound protocol. For example:
69-
```swift
70-
let ex: any ClassBoundProtocol & OtherClassBound = ... // ✅
71-
let ex: any ClassBoundProtocol & Equatable = ... // ❌
72-
```
73-
74-
## Alternatives to existentials
75-
76-
When existentials are not possible (e.g. because you need struct types in an existential), or not desirable (e.g. because the indirection on a class-bound existential causes an observation performance degradation), consider one of the following alternatives (which all have different tradeoffs and code structure implications):
77-
78-
**(1) Avoid using an existential, use generics instead**
79-
80-
```swift
81-
protocol MyProtocol {
82-
func write<T>(t: T)
83-
}
84-
85-
func usingProtocolAsGeneric(p: some MyProtocol) {
86-
p.write(t: 42) // ✅
87-
}
88-
```
89-
90-
**(2) If you only need a different type based on compile-time configuration (e.g. mocking for unit testing), use #if and typealiases:**
91-
```swift
92-
#if UNIT_TESTING
93-
typealias HWAccess = MMIOBasedHWAccess
94-
#else
95-
typealias HWAccess = MockHWAccess
96-
#endif
97-
98-
let v = HWAccess()
99-
```
100-
101-
**(3) If you only have a handful of tightly-coupled types that need to participate in an existential, use an enum instead:**
102-
```swift
103-
enum E {
104-
case type1(Type1)
105-
case type2(Type2)
106-
case type3(Type3)
107-
}
108-
```
3+
Embedded Swift documentation has moved to: [Swift.org](https://docs.swift.org/embedded/documentation/embedded).

0 commit comments

Comments
 (0)