Swiftpack.co - Package - nvzqz/Threadly


Threadly is a Swift µframework that allows for type-safe thread-local storage.

What is Thread-Local Storage?

Thread-local storage (TLS) lets you define a single variable that each thread has its own separate copy of. This is great for cases such as having a mutable global variable that can't be safely accessed by multiple threads.

One example of this is with random number generators. Each thread can have its own seeded generator that's mutated on a per-thread basis. While this may potentially use more memory, it's much faster than accessing a shared global variable through a mutex.

Build Status

| Branch | Status | | :-------: | :----: | | master | Build Status



  • Platforms:
    • macOS 10.9+
    • iOS 8.0+
    • watchOS 2.0+
    • tvOS 9.0+
    • Linux
  • Xcode 8.0+
  • Swift 3.0+

Install Using Swift Package Manager

The Swift Package Manager is a decentralized dependency manager for Swift.

  1. Add the project to your Package.swift.

    import PackageDescription
    let package = Package(
        name: "MyAwesomeProject",
        dependencies: [
            .Package(url: "https://github.com/nvzqz/Threadly.git",
                     majorVersion: 1)
  2. Import the Threadly module.

    import Threadly

Install Using CocoaPods

CocoaPods is a centralized dependency manager for Objective-C and Swift. Go here to learn more.

  1. Add the project to your Podfile.

    pod 'Threadly', '~> 2.0.1'

    If you want to be on the bleeding edge, replace the last line with:

    pod 'Threadly', :git => 'https://github.com/nvzqz/Threadly.git'
  2. Run pod install and open the .xcworkspace file to launch Xcode.

  3. Import the Threadly framework.

    import Threadly

Install Using Carthage

Carthage is a decentralized dependency manager for Objective-C and Swift.

  1. Add the project to your Cartfile.

    github "nvzqz/Threadly"
  2. Run carthage update and follow the additional steps in order to add Threadly to your project.

  3. Import the Threadly framework.

    import Threadly

Install Manually

Simply add Threadly.swift into your project.


Try it out for yourself! Download the repo and open 'Threadly.playground'.


There are two ways to initialize a thread-local value. The value can be initialized lazily when retrieved (init(value:) & init(create:)) or at the call site (init(capturing:)).

Using init(value:) is an @autoclosure shorthand for init(create:). This means that the thread-local value is initialized once per thread.

import Foundation

let array = ThreadLocal(value: [1, 2, 3])

Thread.detachNewThread {
    // Allocates an array with 3 elements for this thread
    let arr = array.inner.value
    doStuff(with: arr)

// Allocates another array of 3 elements for the main thread
doStuff(with: array.inner.value)

When using init(capturing:), the thread-local value is initialized at the call site.

import Foundation

// The inner value gets allocated
let array = ThreadLocal(capturing: [1, 2, 3])

Thread.detachNewThread {
    // Retrieves a shallow copy of the initial value that can be used in this
    // thread. If the thread-local value gets mutated, a deep copy occurs to
    // retain value semantics.
    let arr = array.inner.value
    doStuff(with: arr)

// Same as the other thread, but now in the main thread
doStuff(with: array.inner.value)


Each thread has exclusive access to its own local variable.

import Foundation

let num = ThreadLocal(value: 42)

Thread.detachNewThread {
    withUnsafePointer(to: &num.inner.value) { ptr in
        print(ptr) // 0x00007fa6f86074a0

withUnsafePointer(to: &num.inner.value) { ptr in
    print(ptr) // 0x00007fa6f844c920


All source code for Threadly is released under the MIT License.

Assets for Threadly are released under the Creative Commons Attribution-ShareAlike 4.0 International License and can be found in the assets branch.


Stars: 55
Help us keep the lights on



v2.0.1 - Jul 25, 2017


  • Made withThreadLocal(_:) part of the ThreadLocalRetrievable definition
    • If this method is reimplemented elsewhere, it's not ambiguous to the compiler which version to use
    • Has a default implementation, making this a non-breaking change

v1.2.0 - Jun 25, 2017

New Features

  • Added ThreadLocalRetrievable protocol

v1.1.1 - Jun 24, 2017


  • Failed to compile on early Swift 3 versions due to inability to infer a type

v2.0.0 - Jun 26, 2017

New Features

  • Added conversions between ThreadLocal and DeferredThreadLocal


  • The static threadLcoal value for ThreadLocalRetrievable returns a Box instead of a ThreadLocal
  • Changed internals of ThreadLocal and DeferredThreadLocal, making them struct types instead of class types

v1.1.0 - Jun 23, 2017

New Features

  • Added DeferredThreadLocal for initializing when retrieving the thread-local value