mirror of
https://github.com/apple/swift.git
synced 2025-12-14 20:36:38 +01:00
84 lines
3.6 KiB
Swift
84 lines
3.6 KiB
Swift
//===----------------------------------------------------------------------===//
|
|
//
|
|
// 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 {
|
|
unsafe shared.unownedExecutor
|
|
}
|
|
}
|
|
|