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
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
|
//===----------------------------------------------------------------------===//
//
// This source file is part of the SwiftNIO open source project
//
// Copyright (c) 2023 Apple Inc. and the SwiftNIO project authors
// Licensed under Apache License v2.0
//
// See LICENSE.txt for license information
// See CONTRIBUTORS.txt for the list of SwiftNIO project authors
//
// SPDX-License-Identifier: Apache-2.0
//
//===----------------------------------------------------------------------===//
import Atomics
#if canImport(Darwin)
import Darwin
#elseif os(Windows)
import ucrt
import WinSDK
#elseif canImport(Glibc)
import Glibc
#elseif canImport(Musl)
import Musl
#else
#error("Unsupported C library")
#endif
/// SwiftNIO provided singleton resources for programs & libraries that don't need full control over all operating
/// system resources. This type holds sizing (how many loops/threads) suggestions.
///
/// Users who need very tight control about the exact threads and resources created may decide to set
/// `NIOSingletons.singletonsEnabledSuggestion = false`. All singleton-creating facilities should check
/// this setting and if `false` restrain from creating any global singleton resources. Please note that disabling the
/// global singletons will lead to a crash if _any_ code attempts to use any of the singletons.
public enum NIOSingletons {
}
extension NIOSingletons {
/// A suggestion of how many ``EventLoop``s the global singleton ``EventLoopGroup``s are supposed to consist of.
///
/// The thread count is ``System/coreCount`` unless the environment variable `NIO_SINGLETON_GROUP_LOOP_COUNT`
/// is set or this value was set manually by the user.
///
/// - note: This value must be set _before_ any singletons are used and must only be set once.
public static var groupLoopCountSuggestion: Int {
set {
Self.userSetSingletonThreadCount(rawStorage: globalRawSuggestedLoopCount, userValue: newValue)
}
get {
return Self.getTrustworthyThreadCount(rawStorage: globalRawSuggestedLoopCount,
environmentVariable: "NIO_SINGLETON_GROUP_LOOP_COUNT")
}
}
/// A suggestion of how many threads the global singleton thread pools that can be used for synchronous, blocking
/// functions (such as `NIOThreadPool`) are supposed to consist of
///
/// The thread count is ``System/coreCount`` unless the environment variable
/// `NIO_SINGLETON_BLOCKING_POOL_THREAD_COUNT` is set or this value was set manually by the user.
///
/// - note: This value must be set _before_ any singletons are used and must only be set once.
public static var blockingPoolThreadCountSuggestion: Int {
set {
Self.userSetSingletonThreadCount(rawStorage: globalRawSuggestedBlockingThreadCount, userValue: newValue)
}
get {
return Self.getTrustworthyThreadCount(rawStorage: globalRawSuggestedBlockingThreadCount,
environmentVariable: "NIO_SINGLETON_BLOCKING_POOL_THREAD_COUNT")
}
}
/// A suggestion for whether the global singletons should be enabled. This is `true` unless changed by the user.
///
/// This value cannot be changed using an environment variable.
///
/// - note: This value must be set _before_ any singletons are used and must only be set once.
public static var singletonsEnabledSuggestion: Bool {
get {
let (exchanged, original) = globalRawSingletonsEnabled.compareExchange(expected: 0,
desired: 1,
ordering: .relaxed)
if exchanged {
// Never been set, we're committing to the default (enabled).
assert(original == 0)
return true
} else {
// This has been set before, 1: enabled; -1 disabled.
assert(original != 0)
assert(original == -1 || original == 1)
return original > 0
}
}
set {
let intRepresentation = newValue ? 1 : -1
let (exchanged, _) = globalRawSingletonsEnabled.compareExchange(expected: 0,
desired: intRepresentation,
ordering: .relaxed)
guard exchanged else {
fatalError("""
Bug in user code: Global singleton enabled suggestion has been changed after \
user or has been changed more than once. Either is an error, you must set this value very \
early and only once.
""")
}
}
}
}
// DO NOT TOUCH THESE DIRECTLY, use `userSetSingletonThreadCount` and `getTrustworthyThreadCount`.
private let globalRawSuggestedLoopCount = ManagedAtomic(0)
private let globalRawSuggestedBlockingThreadCount = ManagedAtomic(0)
private let globalRawSingletonsEnabled = ManagedAtomic(0)
extension NIOSingletons {
private static func userSetSingletonThreadCount(rawStorage: ManagedAtomic<Int>, userValue: Int) {
precondition(userValue > 0, "illegal value: needs to be strictly positive")
// The user is trying to set it. We can only do this if the value is at 0 and we will set the
// negative value. So if the user wants `5`, we will set `-5`. Once it's used (set getter), it'll be upped
// to 5.
let (exchanged, _) = rawStorage.compareExchange(expected: 0, desired: -userValue, ordering: .relaxed)
guard exchanged else {
fatalError("""
Bug in user code: Global singleton suggested loop/thread count has been changed after \
user or has been changed more than once. Either is an error, you must set this value very early \
and only once.
""")
}
}
private static func validateTrustedThreadCount(_ threadCount: Int) {
assert(threadCount > 0,
"BUG IN NIO, please report: negative suggested loop/thread count: \(threadCount)")
assert(threadCount <= 1024,
"BUG IN NIO, please report: overly big suggested loop/thread count: \(threadCount)")
}
private static func getTrustworthyThreadCount(rawStorage: ManagedAtomic<Int>, environmentVariable: String) -> Int {
let returnedValueUnchecked: Int
let rawSuggestion = rawStorage.load(ordering: .relaxed)
switch rawSuggestion {
case 0: // == 0
// Not set by user, not yet finalised, let's try to get it from the env var and fall back to
// `System.coreCount`.
let envVarString = getenv(environmentVariable).map { String(cString: $0) }
returnedValueUnchecked = envVarString.flatMap(Int.init) ?? System.coreCount
case .min ..< 0: // < 0
// Untrusted and unchecked user value. Let's invert and then sanitise/check.
returnedValueUnchecked = -rawSuggestion
case 1 ... .max: // > 0
// Trustworthy value that has been evaluated and sanitised before.
let returnValue = rawSuggestion
Self.validateTrustedThreadCount(returnValue)
return returnValue
default:
// Unreachable
preconditionFailure()
}
// Can't have fewer than 1, don't want more than 1024.
let returnValue = max(1, min(1024, returnedValueUnchecked))
Self.validateTrustedThreadCount(returnValue)
// Store it for next time.
let (exchanged, _) = rawStorage.compareExchange(expected: rawSuggestion,
desired: returnValue,
ordering: .relaxed)
if !exchanged {
// We lost the race, this must mean it has been concurrently set correctly so we can safely recurse
// and try again.
return Self.getTrustworthyThreadCount(rawStorage: rawStorage, environmentVariable: environmentVariable)
}
return returnValue
}
}
|
