<!--
{
  "availability" : [

  ],
  "documentType" : "symbol",
  "framework" : "Event",
  "identifier" : "/documentation/Event",
  "metadataVersion" : "0.1.0",
  "role" : "Framework",
  "symbol" : {
    "kind" : "Framework",
    "modules" : [
      "Event"
    ],
    "preciseIdentifier" : "Event"
  },
  "title" : "Event"
}
-->

# Event

Async TCP sockets and event-loop primitives for Swift, backed by a vendored build of libevent.

## Overview

`Event` is the idiomatic Swift face of this package. It wraps [libevent](https://github.com/libevent/libevent) 2.1.12’s event-dispatch machinery behind Swift 6.1 structured concurrency so you can write `async`/`await` code against non-blocking TCP sockets on macOS 13+, iOS 16+, tvOS 16+, watchOS 9+, visionOS 1+, and Linux (Ubuntu 22.04+). The package selects the most efficient I/O multiplexer available at runtime — **kqueue** on Apple platforms, **epoll** on Linux — and exposes it through a small, typed surface with no raw `OpaquePointer` leakage.

Direct-use capabilities shipping today:

- **Event-loop control** — create a loop, drive it per-operation or long-lived, inspect the backend. See ``doc://Event/documentation/Event/EventLoop``.
- **Async TCP client** — `async throws` `connect` / `read` / `write` / `close`. See ``doc://Event/documentation/Event/Socket``.
- **Async TCP server** — `bind` / `listen` / `accept` and an `AsyncThrowingStream` of incoming connections. See ``doc://Event/documentation/Event/ServerSocket``.
- **Address construction** — numeric IPv4 / IPv6 / wildcard factories over `sockaddr_storage`. See ``doc://Event/documentation/Event/SocketAddress``.

```swift
import Event

let loop = EventLoop()
print(loop.backendMethod)
// kqueue   (on macOS / iOS / tvOS / watchOS / visionOS)
// epoll    (on Linux)
```

### Foundation Runtime for Swift Network Stacks

Beyond its direct API, this package ships the raw `libevent` C binding product that other Swift packages link against when they need libevent primitives this Swift API hasn’t wrapped yet (timer events via `evtimer_*`, signal events via `evsignal_*`, custom bufferevents, DNS resolution via `evdns_*`). The concrete example is [`swift-tor`](https://github.com/21-DOT-DEV/swift-tor), whose `libtor` target depends on `libevent` (from this package) alongside `libcrypto` / `libssl` (from [`swift-openssl`](https://github.com/21-DOT-DEV/swift-openssl)) to build a Swift-native Tor daemon. See [Choosing Between Event and libevent](/documentation/Event/ChoosingLibeventVsEvent) for product-selection guidance.

API positioning: `Event` is a thin, libevent-direct, async/await wrapper. It is not a replacement for [SwiftNIO](https://github.com/apple/swift-nio) — if you need NIO’s channel pipelines, back-pressure protocol handlers, or HTTP/2 / WebSocket / TLS off-the-shelf, reach for NIO. Reach for `Event` when you want minimal abstraction over the platform multiplexer, a small dependency surface, or tight interop with C code that already speaks libevent.

## Topics

### Essentials

[Getting Started with Event in Swift](/documentation/Event/GettingStarted)

A task-oriented walkthrough of the three shipping capabilities in `Event`: inspecting the I/O backend, writing an async TCP client, and writing an async TCP server.

[`EventLoop`](/documentation/Event/EventLoop)

A libevent-backed event loop owning an `event_base` for async I/O dispatch.

[`Socket`](/documentation/Event/Socket)

An async non-blocking TCP socket backed by libevent.

[`ServerSocket`](/documentation/Event/ServerSocket)

A listening TCP server socket built on a non-blocking file descriptor and an [`EventLoop`](/documentation/Event/EventLoop).

### Addresses

[`SocketAddress`](/documentation/Event/SocketAddress)

A network socket address backed by `sockaddr_storage` (IPv4 or IPv6).

### Errors

[`SocketError`](/documentation/Event/SocketError)

An error surfaced by [`SocketAddress`](/documentation/Event/SocketAddress), [`Socket`](/documentation/Event/Socket), and [`ServerSocket`](/documentation/Event/ServerSocket) operations.

### Guides

[Choosing Between Event and libevent](/documentation/Event/ChoosingLibeventVsEvent)

This package ships two library products — which one should you link? This article covers the decision boundary, the canonical consumer example (`swift-tor`), and the stability guarantees that differ between the idiomatic Swift API and the raw C bindings.

### Concepts

[Backend and Platforms](/documentation/Event/BackendAndPlatforms)

The I/O multiplexer `Event` uses at runtime, the platform matrix it supports, and the backends deliberately excluded from the build.

[Production Considerations](/documentation/Event/ProductionConsiderations)

Pre-1.0 status, the concurrency model, resource-ownership rules, and the list of capabilities not yet shipping in `Event`.