1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
|
//===----------------------------------------------------------------------===//
//
// This source file is part of the Swift.org open source project
//
// Copyright (c) 2021 Apple Inc. and the Swift project authors
// Licensed under Apache License v2.0 with Runtime Library Exception
//
// See https://swift.org/LICENSE.txt for license information
// See https://swift.org/CONTRIBUTORS.txt for the list of Swift project authors
//
//===----------------------------------------------------------------------===//
import Swift
/// A type that represents a globally-unique actor that can be used to isolate
/// various declarations anywhere in the program.
///
/// A type that conforms to the `GlobalActor` protocol and is marked with
/// the `@globalActor` attribute can be used as a custom attribute. Such types
/// are called global actor types, and can be applied to any declaration to
/// specify that such types are isolated to that global actor type. When using
/// such a declaration from another actor (or from nonisolated code),
/// synchronization is performed through the shared actor instance to ensure
/// mutually-exclusive access to the declaration.
///
/// ## Custom Actor Executors
/// A global actor uses a custom executor if it needs to customize its execution
/// semantics, for example, by making sure all of its invocations are run on a
/// specific thread or dispatch queue.
///
/// This is done the same way as with normal non-global actors, by declaring a
/// ``Actor/unownedExecutor`` nonisolated property in the ``ActorType``
/// underlying this global actor.
///
/// It is *not* necessary to override the ``sharedUnownedExecutor`` static
/// property of the global actor, as its default implementation already
/// delegates to the ``shared.unownedExecutor``, which is the most reasonable
/// and correct implementation of this protocol requirement.
///
/// You can find out more about custom executors, by referring to the
/// ``SerialExecutor`` protocol's documentation.
///
/// - SeeAlso: ``SerialExecutor``
@available(SwiftStdlib 5.1, *)
public protocol GlobalActor {
/// The type of the shared actor instance that will be used to provide
/// mutually-exclusive access to declarations annotated with the given global
/// actor type.
associatedtype ActorType: Actor
/// The shared actor instance that will be used to provide mutually-exclusive
/// access to declarations annotated with the given global actor type.
///
/// The value of this property must always evaluate to the same actor
/// instance.
static var shared: ActorType { get }
/// Shorthand for referring to the `shared.unownedExecutor` of this global actor.
///
/// When declaring a global actor with a custom executor, prefer to implement
/// the underlying actor's ``Actor/unownedExecutor`` property, and leave this
/// `sharedUnownedExecutor` default implementation in-place as it will simply
/// delegate to the `shared.unownedExecutor`.
///
/// The value of this property must be equivalent to `shared.unownedExecutor`,
/// as it may be used by the Swift concurrency runtime or explicit user code with
/// that assumption in mind.
///
/// Returning different executors for different invocations of this computed
/// property is also illegal, as it could lead to inconsistent synchronization
/// of the underlying actor.
///
/// - SeeAlso: ``SerialExecutor``
static var sharedUnownedExecutor: UnownedSerialExecutor { get }
}
@available(SwiftStdlib 5.1, *)
extension GlobalActor {
public static var sharedUnownedExecutor: UnownedSerialExecutor {
shared.unownedExecutor
}
}
|
