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