pax_global_header 0000666 0000000 0000000 00000000064 14165641476 0014530 g ustar 00root root 0000000 0000000 52 comment=3f74afd37d463ba84d337f86f5c324c829ec0744
qcoro-0.4.0/ 0000775 0000000 0000000 00000000000 14165641476 0012654 5 ustar 00root root 0000000 0000000 qcoro-0.4.0/.clang-format 0000664 0000000 0000000 00000010225 14165641476 0015227 0 ustar 00root root 0000000 0000000 ---
Language: Cpp
# BasedOnStyle: LLVM
AccessModifierOffset: -4
AlignAfterOpenBracket: Align
AlignConsecutiveMacros: false
AlignConsecutiveAssignments: false
AlignConsecutiveBitFields: false
AlignConsecutiveDeclarations: false
AlignEscapedNewlines: Right
AlignOperands: Align
AlignTrailingComments: true
AllowAllArgumentsOnNextLine: true
AllowAllConstructorInitializersOnNextLine: true
AllowAllParametersOfDeclarationOnNextLine: true
AllowShortEnumsOnASingleLine: false
AllowShortBlocksOnASingleLine: Never
AllowShortCaseLabelsOnASingleLine: false
AllowShortFunctionsOnASingleLine: Empty
AllowShortLambdasOnASingleLine: All
AllowShortIfStatementsOnASingleLine: Never
AllowShortLoopsOnASingleLine: false
AlwaysBreakAfterDefinitionReturnType: None
AlwaysBreakAfterReturnType: None
AlwaysBreakBeforeMultilineStrings: false
AlwaysBreakTemplateDeclarations: Yes
BinPackArguments: true
BinPackParameters: true
BraceWrapping:
AfterCaseLabel: false
AfterClass: false
AfterControlStatement: Never
AfterEnum: false
AfterFunction: false
AfterNamespace: false
AfterObjCDeclaration: false
AfterStruct: false
AfterUnion: false
AfterExternBlock: false
BeforeCatch: false
BeforeElse: false
BeforeLambdaBody: false
BeforeWhile: false
IndentBraces: false
SplitEmptyFunction: true
SplitEmptyRecord: true
SplitEmptyNamespace: true
BreakBeforeBinaryOperators: None
BreakBeforeBraces: Attach
BreakBeforeInheritanceComma: false
BreakInheritanceList: BeforeColon
BreakBeforeTernaryOperators: true
BreakConstructorInitializersBeforeComma: false
BreakConstructorInitializers: BeforeColon
BreakAfterJavaFieldAnnotations: false
BreakStringLiterals: true
ColumnLimit: 100
CommentPragmas: '^ IWYU pragma:'
CompactNamespaces: false
ConstructorInitializerAllOnOneLineOrOnePerLine: true
ConstructorInitializerIndentWidth: 4
ContinuationIndentWidth: 4
Cpp11BracedListStyle: true
DeriveLineEnding: true
DerivePointerAlignment: false
DisableFormat: false
ExperimentalAutoDetectBinPacking: false
FixNamespaceComments: true
ForEachMacros:
- foreach
- Q_FOREACH
- BOOST_FOREACH
IncludeBlocks: Preserve
IncludeCategories:
- Regex: '^"(qcoro)/'
Priority: 2
SortPriority: 0
- Regex: '^(<|"(gtest|gmock|isl|json)/)'
Priority: 3
SortPriority: 0
- Regex: '.*'
Priority: 1
SortPriority: 0
IncludeIsMainRegex: '(Test)?$'
IncludeIsMainSourceRegex: ''
IndentCaseLabels: false
IndentCaseBlocks: false
IndentGotoLabels: true
IndentPPDirectives: None
IndentExternBlock: AfterExternBlock
IndentWidth: 4
IndentWrappedFunctionNames: false
InsertTrailingCommas: None
JavaScriptQuotes: Leave
JavaScriptWrapImports: true
KeepEmptyLinesAtTheStartOfBlocks: true
MacroBlockBegin: ''
MacroBlockEnd: ''
MaxEmptyLinesToKeep: 1
NamespaceIndentation: None
ObjCBinPackProtocolList: Auto
ObjCBlockIndentWidth: 2
ObjCBreakBeforeNestedBlockParam: true
ObjCSpaceAfterProperty: false
ObjCSpaceBeforeProtocolList: true
PenaltyBreakAssignment: 2
PenaltyBreakBeforeFirstCallParameter: 19
PenaltyBreakComment: 300
PenaltyBreakFirstLessLess: 120
PenaltyBreakString: 1000
PenaltyBreakTemplateDeclaration: 10
PenaltyExcessCharacter: 1000000
PenaltyReturnTypeOnItsOwnLine: 60
PointerAlignment: Right
ReflowComments: false
SortIncludes: true
SortUsingDeclarations: true
SpaceAfterCStyleCast: false
SpaceAfterLogicalNot: false
SpaceAfterTemplateKeyword: false
SpaceBeforeAssignmentOperators: true
SpaceBeforeCpp11BracedList: false
SpaceBeforeCtorInitializerColon: true
SpaceBeforeInheritanceColon: true
SpaceBeforeParens: ControlStatements
SpaceBeforeRangeBasedForLoopColon: true
SpaceInEmptyBlock: false
SpaceInEmptyParentheses: false
SpacesBeforeTrailingComments: 1
SpacesInAngles: false
SpacesInConditionalStatement: false
SpacesInContainerLiterals: true
SpacesInCStyleCastParentheses: false
SpacesInParentheses: false
SpacesInSquareBrackets: false
SpaceBeforeSquareBrackets: false
Standard: Latest
StatementMacros:
- Q_UNUSED
- QT_REQUIRE_VERSION
- addTest
TabWidth: 8
UseCRLF: false
UseTab: Never
WhitespaceSensitiveMacros:
- STRINGIZE
- PP_STRINGIZE
- BOOST_PP_STRINGIZE
...
qcoro-0.4.0/.git-blame-ignore-revs 0000664 0000000 0000000 00000000107 14165641476 0016752 0 ustar 00root root 0000000 0000000 # Initial run of clang-format
0c01ca40fd8bd337ecae3ea21be1e5a97ba40e4b
qcoro-0.4.0/.github/ 0000775 0000000 0000000 00000000000 14165641476 0014214 5 ustar 00root root 0000000 0000000 qcoro-0.4.0/.github/actions/ 0000775 0000000 0000000 00000000000 14165641476 0015654 5 ustar 00root root 0000000 0000000 qcoro-0.4.0/.github/actions/install-qt/ 0000775 0000000 0000000 00000000000 14165641476 0017744 5 ustar 00root root 0000000 0000000 qcoro-0.4.0/.github/actions/install-qt/action.yml 0000664 0000000 0000000 00000003105 14165641476 0021743 0 ustar 00root root 0000000 0000000 name: 'Install Qt'
description: 'Install Qt'
inputs:
qt_version:
description: 'Version of Qt to install'
required: true
qt_modules:
description: 'List of Qt modules to intall'
default: qtbase icu
compiler:
description: 'Name of the compiler to use'
required: true
runs:
using: composite
steps:
- shell: bash
run: |
pip3 install aqtinstall~=1.2.5
if [[ "${{ inputs.compiler }}" == "msvc" ]]; then
aqt install -O C:\Qt -m ${{ inputs.qt_modules }} --noarchives ${{ inputs.qt_version }} windows desktop win64_msvc2019_64
QT_BASE_DIR="C:\Qt\${{ inputs.qt_version }}\msvc2019_64"
powershell "./.github/actions/install-qt/install-dbus.ps1" "$QT_BASE_DIR"
echo "$QT_BASE_DIR\\bin" >> $GITHUB_PATH
echo "CMAKE_PREFIX_PATH=$QT_BASE_DIR\\lib\\cmake" >> $GITHUB_ENV
else
sudo apt-get update
sudo apt-get install -y --no-install-recommends build-essential dbus dbus-x11 libgl-dev libegl-dev
if [[ "${{ inputs.compiler }}" == "clang"* ]]; then
sudo apt-get install -y --no-install-recommends libc++1-11 libc++-11-dev libc++abi-11-dev
fi
aqt install -O /opt/qt -m ${{ inputs.qt_modules }} --noarchives ${{ inputs.qt_version }} linux desktop gcc_64
QT_BASE_DIR="/opt/qt/${{ inputs.qt_version }}/gcc_64/"
echo "$QT_BASE_DIR/bin" >> $GITHUB_PATH
echo "LD_LIBRARY_PATH=$QT_BASE_DIR/lib:$LD_LIBRARY_PATH" >> $GITHUB_ENV
echo "XDG_DATA_DIRS=$QT_BASE_DIR/share:$XDG_DATA_DIRS" >> $GITHUB_ENV
fi
qcoro-0.4.0/.github/actions/install-qt/install-dbus.ps1 0000664 0000000 0000000 00000001057 14165641476 0022775 0 ustar 00root root 0000000 0000000 [Net.ServicePointManager]::SecurityProtocol = [Net.SecurityProtocolType]::Tls12
Install-PackageProvider -Name NuGet -MinimumVersion 2.8.5.201 -Force
Set-PSRepository -Name 'PSGallery' -SourceLocation "https://www.powershellgallery.com/api/v2" -InstallationPolicy Trusted
Install-Module -Name 7Zip4PowerShell -Force
curl https://files.kde.org/craft/master/Qt_5.15.2-1/windows/msvc2019_64/cl/RelWithDebInfo/libs/dbus/dbus-1.13.18-3-131-20210415T121131-windows-msvc2019_64-cl.7z -o C:\Qt\dbus.7z
Expand-7Zip -ArchiveFileName C:\Qt\dbus.7z -TargetPath $args[0]
qcoro-0.4.0/.github/workflows/ 0000775 0000000 0000000 00000000000 14165641476 0016251 5 ustar 00root root 0000000 0000000 qcoro-0.4.0/.github/workflows/build.yml 0000664 0000000 0000000 00000007501 14165641476 0020076 0 ustar 00root root 0000000 0000000 name: Build and Test
on:
push:
branches:
- main
pull_request:
types: [opened, synchronize, reopened, edited]
env:
BUILD_TYPE: RelWithDebInfo
QTEST_FUNCTION_TIMEOUT: 60000
jobs:
build:
strategy:
fail-fast: false
matrix:
os: [ ubuntu-latest, windows-latest ]
qt_version: [ 5.12.1, 6.1.2 ]
compiler: [ gcc-10, clang-11, msvc ]
exclude:
- os: ubuntu-latest
compiler: msvc
- os: windows-latest
compiler: gcc-10
- os: windows-latest
compiler: clang-11
- os: windows-latest
qt_version: 5.12.1
include:
- os: windows-latest
compiler: msvc
qt_version: 5.15.2
runs-on: ${{ matrix.os }}
name: ${{ matrix.os }}-qt${{ matrix.qt_version}}-${{ matrix.compiler }}
steps:
- name: Checkout sources
uses: actions/checkout@v2
- name: Install Qt
uses: ./.github/actions/install-qt
with:
qt_version: ${{ matrix.qt_version }}
compiler: ${{ matrix.compiler }}
- name: Create Build Environment
run: |
cmake -E make_directory ${{github.workspace}}/build
- name: Configure CMake
shell: bash
working-directory: ${{github.workspace}}/build
run: |
QT_VERSION_MAJOR=$(echo ${{ matrix.qt_version }} | cut -d'.' -f1)
ARGS="-DCMAKE_BUILD_TYPE=$BULD_TYPE -DUSE_QT_VERSION=$QT_VERSION_MAJOR -DQCORO_WITH_DBUS=ON"
# Don't enable ASAN on Qt5 MSVC build: it crashes due to some false-positive issue outside of QCoro
if [[ "${{ matrix.compiler }}" != "msvc" || "${QT_VERSION_MAJOR}" != "5" ]]; then
ARGS="${ARGS} -DQCORO_ENABLE_ASAN=ON"
fi
if [[ "${{ matrix.compiler }}" == "gcc-10"* ]]; then
ARGS="$ARGS -DCMAKE_CXX_COMPILER=/usr/bin/g++-10"
elif [[ "${{ matrix.compiler }}" == "clang-11" ]]; then
ARGS="$ARGS -DCMAKE_CXX_COMPILER=/usr/bin/clang++-11"
fi
cmake $GITHUB_WORKSPACE $ARGS
- name: Add ASAN DLL directory to PATH
if: ${{ matrix.os == 'windows-latest' }}
shell: cmd
run: |
setlocal enabledelayedexpansion
for /f "usebackq tokens=*" %%i in (`"%ProgramFiles(x86)%\Microsoft Visual Studio\Installer\vswhere.exe" -latest -products * -requires Microsoft.VisualStudio.Component.VC.Tools.x86.x64 -property installationPath`) do (set InstallDir=%%i)
if exist "%InstallDir%\VC\Auxiliary\Build\Microsoft.VCToolsVersion.default.txt" (
set /p Version=<"%InstallDir%\VC\Auxiliary\Build\Microsoft.VCToolsVersion.default.txt"
set Version=!Version: =!
)
if not "%Version%" == "" (
set /p="%InstallDir%\VC\Tools\MSVC\%Version%\bin\HostX64\x64" < nul > %GITHUB_PATH%
exit 0
)
- name: Build
working-directory: ${{github.workspace}}/build
shell: bash
run: cmake --build . --config $BUILD_TYPE --parallel 4
- name: Test
working-directory: ${{github.workspace}}/build
shell: bash
run: ctest -C $BUILD_TYPE --output-on-failure --verbose --output-junit qcoro-test-results.xml
- name: Upload Test Results
if: always()
uses: actions/upload-artifact@v2
with:
name: Unit Tests Results (${{ matrix.os }}-qt${{ matrix.qt_version }}-${{ matrix.compiler }})
path: |
${{ github.workspace }}/build/qcoro-test-results.xml
- name: Upload build logs on failure
if: failure()
uses: actions/upload-artifact@v2
with:
name: build-${{ matrix.os }}-qt${{ matrix.qt_version }}-${{ matrix.compiler }}
path: build/**
event_file:
name: "Event File"
runs-on: ubuntu-latest
steps:
- name: Upload
uses: actions/upload-artifact@v2
with:
name: Event File
path: ${{ github.event_path }}
qcoro-0.4.0/.github/workflows/unit_tests_results.yml 0000664 0000000 0000000 00000002125 14165641476 0022756 0 ustar 00root root 0000000 0000000 name: Unit Test Results
on:
workflow_run:
workflows: ["Build and Test"]
types:
- completed
jobs:
unit-test-results:
name: Unit Test Results
runs-on: ubuntu-latest
if: github.event.workflow_run.conclusion != 'skipped'
steps:
- name: Download and Extract Artifacts
env:
GITHUB_TOKEN: ${{secrets.GITHUB_TOKEN}}
run: |
mkdir -p artifacts && cd artifacts
artifacts_url=${{ github.event.workflow_run.artifacts_url }}
gh api "$artifacts_url" -q '.artifacts[] | [.name, .archive_download_url] | @tsv' | while read artifact
do
IFS=$'\t' read name url <<< "$artifact"
gh api $url > "$name.zip"
unzip -d "$name" "$name.zip"
done
- name: Publish Unit Test Results
uses: EnricoMi/publish-unit-test-result-action@v1
with:
commit: ${{ github.event.workflow_run.head_sha }}
event_file: artifacts/Event File/event.json
event_name: ${{ github.event.workflow_run.event }}
files: "artifacts/**/*.xml"
qcoro-0.4.0/.github/workflows/update-docs.yml 0000664 0000000 0000000 00000003575 14165641476 0021216 0 ustar 00root root 0000000 0000000 name: Generate documentation
on:
push:
branches:
- main
paths:
- 'mkdocs.yml'
- 'docs/**'
workflow_dispatch:
jobs:
update-docs:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v2
- name: Setup Python
uses: actions/setup-python@v2
with:
python-version: 3.7
- name: Install dependencies
run: |
python -m pip install -r requirements.txt
- name: Build
run: |
echo "{% extends \"base.html\" %}{% block analytics %}
{% endblock %}" > docs/overrides/main.html
mkdocs build -d /tmp/site
- name: Commit files
run: |
git fetch origin gh-pages
git checkout gh-pages
git config --local user.email "41898282+github-actions[bot]@users.noreply.github.com"
git config --local user.name "github-actions[bot]"
git rm -r assets
cp -r /tmp/site/* ./
git add -A
git commit -m "Update docs from main branch ${{ github.sha }}" -a
- name: Publish
if: success()
uses: ad-m/github-push-action@master
with:
github_token: ${{ secrets.GITHUB_TOKEN }}
branch: gh-pages
qcoro-0.4.0/.gitignore 0000664 0000000 0000000 00000000171 14165641476 0014643 0 ustar 00root root 0000000 0000000 build
build-*
.*.swp
.ccls-cache
compile_commands.json
/.vs
/CMakeSettings.json
# Python (from mkdocs)
__pycache__
venv
qcoro-0.4.0/.reuse/ 0000775 0000000 0000000 00000000000 14165641476 0014055 5 ustar 00root root 0000000 0000000 qcoro-0.4.0/.reuse/dep5 0000664 0000000 0000000 00000000433 14165641476 0014635 0 ustar 00root root 0000000 0000000 Format: https://www.debian.org/doc/packaging-manuals/copyright-format/1.0/
Upstream-Name: QCoro
Upstream-Contact: Daniel Vrátil
Source: https://qcoro.github.io
# Sample paragraph, commented out:
#
# Files: src/*
# Copyright: $YEAR $NAME <$CONTACT>
# License: ...
qcoro-0.4.0/CMakeLists.txt 0000664 0000000 0000000 00000012226 14165641476 0015417 0 ustar 00root root 0000000 0000000 cmake_minimum_required(VERSION 3.19)
set(qcoro_VERSION 0.4.0)
set(qcoro_SOVERSION 0)
project(qcoro LANGUAGES CXX VERSION ${qcoro_VERSION})
set(CMAKE_MODULE_PATH ${CMAKE_MODULE_PATH} ${CMAKE_CURRENT_SOURCE_DIR}/cmake)
include(GNUInstallDirs)
include(CTest)
include(FeatureSummary)
# Custom includes
include(GenerateHeaders)
include(AddQCoroLibrary)
#-----------------------------------------------------------#
# Options
#-----------------------------------------------------------#
option(QCORO_BUILD_EXAMPLES "Build examples" ON)
add_feature_info(Examples QCORO_BUILD_EXAMPLES "Build examples")
option(QCORO_ENABLE_ASAN "Build with AddressSanitizer" OFF)
add_feature_info(Asan QCORO_ENABLE_ASAN "Build with AddressSanitizer")
if(WIN32 OR APPLE OR ANDROID)
option(QCORO_WITH_QTDBUS "Build QtDBus support" OFF)
else()
option(QCORO_WITH_QTDBUS "Build QtDBus support" ON)
endif()
add_feature_info(QtDBus QCORO_WITH_QTDBUS "Build QtDBus support")
option(QCORO_WITH_QTNETWORK "Build QtNetwork support" ON)
add_feature_info(QtNetwork QCORO_WITH_QTNETWORK "Build QtNetwork support")
#-----------------------------------------------------------#
# Compiler Settings
#-----------------------------------------------------------#
set(CMAKE_CXX_STANDARD 20)
set(CMAKE_AUTOMOC ON)
if (MSVC)
set(CMAKE_CXX_FLAGS "${CMAKE_CXX_FLAGS} /W4 /WX")
# Disable warning C5054: "operator '&': deprecated between enumerations of different types" caused by QtWidgets/qsizepolicy.h
# Disable warning C4127: "conditional expression is constant" caused by QtCore/qiterable.h
set(CMAKE_CXX_FLAGS "${CMAKE_CXX_FLAGS} /wd5054 /wd4127")
else()
set(CMAKE_CXX_FLAGS "${CMAKE_CXX_FLAGS} -Wall -Wextra -Werror -pedantic")
endif()
if (QCORO_ENABLE_ASAN)
if (MSVC)
set(CMAKE_CXX_FLAGS "${CMAKE_CXX_FLAGS} /fsanitize=address")
else()
set(CMAKE_CXX_FLAGS "${CMAKE_CXX_FLAGS} -fsanitize=address -fno-omit-frame-pointer")
endif()
endif()
include(qcoro/QCoroMacros.cmake)
qcoro_enable_coroutines()
#-----------------------------------------------------------#
# Dependencies
#-----------------------------------------------------------#
find_package(Threads REQUIRED)
set(REQUIRED_QT_COMPONENTS Core)
if (QCORO_WITH_QTDBUS)
list(APPEND REQUIRED_QT_COMPONENTS DBus)
endif()
if (QCORO_WITH_QTNETWORK)
list(APPEND REQUIRED_QT_COMPONENTS Network)
endif()
if (QCORO_BUILD_EXAMPLES)
list(APPEND REQUIRED_QT_COMPONENTS Widgets Concurrent)
endif()
if (BUILD_TESTING)
list(APPEND REQUIRED_QT_COMPONENTS Test Concurrent)
endif()
set(MIN_REQUIRED_QT5_VERSION "5.12")
# 6.1.2 fixes QTBUG-93270 which prevents compiling against Qt6 with C++20 enabled
set(MIN_REQUIRED_QT6_VERSION "6.1.2")
if (NOT USE_QT_VERSION)
# FIXME: find_package(QT NAMES Qt6 Qt5 ...) seems to prefer Qt5 on my system
find_package(Qt6 ${MIN_REQUIRED_QT6_VERSION} COMPONENTS ${REQUIRED_QT_COMPONENTS})
if (NOT Qt6_FOUND)
find_package(Qt5 ${MIN_REQUIRED_QT5_VERSION} COMPONENTS ${REQUIRED_QT_COMPONENTS} REQUIRED)
set(QT_VERSION_MAJOR 5)
else()
set(QT_VERSION_MAJOR 6)
endif()
else()
find_package(Qt${USE_QT_VERSION} ${MIN_REQUIRED_QT${USE_QT_VERSION}_VERSION}
COMPONENTS ${REQUIRED_QT_COMPONENTS} REQUIRED)
set(QT_VERSION_MAJOR ${USE_QT_VERSION})
endif()
configure_file(
${CMAKE_CURRENT_SOURCE_DIR}/config.cmake.in
${CMAKE_CURRENT_BINARY_DIR}/config.h
)
#-----------------------------------------------------------#
# Definitions
#-----------------------------------------------------------#
set(QCORO_TARGET_PREFIX "QCoro${QT_VERSION_MAJOR}")
set(QCORO_INSTALL_INCLUDEDIR "${CMAKE_INSTALL_INCLUDEDIR}/qcoro${QT_VERSION_MAJOR}")
#-----------------------------------------------------------#
# Sources
#-----------------------------------------------------------#
set(QCORO_SOURCE_DIR ${CMAKE_CURRENT_SOURCE_DIR})
add_subdirectory(qcoro)
if (QCORO_BUILD_EXAMPLES)
add_subdirectory(examples)
endif()
if (BUILD_TESTING)
add_subdirectory(tests)
endif()
#-----------------------------------------------------------#
# Installation
#-----------------------------------------------------------#
include(CMakePackageConfigHelpers)
install(FILES
${CMAKE_CURRENT_BINARY_DIR}/config.h
DESTINATION ${QCORO_INSTALL_INCLUDEDIR}/qcoro
COMPONENT Devel
)
configure_package_config_file(
"${CMAKE_CURRENT_SOURCE_DIR}/QCoroConfig.cmake.in"
"${CMAKE_CURRENT_BINARY_DIR}/QCoro${QT_VERSION_MAJOR}Config.cmake"
INSTALL_DESTINATION "${CMAKE_INSTALL_LIBDIR}/cmake/QCoro${QT_VERSION_MAJOR}"
PATH_VARS CMAKE_INSTALL_INCLUDEDIR
)
write_basic_package_version_file(
"${CMAKE_CURRENT_BINARY_DIR}/QCoro${QT_VERSION_MAJOR}ConfigVersion.cmake"
VERSION ${qcoro_VERSION}
COMPATIBILITY SameMajorVersion
)
install(
FILES "${CMAKE_CURRENT_BINARY_DIR}/QCoro${QT_VERSION_MAJOR}Config.cmake"
"${CMAKE_CURRENT_BINARY_DIR}/QCoro${QT_VERSION_MAJOR}ConfigVersion.cmake"
DESTINATION "${CMAKE_INSTALL_LIBDIR}/cmake/QCoro${QT_VERSION_MAJOR}"
COMPONENT Devel
)
#-----------------------------------------------------------#
# Summary
#-----------------------------------------------------------#
feature_summary(FATAL_ON_MISSING_REQUIRED_PACKAGES WHAT ALL)
qcoro-0.4.0/LICENSES/ 0000775 0000000 0000000 00000000000 14165641476 0014061 5 ustar 00root root 0000000 0000000 qcoro-0.4.0/LICENSES/MIT.txt 0000664 0000000 0000000 00000002101 14165641476 0015245 0 ustar 00root root 0000000 0000000 MIT License
Copyright (c) 2021 Daniel Vrátil
Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
qcoro-0.4.0/QCoroConfig.cmake.in 0000664 0000000 0000000 00000003161 14165641476 0016435 0 ustar 00root root 0000000 0000000 if (CMAKE_VERSION VERSION_LESS 3.1.0)
message(FATAL_ERROR \"QCoro@QT_VERSION_MAJOR@ requires at least CMake version 3.1.0\")
endif()
if (NOT QCoro@QT_VERSION_MAJOR@_FIND_COMPONENTS)
set(QCoro@QT_VERSION_MAJOR@_NOT_FOUND_MESSAGE "The QCoro@QT_VERSION_MAJOR@ package requires at least one component")
set(QCoro@QT_VERSION_MAJOR@_FOUND FALSE)
return()
endif()
set(_QCoro_FIND_PARTS_REQUIRED)
if (QCoro@QT_VERSION_MAJOR@_FIND_REQUIRED)
set(_QCoro_FIND_PARTS_REQUIRED REQUIRED)
endif()
set(_QCoro_FIND_PARTS_QUIET)
if (QCoro@QT_VERSION_MAJOR@_FIND_QUIET)
set(_QCoro_FIND_PARTS_QUIET QUIET)
endif()
get_filename_component(_qcoro_install_prefix "${CMAKE_CURRENT_LIST_DIR}/.." ABSOLUTE)
set(_QCoro_NOTFOUND_MESSAGE)
foreach(module ${QCoro@QT_VERSION_MAJOR@_FIND_COMPONENTS})
find_package(QCoro@QT_VERSION_MAJOR@${module}
${_QCoro_FIND_PARTS_QUIET}
${_QCoro_FIND_PARTS_REQUIRED}
PATHS ${_qcoro_install_prefix} NO_DEFAULT_PATH
)
if (NOT QCoro@QT_VERSION_MAJOR@${module}_FOUND)
if (QCoro@QT_VERSION_MAJOR@_FIND_REQUIRED_${module})
set(_QCoro_NOTFOUND_MESSAGE "${_QCoro_NOTFOUND_MESSAGE}Failed to find QCoro component \"${module}\" config file at \"${_qcoro_install_prefix}\"\n")
elseif (NOT QCoro@QT_VERSION_MAJOR@_FIND_QUIETLY)
message(WARNING "Failed to find QCoro@QT_VERSION_MAJOR@ component \"${module}\" config file at \"${_qcoro_install_prefix}\"")
endif()
endif()
endforeach()
if (_QCoro_NOTFOUND_MESSAGE)
set(QCoro@QT_VERSION_MAJOR@_NOT_FOUND_MESSAGE "${_QCoro_NOTFOUND_MESSAGE}")
set(QCoro@QT_VERSION_MAJOR@_FOUND FALSE)
endif()
qcoro-0.4.0/README.md 0000664 0000000 0000000 00000007625 14165641476 0014145 0 ustar 00root root 0000000 0000000 [](https://github.com/danvratil/qcoro/actions/workflows/build.yml)
# QCoro - Coroutines for Qt5 and Qt6
The QCoro library provides set of tools to make use of the C++20 coroutines in connection
with certain asynchronous Qt actions.
Take a look at the example below to see what an amazing thing coroutines are:
```cpp
QNetworkAccessManager networkAccessManager;
// co_await the reply - the coroutine is suspended until the QNetworkReply is finished.
// While the coroutine is suspended, *the Qt event loop runs as usual*.
const QNetworkReply *reply = co_await networkAccessManager.get(url);
// Once the reply is finished, your code resumes here as if nothing amazing has just happened ;-)
const auto data = reply->readAll();
```
This is a rather experimental library that helps me to understand coroutines
in C++.
It requires compiler with support for the couroutines TS.
## Documentation
👉 📘 [Documentation](https://qcoro.dvratil.cz/)
## Supported Qt Types
QCoro supports using the `co_await` keyword with several Qt types:
### `QDBusPendingCall`
QCoro can wait for an asynchronous D-Bus call to finish. There's no need to use `QDBusPendingCallWatcher`
with QCoro - just `co_await` the result instead. While co_awaiting, the Qt event loop runs as usual.
```cpp
QDBusInterface remoteServiceInterface{serviceName, objectPath, interface};
const QDBusReply isReady = co_await remoteServiceInterface.asyncCall(QStringLiteral("isReady"));
```
[Full documentation here](https://qcoro.dvratil.cz/reference/qdbuspendingcall).
### `QFuture`
QFuture represents a result of an asynchronous task. Normally you have to use `QFutureWatcher` to get
notified when the future is ready. With QCoro, you can just `co_await` it!
```cpp
const QFuture task1 = QtConcurrent::run(....);
const QFuture task2 = QtConcurrent::run(....);
const int a = co_await task1;
const int b = co_await task2;
co_return a + b;
```
[Full documentation here](https://qcoro.dvratil.cz/reference/qfuture).
### `QNetworkReply`
Doing network requests with Qt can be tedious - the signal/slot approach breaks the flow
of your code. Chaining requests and error handling quickly become mess and your code is
broken into numerous functions. But not with QCoro, where you can simply `co_await` the
`QNetworkReply` to finish:
```cpp
QNetworkReply qnam;
QNetworkReply *reply = qnam.get(QStringLiteral("https://github.com/danvratil/qcoro"));
const auto contents = co_await reply;
reply->deleteLater();
if (reply->error() != QNetworkReply::NoError) {
co_return handleError(reply);
}
const auto link = findLinkInReturnedHtmlCode(contents);
reply = qnam.get(link);
const auto data = co_await reply;
reply->deleteLater();
if (reply->error() != QNetworkReply::NoError) {
co_return handleError(reply);
}
...
```
[Full documentation here](https://qcoro.dvratil.cz/reference/qnetworkreply).
### `QTimer`
Maybe you want to delay executing your code for a second, maybe you want to execute some
code in repeated interval. This becomes super-trivial with `co_await`:
```cpp
QTimer timer;
timer.setInterval(1s);
timer.start();
for (int i = 1; i <= 100; ++i) {
co_await timer;
qDebug() << "Waiting for " << i << " seconds...";
}
qDebug() << "Done!";
```
[Full documentation here](https://qcoro.dvratil.cz/reference/qtimer).
### `QIODevice`
`QIODevice` is a base-class for many classes in Qt that allow data to be asynchronously
written and read. How do you find out that there are data ready to be read? You could
connect to `QIODevice::readyRead()` singal, or you could use QCoro and `co_await` the object:
```cpp
socket->write("PING");
// Waiting for "pong"
const auto data = co_await socket;
co_return calculateLatency(data);
```
[Full documentation here](https://qcoro.dvratil.cz/reference/qiodevice).
### ...and more!
Go check the [full documentation](https://qcoro.dvratil.cz) to learn more.
qcoro-0.4.0/cmake/ 0000775 0000000 0000000 00000000000 14165641476 0013734 5 ustar 00root root 0000000 0000000 qcoro-0.4.0/cmake/AddQCoroLibrary.cmake 0000664 0000000 0000000 00000010530 14165641476 0017716 0 ustar 00root root 0000000 0000000 # SPDX-FileCopyrightText: 2022 Daniel Vrátil
#
# SPDX-License-Identifier: MIT
include(GenerateHeaders)
include(CMakePackageConfigHelpers)
function(add_qcoro_library)
function(prefix_libraries)
set(oneValueArgs PREFIX OUTPUT)
set(multiValueArgs LIBRARIES)
cmake_parse_arguments(prf "" "${oneValueArgs}" "${multiValueArgs}" ${ARGN})
set(_libs)
foreach(libname ${prf_LIBRARIES})
if ("${libname}" MATCHES "PUBLIC|PRIVATE|INTERFACE")
list(APPEND _libs "${libname}")
else()
list(APPEND _libs "${prf_PREFIX}::${libname}")
endif()
endforeach()
set(${prf_OUTPUT} ${_libs} PARENT_SCOPE)
endfunction()
set(params INTERFACE)
set(oneValueArgs NAME)
set(multiValueArgs SOURCES CAMELCASE_HEADERS HEADERS QCORO_LINK_LIBRARIES QT_LINK_LIBRARIES)
cmake_parse_arguments(LIB "${params}" "${oneValueArgs}" "${multiValueArgs}" ${ARGN})
set(target_name "${QCORO_TARGET_PREFIX}${LIB_NAME}")
string(TOLOWER "${target_name}" target_name_lowercase)
set(target_interface)
set(target_include_interface "PUBLIC")
if (LIB_INTERFACE)
set(target_interface "INTERFACE")
set(target_include_interface "INTERFACE")
endif()
prefix_libraries(
PREFIX ${QCORO_TARGET_PREFIX}
LIBRARIES ${LIB_QCORO_LINK_LIBRARIES}
OUTPUT qcoro_LIBS
)
prefix_libraries(
PREFIX Qt${QT_VERSION_MAJOR}
LIBRARIES ${LIB_QT_LINK_LIBRARIES}
OUTPUT qt_LIBS
)
# TODO: How is it done in Qt?
# We want to export target QCoro5::Network but so far we are exporting
# QCoro5::QCoro5Network :shrug:
add_library(${target_name} ${target_interface})
add_library(${QCORO_TARGET_PREFIX}::${LIB_NAME} ALIAS ${target_name})
if (LIB_SOURCES)
target_sources(${target_name} PRIVATE ${LIB_SOURCES})
endif()
target_include_directories(
${target_name}
${target_include_interface} $
${target_include_interface} $
${target_include_interface} $
${target_include_interface} $
${target_include_interface} $
${target_include_interface} $
${target_include_interface} $
)
target_link_libraries(${target_name} ${qcoro_LIBS})
target_link_libraries(${target_name} ${qt_LIBS})
set_target_properties(
${target_name}
PROPERTIES
WINDOWS_EXPORT_ALL_SYMBOLS 1
VERSION ${qcoro_VERSION}
SOVERSION ${qcoro_SOVERSION}
EXPORT_NAME ${LIB_NAME}
)
generate_headers(
camelcase_HEADERS
HEADER_NAMES ${LIB_CAMELCASE_HEADERS}
OUTPUT_DIR QCoro
ORIGINAL_HEADERS_VAR source_HEADERS
)
configure_package_config_file(
"${CMAKE_CURRENT_SOURCE_DIR}/QCoro${LIB_NAME}Config.cmake.in"
"${CMAKE_CURRENT_BINARY_DIR}/${target_name}Config.cmake"
INSTALL_DESTINATION ${CMAKE_INSTALL_LIBDIR}/cmake/${target_name}
PATH_VARS CMAKE_INSTALL_INCLUDEDIR
)
write_basic_package_version_file(
"${CMAKE_CURRENT_BINARY_DIR}/${target_name}ConfigVersion.cmake"
VERSION ${qcoro_VERSION}
COMPATIBILITY SameMajorVersion
)
install(
TARGETS ${target_name}
EXPORT ${target_name}Targets
)
install(
FILES ${source_HEADERS} ${LIB_HEADERS}
DESTINATION ${QCORO_INSTALL_INCLUDEDIR}/qcoro/
COMPONENT Devel
)
install(
FILES ${camelcase_HEADERS}
DESTINATION ${QCORO_INSTALL_INCLUDEDIR}/QCoro/
COMPONENT Devel
)
install(
FILES "${CMAKE_CURRENT_BINARY_DIR}/${target_name}Config.cmake"
"${CMAKE_CURRENT_BINARY_DIR}/${target_name}ConfigVersion.cmake"
DESTINATION "${CMAKE_INSTALL_LIBDIR}/cmake/${target_name}"
COMPONENT Devel
)
install(
EXPORT ${target_name}Targets
DESTINATION "${CMAKE_INSTALL_LIBDIR}/cmake/${target_name}"
FILE "${target_name}Targets.cmake"
NAMESPACE ${QCORO_TARGET_PREFIX}::
COMPONENT Devel
)
endfunction()
qcoro-0.4.0/cmake/GenerateHeaders.cmake 0000664 0000000 0000000 00000002264 14165641476 0017770 0 ustar 00root root 0000000 0000000 function(generate_headers output_var)
set(options)
set(oneValueArgs OUTPUT_DIR ORIGINAL_PREFIX ORIGINAL_HEADERS_VAR)
set(multiValueArgs HEADER_NAMES)
cmake_parse_arguments(GH "${options}" "${oneValueArgs}" "${multiValueArgs}" ${ARGN})
if (GH_OUTPUT_DIR)
set(GH_OUTPUT_DIR "${GH_OUTPUT_DIR}/")
endif()
foreach(_headername ${GH_HEADER_NAMES})
string(TOLOWER "${_headername}" originalbase)
set(CC_ORIGINAL_FILE "${CMAKE_CURRENT_SOURCE_DIR}/${GH_ORIGINAL_PREFIX}/${originalbase}.h")
if (NOT EXISTS ${CC_ORIGINAL_FILE})
message(FATAL_ERROR "Could not find header \"${CC_ORIGINAL_FILE}\"")
endif()
set(CC_HEADER_FILE "${CMAKE_CURRENT_BINARY_DIR}/${GH_OUTPUT_DIR}/${_headername}")
if (NOT EXISTS ${CC_HEADER_FILE})
file(WRITE ${CC_HEADER_FILE} "#include \"${GH_ORIGINAL_PREFIX}${originalbase}.h\"")
endif()
list(APPEND ${output_var} ${CC_HEADER_FILE})
list(APPEND ${GH_ORIGINAL_HEADERS_VAR} ${CC_ORIGINAL_FILE})
endforeach()
set(${output_var} ${${output_var}} PARENT_SCOPE)
set(${GH_ORIGINAL_HEADERS_VAR} ${${GH_ORIGINAL_HEADERS_VAR}} PARENT_SCOPE)
endfunction()
qcoro-0.4.0/config.cmake.in 0000664 0000000 0000000 00000000045 14165641476 0015527 0 ustar 00root root 0000000 0000000 #cmakedefine QCORO_QT_HAS_COMPAT_ABI
qcoro-0.4.0/docs/ 0000775 0000000 0000000 00000000000 14165641476 0013604 5 ustar 00root root 0000000 0000000 qcoro-0.4.0/docs/about/ 0000775 0000000 0000000 00000000000 14165641476 0014716 5 ustar 00root root 0000000 0000000 qcoro-0.4.0/docs/about/license.md 0000664 0000000 0000000 00000002176 14165641476 0016670 0 ustar 00root root 0000000 0000000 # License
---
QCoro is published under the MIT License
## MIT License
Copyright (c) 2021 Daniel Vrátil
Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
qcoro-0.4.0/docs/building-and-using.md 0000664 0000000 0000000 00000003277 14165641476 0017617 0 ustar 00root root 0000000 0000000 # Building and Using QCoro
## Building QCoro
QCoro uses CMake build system. You can pass following options to the `cmake` command when building
QCoro to customize the build:
* `-DQCORO_BUILD_EXAMPLES` - whether to build examples or not (`ON` by default).
* `-DQCORO_ENABLE_ASAN` - whether to build QCoro with AddressSanitizer (`OFF` by default).
* `-DBUILD_SHARED_LIBS` - whether to build QCoro as a shared library (`OFF` by default).
* `-DBUILD_TESTING` - whether to build tests (`ON` by default).
* `-DUSE_QT_VERSION` - set to `5` or `6` to force a particular version of Qt. When not set the highest available version is used.
* `-DQCORO_WITH_QTDBUS` - whether to compile support for QtDBus (`ON` by default).
* `-DQCORO_WITH_QTNETWORK` - whether to compile support for QtNetwork (`ON` by default).
```
mkdir build
cd build
cmake ..
make
# This will install QCoro into /usr/local/ prefix, change it by passing -DCMAKE_INSTALL_PREFIX=/usr
# to the cmake command above.
sudo make install
```
## Add it to your CMake
Depending on whether you want to use Qt5 or Qt6 build of QCoro, you should use `QCoro5` or QCoro6` in your
CMake code, respectively. The example below is assuming Qt6:
```cmake
# Use QCoro5 if you are building for Qt5!
find_package(QCoro6 REQUIRED COMPONENTS Core Network DBus)
# Set necessary compiler flags to enable coroutine support
qcoro_enable_coroutines()
...
target_link_libraries(your-target QCoro::Core QCoro::Network QCoro::DBus)
```
Note the missing Qt version number in the `QCoro` target namespace: QCoro provides both
versioned (`QCoro5` and `QCoro6`) namespaces as well as version-less namespace, which is
especially useful for transitioning codebase from Qt5 to Qt6.
qcoro-0.4.0/docs/changelog.md 0000664 0000000 0000000 00000013575 14165641476 0016070 0 ustar 00root root 0000000 0000000 # Changelog
## 0.4.0 (2022-01-06)
Major highlights in this release:
* Co-installability of Qt5 and Qt6 builds of QCoro
* Complete re-work of CMake configuration
* Support for compiling QCoro with Clang against libstdc++
### Co-installability of Qt5 and Qt6 builds of QCoro
This change mostly affects packagers of QCoro. It is now possible to install both Qt5 and Qt6 versions
of QCoro alongside each other without conflicting files. The shared libraries now contain the Qt version
number in their name (e.g. `libQCoro6Core.so`) and header files are also located in dedicated subdirectories
(e.g. `/usr/include/qcoro6/{qcoro,QCoro}`). User of QCoro should not need to do any changes to their codebase.
### Complete re-work of CMake configuration
This change affects users of QCoro, as they will need to adjust CMakeLists.txt of their projects. First,
depending on whether they want to use Qt5 or Qt6 version of QCoro, a different package must be used.
Additionally, list of QCoro components to use must be specified:
```
find_package(QCoro5 REQUIRED COMPONENTS Core Network DBus)
```
Finally, the target names to use in `target_link_libraries` have changed as well:
* `QCoro::Core`
* `QCoro::Network`
* `QCoro::DBus`
The version-less `QCoro` namespace can be used regardless of whether using Qt5 or Qt6 build of QCoro.
`QCoro5` and `QCoro6` namespaces are available as well, in case users need to combine both Qt5 and Qt6
versions in their codebase.
This change brings QCoro CMake configuration system to the same style and behavior as Qt itself, so it
should now be easier to use QCoro, especially when supporting both Qt5 and Qt6.
### Support for compiling QCoro with Clang against libstdc++
Until now, when the Clang compiler was detected, QCoro forced usage of LLVM's libc++ standard library.
Coroutine support requires tight co-operation between the compiler and standard library. Because Clang
still considers their coroutine support experimental it expects all coroutine-related types in standard
library to be located in `std::experimental` namespace. In GNU's libstdc++, coroutines are fully supported
and thus implemented in the `std` namespace. This requires a little bit of extra glue, which is now in place.
### Full changelog
* QCoro can now be built with Clang against libstdc++ ([#38](https://github.com/danvratil/qcoro/pull/38), [#22](https://github.com/danvratil/qcoro/issues/22))
* Qt5 and Qt6 builds of QCoro are now co-installable ([#36](https://github.com/danvratil/qcoro/issues/36), [#37](https://github.com/danvratil/qcoro/pull/37))
* Fixed early co_return not resuming the caller ([#24](https://github.com/danvratil/qcoro/issue/24), [#35](https://github.com/danvratil/qcoro/pull/35))
* Fixed QProcess example ([#34](https://github.com/danvratil/qcoro/pull/34))
* Test suite has been improved and extended ([#29](https://github.com/danvratil/qcoro/pull/29), [#31](https://github.com/danvratil/qcoro/pull/31))
* Task move assignment operator checks for self-assignment ([#27](https://github.com/danvratil/qcoro/pull/27))
* QCoro can now be built as a subdirectory inside another CMake project ([#25](https://github.com/danvratil/qcoro/pull/25))
* Fixed QCoroCore/qcorocore.h header ([#23](https://github.com/danvratil/qcoro/pull/23))
* DBus is disabled by default on Windows, Mac and Android ([#21](https://github.com/danvratil/qcoro/pull/21))
Thanks to everyone who contributed to QCoro!
## 0.3.0 (2021-10-11)
* Added SOVERSION to shared libraries ([#17](https://github.com/danvratil/qcoro/pull/17))
* Fixed building tests when not building examples ([#19](https://github.com/danvratil/qcoro/pull/19))
* Fixed CI
Thanks to everyone who contributed to QCoro 0.3.0!
## 0.2.0 (2021-09-08)
### Library modularity
The code has been reorganized into three modules (and thus three standalone libraries): QCoroCore, QCoroDBus and
QCoroNetwork. QCoroCore contains the elementary QCoro tools (`QCoro::Task`, `qCoro()` wrapper etc.) and coroutine
support for some QtCore types. The QCoroDBus module contains coroutine support for types from the QtDBus module
and equally the QCoroNetwork module contains coroutine support for types from the QtNetwork module. The latter two
modules are also optional, the library can be built without them. It also means that an application that only uses
let's say QtNetwork and has no DBus dependency will no longer get QtDBus pulled in through QCoro, as long as it
only links against `libQCoroCore` and `libQCoroNetwork`. The reorganization will also allow for future
support of additional Qt modules.
### Headers clean up
The include headers in QCoro we a bit of a mess and in 0.2.0 they all got a unified form. All public header files
now start with `qcoro` (e.g. `qcorotimer.h`, `qcoronetworkreply.h` etc.), and QCoro also provides CamelCase headers
now. Thus users should simply do `#include ` if they want coroutine support for `QTimer`.
The reorganization of headers makes QCoro 0.2.0 incompatible with previous versions and any users of QCoro will
have to update their `#include` statements. I'm sorry about this extra hassle, but with this brings much needed
sanity into the header organization and naming scheme.
### Docs update
The documentation has been updated to reflect the reorganization as well as some internal changes. It should be
easier to understand now and hopefully will make it easier for users to start with QCoro now.
### Internal API cleanup and code de-duplication
Historically, certain types types which can be directly `co_await`ed with QCoro, for instance `QTimer` has their
coroutine support implemented differently than types that have multiple asynchronous operations and thus have
a coroutine-friendly wrapper classes (like `QIODevice` and it's `QCoroIODevice` wrapper). In 0.2.0 I have unified
the code so that even the coroutine support for simple types like `QTimer` are implemented through wrapper classes
(so there's `QCoroTimer` now)
## 0.1.0 (2021-08-15)
* Initial release QCoro
qcoro-0.4.0/docs/coroutines/ 0000775 0000000 0000000 00000000000 14165641476 0015776 5 ustar 00root root 0000000 0000000 qcoro-0.4.0/docs/coroutines/coawait.md 0000664 0000000 0000000 00000004432 14165641476 0017752 0 ustar 00root root 0000000 0000000 # `co_await` Explained
The following paragraphs try to explain what is a coroutine and what `co_await` does in some
simple way. I don't guarantee that any of this is factically correct. For more gritty (and
correct) details, refer to the articles linked at the bottom of this document.
Coroutines, simply put, are like normal functions except that they can be suspended (and resumed)
in the middle. When a coroutine is suspended, execution returns to the function that has called
the coroutine. If that function is also a coroutine and is waiting (`co_await`ing) for the current
coroutine to finish, then it is suspended as well and the execution returns to the function that has
called that coroutine and so on, until a function that is an actual function (not a coroutine) is reached.
In case of a regular Qt program, this "top-level" non-coroutine function will be the Qt's event loop -
which means that while your coroutine, when called from the Qt event loop is suspended, the Qt event
loop will continue to run until the coroutine is resumed again.
Amongst many other things, this allows you to write asynchronous code as if it were synchronous without
blocking the Qt event loop and making your application unresponsive. See the different examples in this
document.
Now let's look at the `co_await` keyword. This keyword tells the compiler that this is the point where
the coroutine wants to be suspended, until the *awaited* object (the *awaitable*) is ready. Anything type
can be *awaitable* - either because it directly implements the interface needed by the C++ coroutine
machinery, or because some external tools (like this library) are provided to wrap that type into something
that implements the *awaitable* interface.
The C++ coroutines introduce two additional keywords -`co_return` and `co_yield`:
From an application programmer point of view, `co_return` behaves exactly the same as `return`, except that
you cannot use the regular `return` in coroutines. There are some major differences under the hood, though,
which is likely why there's a special keyword for returning from coroutines.
`co_yield` allows a coroutine to produce a result without actually returning. Can be used for writing
generators. Currently, this library has no support/usage of `co_yield`, so I won't go into more details
here.
qcoro-0.4.0/docs/coroutines/qt-vs-coawait.md 0000664 0000000 0000000 00000002570 14165641476 0021023 0 ustar 00root root 0000000 0000000 # Qt vs. co_await
One of the best examples where coroutines simplify your code is when dealing with asynchronous
operations, like network operations.
Let's see how a simple HTTP request would be handled in Qt using the signals/slots mechanism:
```cpp
void MyClass::fetchData() {
auto *nam = new QNetworkAccessManager(this);
auto *reply = nam->get(QUrl{QStringLiteral("https://.../api/fetch")});
QObject::connect(reply, &QNetworkReply::finished,
[reply, nam]() {
const auto data = reply->readAll();
doSomethingWithData(data);
reply->deleteLater();
nam->deleteLater();
});
}
```
Now let's see how the code looks like if we use coroutines:
```cpp
QCoro::Task<> MyClass::fetchData() {
QNetworkReply nam;
auto *reply = co_await nam.get(QUrl{QStringLiteral("https://.../api/fetch")});
const auto data = reply->readAll();
reply->deleteLater();
doSomethingWithData(data);
}
```
The magic here is the `co_await` keyword which has turned our method `fetchData()`
into a coroutine and suspended its execution while the network request was running.
When the request finishes, the coroutine is resumed from where it was suspended and
continues.
And the best part? While the coroutine is suspended, the Qt event loop runs as usual!
qcoro-0.4.0/docs/coroutines/reading.md 0000664 0000000 0000000 00000001442 14165641476 0017732 0 ustar 00root root 0000000 0000000 # More reading
This library is inspired by Lewis Bakers' cppcoro library, which also served as a guide to implementing
the coroutine machinery, alongside his great series on C++ coroutines:
* [Coroutine Theory](https://lewissbaker.github.io/2017/09/25/coroutine-theory)
* [Understanding Operator co_await](https://lewissbaker.github.io/2017/11/17/understanding-operator-co-await)
* [Understanding the promise type](https://lewissbaker.github.io/2018/09/05/understanding-the-promise-type)
* [Understanding Symmetric Transfer](https://lewissbaker.github.io/2020/05/11/understanding_symmetric_transfer)
I can also recommend numerous articles about C++ coroutines by [Raymond Chen on his blog OldNewThink][oldnewthing].
[oldnewthing]: https://devblogs.microsoft.com/oldnewthing/author/oldnewthing
qcoro-0.4.0/docs/examples/ 0000775 0000000 0000000 00000000000 14165641476 0015422 5 ustar 00root root 0000000 0000000 qcoro-0.4.0/docs/examples/qdbus.cpp 0000664 0000000 0000000 00000002675 14165641476 0017256 0 ustar 00root root 0000000 0000000 #include
QCoro::Task PlayerControl::nextSong() {
// Create a regular QDBusInterface representing the Spotify MPRIS interface
QDBusInterface spotifyPlayer{QStringLiteral("org.mpris.MediaPlayer2.spotify"),
QStringLiteral("/org/mpris/MediaPlayer2"),
QStringLiteral("org.mpris.MediaPlayer2.Player")};
// Call CanGoNext DBus method and co_await reply. During that the current coroutine is suspended.
const QDBusReply canGoNext = co_await spotifyPlayer.asyncCall(QStringLiteral("CanGoNext"));
// Response has arrived and coroutine is resumed. If the player can go to the next song,
// do another async call to do so.
if (static_cast(canGoNext)) {
// co_await the call to finish, but throw away the result
co_await spotifyPlayer.asyncCall(QStringLiteral("Next"));
}
// Finally, another async call to retrieve new track metadata. Once again, the coroutine
// is suspended while we wait for the result.
const QDBusReply metadata = co_await spotifyPlayer.asyncCall(QStringLiteral("Metadata"));
// Since this function uses co_await, it is in fact a coroutine, so it must use co_return in order
// to return our result. By definition, the result of this function can be co_awaited by the caller.
co_return static_cast(metadata)[QStringLiteral("xesam:title")].toString();
}
qcoro-0.4.0/docs/examples/qfuture.cpp 0000664 0000000 0000000 00000001042 14165641476 0017616 0 ustar 00root root 0000000 0000000 #include
QCoro::Task<> runTask() {
// Starts a concurrent task and co_awaits on the returned QFuture. While the task is
// running, the coroutine is suspended.
const QString value = co_await QtConcurrent::run([]() {
QString result;
...
// do some long-running computation
...
return result;
});
// When the future has finished, the coroutine is resumed and the result of the
// QFuture is returned and stored in `value`.
// ... now do something with the value
}
qcoro-0.4.0/docs/examples/qnetworkreply.cpp 0000664 0000000 0000000 00000001344 14165641476 0021056 0 ustar 00root root 0000000 0000000 #include
QCoro::Task<> MyClass::fetchData() {
// Creates QNetworkAccessManager on stack
QNetworkAccessManager nam;
// Calls QNetworkAccessManager::get() and co_awaits on the returned QNetworkReply*
// until it finishes. The current coroutine is suspended until that.
auto *reply = co_await nam.get(QUrl{QStringLiteral("https://.../api/fetch")});
// When the reply finishes, the coroutine is resumed and we can access the reply content.
const auto data = reply->readAll();
// Raise your hand if you never forgot to delete a QNetworkReply...
delete reply;
doSomethingWithData(data);
// Extra bonus: the QNetworkAccessManager is destroyed automatically, since it's on stack.
}
qcoro-0.4.0/docs/examples/qprocess.cpp 0000664 0000000 0000000 00000000626 14165641476 0017771 0 ustar 00root root 0000000 0000000 #include
QCoro::Task listDir(const QString &dirPath) {
QProcess basicProcess;
auto process = qCoro(basicProcess);
qDebug() << "Starting ls...";
co_await process.start(QStringLiteral("/bin/ls"), {dirPath});
qDebug() << "Ls started, reading directory...";
co_await process.waitForFinished();
qDebug() << "Done";
return basicProcess.readAll();
}
qcoro-0.4.0/docs/examples/qtcpserver.cpp 0000664 0000000 0000000 00000000527 14165641476 0020330 0 ustar 00root root 0000000 0000000 #include
QCoro::Task<> runServer(uint16_t port) {
QTcpServer server;
server.listen(QHostAddress::LocalHost, port);
while (server.isListening()) {
auto *socket = co_await qCoro(server).waitForNewConnection(10s);
if (socket != nullptr) {
newClientConnection(socket);
}
}
}
qcoro-0.4.0/docs/examples/qtcpsocket.cpp 0000664 0000000 0000000 00000000712 14165641476 0020306 0 ustar 00root root 0000000 0000000 #include
QCoro::Task requestDataFromServer(const QString &hostName) {
QTcpSocket socket;
if (!co_await qCoro(socket).connectToHost(hostName)) {
qWarning() << "Failed to connect to the server";
co_return QByteArray{};
}
socket.write("SEND ME DATA!");
QByteArray data;
while (!data.endsWith("\r\n.\r\n")) {
data += co_await qCoro(socket).readAll();
}
co_return data;
}
`
qcoro-0.4.0/docs/index.md 0000664 0000000 0000000 00000010677 14165641476 0015250 0 ustar 00root root 0000000 0000000 # QCoro
C++ Coroutine library for Qt5 and Qt6
---
## Overview
QCoro is a C++ library that provide set of tools to make use of C++20 coroutines
in connection with certain asynchronous Qt actions.
Take a look at the example below to see what an amazing thing coroutines are:
```cpp
QNetworkAccessManager networkAccessManager;
// co_await the reply - the coroutine is suspended until the QNetworkReply is finished.
// While the coroutine is suspended, *the Qt event loop runs as usual*.
const QNetworkReply *reply = co_await networkAccessManager.get(url);
// Once the reply is finished, your code resumes here as if nothing amazing has just happened ;-)
const auto data = reply->readAll();
```
This library has only one class and one function that the user must be aware of: the class is
[`QCoro::Task`](reference/coro/task.md) and must be used as a return type for any coroutine that `co_await`s
a Qt type. The function is [`qCoro()`](reference/coro/coro.md) and it provides coroutine-friendly
wrappers for Qt types that have multiple asynchronous operations that the user may want to `co_await`
(for example [`QProcess`](reference/core/qprocess.md)). All the other code (basically everything in the
`QCoro::detail` namespace) is here to provide the cogs and gears for the C++ coroutine machinery,
making it possible to use Qt types with coroutines.
The major benefit of using coroutines with Qt types is that it allows writing asynchronous code as if it
were synchronous and, most importantly, while the coroutine is `co_await`ing, the __Qt event loop runs
as usual__, meaning that your application remains responsive.
This is a rather experimental library that I started working on to better understand coroutines
in C++. After reading numerous articles and blog posts about coroutines, it still wasn't exactly
clear to me how the whole thing works, so I started working on this library to get a better idea
about coroutines.
## Coroutines
Coroutines are regular functions, except that they can be suspended and resumed again. When
a coroutine is suspended, it returns sort of a promise to the caller and the caller continues
executing their code. At some point, the caller can use the newly introduced `co_await` keyword
to wait for the returned promise to be fulfilled. When that happens, the caller is suspended
and instead the coroutine is resumed.
This allows writing asynchronous code as if it were synchronous, making it much easier to read
and understand.
That's not all that coroutines can do, you can read more about it in the 'Coroutines' section
of this documentation.
## Supported Compilers
This library requires a compiler that supports the Coroutine TS (obviously). Currently
GCC, Clang and MSVC are supported.
All examples were tested with GCC 10 and Clang 11, although even slightly older versions
should work.
In both GCC and Clang, coroutine support must be explicitly enabled.
### GCC
To enable coroutines support in GCC, add `-fcoroutines` to `CXX_FLAGS`.
CMake:
```
set(CMAKE_CXX_STANDARD 20)
set(CMAKE_CXX_FLAGS "${CMAKE_CXX_FLAGS} -fcoroutines")
```
Alternatively, just use `qcoro_enable_coroutines()` CMake macro provided by QCoro to set the
flags automatically.
### Clang
In Clang coroutines are still considered experimental (unlike in GCC), so
you cannot mix Clang and libstdc++. You must use Clang with libc++. Coroutines
are enabled by adding `-fcoroutines-ts` to `CMAKE_CXX_FLAGS`.
CMake:
```
set(CMAKE_CXX_STANDARD 20)
set(CMAKE_CXX_FLAGS "${CMAKE_CXX_FLAGS} -fcoroutines-ts -stdlib=libc++")
```
Alternatively, just use `qcoro_enable_coroutines()` CMake macro provided by QCoro to set the
flags automatically.
!!! info "LLVM libc++ vs. GNU libstdc++"
While both libraries implement the same standard they are not mutually compatible - for one thing LLVM's
libc++ is a bit behind libstdc++ on implementing all the features, but more importantly they are not
ABI compatible. That means that if you compile Qt with libstdc++ (which most Linux distributions do)
and your application with QCoro using libc++, you will likely run into `undefined reference` errors
when linking your app against Qt.
One option is to build Qt youself with libc++, other option is to use GCC or MSVC and avoid Clang until
it has full support for coroutines, which will hopefully allow using libstdc++ with Clang.
### MSVC
Coroutine support in MSVC is enabled automatically by CMake when C++20 standard is specified
in `CMAKE_CXX_STANDARD`:
```
set(CMAKE_CXX_STANDARD 20)
```
qcoro-0.4.0/docs/macros.py 0000664 0000000 0000000 00000001447 14165641476 0015450 0 ustar 00root root 0000000 0000000 def define_env(env):
@env.macro
def doctable(module, include, inherits=None, inheritedBy=[]):
def row(th, td):
return f"| { th } | { td } |
|---|
"
def inheritsLink(inherits):
return f"""{inherits[1]}"""
out = """"""
out += row("Module", module)
out += row("Include", f"""
```cpp
#include <{include}>
```
""")
out += row("CMake", f"""
```cpp
target_link_libraries(myapp QCoro::{module})
```
""")
if inherits:
out += row("Inherits", inheritsLink(inherits))
if inheritedBy:
out += row("Inherited By", ', '.join(sorted(map(inheritsLink, inheritedBy))))
out += "