Merge remote-tracking branch 'origin/main' into automerge/merge-main-2026-10-17_09-08

This commit is contained in:
Jonathan Flat committed 2026-10-17 13:38:14 -06:00
commit feb66db229
12 files changed
+870 -98

No files matched your search

+20
View File
@@ -0,0 +1,20 @@
name: Create PR to merge release branch into the main branch
# Changes should land on the earliest release branch they will need to ship on and then be automatically forwarded to main
permissions:
contents: read
on:
schedule:
- cron: '0 9 * * *'
workflow_dispatch:
jobs:
create_merge_pr:
name: Create PR to merge release branch into main branch
uses: swiftlang/github-workflows/.github/workflows/create_automerge_pr.yml@0.0.15
with:
base_branch: main
head_branch: release/1.8.x
pr_message: This PR was automatically opened by a GitHub action. Review the changes included in this PR and determine if they should be included on main. If yes, merge the PR. Otherwise revert changes that should not be included on this branch.
permissions:
contents: write
pull-requests: write
if: (github.event_name == 'schedule' && github.repository == 'apple/swift-system') || (github.event_name != 'schedule') # Ensure that we don't run this on a schedule in a fork
+1 -1
View File
@@ -5,7 +5,7 @@ permissions:
on:
pull_request:
types: [opened, reopened, synchronize]
types: [opened, reopened, synchronize, ready_for_review]
jobs:
tests:
-38
View File
@@ -1,38 +0,0 @@
# Code of Conduct
To be a truly great community, Swift.org needs to welcome developers from all walks of life, with different backgrounds, and with a wide range of experience. A diverse and friendly community will have more great ideas, more unique perspectives, and produce more great code. We will work diligently to make the Swift community welcoming to everyone.
To give clarity of what is expected of our members, this code of conduct is based on [contributor-covenant.org](http://contributor-covenant.org). This document is used across many open source communities, and we think it articulates our values well.
### Contributor Code of Conduct v1.4
In the interest of fostering an open and welcoming environment, we as contributors and maintainers pledge to make participation in our project and our community a harassment-free experience for everyone, regardless of age, body size, disability, ethnicity, sex characteristics, gender identity and expression, level of experience, education, socio-economic status, nationality, personal appearance, race, religion, or sexual identity and orientation.
Examples of behavior that contributes to creating a positive environment include:
* Using welcoming and inclusive language (e.g., prefer non-gendered words like “folks” to “guys”, non-ableist words like “soundness check” to “sanity check”, etc.)
* Being respectful of differing viewpoints and experiences
* Gracefully accepting constructive criticism
* Focusing on what is best for the community
* Showing empathy towards other community members
Examples of unacceptable behavior by participants include:
* The use of sexualized language or imagery and unwelcome sexual attention or advances
* Trolling, insulting/derogatory comments, and personal or political attacks
* Public or private harassment
* Publishing others’ private information, such as a physical or electronic address, without explicit permission
* Other conduct which could reasonably be considered inappropriate in a professional setting
Project maintainers are responsible for clarifying the standards of acceptable behavior and are expected to take appropriate and fair corrective action in response to any instances of unacceptable behavior.
Project maintainers have the right and responsibility to remove, edit, or reject comments, commits, code, wiki edits, issues, and other contributions that are not aligned to this Code of Conduct, or to ban temporarily or permanently any contributor for other behaviors that they deem inappropriate, threatening, offensive, or harmful.
This Code of Conduct applies within all project spaces managed by Swift.org, including (but not limited to) source code repositories, bug trackers, web sites, documentation, and online forums. It also applies when an individual is representing the project or its community in public spaces. Examples of representing a project or community include using an official project e-mail address, posting via an official social media account, or acting as an appointed representative at an online or offline event.
Instances of abusive, harassing, or otherwise unacceptable behavior may be reported by contacting a member of the [Swift Core Team](https://swift.org/community/#community-structure) or by flagging the behavior for moderation (e.g., in the Forums), whether you are the target of that behavior or not. All complaints will be reviewed and investigated and will result in a response that is deemed necessary and appropriate to the circumstances. Maintainers are obligated to maintain confidentiality with regard to the reporter of an incident. The site of the disputed behavior is usually not an acceptable place to discuss moderation decisions, and moderators may move or remove any such discussion.
Project maintainers are held to a higher standard, and project maintainers who do not follow or enforce the Code of Conduct in good faith may face temporary or permanent repercussions as determined by other members of the project’s leadership.
If you disagree with a moderation action, you can appeal to the Core Team (or individual Core Team members) privately.
This policy is adapted from the Contributor Code of Conduct [version 1.4](https://www.contributor-covenant.org/version/1/4/code-of-conduct/).
+1
View File
@@ -81,6 +81,7 @@ let swiftSettings = swiftSettingsAvailability + swiftSettingsCI + [
.define("SYSTEM_PACKAGE"),
.define("ENABLE_MOCKING", .when(configuration: .debug)),
.enableExperimentalFeature("Lifetimes"),
.enableUpcomingFeature("MemberImportVisibility"),
]
let cSettings: [CSetting] = [
+2 -2
View File
@@ -120,10 +120,10 @@ Changes must land on the branch corresponding to the earliest release that they
`release/1.7.0` → `release/1.8.x` → `main`
For example, anything landing on `release/1.6.0` will eventually appear on `release/1.7.0`, then `release/1.8.x` and finally `main` as well. There is no need to file standalone PRs for each release line. (Change propagation currently requires manual work -- it is performed by project maintainers.)
For example, anything landing on `release/1.7.0` will eventually appear on `release/1.8.x` and finally `main` as well. There is no need to file standalone PRs for each release line. (Merges into `main` are performed by the [automerger](.github/workflows/automerge_to_main.yml); propagation between release branches is performed by project maintainers.)
### Code of Conduct
Like all Swift.org projects, we would like the Swift System project to foster a diverse and friendly community. We expect contributors to adhere to the [Swift.org Code of Conduct](https://swift.org/code-of-conduct/). A copy of this document is [available in this repository][coc].
[coc]: CODE_OF_CONDUCT.md
[coc]: https://github.com/apple/.github/blob/main/CODE_OF_CONDUCT.md
+1
View File
@@ -68,6 +68,7 @@ if(CMAKE_SYSTEM_NAME STREQUAL Linux)
IORing/IORequest.swift
IORing/IORing.swift
IORing/IORing+Util.swift
IORing/PollEvents.swift
IORing/RawIORequest.swift)
endif()
target_sources(SystemPackage PRIVATE
+24
View File
@@ -1,3 +1,12 @@
/*
This source file is part of the Swift System open source project
Copyright (c) 2023 - 2025 Apple Inc. and the Swift System project authors
Licensed under Apache License v2.0 with Runtime Library Exception
See https://swift.org/LICENSE.txt for license information
*/
#if compiler(>=6.2) && $Lifetimes
#if os(Linux)
@@ -45,12 +54,27 @@ public extension IORing.Completion {
}
}
/// The result of the completed operation.
///
/// A non-negative value is the operation's success result: a byte count
/// for a read or a write, an event mask for a poll, and so on.
///
/// A negative value is an `errno` code multiplied by -1. Recover the error
/// by negating it again: `Errno(rawValue: -completion.result)`, or use
/// ``error``.
@inlinable var result: Int32 {
get {
rawValue.res
}
}
/// The error of the completed operation, or `nil` if the operation succeeded.
@inlinable var error: Errno? {
get {
rawValue.res < 0 ? Errno(rawValue: -rawValue.res) : nil
}
}
@inlinable var flags: IORing.Completion.Flags {
get {
Flags(rawValue: rawValue.flags & 0x0000FFFF)
+174 -17
View File
@@ -1,3 +1,12 @@
/*
This source file is part of the Swift System open source project
Copyright (c) 2023 - 2026 Apple Inc. and the Swift System project authors
Licensed under Apache License v2.0 with Runtime Library Exception
See https://swift.org/LICENSE.txt for license information
*/
#if compiler(>=6.2) && $Lifetimes
#if os(Linux)
@@ -23,6 +32,12 @@ internal enum IORequestCore {
intoSlot: IORing.RegisteredFile,
context: UInt64 = 0
)
case pollAdd(
file: FileDescriptor,
events: IORing.Request.PollEvents,
isMultiShot: Bool = false,
context: UInt64 = 0
)
case read(
file: FileDescriptor,
buffer: IORing.RegisteredBuffer,
@@ -187,6 +202,118 @@ extension IORing.Request {
.init(core: .nop)
}
// Poll
/// Multishot poll: the poll handler continues to report CQEs on behalf
/// of the same SQE, each flagged with
/// ``IORing/Completion/Flags/moreCompletions``.
///
/// Corresponds to `IORING_POLL_ADD_MULTI`. Note that since
/// `sqe->poll_events` is the event space, the command flags for
/// `POLL_ADD` are stored in `sqe->len`.
@_alwaysEmitIntoClient
internal static var SWIFT_IORING_POLL_ADD_MULTI: UInt32 { 1 << 0 }
/// Adds a poll operation to monitor a file descriptor for specific I/O
/// events.
///
/// This method creates an `io_uring` poll operation that monitors the
/// specified file descriptor for I/O readiness events. The operation
/// completes when any of the requested events occur on the file
/// descriptor, such as data becoming available for reading or the
/// descriptor becoming ready for writing.
///
/// Poll operations are useful for implementing efficient I/O
/// multiplexing, allowing you to monitor multiple file descriptors
/// concurrently within a single `io_uring` instance. When used with
/// multishot mode, a single poll operation can deliver multiple
/// completion events without needing to be resubmitted.
///
/// Poll requests on a ring created with
/// ``IORing/SetupFlags/pollCompletions`` fail with
/// ``Errno/invalidArgument``.
///
/// ## Multishot Behavior
///
/// When `isMultiShot` is `true`, the poll operation automatically rearms
/// after each completion event, continuing to monitor the file descriptor
/// for subsequent events. This reduces submission overhead for long-lived
/// monitoring operations. The poll stays armed until it's canceled or the
/// kernel ends it; its last completion is the one without
/// ``IORing/Completion/Flags/moreCompletions``. Neither a hangup nor
/// closing the descriptor ends the poll, and the request keeps the file
/// open until the poll ends.
///
/// When `isMultiShot` is `false`, the poll operation completes once after
/// the first matching event occurs, requiring resubmission to continue
/// monitoring.
///
/// ## Example Usage
///
/// ```swift
/// // Monitor a socket for incoming connections
/// var ring = try IORing(queueDepth: 32)
/// let pollRequest = IORing.Request.pollAdd(
/// listenSocket,
/// events: .readable,
/// isMultiShot: true,
/// context: 1
/// )
/// guard try ring.submit(linkedRequests: pollRequest) else {
/// // The submission queue was full; retry or drain completions first.
/// return
/// }
///
/// // Process completions. A multishot poll stays armed while its
/// // completions contain `.moreCompletions`.
/// var armed = true
/// while armed {
/// let completion = try ring.blockingConsumeCompletion()
/// guard completion.context == 1 else {
/// // Handle completions for other requests.
/// continue
/// }
/// armed = completion.flags.contains(.moreCompletions)
/// if let error = completion.error {
/// // The poll ended with an error, such as `.canceled`.
/// throw error
/// }
/// // Handle incoming connection
/// }
/// ```
///
/// If the poll ends with an error, such as ``Errno/canceled``, its last
/// completion carries that error in ``IORing/Completion/error`` and
/// doesn't contain `.moreCompletions`.
///
/// - Parameters:
/// - file: The file descriptor to monitor for I/O events.
/// - events: The I/O events to monitor on the file descriptor.
/// - isMultiShot: If `true`, the poll operation automatically rearms
/// after each event, continuing to monitor the file descriptor. If
/// `false`, the operation completes after the first matching event.
/// Defaults to `false`.
/// - context: An application-specific value passed through to the
/// completion event, allowing you to identify which operation
/// completed. Defaults to `0`.
///
/// - Returns: An I/O ring request that monitors the file descriptor for
/// the specified events.
///
/// ## See Also
///
/// - ``PollEvents``: The events that can be monitored.
/// - ``IORing/Request/cancel(_:matching:)-(_,FileDescriptor)``:
/// Canceling poll operations.
@inlinable public static func pollAdd(
_ file: FileDescriptor,
events: PollEvents,
isMultiShot: Bool = false,
context: UInt64 = 0
) -> IORing.Request {
.init(core: .pollAdd(file: file, events: events, isMultiShot: isMultiShot, context: context))
}
@inlinable public static func read(
_ file: IORing.RegisteredFile,
into buffer: IORing.RegisteredBuffer,
@@ -316,24 +443,46 @@ extension IORing.Request {
// Cancel
/*
* ASYNC_CANCEL flags.
*
* IORING_ASYNC_CANCEL_ALL Cancel all requests that match the given key
* IORING_ASYNC_CANCEL_FD Key off 'fd' for cancellation rather than the
* request 'user_data'
* IORING_ASYNC_CANCEL_ANY Match any request
* IORING_ASYNC_CANCEL_FD_FIXED 'fd' passed in is a fixed descriptor
* IORING_ASYNC_CANCEL_USERDATA Match on user_data, default for no other key
* IORING_ASYNC_CANCEL_OP Match request based on opcode
*/
/// Cancel every request matching the given key.
///
/// Corresponds to `IORING_ASYNC_CANCEL_ALL`.
@_alwaysEmitIntoClient
internal static var SWIFT_IORING_ASYNC_CANCEL_ALL: UInt32 { 1 << 0 }
@inlinable internal static var SWIFT_IORING_ASYNC_CANCEL_ALL: UInt32 { 1 << 0 }
@inlinable internal static var SWIFT_IORING_ASYNC_CANCEL_FD: UInt32 { 1 << 1 }
@inlinable internal static var SWIFT_IORING_ASYNC_CANCEL_ANY: UInt32 { 1 << 2 }
@inlinable internal static var SWIFT_IORING_ASYNC_CANCEL_FD_FIXED: UInt32 { 1 << 3 }
@inlinable internal static var SWIFT_IORING_ASYNC_CANCEL_USERDATA: UInt32 { 1 << 4 }
@inlinable internal static var SWIFT_IORING_ASYNC_CANCEL_OP: UInt32 { 1 << 5 }
/// Cancel any request matching the given file descriptor.
///
/// Corresponds to `IORING_ASYNC_CANCEL_FD`. Cannot be combined with
/// ``SWIFT_IORING_ASYNC_CANCEL_ANY``.
@_alwaysEmitIntoClient
internal static var SWIFT_IORING_ASYNC_CANCEL_FD: UInt32 { 1 << 1 }
/// Cancel any matching request, disregarding every other key.
///
/// Corresponds to `IORING_ASYNC_CANCEL_ANY`. Cannot be combined with
/// ``SWIFT_IORING_ASYNC_CANCEL_FD`` or ``SWIFT_IORING_ASYNC_CANCEL_OP``.
@_alwaysEmitIntoClient
internal static var SWIFT_IORING_ASYNC_CANCEL_ANY: UInt32 { 1 << 2 }
/// Cancel any request matching a registered file.
///
/// Corresponds to `IORING_ASYNC_CANCEL_FD_FIXED`, and accompanies
/// ``SWIFT_IORING_ASYNC_CANCEL_FD``.
@_alwaysEmitIntoClient
internal static var SWIFT_IORING_ASYNC_CANCEL_FD_FIXED: UInt32 { 1 << 3 }
/// Cancel requests matching the `user_data`. This is the default when no other
/// key is given.
///
/// Corresponds to `IORING_ASYNC_CANCEL_USERDATA`.
@_alwaysEmitIntoClient
internal static var SWIFT_IORING_ASYNC_CANCEL_USERDATA: UInt32 { 1 << 4 }
/// Cancel requests matching the operation.
///
/// Corresponds to `IORING_ASYNC_CANCEL_OP`. Cannot be combined with
/// ``SWIFT_IORING_ASYNC_CANCEL_ANY``.
@_alwaysEmitIntoClient
internal static var SWIFT_IORING_ASYNC_CANCEL_OP: UInt32 { 1 << 5 }
public enum CancellationMatch {
case all
@@ -477,6 +626,14 @@ extension IORing.Request {
case .cancel(let flags):
request.operation = .asyncCancel
request.cancel_flags = flags
case .pollAdd(let file, let events, let isMultiShot, let context):
request.operation = .pollAdd
request.fileDescriptor = file
request.rawValue.user_data = context
if isMultiShot {
request.rawValue.len = Self.SWIFT_IORING_POLL_ADD_MULTI
}
request.pollEvents = events
}
return request
+48 -23
View File
@@ -1,3 +1,12 @@
/*
This source file is part of the Swift System open source project
Copyright (c) 2023 - 2026 Apple Inc. and the Swift System project authors
Licensed under Apache License v2.0 with Runtime Library Exception
See https://swift.org/LICENSE.txt for license information
*/
#if compiler(>=6.2) && $Lifetimes
#if os(Linux)
@@ -43,8 +52,8 @@ extension UnsafeMutableRawBufferPointer {
}
/// Owns the FilePaths whose interior pointers have been written into pending
/// SQEs. The kernel copies SQE-referenced data out during io_uring_enter (due to
/// IORING_FEAT_SUBMIT_STABLE), so the paths only need to live across the prepare->submit gap
/// SQEs. The kernel copies SQE-referenced data out during `io_uring_enter` (due to
/// `IORING_FEAT_SUBMIT_STABLE`), so the paths only need to live across the prepare->submit gap
/// This is a class purely to avoid making methods calling `pin` mutating, which would be an API break
@usableFromInline
internal final class PendingPathBuffers {
@@ -511,11 +520,10 @@ public struct IORing: ~Copyable {
var count = 0
while let completion = _tryConsumeCompletion(ring: completionRing) {
count += 1
if completion.result < 0 {
try consumer(nil, Errno(rawValue: -completion.result), false)
} else {
try consumer(completion, nil, false)
}
// We still return the completion for a failed operation so that the
// caller can tell which request failed through its `context`.
let error = completion.error
try consumer(completion, error, false)
if count == maximumCount {
try consumer(nil, nil, true)
return
@@ -567,17 +575,14 @@ public struct IORing: ~Copyable {
var count = 0
while let completion = _tryConsumeCompletion(ring: completionRing) {
count += 1
if completion.result < 0 {
try consumer(nil, Errno(rawValue: -completion.result), false)
} else {
try consumer(completion, nil, false)
}
let error = completion.error
try consumer(completion, error, false)
if count == maximumCount {
break
}
}
try consumer(nil, nil, true)
}
try consumer(nil, nil, true)
}
@inlinable
@@ -587,17 +592,23 @@ public struct IORing: ~Copyable {
var result: Completion? = nil
try _blockingConsumeCompletionGuts(minimumCount: 1, maximumCount: 1, extraArgs: extraArgs) {
(completion: consuming Completion?, error, done) throws(Errno) in
if let error {
throw error
}
if let completion {
result = consume completion
} else if let error {
throw error
}
}
return result.take()!
}
/// Synchronously waits for an operation to complete for up to `timeout` (or forever if not specified)
///
/// The completion is returned even if its operation failed. Check
/// ``IORing/Completion/error`` to find out whether it did, and
/// ``IORing/Completion/context`` to find out which request it belongs to.
///
/// - Throws: An error of the ring itself, such as ``Errno/timeout`` when
/// no operation completed within `timeout`.
@inlinable
public func blockingConsumeCompletion(
timeout: Duration? = nil
@@ -621,7 +632,17 @@ public struct IORing: ~Copyable {
}
}
/// Synchronously waits for `minimumCount` or more operations to complete for up to `timeout` (or forever if not specified). For each completed operation found, `consumer` is called to handle processing it
/// Synchronously waits for `minimumCount` or more operations to complete for up to `timeout`
/// (or forever if not specified). For each completed operation found, `consumer` is called to handle
/// processing it.
///
/// `consumer` receives a completion, an error, and whether consuming is done:
/// - For each completed operation, it receives the completion. If the
/// operation failed, it receives the operation's error alongside the
/// completion.
/// - If the ring itself fails, such as with ``Errno/timeout``, it receives
/// the error without a completion.
/// - Once consuming is done, it is called a final time with `done` set to `true`.
@inlinable
public func blockingConsumeCompletions<Err: Error>(
minimumCount: UInt32 = 1,
@@ -650,10 +671,6 @@ public struct IORing: ~Copyable {
}
}
// public func peekNextCompletion() -> IOCompletion {
// }
/// Takes a completed operation from the ring and returns it, if one is ready. Otherwise, returns nil.
@inlinable
public func tryConsumeCompletion() -> Completion? {
@@ -802,6 +819,14 @@ public struct IORing: ~Copyable {
}
/// Sends all prepared requests to the kernel for processing, and then dequeues at least `minimumCount` completions, waiting up to `timeout` for them to become available. `consumer` is called to process each completed IO operation as it becomes available.
///
/// `consumer` receives a completion, an error, and whether consuming is done:
/// - For each completed operation, it receives the completion. If the
/// operation failed, it receives the operation's error alongside the
/// completion.
/// - If submitting the requests or waiting for completions fails, such as
/// with ``Errno/timeout``, it receives the error without a completion.
/// - Once consuming is done, it is called a final time with `done` set to `true`.
@inlinable
public func submitPreparedRequestsAndConsumeCompletions<Err: Error>(
minimumCount: UInt32 = 1,
@@ -877,7 +902,7 @@ public struct IORing: ~Copyable {
return true
}
/// Describes which io_uring features are supported by the kernel this program is running on
/// Describes which `io_uring` features are supported by the kernel this program is running on
public struct Features: OptionSet, RawRepresentable, Hashable {
public let rawValue: UInt32
@@ -903,7 +928,7 @@ public struct IORing: ~Copyable {
@inlinable public static var bundledSendReceive: Features { .init(rawValue: UInt32(1) << 14) } //IORING_FEAT_RECVSEND_BUNDLE
}
/// Describes which io_uring features are supported by the kernel this program is running on
/// Describes which `io_uring` features are supported by the kernel this program is running on
public var supportedFeatures: Features {
return features
}
+168
View File
@@ -0,0 +1,168 @@
/*
This source file is part of the Swift System open source project
Copyright (c) 2026 Apple Inc. and the Swift System project authors
Licensed under Apache License v2.0 with Runtime Library Exception
See https://swift.org/LICENSE.txt for license information
*/
#if compiler(>=6.2) && $Lifetimes
#if os(Linux)
extension IORing.Request {
/// A set of I/O events that can be monitored on a file descriptor.
///
/// `PollEvents` represents the event mask used with `io_uring` poll
/// operations to specify which I/O conditions to monitor on a file
/// descriptor. These events correspond to the standard POSIX poll events
/// defined in the kernel's `poll.h` header.
///
/// Use `PollEvents` with
/// ``IORing/Request/pollAdd(_:events:isMultiShot:context:)`` to
/// register interest in specific I/O events. The poll operation completes
/// when any of the specified events become active on the file descriptor.
///
/// ## Usage
///
/// ```swift
/// // Monitor a socket for incoming data
/// let request = IORing.Request.pollAdd(
/// socketFD,
/// events: .readable,
/// isMultiShot: true
/// )
/// ```
public struct PollEvents: OptionSet, Hashable, Codable {
public let rawValue: UInt32
@inlinable
public init(rawValue: UInt32) {
self.rawValue = rawValue
}
@usableFromInline
init(_ event: Event) {
self.rawValue = event.rawValue
}
@usableFromInline
enum Event: UInt32, RawRepresentable, Hashable, CaseIterable {
case readable = 0x0001
case priorityData = 0x0002
case writable = 0x0004
case error = 0x0008
case hangUp = 0x0010
case invalidDescriptor = 0x0020
case peerClosed = 0x2000
}
/// An event indicating data is available for reading.
///
/// This event becomes active when data arrives on the file descriptor
/// and can be read without blocking. For sockets, this includes when
/// a new connection is available on a listening socket. Corresponds
/// to the POSIX `POLLIN` event flag.
@inlinable
public static var readable: PollEvents { PollEvents(.readable) }
@_alwaysEmitIntoClient
@available(*, unavailable, renamed: "readable")
public static var POLLIN: PollEvents { readable }
/// An event indicating out-of-band data is available for reading.
///
/// For sockets this signals urgent data; it is also used to report
/// exceptional conditions on descriptors that have no other way to
/// signal them, such as a `sysfs` attribute that has changed value.
/// Corresponds to the POSIX `POLLPRI` event flag.
@inlinable
public static var priorityData: PollEvents { PollEvents(.priorityData) }
@_alwaysEmitIntoClient
@available(*, unavailable, renamed: "priorityData")
public static var POLLPRI: PollEvents { priorityData }
/// An event indicating the file descriptor is ready for writing.
///
/// This event becomes active when writing to the file descriptor will
/// not block. For sockets, this indicates that send buffer space is
/// available. Corresponds to the POSIX `POLLOUT` event flag.
@inlinable
public static var writable: PollEvents { PollEvents(.writable) }
@_alwaysEmitIntoClient
@available(*, unavailable, renamed: "writable")
public static var POLLOUT: PollEvents { writable }
/// An event indicating an error condition on the file descriptor.
///
/// The kernel reports this event whether or not it was requested, so
/// it can appear in a completion's result mask even when the poll
/// asked only for ``readable`` or ``writable``. Requesting it
/// explicitly has no effect. Corresponds to the POSIX `POLLERR` event
/// flag.
@inlinable
public static var error: PollEvents { PollEvents(.error) }
@_alwaysEmitIntoClient
@available(*, unavailable, renamed: "error")
public static var POLLERR: PollEvents { error }
/// An event indicating the peer closed its end of the channel.
///
/// For a pipe this means the writing end was closed; for a socket, that
/// the connection was shut down.
///
/// The kernel reports this event whether or not it was requested, and
/// requesting it explicitly has no effect. Corresponds to the POSIX
/// `POLLHUP` event flag.
@inlinable
public static var hangUp: PollEvents { PollEvents(.hangUp) }
@_alwaysEmitIntoClient
@available(*, unavailable, renamed: "hangUp")
public static var POLLHUP: PollEvents { hangUp }
/// An event indicating that the object a descriptor refers to is no
/// longer valid.
///
/// This arises when the descriptor itself resolves, but the thing it
/// refers to has since become invalid. For example, the disconnection
/// of a sound device could cause this event.
///
/// A descriptor that doesn't resolve at all would make the request
/// fail with ``Errno/badFileDescriptor`` instead.
///
/// The kernel reports this event whether or not it was requested, and
/// requesting it explicitly has no effect. Corresponds to the POSIX
/// `POLLNVAL` event flag.
@inlinable
public static var invalidDescriptor: PollEvents {
PollEvents(.invalidDescriptor)
}
@_alwaysEmitIntoClient
@available(*, unavailable, renamed: "invalidDescriptor")
public static var POLLNVAL: PollEvents { invalidDescriptor }
/// An event indicating the peer closed its writing end of a stream
/// socket, or shut it down for writing.
///
/// Unlike ``hangUp``, this event can arrive while the connection is
/// still half-open: data already in flight can still be read, and the
/// local end can still write. Once both directions are shut down,
/// ``hangUp`` is reported alongside this event.
///
/// Unlike `poll(2)`, `io_uring` reports this event whether or not it
/// was requested, and requesting it explicitly has no effect.
/// Corresponds to the Linux `POLLRDHUP` event flag.
@inlinable
public static var peerClosed: PollEvents { PollEvents(.peerClosed) }
@_alwaysEmitIntoClient
@available(*, unavailable, renamed: "peerClosed")
public static var POLLRDHUP: PollEvents { peerClosed }
}
}
#endif
#endif
+30
View File
@@ -1,3 +1,12 @@
/*
This source file is part of the Swift System open source project
Copyright (c) 2023 - 2026 Apple Inc. and the Swift System project authors
Licensed under Apache License v2.0 with Runtime Library Exception
See https://swift.org/LICENSE.txt for license information
*/
#if compiler(>=6.2) && $Lifetimes
#if os(Linux)
@@ -80,6 +89,27 @@ extension RawIORequest {
set { rawValue.addr = newValue }
}
/// The poll event mask, stored in `sqe->poll32_events`.
///
/// Big-endian kernels swap the halfwords of this field before reading it.
/// Equivalent to liburing's `__io_uring_prep_poll_mask`.
@_alwaysEmitIntoClient var pollEvents: IORing.Request.PollEvents {
get { .init(rawValue: Self._applyPollMask(rawValue.poll32_events)) }
set { rawValue.poll32_events = Self._applyPollMask(newValue.rawValue) }
}
/// Converts a poll event mask between its in-memory and `sqe` encodings.
///
/// This is a halfword rotate (`swahw32` from `<linux/swab.h>`), which keeps
/// the byte order within each half.
@_alwaysEmitIntoClient static func _applyPollMask(_ mask: UInt32) -> UInt32 {
#if _endian(big)
return (mask &<< 16) | (mask &>> 16)
#else
return mask
#endif
}
@inlinable public var flags: Flags {
get { Flags(rawValue: rawValue.flags) }
set { rawValue.flags = newValue.rawValue }
+401 -17
View File
@@ -11,9 +11,9 @@ import Musl // for errno
#endif
#if SYSTEM_PACKAGE
import SystemPackage
@testable import SystemPackage
#else
import System
@testable import System
#endif
// Cache `isUringEnabled()`. The probe is complex and the answer doesn't change
@@ -26,6 +26,8 @@ let uringEnabled: Bool = {
}
}()
let failureMessage = "Runtime environment does not support IORing."
func isUringEnabled() throws -> Bool {
// Even if the kernel supports io_uring, the SystemPackage build may have
// been compiled against older kernel headers that lack features it needs
@@ -84,12 +86,12 @@ final class IORingTests: XCTestCase {
}
func testInit() throws {
guard uringEnabled else { return }
try XCTSkipIf(!uringEnabled, failureMessage)
_ = try IORing(queueDepth: 32, flags: [])
}
func testNop() throws {
guard uringEnabled else { return }
try XCTSkipIf(!uringEnabled, failureMessage)
var ring = try IORing(queueDepth: 32, flags: [])
_ = try ring.submit(linkedRequests: .nop())
let completion = try ring.blockingConsumeCompletion()
@@ -125,7 +127,7 @@ final class IORingTests: XCTestCase {
}
func testUndersizedSubmissionQueue() throws {
guard uringEnabled else { return }
try XCTSkipIf(!uringEnabled, failureMessage)
var ring: IORing = try IORing(queueDepth: 1)
let enqueued = ring.prepare(linkedRequests: .nop(), .nop())
XCTAssertFalse(enqueued)
@@ -133,7 +135,7 @@ final class IORingTests: XCTestCase {
// Exercises opening, reading, closing, registered files, registered buffers, and eventfd
func testOpenReadAndWriteFixedFile() throws {
guard uringEnabled else { return }
try XCTSkipIf(!uringEnabled, failureMessage)
let (parent, path) = try makeHelloWorldFile()
let rawBuffer = UnsafeMutableRawBufferPointer.allocate(byteCount: 13, alignment: 16)
var ring = try setupTestRing(depth: 6, fileSlots: 1, buffers: [rawBuffer])
@@ -178,7 +180,7 @@ final class IORingTests: XCTestCase {
let bytesRead = try nonRingFD.read(into: rawBuffer)
XCTAssert(bytesRead == 13)
let result2 = String(cString: rawBuffer.assumingMemoryBound(to: CChar.self).baseAddress!)
XCTAssertEqual(result2, "Hello, World!")
XCTAssertEqual(result2, "Hello, World!")
try cleanUpHelloWorldFile(parent)
efdBuf.deallocate()
rawBuffer.deallocate()
@@ -190,7 +192,7 @@ final class IORingTests: XCTestCase {
// dangling pointer. Here we deliberately let the FilePath go out of scope
// between prepare and submit, then churn the heap to make UAFs observable.
func testPathBufferLifetimeAcrossPrepareSubmit() throws {
guard uringEnabled else { return }
try XCTSkipIf(!uringEnabled, failureMessage)
let (parent, _) = try makeHelloWorldFile()
var ring = try IORing(queueDepth: 6)
@@ -224,7 +226,7 @@ final class IORingTests: XCTestCase {
}
func testPathBufferLifetimeAcrossLinkedRequests() throws {
guard uringEnabled else { return }
try XCTSkipIf(!uringEnabled, failureMessage)
let (parent, _) = try makeHelloWorldFile()
let rawBuffer = UnsafeMutableRawBufferPointer.allocate(byteCount: 13, alignment: 16)
var ring = try setupTestRing(depth: 6, fileSlots: 1, buffers: [rawBuffer])
@@ -261,12 +263,12 @@ final class IORingTests: XCTestCase {
// Timeout test for `blockingConsumeCompletion(timeout:)`:
func testBlockingConsumeCompletionWithTimeoutOnIdleRing() throws {
guard uringEnabled else { return }
try XCTSkipIf(!uringEnabled, failureMessage)
let ring = try IORing(queueDepth: 4, flags: [])
guard ring.supportedFeatures.contains(.extendedArguments) else {
// Kernel < 5.11: timeouts in io_uring_enter aren't supported.
return
}
try XCTSkipIf(
!ring.supportedFeatures.contains(.extendedArguments),
"Kernel < 5.11: timeouts in io_uring_enter aren't supported."
)
let clock = ContinuousClock()
let start = clock.now
@@ -285,8 +287,83 @@ final class IORingTests: XCTestCase {
XCTAssertGreaterThanOrEqual(elapsed, .milliseconds(50))
}
func testBlockingConsumeCompletionsSendsDone() throws {
try XCTSkipIf(!uringEnabled, failureMessage)
var ring = try IORing(queueDepth: 4)
XCTAssertTrue(try ring.submit(linkedRequests: .nop()))
var dones: [Bool] = []
ring.blockingConsumeCompletions { (completion: consuming IORing.Completion?, error, done) in
dones.append(done)
}
XCTAssertEqual(dones, [false, true])
}
func testBlockingConsumeCompletionsKeepsContextOfFailedCompletion() throws {
try XCTSkipIf(!uringEnabled, failureMessage)
var ring = try IORing(queueDepth: 4)
XCTAssertTrue(try ring.submit(
linkedRequests: .close(FileDescriptor(rawValue: -1), context: 42)
))
var received: [(context: UInt64?, error: Errno?, done: Bool)] = []
ring.blockingConsumeCompletions { (completion: consuming IORing.Completion?, error, done) in
received.append((completion?.context, error, done))
}
XCTAssertEqual(received.count, 2)
XCTAssertEqual(received.first?.context, 42)
XCTAssertEqual(received.first?.error, .badFileDescriptor)
XCTAssertEqual(received.first?.done, false)
XCTAssertEqual(received.last?.context, nil)
XCTAssertEqual(received.last?.error, nil)
XCTAssertEqual(received.last?.done, true)
}
func testBlockingConsumeCompletionReturnsFailedCompletion() throws {
try XCTSkipIf(!uringEnabled, failureMessage)
var ring = try IORing(queueDepth: 4)
XCTAssertTrue(try ring.submit(
linkedRequests: .close(FileDescriptor(rawValue: -1), context: 43)
))
let completion = try ring.blockingConsumeCompletion()
XCTAssertEqual(completion.context, 43)
XCTAssertEqual(completion.error, .badFileDescriptor)
XCTAssertEqual(completion.result, -Errno.badFileDescriptor.rawValue)
}
func testSubmitAndConsumeCompletionsKeepsContextOfFailedCompletion() throws {
try XCTSkipIf(!uringEnabled, failureMessage)
var ring = try IORing(queueDepth: 4)
XCTAssertTrue(ring.prepare(request: .close(FileDescriptor(rawValue: -1), context: 44)))
var received: [(context: UInt64?, error: Errno?, done: Bool)] = []
ring.submitPreparedRequestsAndConsumeCompletions {
(completion: consuming IORing.Completion?, error, done) in
received.append((completion?.context, error, done))
}
XCTAssertEqual(received.count, 2)
XCTAssertEqual(received.first?.context, 44)
XCTAssertEqual(received.first?.error, .badFileDescriptor)
XCTAssertEqual(received.first?.done, false)
XCTAssertEqual(received.last?.context, nil)
XCTAssertEqual(received.last?.error, nil)
XCTAssertEqual(received.last?.done, true)
}
func testCompletionOfSuccessfulOperationHasNoError() throws {
try XCTSkipIf(!uringEnabled, failureMessage)
var ring = try IORing(queueDepth: 4)
XCTAssertTrue(try ring.submit(linkedRequests: .nop()))
let completion = try ring.blockingConsumeCompletion()
XCTAssertEqual(completion.result, 0)
XCTAssertNil(completion.error)
}
func testRegisterEventFDTwiceThrows() throws {
guard uringEnabled else { return }
try XCTSkipIf(!uringEnabled, failureMessage)
var ring = try IORing(queueDepth: 4)
let efd = FileDescriptor(rawValue: eventfd(0, Int32(EFD_SEMAPHORE)))
defer { try? efd.close() }
@@ -301,16 +378,323 @@ final class IORingTests: XCTestCase {
}
func testSubmitOnDisabledRingThrows() throws {
guard uringEnabled else { return }
try XCTSkipIf(!uringEnabled, failureMessage)
var ring = try IORing(queueDepth: 4, flags: [.startDisabled])
do throws(Errno) {
do throws(Errno) {
_ = try ring.submit(linkedRequests: .nop())
XCTFail("expected submit on a disabled ring to throw")
} catch {
XCTAssertEqual(error, Errno(rawValue: EBADFD))
}
}
func testPollAddPollIn() throws {
try XCTSkipIf(!uringEnabled, failureMessage)
var ring = try IORing(queueDepth: 32, flags: [])
// This test case requires timeout support
try XCTSkipIf(
!ring.supportedFeatures.contains(.extendedArguments),
"Kernel < 5.11: timeouts in io_uring_enter aren't supported."
)
// Test POLLIN: Create an eventfd to monitor for read readiness
let testEventFD = FileDescriptor(rawValue: eventfd(0, 0))
defer {
try? testEventFD.close()
}
let pollInContext: UInt64 = 42
// Submit a pollAdd request to monitor for POLLIN events (data available for reading)
let enqueued = try ring.submit(linkedRequests:
.pollAdd(testEventFD, events: .readable, isMultiShot: false, context: pollInContext))
XCTAssert(enqueued)
// Write to the eventfd to trigger the POLLIN event
var value: UInt64 = 1
withUnsafeBytes(of: &value) { bufferPtr in
_ = try? testEventFD.write(bufferPtr)
}
// Consume the completion from the poll operation
let completion = try ring.blockingConsumeCompletion(
timeout: .seconds(1)
)
XCTAssertEqual(completion.context, pollInContext)
let readable = Int32(IORing.Request.PollEvents.readable.rawValue)
XCTAssertNotEqual(
completion.result & readable, 0, "expected POLLIN in the result mask"
)
}
func testPollAddPollOut() throws {
try XCTSkipIf(!uringEnabled, failureMessage)
var ring = try IORing(queueDepth: 32, flags: [])
// This test case requires timeout support
try XCTSkipIf(
!ring.supportedFeatures.contains(.extendedArguments),
"Kernel < 5.11: timeouts in io_uring_enter aren't supported."
)
// Test POLLOUT: Create a pipe to monitor for write readiness
var pipeFDs: [Int32] = [0, 0]
let pipeResult = pipe(&pipeFDs)
XCTAssertEqual(pipeResult, 0)
let writeFD = FileDescriptor(rawValue: pipeFDs[1])
let readFD = FileDescriptor(rawValue: pipeFDs[0])
defer {
try? writeFD.close()
try? readFD.close()
}
let pollOutContext: UInt64 = 43
// Submit a pollAdd request to monitor for POLLOUT events (ready for writing)
// Pipes are typically ready for writing when empty
let enqueuedOut = try ring.submit(linkedRequests:
.pollAdd(writeFD, events: .writable, isMultiShot: false, context: pollOutContext))
XCTAssert(enqueuedOut)
// Consume the completion from the poll operation
let completionOut = try ring.blockingConsumeCompletion(
timeout: .seconds(1)
)
XCTAssertEqual(completionOut.context, pollOutContext)
let writable = Int32(IORing.Request.PollEvents.writable.rawValue)
XCTAssertNotEqual(
completionOut.result & writable, 0,
"expected POLLOUT in the result mask"
)
}
// Similar to the multishot example in the documentation for
// `pollAdd(_:events:isMultiShot:context:)`: arm a multishot poll,
// then consume completions for as long as they carry `.moreCompletions`.
func testPollAddMultiShotRearmsAcrossEvents() throws {
try XCTSkipIf(!uringEnabled, failureMessage)
var ring = try IORing(queueDepth: 32, flags: [])
// This test case requires timeout support
try XCTSkipIf(
!ring.supportedFeatures.contains(.extendedArguments),
"Kernel < 5.11: timeouts in io_uring_enter aren't supported."
)
var pipeFDs: [Int32] = [0, 0]
XCTAssertEqual(pipe(&pipeFDs), 0)
let readFD = FileDescriptor(rawValue: pipeFDs[0])
let writeFD = FileDescriptor(rawValue: pipeFDs[1])
defer {
try? readFD.close()
try? writeFD.close()
}
func writeByte() throws {
var byte: UInt8 = 1
try withUnsafeBytes(of: &byte) {
try XCTAssertEqual(writeFD.write($0), 1)
}
}
func readByte() throws {
var scratch: UInt8 = 0
try withUnsafeMutableBytes(of: &scratch) {
try XCTAssertEqual(readFD.read(into: $0), 1)
}
}
let context: UInt64 = 44
let readable = Int32(IORing.Request.PollEvents.readable.rawValue)
let pollRequest = IORing.Request.pollAdd(
readFD, events: .readable, isMultiShot: true, context: context
)
let enqueued = try ring.submit(linkedRequests: pollRequest)
XCTAssert(enqueued)
try writeByte()
let first = try ring.blockingConsumeCompletion(timeout: .seconds(1))
// Kernels before 5.13 reject IORING_POLL_ADD_MULTI
try XCTSkipIf(
first.result == -EINVAL,
"Kernel < 5.13: multishot poll is unsupported."
)
XCTAssertEqual(first.context, context)
XCTAssertNotEqual(
first.result & readable, 0, "expected POLLIN in the result mask"
)
XCTAssert(first.flags.contains(.moreCompletions))
// Drain the pipe, then any extra completions.
try readByte()
while ring.tryConsumeCompletion() != nil {}
try writeByte()
// This written byte will only be reported by a re-armed poll.
let second = try ring.blockingConsumeCompletion(timeout: .seconds(1))
XCTAssertEqual(second.context, context)
XCTAssertNotEqual(
second.result & readable, 0, "expected POLLIN in the result mask"
)
// Drain again
try readByte()
while ring.tryConsumeCompletion() != nil {}
// Cancel to end the multishot poll.
try XCTAssert(
ring.submit(linkedRequests: .cancel(.all, matchingContext: context))
)
var terminal: (result: Int32, flags: IORing.Completion.Flags)? = nil
var observed: [(context: UInt64, result: Int32, flags: UInt32)] = []
// The cancel posts a completion of its own under a different context,
// and the two may land a moment apart, so retry briefly rather than
// draining exactly once.
for _ in 0..<100 where terminal == nil {
while let completion = ring.tryConsumeCompletion() {
observed.append(
(
completion.context,
completion.result,
completion.flags.rawValue
)
)
if completion.context == context {
terminal = (completion.result, completion.flags)
}
}
if terminal == nil { usleep(1000) }
}
XCTAssertNotNil(
terminal,
"no terminal completion for the cancelled poll; "
+ "completions seen: \(observed)"
)
if let terminal {
XCTAssertEqual(terminal.result, -ECANCELED)
XCTAssertFalse(
terminal.flags.contains(.moreCompletions),
"poll kept its armed state after being cancelled"
)
}
}
func testPollHangup() throws {
try XCTSkipIf(!uringEnabled, failureMessage)
var ring = try IORing(queueDepth: 8)
let (readFD, writeFD) = try FileDescriptor.pipe()
// The hangup is produced by closing the write end mid-test, so the
// cleanup below must not close it a second time: the descriptor number
// may already have been reused elsewhere in the test process.
var writeEndClosed = false
defer {
try? readFD.close()
if !writeEndClosed { try? writeFD.close() }
}
// This test case requires timeout support
try XCTSkipIf(
!ring.supportedFeatures.contains(.extendedArguments),
"Kernel < 5.11: timeouts in io_uring_enter aren't supported."
)
let request = IORing.Request.pollAdd(
readFD, events: .readable, isMultiShot: false, context: 97
)
let success = try ring.submit(linkedRequests: request)
XCTAssertEqual(success, true)
try writeFD.close()
writeEndClosed = true
let dt = Duration.seconds(1)
let completion = try ring.blockingConsumeCompletion(timeout: dt)
for event in IORing.Request.PollEvents.Event.allCases {
if completion.result & Int32(event.rawValue) != 0 {
XCTAssertEqual(event, .hangUp)
return
}
}
let unexpected = completion.result
XCTFail("Unexpected poll event: 0x\(String(unexpected, radix: 16))")
}
func testPollError() throws {
try XCTSkipIf(!uringEnabled, failureMessage)
var ring = try IORing(queueDepth: 8)
let (readFD, writeFD) = try FileDescriptor.pipe(options: .nonBlocking)
// POLLERR is produced by closing the read end mid-test; see the note in
// `testPollHangup` for why cleanup must not close it twice.
var readEndClosed = false
defer {
if !readEndClosed { try? readFD.close() }
try? writeFD.close()
}
// This test case requires timeout support
try XCTSkipIf(
!ring.supportedFeatures.contains(.extendedArguments),
"Kernel < 5.11: timeouts in io_uring_enter aren't supported."
)
let chunk = [UInt8](repeating: 0, count: 4096)
chunk.withUnsafeBytes {
// Fill the pipe by writing until an operation fails
while let written = try? writeFD.write($0), written > 0 {}
}
let request = IORing.Request.pollAdd(
writeFD, events: .writable, isMultiShot: false, context: 98
)
let success = try ring.submit(linkedRequests: request)
XCTAssertEqual(success, true)
try readFD.close()
readEndClosed = true
let dt = Duration.seconds(1)
let completion = try ring.blockingConsumeCompletion(timeout: dt)
XCTAssertEqual(completion.context, 98)
let pollError = IORing.Request.PollEvents.error.rawValue
let result = completion.result & Int32(pollError)
if result != pollError {
XCTFail("expected POLLERR, got 0x\(String(result, radix: 16))")
}
}
// A completion's `result` is two things in one field: a non-negative
// value is an event mask, and a negative value is a negated errno. The
// sign is the only thing distinguishing them, so it has to be checked
// before the value is treated as anything else.
func testPollAddOnInvalidDescriptor() throws {
try XCTSkipIf(!uringEnabled, failureMessage)
var ring = try IORing(queueDepth: 8)
let request = IORing.Request.pollAdd(
FileDescriptor(rawValue: -1), events: .readable,
isMultiShot: false, context: 99
)
let success = try ring.submit(linkedRequests: request)
XCTAssertEqual(success, true)
guard let completion = ring.tryConsumeCompletion() else {
XCTFail("expected a completion for the failed poll")
return
}
XCTAssertEqual(completion.context, 99)
// A negative value for `result` marks the completion a a failure.
XCTAssertLessThan(completion.result, 0, "expected a failure")
// The negative value is the error code multiplied by -1.
XCTAssertEqual(Errno(rawValue: -completion.result), .badFileDescriptor)
// A negative result may look like another result code.
// Checking for the error must happen first.
let invalidDescriptor = Int32(IORing.Request.PollEvents.invalidDescriptor.rawValue)
XCTAssertNotEqual(completion.result & invalidDescriptor, 0)
}
}
#endif // os(Linux)
#endif // compiler(>=6.2) && $Lifetimes