diff --git a/TSPL.docc/ReferenceManual/Declarations.md b/TSPL.docc/ReferenceManual/Declarations.md index 46274f0fd..0f2a2a095 100644 --- a/TSPL.docc/ReferenceManual/Declarations.md +++ b/TSPL.docc/ReferenceManual/Declarations.md @@ -860,7 +860,7 @@ A *parameter modifier* changes how an argument is passed to the function. ``` To use a parameter modifier, -write `inout`, `borrowing`, or `consuming` +write `inout`, `isolated`, `nonisolated`, `borrowing`, or `consuming` before the argument's type. ```swift @@ -1059,6 +1059,32 @@ see . ``` --> +#### Actor-Isolated Parameters + +The `isolated` modifier on a parameter +indicates that the function is actor-isolated, +in the same way methods of an actor are isolated to that actor's instances. + +When calling a function that has a parameter marked `isolated`, +the argument to that parameter must be an instance of an actor type. +The function is isolated to that actor instance, +and the function can access that actor's state. + +```swift +actor SomeActor { + var number: Int + init () { self.number = 12 } +} +let anActor = SomeActor() +anActor.number = 99 // Error: Can't access isolated state + +func setNumber(to newNumber: Int, on myActor: isolated SomeActor) { + myActor.number = 34 // OK +} +``` + +A function can have at most one parameter marked `isolated`. + #### Borrowing and Consuming Parameters By default, Swift uses a set of rules @@ -1707,7 +1733,7 @@ but the new method must preserve its return type and nonreturning behavior. > *external-parameter-name* → *identifier* \ > *local-parameter-name* → *identifier* \ > *parameter-type-annotation* → **`:`** *attributes*_?_ *parameter-modifier*_?_ *type* \ -> *parameter-modifier* → **`inout`** | **`borrowing`** | **`consuming`** +> *parameter-modifier* → **`inout`** | **`borrowing`** | **`consuming`** | **`isolated`** | **`nonisolated`** > *default-argument-clause* → **`=`** *expression* + + When you mark a method or property `nonisolated`, + code that calls or accesses it don't mark use `await`. + This can be a first step towards adopting concurrency, + by marking code that you want to move off of the main actor + and then using the compiler errors to guide refactoring. + + Swift restricts nonisolated stored variables, + to ensure they provide data isolation without using an actor. + Nonisolated global variables, + static properties, + and instance properties of actors and sendable classes + must be constants of a sendable type. + Nonisolated instance properties of sendable structures + must have a sendable type, but they are allowed to be mutable. + + + + If a stored variable meets the conditions for being nonisolated + but isn't marked `nonisolated`, + you can use it as a nonisolated property + only within the module that defines it. + To use it as `nonisolated` outside of that module, + mark it `nonisolated` explicitly. + + On a declaration inside an actor, + `nonisolated` suppresses the default isolation to `self`. + Because a nonisolated member of an actor + can't access the actor's isolated state, + it can satisfy a synchronous requirement of a protocol. + + On a structure, class, or enumeration declaration, + `nonisolated` applies to that type and its members, + but not to any nested type declarations. + + On a protocol declaration, + `nonisolated` suppresses any inferred global-actor isolation, + which allows conforming types to be either actor-isolated or nonisolated. + + ```swift + // Explicitly isolated to the main actor. + @MainActor protocol SomeProtocol + + // Implicitly isolated to the main actor. + protocol MyProtocol: SomeProtocol + struct MyStruct: SomeProtocol + + // Not isolated to the main actor. + nonisolated protocol AnotherProtocol: SomeProtocol + nonisolated struct AnotherStruct: SomeProtocol + ``` + + On an extension, + `nonisolated` applies to each declaration in the extension. + + + + You can't write `nonisolated` on a declaration + that's also marked with the `MainActor` attribute + or isolated to another global actor, + on a sendable type's property if that property's type isn't sendable, + or on a sendable class's stored property if that property is mutable. + +- term `nonisolated(unsafe)`: + Apply this modifier to a stored property to suppress any implicit isolation, + even though the property doesn't satisfy the restrictions + and can't be marked `nonisolated`. + You are responsible for ensuring + that all access to the property is correctly ordered. + This may be appropriate if, for example, + you are protecting the value with a mutex + and can't use the [`Mutex`][] type from the Synchronization module. + + + [`Mutex`]: https://developer.apple.com/documentation/synchronization/mutex + - term `optional`: Apply this modifier to a protocol's property, method, or subscript members to indicate that a conforming type isn't required