Grand Central Dispatch

https://github.com/swiftlang/swift-corelibs-libdispatch
Admin
A C library providing comprehensive support for concurrent code execution on multicore hardware...
Tokens:4,907
Snippets:57
Trust Score:9.4
License:Apache-2.0
Update:2 months ago
Show doc for...
Tokens:
Raw
### Basic libdispatch Installation

Source: https://github.com/swiftlang/swift-corelibs-libdispatch/blob/main/INSTALL.md

Standard procedure for building and installing libdispatch using autoconf, automake, and libtool. Ensure all dependencies are met before running.

```shell
sh autogen.sh
./configure
make
make install
```

--------------------------------

### Install OS Headers

Source: https://github.com/swiftlang/swift-corelibs-libdispatch/blob/main/os/CMakeLists.txt

Installs generic header files to the OS headers directory. This is used for system-level header installations.

```cmake
install(FILES
          generic_base.h
          generic_unix_base.h
          generic_win_base.h
          object.h
        DESTINATION
          "${INSTALL_OS_HEADERS_DIR}")
```

--------------------------------

### Install Required Packages for Linux

Source: https://github.com/swiftlang/swift-corelibs-libdispatch/blob/main/INSTALL.md

Install necessary packages for building libdispatch on Ubuntu. Requires clang 3.8+ and the gold linker.

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

--------------------------------

### Typical Configuration for OS X El Capitan

Source: https://github.com/swiftlang/swift-corelibs-libdispatch/blob/main/INSTALL.md

Example configuration commands for building libdispatch on OS X El Capitan, targeting replacement of the system's libdispatch.dylib. Ensure paths to Apple's libraries are correct.

```shell
clangpath=$(dirname `xcrun --find clang`)
sudo mkdir -p "$clangpath/../local/lib/clang/enable_objc_gc"
LIBTOOLIZE=glibtoolize sh autogen.sh
cflags='-arch x86_64 -arch i386 -g -Os'
./configure CFLAGS="$cflags" OBJCFLAGS="$cflags" CXXFLAGS="$cflags" \
    --prefix=/usr --libdir=/usr/lib/system --disable-static \
    --enable-apple-tsd-optimizations \
    --with-apple-libpthread-source=/path/to/10.11.0/libpthread-137.1.1 \
    --with-apple-libplatform-source=/path/to/10.11.0/libplatform-73.1.1 \
    --with-apple-xnu-source=/path/to/10.11.0/xnu-3247.1.106 \
make check
```

--------------------------------

### Configure libdispatch for Linux

Source: https://github.com/swiftlang/swift-corelibs-libdispatch/blob/main/INSTALL.md

Build and install libdispatch on supported Ubuntu versions using clang and ninja. Ensure clang 3.8+ and gold linker are available.

```bash
cmake -G Ninja -DCMAKE_C_COMPILER=clang -DCMAKE_CXX_COMPILER=clang++ <path-to-source>
```

```bash
ninja
```

```bash
ninja install
```

--------------------------------

### Build libdispatch with Swift API (Pre-built Toolchain)

Source: https://github.com/swiftlang/swift-corelibs-libdispatch/blob/main/INSTALL.md

Install libdispatch into a pre-built Swift toolchain to enable Swift code to import Dispatch. Ensure you replace placeholders with actual paths.

```shell
sh autogen.sh
./configure --with-swift-toolchain=<PATH_TO_SWIFT_TOOLCHAIN> --prefix=<PATH_TO_SWIFT_TOOLCHAIN>
make
make install
```

--------------------------------

### Configure libdispatch for FreeBSD

Source: https://github.com/swiftlang/swift-corelibs-libdispatch/blob/main/INSTALL.md

Use this configuration for FreeBSD 8.x and 9.x with clang and blocks support. Ensure BlocksRuntime is installed.

```bash
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>
```

```bash
ninja
```

```bash
ninja test
```

--------------------------------

### Install Private Headers Conditionally

Source: https://github.com/swiftlang/swift-corelibs-libdispatch/blob/main/private/CMakeLists.txt

Installs private header files for libdispatch if the INSTALL_PRIVATE_HEADERS option is enabled. This is typically used during development or for specific build configurations.

```cmake
if (INSTALL_PRIVATE_HEADERS)
  install(FILES
            benchmark.h
            data_private.h
            introspection_private.h
            io_private.h
            layout_private.h
            mach_private.h
            private.h
            queue_private.h
            source_private.h
            time_private.h
            workloop_private.h
          DESTINATION
            "${INSTALL_DISPATCH_HEADERS_DIR}")
endif()
```

--------------------------------

### Include Common CMake Modules

Source: https://github.com/swiftlang/swift-corelibs-libdispatch/blob/main/CMakeLists.txt

Includes various CMake modules for checking compiler flags, source compilation, function existence, include files, library existence, linker flags, symbol existence, GNU install directories, and CTest. Also includes project-specific modules for Apple options, sanitization, compiler warnings, DTrace, and frame pointers.

```cmake
include(CheckCCompilerFlag)
include(CheckCSourceCompiles)
include(CheckFunctionExists)
include(CheckIncludeFiles)
include(CheckLibraryExists)
include(CheckLinkerFlag)
include(CheckSymbolExists)
include(GNUInstallDirs)
include(CTest)

include(DispatchAppleOptions)
include(DispatchSanitization)
include(DispatchCompilerWarnings)
include(DTrace)

include(EnableFramePointers)
```

--------------------------------

### Build Swift Toolchain with libdispatch on Linux

Source: https://github.com/swiftlang/swift-corelibs-libdispatch/blob/main/INSTALL.md

Command to execute after modifying build-presets.ini to create a local Swift toolchain that includes libdispatch on Linux.

```shell
./swift/utils/build-toolchain local.swift
```

--------------------------------

### Configure Library and Runtime Output Directories for Windows

Source: https://github.com/swiftlang/swift-corelibs-libdispatch/blob/main/CMakeLists.txt

Sets the library and runtime output directories to the binary directory for Windows. This is a workaround for Windows' lack of rpath support, using the PATH environment variable for library lookup.

```cmake
# NOTE(compnerd) this is a horrible workaround for Windows to ensure that the
# tests can run as there is no rpath equivalent and `PATH` is used to lookup the
# libraries.
set(CMAKE_LIBRARY_OUTPUT_DIRECTORY ${CMAKE_BINARY_DIR})
set(CMAKE_RUNTIME_OUTPUT_DIRECTORY ${CMAKE_BINARY_DIR})
```

--------------------------------

### Enable and Run Extended libdispatch Tests

Source: https://github.com/swiftlang/swift-corelibs-libdispatch/blob/main/TESTING.md

Enable an extended test suite, which includes tests that may occasionally fail, by configuring the build. Then, run the tests using 'make check'.

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

--------------------------------

### Run Default libdispatch Tests

Source: https://github.com/swiftlang/swift-corelibs-libdispatch/blob/main/TESTING.md

Execute the default set of tests that are always expected to pass. This is the standard way to verify basic functionality.

```bash
make check
```

--------------------------------

### Configure libdispatch for Linux Toolchain

Source: https://github.com/swiftlang/swift-corelibs-libdispatch/blob/main/INSTALL.md

Steps to add libdispatch support to a Linux Swift toolchain by modifying build-presets.ini and running the build-toolchain script.

```ini
[preset: buildbot_linux]
mixin-preset=mixin_linux_installation
build-subdir=buildbot_linux
lldb
release
test
validation-test
long-test
libdispatch
foundation
lit-args=-v
dash-dash

install-libdispatch
install-foundation
reconfigure
```

--------------------------------

### Project Definition and Versioning

Source: https://github.com/swiftlang/swift-corelibs-libdispatch/blob/main/CMakeLists.txt

Defines the project name as 'dispatch' with version 1.3 and specifies C and CXX as the supported languages. Sets position-independent code to YES.

```cmake
project(dispatch
  VERSION 1.3
  LANGUAGES C CXX)

set(CMAKE_POSITION_INDEPENDENT_CODE YES)
```

--------------------------------

### BSD Test Harness Executable Configuration

Source: https://github.com/swiftlang/swift-corelibs-libdispatch/blob/main/tests/CMakeLists.txt

Configures the 'bsdtestharness' executable, setting include directories and linking necessary libraries.

```cmake
add_executable(bsdtestharness
               bsdtestharness.c)
target_include_directories(bsdtestharness
                           PRIVATE
                             ${CMAKE_CURRENT_BINARY_DIR}
                             ${CMAKE_CURRENT_SOURCE_DIR}
                             ${PROJECT_SOURCE_DIR})
target_link_libraries(bsdtestharness
                      PRIVATE
                        bsdtests
                        dispatch)
```

--------------------------------

### BSD Tests Library Configuration

Source: https://github.com/swiftlang/swift-corelibs-libdispatch/blob/main/tests/CMakeLists.txt

Defines and configures the 'bsdtests' static library, including source files, public/private include directories, and linking dependencies.

```cmake
add_library(bsdtests
            STATIC
              bsdtests.c
              dispatch_test.c)
target_link_libraries(bsdtests PUBLIC
  dispatch)
target_include_directories(bsdtests
                           PRIVATE
                             ${CMAKE_CURRENT_BINARY_DIR}
                             ${CMAKE_CURRENT_SOURCE_DIR}
                             ${PROJECT_SOURCE_DIR}
                           PUBLIC
                             # bsdtests.h needs config_ac.h
                             ${PROJECT_BINARY_DIR})
```

--------------------------------

### Configure libdispatch for Android

Source: https://github.com/swiftlang/swift-corelibs-libdispatch/blob/main/INSTALL.md

Build libdispatch for Android on Linux using the Android NDK. Tested with API Level 21.

```bash
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>
```

```bash
ninja
```

--------------------------------

### Build libdispatch with Swift API (Custom Toolchain)

Source: https://github.com/swiftlang/swift-corelibs-libdispatch/blob/main/INSTALL.md

Integrate libdispatch with a custom-built Swift toolchain. This method is used when compiling your own Swift toolchain from source.

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

--------------------------------

### Platform-Specific File Copying/Symlinking

Source: https://github.com/swiftlang/swift-corelibs-libdispatch/blob/main/tests/CMakeLists.txt

Copies or creates symlinks for private directories and wrapper scripts based on the operating system (Windows vs. others).

```cmake
if(WIN32)
    execute_process(COMMAND
                      "${CMAKE_COMMAND}" -E copy_directory "${PROJECT_SOURCE_DIR}/private"
                      "${CMAKE_CURRENT_BINARY_DIR}/dispatch")
    execute_process(COMMAND
                      "${CMAKE_COMMAND}" -E copy "${CMAKE_CURRENT_SOURCE_DIR}/leaks-wrapper.sh"
                      "${CMAKE_CURRENT_BINARY_DIR}/leaks-wrapper")
else()
    execute_process(COMMAND
                      "${CMAKE_COMMAND}" -E create_symlink "${PROJECT_SOURCE_DIR}/private"
                      "${CMAKE_CURRENT_BINARY_DIR}/dispatch")
    execute_process(COMMAND
                      "${CMAKE_COMMAND}" -E create_symlink "${CMAKE_CURRENT_SOURCE_DIR}/leaks-wrapper.sh"
                      "${CMAKE_CURRENT_BINARY_DIR}/leaks-wrapper")
endif()
```

--------------------------------

### Windows Specific Sources and Definitions for bsdtests

Source: https://github.com/swiftlang/swift-corelibs-libdispatch/blob/main/tests/CMakeLists.txt

Adds Windows-specific source files and compile definitions to the 'bsdtests' library. Also links the 'bcrypt' library on Windows.

```cmake
if (WIN32)
  target_sources(bsdtests
                 PRIVATE
                   generic_win_port.c)
  target_compile_definitions(bsdtests
                             PUBLIC
                               _CRT_NONSTDC_NO_WARNINGS
                               _CRT_SECURE_NO_WARNINGS
                               _USE_MATH_DEFINES)
  target_link_libraries(bsdtests
                        PUBLIC
                          bcrypt)
endif ()
```

--------------------------------

### Set Minimum CMake Version and Module Path

Source: https://github.com/swiftlang/swift-corelibs-libdispatch/blob/main/CMakeLists.txt

Specifies the minimum required CMake version and appends a custom modules path. This ensures compatibility and allows for modular CMake scripts.

```cmake
cmake_minimum_required(VERSION 3.26...3.29)

list(APPEND CMAKE_MODULE_PATH ${CMAKE_CURRENT_SOURCE_DIR}/cmake/modules)
```

--------------------------------

### Set C and C++ Standards

Source: https://github.com/swiftlang/swift-corelibs-libdispatch/blob/main/CMakeLists.txt

Sets the C and C++ standards to C11 and C++11 respectively. These are required for the project and ensure consistent language features.

```cmake
set(CMAKE_C_STANDARD 11)
set(CMAKE_C_STANDARD_REQUIRED YES)

set(CMAKE_CXX_STANDARD 11)
```

--------------------------------

### Manage CMake Policies

Source: https://github.com/swiftlang/swift-corelibs-libdispatch/blob/main/CMakeLists.txt

Configures specific CMake policies to control behavior. CMP0157 is set to OLD if the Swift compiler uses the old driver, and CMP0181 is set to NEW.

```cmake
if(POLICY CMP0157 AND CMAKE_Swift_COMPILER_USE_OLD_DRIVER)
  cmake_policy(SET CMP0157 OLD)
endif()

if(POLICY CMP0181)
  cmake_policy(SET CMP0181 NEW)
endif()
```

--------------------------------

### Custom Unit Test Function

Source: https://github.com/swiftlang/swift-corelibs-libdispatch/blob/main/tests/CMakeLists.txt

Defines a CMake function `add_unit_test` to streamline the creation of unit test executables. It handles source files, include directories, compile options, and linking for tests.

```cmake
function(add_unit_test name)
  set(options DISABLED_TEST)
  set(single_value_args)
  set(multiple_value_args SOURCES)
  cmake_parse_arguments(AUT "${options}" "${single_value_args}" "${multiple_value_args}" ${ARGN})

  if(AUT_DISABLED_TEST)
    return()
  endif()

  add_executable(${name} ${AUT_SOURCES})
  target_include_directories(${name}
                             PRIVATE
                               ${CMAKE_CURRENT_BINARY_DIR}
                               ${CMAKE_CURRENT_SOURCE_DIR}
                               ${PROJECT_SOURCE_DIR})
  if(ENABLE_SWIFT)
    # For testing in swift.org CI system; make deadlines lenient by default
    # to reduce probability of test failures due to machine load.
    target_compile_options(${name} PRIVATE -DLENIENT_DEADLINES=1)
  endif()
  target_include_directories(${name}
                             SYSTEM BEFORE PRIVATE
                               "${BlocksRuntime_INCLUDE_DIR}")
  if("${CMAKE_C_COMPILER_FRONTEND_VARIANT}" STREQUAL "MSVC")
    target_compile_options(${name} PRIVATE -Xclang -fblocks)
    target_compile_options(${name} PRIVATE /W3 -Wno-deprecated-declarations)
  else()
    target_compile_options(${name} PRIVATE -fblocks)
    target_compile_options(${name} PRIVATE -Wall -Wno-deprecated-declarations)
  endif()
  # Without this flag, cross-compiling static test executables for Android armv7
  # fails with the multiple definition errors seen in android/ndk#176, so I
  # pulled in this workaround noted there. The tests build and run with this
  # flag applied.
  if(NOT BUILD_SHARED_LIBS AND ANDROID AND CMAKE_SYSTEM_PROCESSOR STREQUAL armv7-a)
    target_link_options(${name} PRIVATE "LINKER:--allow-multiple-definition")
  endif()
  target_link_libraries(${name}
                        PRIVATE
                          dispatch
                          Threads::Threads
                          BlocksRuntime::BlocksRuntime)
  target_link_libraries(${name} PRIVATE bsdtests)
  add_test(NAME ${name}
           COMMAND bsdtestharness $<TARGET_FILE:${name}>)
  set_tests_properties(${name}
                       PROPERTIES
                         TIMEOUT 120
                         DEPENDS bsdtestharness
                         WORKING_DIRECTORY ${CMAKE_CURRENT_BINARY_DIR})
  if(NOT leaks_EXECUTABLE)
    set_tests_properties(${name}
                         PROPERTIES
                           ENVIRONMENT NOLEAKS=1)
  endif()
endfunction()
```

--------------------------------

### Set C Visibility Options

Source: https://github.com/swiftlang/swift-corelibs-libdispatch/blob/main/CMakeLists.txt

Configures C visibility to 'hidden' and 'inlines_hidden' to YES. This is a common practice for libraries to reduce symbol visibility and potential conflicts.

```cmake
set(CMAKE_C_VISIBILITY_PRESET hidden)
set(CMAKE_C_VISIBILITY_INLINES_HIDDEN YES)
```

--------------------------------

### Thread Preference and Pthread Handling

Source: https://github.com/swiftlang/swift-corelibs-libdispatch/blob/main/CMakeLists.txt

Sets preferences for using pthreads for threading. It ensures CMAKE_THREAD_PREFER_PTHREAD and THREADS_PREFER_PTHREAD_FLAG are set to TRUE, and specifically sets CMAKE_HAVE_LIBC_PTHREAD to YES on Android.

```cmake
set(CMAKE_THREAD_PREFER_PTHREAD TRUE)
set(THREADS_PREFER_PTHREAD_FLAG TRUE)
if(ANDROID)
  set(CMAKE_HAVE_LIBC_PTHREAD YES)
endif()
find_package(Threads REQUIRED)
```

--------------------------------

### Windows-Specific C Source Compilation Checks

Source: https://github.com/swiftlang/swift-corelibs-libdispatch/blob/main/CMakeLists.txt

Includes checks for Windows-specific C source code compilation to determine the availability of certain features or types. These checks define preprocessor macros if successful.

```cmake
if(WIN32)
  include(CheckCSourceCompiles)
  include(CheckSymbolExists)

  check_c_source_compiles([=[
#include <Windows.h>
int main(int argc, char *argv[]) {
  switch ((LOGICAL_PROCESSOR_RELATIONSHIP)0) {
  case RelationProcessorDie:
  case RelationNumaNodeEx:
    return 0;
  }
  return 0;
}
]=] DISPATCH_HAVE_EXTENDED_SLPI_20348)
  if(DISPATCH_HAVE_EXTENDED_SLPI_20348)
    add_compile_definitions(DISPATCH_HAVE_EXTENDED_SLPI_20348)
  endif()

  check_c_source_compiles([=[
#include <Windows.h>
int main(int argc, char *argv[]) {
  switch ((LOGICAL_PROCESSOR_RELATIONSHIP)0) {
  case RelationProcessorModule:
    return 0;
  }
  return 0;
}
]=] DISPATCH_HAVE_EXTENDED_SLPI_22000)
  if(DISPATCH_HAVE_EXTENDED_SLPI_22000)
    add_compile_definitions(DISPATCH_HAVE_EXTENDED_SLPI_22000)
  endif()

  check_c_source_compiles([=[
#include <Windows.h>
#include <winternl.h>
int main(int argc, char *argv[]) {
  FILE_PIPE_LOCAL_INFORMATION fpli;
}
]=] HAVE_FILE_PIPE_LOCAL_INFORMATION)
  if(HAVE_FILE_PIPE_LOCAL_INFORMATION)
    add_compile_definitions(HAVE_FILE_PIPE_LOCAL_INFORMATION)
  endif()

  check_symbol_exists(mkstemp "stdlib.h" HAVE_MKSTEMP)
  if(HAVE_MKSTEMP)
    add_compile_definitions(HAVE_MKSTEMP)
  endif()

  check_c_source_compiles([=[
#include <sys/types.h>
int main(int argc, char *argv[]) {
  mode_t mode;
}
]=] HAVE_MODE_T)
  if(HAVE_MODE_T)
    add_compile_definitions(HAVE_MODE_T)
  endif()

  check_c_source_compiles([=[
#include <sys/types.h>
int main(int argc, char *argv[]) {
  pid_t mode;
}
]=] HAVE_PID_T)
  if(HAVE_PID_T)
    add_compile_definitions(HAVE_PID_T)
  endif()
endif()
```

--------------------------------

### Linux Specific Linker Flags

Source: https://github.com/swiftlang/swift-corelibs-libdispatch/blob/main/tests/CMakeLists.txt

Adds the 'rt' library to the linker flags when building on Linux systems.

```cmake
if(LINUX)
    set(CMAKE_EXE_LINKER_FLAGS "${CMAKE_EXE_LINKER_FLAGS} -lrt")
endif()
```

--------------------------------

### Control Shared vs. Static Library Generation

Source: https://github.com/swiftlang/swift-corelibs-libdispatch/blob/main/CMakeLists.txt

This comment indicates that the following CMake code controls whether shared or static libraries are generated, impacting the behavior of the `add_library` command.

```cmake
# NOTE(abdulras) this is the CMake supported way to control whether we generate
# shared or static libraries.  This impacts the behaviour of `add_library` in

```
Tokens:
Raw