CocoaAsyncSocket: GCD-Based TCP and UDP Sockets for Apple Platforms

What CocoaAsyncSocket Replaces in an Apple App

The BSD socket API on Darwin is usable from Objective-C, but it forces you to manage file descriptors, blocking calls, partial reads, and the run loop or dispatch queue that drives them. CocoaAsyncSocket packages that work into two classes. GCDAsyncSocket covers TCP/IP and GCDAsyncUdpSocket covers UDP/IP, and the README describes both as native Objective-C and fully self-contained in one class, so you do not have to muck around with sockets or streams.

The target audience is narrow and specific: developers building Mac, iOS, or tvOS apps that speak a non-HTTP protocol, or that need a server socket inside the app. A chat client on a custom wire format, a local discovery service, a device-control app talking to hardware over TCP. If your traffic is HTTP or HTTPS, this library is the wrong layer, and URLSession already handles it.

The README also points newcomers at the project wiki, with a blunt warning that sockets might not work exactly like you think they do. That is an honest signal about the learning curve: the library removes boilerplate, not the need to understand stream semantics.

How GCDAsyncSocket and GCDAsyncUdpSocket Move Data

Both classes run entirely within their own GCD dispatch_queue, and the README states they are completely thread-safe. Delegate methods are invoked asynchronously onto a dispatch_queue of your choosing, which separates socket I/O from your processing code. That design is the core of the library: you never block a thread waiting on a read, and you never touch the socket from an arbitrary queue.

Reads and writes are queued and non-blocking, with optional timeouts. You tell the socket what to read or write, and the library handles queueing, buffering, and searching for termination sequences within the stream. That last part matters. TCP gives you a byte stream, not messages, so a read completion can land mid-message. The termination-sequence search is how the library lets you express message boundaries without writing your own accumulator.

For servers, a single GCDAsyncSocket instance can accept connections, and the README says it calls you with new instances of itself for each connection. The same class handles IPv4 and IPv6, so one server socket accepts both families rather than forcing you to bind twice. TLS and SSL are enabled with a single method call on client or server sockets, per the README.

GCDAsyncUdpSocket mirrors the model for datagrams: queued non-blocking send and receive with optional timeouts, delegate callbacks for errors, send completions, receive completions, and disconnections, plus IPv4 and IPv6 support. Because UDP has no stream and no connection, the buffering and termination-sequence machinery from the TCP class does not apply here; each datagram arrives whole or not at all.

Installing CocoaAsyncSocket and Opening a First TCP Connection

The README lists four installation paths: CocoaPods, Carthage, Swift Package Manager, and adding the source files manually. The manual route is documented but discouraged; the README says you should probably be using a dependency manager to keep up to date. The CocoaPods line goes in your Podfile, and the use_frameworks! directive is required for iOS 8 or later and for Swift.

use_frameworks! # Add this if you are targeting iOS 8+ or using Swift
pod 'CocoaAsyncSocket'

For Carthage, the README gives this line for your Cartfile, pinned to the master branch:

github "robbiehanson/CocoaAsyncSocket" "master"

After a Carthage build, the README says the frameworks land in Carthage/Build/iOS/CocoaAsyncSocket.framework, Carthage/Build/tvOS/CocoaAsyncSocket.framework, and Carthage/Build/Mac/CocoaAsyncSocket.framework. You select the correct one and drag it into your project.

With Swift Package Manager, the README shows a dependency entry in Package.swift, using version 7.6.4 as the floor:

dependencies: [
    .package(url: "https://github.com/robbiehanson/CocoaAsyncSocket", from: "7.6.4")
]

Importing differs by language. In Objective-C with Clang modules you write @import CocoaAsyncSocket;, and without modules you import the header directly: #import "GCDAsyncSocket.h" for TCP, or #import "GCDAsyncUdpSocket.h" for UDP. In Swift, the README gives a single import line:

import CocoaAsyncSocket

That is where the README stops. It does not walk through delegate conformance, connect calls, or a read loop; for those it points to the wiki and the mailing list. The Examples directory in the repository has two subdirectories, Examples/GCD/ and Examples/RunLoop/, which are the place to look for working call sequences rather than the README itself.

Where CocoaAsyncSocket Stops Being the Right Tool

The library is Objective-C, and the README's Swift instructions are about import and package consumption, not about a Swift-native API. If you want async/await, structured concurrency, or an API that reads like modern Swift, this is not it. You are consuming an Objective-C delegate protocol from Swift.

The README documents no HTTP handling, no WebSocket framing, no DNS resolution strategy, and no connection pooling or retry policy. Those are your responsibility. A team that wants a networking stack with caching, authentication challenges, and background transfer support should use URLSession instead, because CocoaAsyncSocket operates one layer below all of that.

Release cadence is the other constraint. The most recent release listed is 7.6.5, dated 2020-12-13, and the release before it was 7.6.4 in 2020. The repository itself was pushed on 2026-08-30, so the codebase is not frozen, but the published version line has not moved in years. If your process requires frequent tagged releases with changelogs, you will be tracking master rather than a release, which the Carthage instructions already do. The README does not document a rollback or deprecation policy, and it does not state a minimum supported OS version beyond the iOS 8 note attached to use_frameworks!.

CocoaAsyncSocket Against Network.framework and SwiftNIO

The most direct alternative on Apple platforms is Network.framework, introduced by Apple. The difference in approach is architectural: Network.framework exposes connections as objects you can attach to, with built-in support for TLS, and it is the direction Apple pushes for new code. CocoaAsyncSocket predates it and wraps BSD sockets plus GCD, which is why it runs on older deployment targets and why its delegate model feels like the pre-async era.

If your code is cross-platform, or your server side is Swift, SwiftNIO is the closer comparison. SwiftNIO is an event-driven, non-blocking I/O framework built around channels and pipelines, and it is not tied to Apple platforms. CocoaAsyncSocket is Apple-only, per its README, and its abstractions are per-socket classes rather than a pipeline of handlers. Choosing between them is mostly a question of whether the same networking code needs to run outside an Apple app.

A third option is to write against BSD sockets directly. That gives you total control and no dependency, at the cost of the buffering, queueing, and termination-sequence search that the README lists as handled for you. For a small, single-purpose client, that trade can be worth it; for a server accepting many connections over IPv4 and IPv6 with TLS, it usually is not.

Licence Status and Upgrade Cost

The repository metadata reports the licence as NOASSERTION, which means the automated classifier could not map the LICENSE.txt file to a known SPDX identifier. The README's own badge says Public Domain and links to the Wikipedia entry for public domain. Those two signals do not agree in form, so read LICENSE.txt yourself before shipping; this is a description of what the repository states, not legal advice.

Upgrade cost is low in one sense and awkward in another. There are no transitive dependencies to reconcile, and the package is consumed through CocoaPods, Carthage, or Swift Package Manager. But the release history shows 7.6.3 in 2018, 7.6.4 in 2020, and 7.6.5 in 2020-12-13, while the repository has been pushed as recently as 2026-08-30. That gap means fixes may exist on master that are not in any tagged version. Pinning to a tag keeps you stable but possibly behind; following master, as the Carthage snippet does, keeps you current but gives up the release boundary. Decide which of those two you want before you add the dependency, because switching later means auditing delegate behaviour against a different revision.

Editorial conclusion

Adopt CocoaAsyncSocket when you need TCP or UDP sockets with delegate callbacks, TLS, and IPv4/IPv6 handling inside an Apple-platform app, and when Objective-C or Swift interoperability is acceptable. Do not adopt it for HTTP work (URLSession covers that), for cross-platform code, or for a server that must track a modern release cadence, since the newest release listed is 7.6.5 from 2020-12-13. Before committing, check the LICENSE.txt file for the exact terms, because the repository metadata reports NOASSERTION while the README badges say Public Domain, and read the wiki page on sockets before writing your first read loop.

Frequently asked questions

Official sources

1. Issues
2. README
3. Releases
4. robbiehanson/CocoaAsyncSocket on GitHub