NIOCore

Overview

NIOCore contains the fundamental abstractions that are used in all SwiftNIO programs. The goal of this module is to be platform-independent, and to be the most-common building block used for NIO protocol implementations.

More specialized modules provide concrete implementations of many of the abstractions defined in NIOCore.

Articles

• NIO and Swift Concurrency

  This article explains how to interface between NIO and Swift Concurrency.

  Read More

• Writing length-prefixed data in ByteBuffer

  This article explains how to write data prefixed with a length, where the length could be encoded in various ways.

  Read More

Event Loops and Event Loop Groups

• protocol EventLoopGroup

  Provides an endless stream of EventLoops to use.

• protocol EventLoop

  An EventLoop processes IO / tasks in an endless loop for Channels until it’s closed.

• enum NIOEventLoopGroupProvider

  This type is intended to be used by libraries which use NIO, and offer their users either the option to .share an existing event loop group or create (and manage) a new one (.createNew) and let it be managed by given library and its lifecycle.

• struct EventLoopIterator

  An iterator over the EventLoops forming an EventLoopGroup.

• struct Scheduled<T>

  Returned once a task was scheduled on the EventLoop for later execution.

• class RepeatedTask

  Returned once a task was scheduled to be repeatedly executed on the EventLoop.

• struct NIOLoopBound<Value>

  NIOLoopBound is an always-Sendable, value-typed container allowing you access to value if and only if you are accessing it on the right EventLoop.

• class NIOLoopBoundBox<Value>

  NIOLoopBoundBox is an always-Sendable, reference-typed container allowing you access to value if and only if you are accessing it on the right EventLoop.

Channels and Channel Handlers

• protocol Channel

  A Channel is easiest thought of as a network socket. But it can be anything that is capable of I/O operations such as read, write, connect, and bind.

• protocol MulticastChannel

  A MulticastChannel is a Channel that supports IP multicast operations: that is, a channel that can join multicast groups.

• protocol ChannelHandler

  Base protocol for handlers that handle I/O events or intercept an I/O operation.

• protocol ChannelOutboundHandler

  ChannelHandler which handles outbound I/O events or intercept an outbound I/O operation for a Channel.

• protocol ChannelInboundHandler

  ChannelHandler which handles inbound I/O events for a Channel.

• typealias ChannelDuplexHandler

  A combination of ChannelInboundHandler and ChannelOutboundHandler.

• class ChannelHandlerContext

  Every ChannelHandler has – when added to a ChannelPipeline – a corresponding ChannelHandlerContext which is the way ChannelHandlers can interact with other ChannelHandlers in the pipeline.

• class ChannelPipeline

  A list of ChannelHandlers that handle or intercept inbound events and outbound operations of a Channel. ChannelPipeline implements an advanced form of the Intercepting Filter pattern to give a user full control over how an event is handled and how the ChannelHandlers in a pipeline interact with each other.

• protocol RemovableChannelHandler

  A RemovableChannelHandler is a ChannelHandler that can be dynamically removed from a ChannelPipeline whilst the Channel is operating normally. A RemovableChannelHandler is required to remove itself from the ChannelPipeline (using ChannelHandlerContext.leavePipeline) as soon as possible.

• struct NIOAny

  NIOAny is an opaque container for values of any type, similar to Swift’s builtin Any type. Contrary to Any the overhead of NIOAny depends on the the type of the wrapped value. Certain types that are important for the performance of a SwiftNIO application like ByteBuffer, FileRegion and AddressEnvelope<ByteBuffer> can be expected to be wrapped almost without overhead. All others will have similar performance as if they were passed as an Any as NIOAny just like Any will contain them within an existential container.

• enum ChannelEvent

  An Channel related event that is passed through the ChannelPipeline to notify the user.

• enum CloseMode

  Specify what kind of close operation is requested.

• struct ChannelShouldQuiesceEvent

  A Channel user event that is sent when the Channel has been asked to quiesce.

Buffers and Files

• struct ByteBuffer

  ByteBuffer stores contiguously allocated raw bytes. It is a random and sequential accessible sequence of zero or more bytes (octets).

• struct ByteBufferView

  A view into a portion of a ByteBuffer.

• struct ByteBufferAllocator

  The preferred allocator for ByteBuffer values. The allocation strategy is opaque but is currently libc’s malloc, realloc and free.

• enum Endianness

  Endianness refers to the sequential order in which bytes are arranged into larger numerical values when stored in memory or when transmitted over digital links.

• class NIOFileHandle

  A NIOFileHandle is a handle to an open file.

• protocol FileDescriptor
• struct FileRegion

  A FileRegion represent a readable portion usually created to be sent over the network.

• typealias NIOPOSIXFileMode
• enum IOData

  IOData unifies standard SwiftNIO types that are raw bytes of data; currently ByteBuffer and FileRegion.

Futures and Promises

• class EventLoopFuture<Value>

  Holder for a result that will be provided later.

• struct EventLoopPromise<Value>

  A promise to provide a result later.

Configuring Channels

• protocol ChannelOption

  A configuration option that can be set on a Channel to configure different behaviour.

• protocol NIOSynchronousChannelOptions
• struct ChannelOptions

  Provides ChannelOptions to be used with a Channel, Bootstrap or ServerBootstrap.

• protocol SocketOptionProvider

  This protocol defines an object, most commonly a Channel, that supports setting and getting socket options (via setsockopt/getsockopt or similar). It provides a strongly typed API that makes working with larger, less-common socket options easier than the ChannelOption API allows.

• protocol RecvByteBufferAllocator

  Allocates ByteBuffers to be used to read bytes from a Channel and records the number of the actual bytes that were used.

• struct AdaptiveRecvByteBufferAllocator

  RecvByteBufferAllocator which will gracefully increment or decrement the buffer size on the feedback that was recorded.

• struct FixedSizeRecvByteBufferAllocator

  RecvByteBufferAllocator which will always return a ByteBuffer with the same fixed size no matter what was recorded.

• typealias AllocatorOption
• typealias AllowRemoteHalfClosureOption
• typealias AutoReadOption
• typealias BacklogOption
• typealias ConnectTimeoutOption
• typealias DatagramVectorReadMessageCountOption
• typealias MaxMessagesPerReadOption
• typealias RecvAllocatorOption
• typealias SocketOption
• typealias SocketOptionLevel
• typealias SocketOptionName
• typealias SocketOptionValue
• typealias WriteBufferWaterMarkOption
• typealias WriteBufferWaterMark
• typealias WriteSpinOption

Message Oriented Protocol Helpers

• struct AddressedEnvelope<DataType>

  A data structure for processing addressed datagrams, such as those used by UDP.

• struct NIOPacketInfo
• enum NIOExplicitCongestionNotificationState

  Possible Explicit Congestion Notification States

Generic Bootstraps

• struct NIOClientTCPBootstrap

  NIOClientTCPBootstrap is a bootstrap that allows you to bootstrap client TCP connections using NIO on BSD Sockets, NIO Transport Services, or other ways.

• protocol NIOClientTCPBootstrapProtocol

  NIOClientTCPBootstrapProtocol is implemented by various underlying transport mechanisms. Typically, this will be the BSD Sockets API implemented by ClientBootstrap.

• protocol NIOClientTLSProvider
• struct NIOInsecureNoTLS<Bootstrap>

Simple Message Handling

• protocol ByteToMessageDecoder

  ByteToMessageDecoders decode bytes in a stream-like fashion from ByteBuffer to another message type.

• protocol WriteObservingByteToMessageDecoder

  Some ByteToMessageDecoders need to observe writes (which are outbound events). ByteToMessageDecoders which implement the WriteObservingByteToMessageDecoder protocol will be notified about every outbound write.

• enum DecodingState

  State of the current decoding process.

• class ByteToMessageHandler<Decoder>

  A handler which turns a given ByteToMessageDecoder into a ChannelInboundHandler that can then be added to a ChannelPipeline.

• protocol NIOSingleStepByteToMessageDecoder

  A simplified version of ByteToMessageDecoder that can generate zero or one messages for each invocation of decode or decodeLast. Having decode and decodeLast return an optional message avoids re-entrancy problems, since the functions relinquish exclusive access to the ByteBuffer when returning. This allows for greatly simplified processing.

• class NIOSingleStepByteToMessageProcessor<Decoder>

  NIOSingleStepByteToMessageProcessor uses a NIOSingleStepByteToMessageDecoder to produce messages from a stream of incoming bytes. It works like ByteToMessageHandler but may be used outside of the channel pipeline. This allows processing of wrapped protocols in a general way.

• protocol MessageToByteEncoder

  A protocol for straightforward encoders which encode custom messages to ByteBuffers. To add a MessageToByteEncoder to a ChannelPipeline, use channel.pipeline.addHandler(MessageToByteHandler(myEncoder).

• class MessageToByteHandler<Encoder>

  A handler which turns a given MessageToByteEncoder into a ChannelOutboundHandler that can then be added to a ChannelPipeline.

Core Channel Handlers

• class AcceptBackoffHandler

  A ChannelHandler that implements a backoff for a ServerChannel when accept produces an IOError. These errors are often recoverable by reducing the rate at which we call accept.

• class BackPressureHandler

  ChannelHandler implementation which enforces back-pressure by stopping to read from the remote peer when it cannot write back fast enough. It will start reading again once pending data was written.

• class NIOCloseOnErrorHandler

  A ChannelInboundHandler that closes the channel when an error is caught

• class IdleStateHandler

  Triggers an IdleStateEvent when a Channel has not performed read, write, or both operation for a while.

Async Sequences

• struct NIOAsyncSequenceProducer<Element, Strategy, Delegate>

  This is an AsyncSequence that supports a unicast AsyncIterator.

• struct NIOThrowingAsyncSequenceProducer<Element, Failure, Strategy, Delegate>

  This is an AsyncSequence that supports a unicast AsyncIterator.

• protocol NIOAsyncSequenceProducerBackPressureStrategy

  A protocol for the back-pressure strategy of the NIOAsyncSequenceProducer.

• enum NIOAsyncSequenceProducerBackPressureStrategies
• protocol NIOAsyncSequenceProducerDelegate

  The delegate of NIOAsyncSequenceProducer.

• struct NIOAsyncWriter<Element, Delegate>

  A NIOAsyncWriter is a type used to bridge elements from the Swift Concurrency domain into a synchronous world. The Tasks that are yielding to the NIOAsyncWriter are the producers. Whereas the NIOAsyncWriterSinkDelegate is the consumer.

• protocol NIOAsyncWriterSinkDelegate

  The delegate of the NIOAsyncWriter. It is the consumer of the yielded writes to the NIOAsyncWriter. Furthermore, the delegate gets informed when the NIOAsyncWriter terminated.

Time

• struct TimeAmount

  Represents a time interval.

• struct NIODeadline

  Represents a point in time.

Circular Buffers

• struct CircularBuffer<Element>

  An automatically expanding ring buffer implementation backed by a ContiguousArray. Even though this implementation will automatically expand if more elements than initialCapacity are stored, it’s advantageous to prevent expansions from happening frequently. Expansions will always force an allocation and a copy to happen.

• struct MarkedCircularBuffer<Element>

  A circular buffer that allows one object at a time to be “marked” and easily identified and retrieved later.

Operating System State

• enum System
• struct NIONetworkDevice

  A representation of a single network device on a system.

• class NIONetworkInterface

  A representation of a single network interface on a system.

• enum SocketAddress

  Represent a socket address to which we may want to connect or bind.

• enum NIOBSDSocket
• struct NIOIPProtocol

  In the Internet Protocol version 4 (IPv4) [RFC791] there is a field called “Protocol” to identify the next level protocol. This is an 8 bit field. In Internet Protocol version 6 (IPv6) [RFC8200], this field is called the “Next Header” field.

Implementing Core Abstractions

• protocol ChannelCore

  The core Channel methods that are for internal use of the Channel implementation only.

• protocol ChannelInvoker

  A protocol that signals that outbound and inbound events are triggered by this invoker.

• protocol ChannelInboundInvoker

  Fire inbound events related to a Channel through the ChannelPipeline until its end is reached or it’s consumed by a ChannelHandler.

• protocol ChannelOutboundInvoker

  Allows users to invoke an “outbound” operation related to a Channel that will flow through the ChannelPipeline until it will finally be executed by the the ChannelCore implementation.

Sendable Helpers

• typealias NIOSendable
• typealias NIOPreconcurrencySendable

Error Types

• enum ByteToMessageDecoderError

  Common errors thrown by ByteToMessageDecoders.

• enum ChannelError

  An error that can occur on Channel operations.

• enum ChannelPipelineError

  Error that is used by the ChannelPipeline to inform the user of an error.

• enum DatagramChannelError
• enum EventLoopError

  Different Errors that are specific to EventLoop operations / implementations.

• struct IOError

  An Error for an IO operation.

• struct NIOAsyncWriterError

  Errors thrown by the NIOAsyncWriter.

• struct NIOAttemptedToRemoveHandlerMultipleTimesError

  The removal of a ChannelHandler using ChannelPipeline.removeHandler has been attempted more than once.

• struct NIOMulticastNotImplementedError

  Multicast has not been properly implemented on this channel.

• struct NIOMulticastNotSupportedError

  Multicast is not supported on this interface.

• struct NIOTooManyBytesError

  An error that is thrown when the number of bytes in an AsyncSequence exceeds the limit.

• enum SocketAddressError

  Special Error that may be thrown if we fail to create a SocketAddress.