DOCSEARCHbyAlgolia
Submit Docs

swift-corelibs-libdispatch

repository·main·Indexed 25 days ago

https://github.com/swiftlang/swift-corelibs-libdispatch

A portable implementation of the Grand Central Dispatch (GCD/libdispatch) concurrency framework for non-Darwin Swift platforms. It provides a user-space implementation of the libdispatch API using pthread primitives, specifically targeting Linux, FreeBSD, and Android.

Tokens
11.9K
Snippets
20
Records
74
Agent score
83%

What's inside swift-corelibs-libdispatch

  1. Overview of Grand Central Dispatch (libdispatch)

    main
    Grand Central Dispatch (GCD or libdispatch) is a framework that provides support for concurrent code execution on multicore hardware. While natively available on Darwin platforms via a combination of kernel and user-space logic, this project provides a portable version of the libdispatch API for other Swift platforms (such as Linux) using a user-space implementation based on pthread primitives.

  2. Build libdispatch for Linux

    main

    libdispatch development is targeted at Ubuntu (versions 14.04, 15.10, and 16.04).

    1. Install Dependencies

    Install the required system packages using apt-get:

    sudo apt-get install cmake ninja-build clang systemtap-sdt-dev libbsd-dev linux-libc-dev

    Note: Requires clang 3.8+ and the gold linker. On older Ubuntu releases, you may need to install binutils-gold.

    2. Build and Install

    Use cmake with the Ninja generator:

    cmake -G Ninja -DCMAKE_C_COMPILER=clang -DCMAKE_CXX_COMPILER=clang++ <path-to-source>
ninja
ninja install
    sudo apt-get install cmake ninja-build clang systemtap-sdt-dev libbsd-dev linux-libc-dev

cmake -G Ninja -DCMAKE_C_COMPILER=clang -DCMAKE_CXX_COMPILER=clang++ <path-to-source>
ninja
ninja install

  4. Run the libdispatch test suite

    main

    The libdispatch test suite is C-based and uses the automake testing harness.

    To run the default set of tests that are expected to pass, use:

    make check

    To run an extended test suite that includes tests which may occasionally fail, you must enable it during the configuration step:

    ./configure --enable-extended-test-suite
make check
    make check

  5. Build libdispatch for FreeBSD

    main

    To build libdispatch for FreeBSD 8.x and 9.x with clang and blocks support, use cmake with the Ninja generator:

    cmake -G Ninja -DCMAKE_C_COMPILER=clang -DCMAKE_CXX_COMPILER=clang++ -DBlocksRuntime_INCLUDE_DIR=/usr/local/include -DBlocksRuntime_LIBRARIES=/usr/local/lib/libBlocksRuntime.so <path-to-source>
ninja
ninja test
    cmake -G Ninja -DCMAKE_C_COMPILER=clang -DCMAKE_CXX_COMPILER=clang++ -DBlocksRuntime_INCLUDE_DIR=/usr/local/include -DBlocksRuntime_LIBRARIES=/usr/local/lib/libBlocksRuntime.so <path-to-source>
ninja
ninja test

  6. Build libdispatch for Android

    main

    Building for Android assumes you are on a Linux host and have the Android NDK available. It has been tested against API Level 21.

    cmake -G Ninja -DCMAKE_C_COMPILER=clang -DCMAKE_CXX_COMPILER=clang++ -DCMAKE_SYSTEM_NAME=Android -DCMAKE_SYSTEM_VERSION=21 -DCMAKE_ANDROID_NDK=<path to android NDK> <path-to-source>
ninja
    cmake -G Ninja -DCMAKE_C_COMPILER=clang -DCMAKE_CXX_COMPILER=clang++ -DCMAKE_SYSTEM_NAME=Android -DCMAKE_SYSTEM_VERSION=21 -DCMAKE_ANDROID_NDK=<path to android NDK> <path-to-source>
ninja

  7. Build libdispatch with Swift API support

    main

    You can optionally build libdispatch to include a Swift API. The method depends on whether you are building your own Swift toolchain or using a pre-built one.

    Using a custom Swift toolchain build script

    If you are building your own Swift toolchain from source, use the swift/utils/build-script with additional arguments:

    ./swift/utils/build-script --libdispatch -- --install-libdispatch

    Using a pre-built Swift toolchain

    To build libdispatch using an existing toolchain and install it into that toolchain (enabling import Dispatch in Swift code), use the following configuration:

    1. Generate build files: sh autogen.sh
    2. Configure with toolchain paths: ./configure --with-swift-toolchain=<PATH_TO_SWIFT_TOOLCHAIN> --prefix=<PATH_TO_SWIFT_TOOLCHAIN>
    3. Compile and install: make and make install

    Warning: Once installed into a toolchain, that toolchain cannot be used to compile libdispatch again without running make uninstall first.

    ./swift/utils/build-script --libdispatch -- --install-libdispatch

  9. Overview of the dispatch framework

    main

    The dispatch framework (Grand Central Dispatch) provides a mechanism for scheduling blocks for asynchronous and concurrent execution. It is organized around three primary concepts:

    1. Dispatch Queues: The basic units of organization for blocks. The framework provides several default queues, and developers can create custom queues using dispatch_queue_create.
    2. Dispatch Groups: Used to track the progress of blocks submitted to queues, allowing applications to perform actions once a group of blocks completes. Use dispatch_group_create to initialize a group.
    3. Dispatch Sources: Functions that monitor underlying system events and automatically submit event handler blocks to dispatch queues.

    To use the framework, include the following header:

    #include <dispatch/dispatch.h>

  12. Integrate dispatch objects with Objective-C and ARC

    main

    When using an Objective-C or Objective-C++ compiler, dispatch objects are treated as Objective-C types.

    • ARC (Automated Reference Counting): If ARC is enabled, dispatch objects are managed by the Objective-C runtime. Explicit calls to dispatch_retain and dispatch_release will cause build errors.
    • Blocks: The Blocks runtime automatically retains and releases dispatch objects captured by blocks during Block_copy and Block_release (e.g., during dispatch_async).
    • Retain Cycles: If a dispatch source object is captured by its own handler block, a retain cycle may occur. Break these by using __weak references or by calling dispatch_source_cancel to explicitly release the handler blocks.
    • Interior Pointers: When using functions that return interior pointers (like dispatch_data_create_map or dispatch_data_apply), ensure the associated object is not prematurely released. You may need to use the objc_precise_lifetime attribute or store the object in a __strong instance variable.