Arcana.cpp - Arcana.cpp is a collection of helpers and utility code for low overhead, cross platform C++ implementation of task-based asynchrony.

Overview

Arcana.cpp

Arcana is a collection of general purpose C++ utilities with no code that is specific to a particular project or specialized technology area, sort of like an extension to the STL. At present, the most notable of these utilities is the Arcana task library.

You can learn more about API usage in the arcana.cpp documentation.

Getting Started

  1. Clone the repo and checkout the master branch.
  2. Arcana depends on GSL, so be sure to update your submodules: git submodule update --init --recursive

Prerequisites

Visual Studio 2017

You will need the following optional components:

  • UWP
  • Windows 10 SDK
  • Android

You can add these to your Visual Studio installation via:

"C:\Program Files (x86)\Microsoft Visual Studio\Installer\vs_installer.exe" modify ^
--installPath "C:\Program Files (x86)\Microsoft Visual Studio\2017\Enterprise" ^
--add Microsoft.VisualStudio.Component.UWP.Support ^
--add Microsoft.VisualStudio.Component.Windows10SDK.17134 ^
--add Component.Android.NDK.R15C ^
--add Component.Android.NDK.R15C_3264 ^
--add Component.Android.SDK19.Private ^
--add Component.Android.SDK21.Private ^
--add Component.Android.SDK22.Private ^
--add Component.Android.SDK23 ^
--add Component.Android.SDK23.Private ^
--add Component.Android.SDK25.Private ^
--add Component.MDD.Android

Installing

Build the Code

The code can be built from Visual Studio via:

  1. Open Source\Arcana.cpp.sln.
  2. Select a target configuration (e.g. Debug) and platform (e.g. x86).
  3. Build the solution.

Alternatively, the code can be built from the command line via:

  1. Open the Developer Command Prompt for VS 2017
  2. Type msbuild Source\Arcana.cpp.sln /p:Configuration=Release /p:Platform=x86

Replace Release and x86 with whatever configuration and platform you would like to build locally.

Running the tests

The unit tests can be run within Visual Studio via Test Explorer, or from the Developer Command Prompt for VS 2017 via:

"C:\Program Files (x86)\Microsoft Visual Studio\2017\Enterprise\Common7\IDE\Extensions\TestPlatform\vstest.console.exe" .\BuildOutput\Debug\Win32\Arcana.UWP.Test\Bin\Arcana.UWP.Test.dll

Deployment

There is no official deployment mechanism available at this time.

Contributing

Please read CONTRIBUTING.md for details on our code of conduct, and the process for submitting pull requests to us.

Versioning

arcana.cpp does not use SemVer. Instead, it uses a version derived from the current date. Therefore, the version contains no semantic information.

Maintainers

With questions, please contact one of the maintainers:

Credits

Arcana owes especial thanks to:

Reporting Security Issues

Security issues and bugs should be reported privately, via email, to the Microsoft Security Response Center (MSRC) at [email protected]. You should receive a response within 24 hours. If for some reason you do not, please follow up via email to ensure we received your original message. Further information, including the MSRC PGP key, can be found in the Security TechCenter.

Comments
  • Add performance tracing abstraction

    Add performance tracing abstraction

    This is intended to be a light weight mechanism to perform a performance trace interval. The implementation will be different per platform, and so far I've only implemented it for Apple. Ideally they would all share a header to ensure the contract is identical across platforms, but I'm not sure how to do this in way that is both header only and the implementations are per platform. Open to suggestions on this.

    opened by ryantrem 2
  • Added lazy type.

    Added lazy type.

    A use case came up for this while fixing a Babylon Native bug where an XR-related global needs to be lazily instantiated (or some alternative) so that it's never created on computers that don't have an OpenXR runtime. We can do without this -- the precipitating issue is small enough to be gracefully handled with a bespoke implementation -- but lazy evaluation is a common enough pattern that I was actually a little surprised there doesn't appear to be an STL type for this (there's an experimental one in Rust, but I didn't see one in C++).

    Note: If we decide we actually want this, a little more thought will need to be given to things like implicit constructors and copyability. This draft is just to propose the type and discuss if it's something we think is worth having.

    opened by syntheticmagus 2
  • Rethrow unhandled errors

    Rethrow unhandled errors

    Change behavior of returning payloads to rethrow unhandled errors -- that is, errors which remain on a dying payload which has never executed a continuation. Open questions remain about how this functionality relates to teardown and/or cancellation.

    opened by syntheticmagus 1
  • This repo is missing important files

    This repo is missing important files

    There are important files that Microsoft projects should all have that are not present in this repository. A pull request has been opened to add the missing file(s). When the pr is merged this issue will be closed automatically.

    Microsoft teams can learn more about this effort and share feedback within the open source guidance available internally.

    Merge this pull request

    opened by microsoft-github-policy-service[bot] 0
  • Adding Microsoft SECURITY.MD

    Adding Microsoft SECURITY.MD

    Please accept this contribution adding the standard Microsoft SECURITY.MD :lock: file to help the community understand the security policy and how to safely report security issues. GitHub uses the presence of this file to light-up security reminders and a link to the file. This pull request commits the latest official SECURITY.MD file from https://github.com/microsoft/repo-templates/blob/main/shared/SECURITY.md.

    Microsoft teams can learn more about this effort and share feedback within the open source guidance available internally.

    opened by microsoft-github-policy-service[bot] 0
  • Pinnable cancellations

    Pinnable cancellations

    Changes the behavior of cancellation by making cancellation tokens "pin" the cancellation source under certain circumstances. Most importantly, cancellations get pinned while the work payload they are made to cancel is being executed. This makes cancelling a cancel source a blocking operation; a pinned cancellation source will block on cancel until it is unpinned. At the same time, cancelling immediately prevents any further pinning. The end result is that calling cancel() now means that no new work guarded by this cancellation can be started, but all work guarded by this cancellation will be finished before cancel() returns. This can be used, for example, to ensure that task can safely utilize resources without taking ownership of them. Suppose, for example, that a class Foo has a member variable m_bar and a cancellation source m_cancelSource. So long as ~Foo() calls m_cancelSource.cancel() before it destructs m_bar, tasks run using m_cancelSource can safely use m_bar without worrying that it might be destructed by Foo's lifecycle after the task has started but before the task completes.

    opened by syntheticmagus 0
  • No destroy cancellation none

    No destroy cancellation none

    This change addresses a problem we were encountering in Babylon Native where cancellation::none was getting torn down by one thread while another thread still needed it to exist. A proposal, referenced in a comment in the code, exists to standardize a mechanism for handling this type of error:

    http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2018/p1247r0.html

    However, since this proposal is not yet standard, I instead adopted one of the alternatives listed in the proposal to resolve this problem for now. This change has been tested and confirmed to solve the problem Babylon Native was exhibiting.

    opened by syntheticmagus 0
  • Fix issues with run_loop_scheduler

    Fix issues with run_loop_scheduler

    We found a couple of problems with the run_loop_scheduler when used in the context of React Native (but these are problems in general).

    1. Work queued into a CFRunLoop is not necessarily automatically dequeued and run. Something needs to "wake up" the run loop thread and tell it to process pending work. Without an explicit call to CFRunLoopWakeUp, we are depending on someone else happening to call that. In the context of Babylon React Native, this was happening through other operations on the JS thread (in the demo app, it was specifically updates happening between the UI thread and JS thread to update the FPS counter, such that if the FPS counter was turned off, the scene stopped rendering because the CFRunLoop stopped dequeuing pending operations because no one was calling CFRunLoopWakeUp). We should call this explicitly every time we queue work in the CFRunLoop since this is the purpose of the scheduler.
    2. Scheduling with kCFRunLoopDefaultMode can cause our queued operations to be starved if higher priority operations are queued. Scheduling with kCFRunLoopCommonModes ensures that our queued work is treated fairly with most other scheduled work, preventing possible starvation.

    For another example of using the CFRunLoop in this way, see https://github.com/facebook/react-native/blob/d0871d0a9a373e1d3ac35da46c85c0d0e793116d/React/CxxBridge/RCTMessageThread.mm#L47

    opened by ryantrem 0
  • Add run_loop_scheduler

    Add run_loop_scheduler

    This change primarily is adding a run_loop_scheduler based on CFRunLoop (the lowest level version of a run loop on Apple).

    As a minor fix, I also added a #include <thread> as it was previously missing and resulting in a compile error (due to the pre-existing use of std::thread) for me.

    opened by ryantrem 0
  • Uncopyable work queue

    Uncopyable work queue

    Modified dispatcher.h to use uncopyable inplace_functions. This required some significant modification to the uncopyable features added to inplace_function previously, as that implementation had some serious flaws. In particular, while the implementation prevented copying and prevented the copy constructor from existing, it didn't actually delete the copy constructor. This meant that code which was simply looking to see whether uncopyable inplace_functions had a copy constructor -- notably std::is_copy_constructible -- to see that the copy constructor still existed and to conclude, therefore, that the type was copyable. This caused problems when it led MSVC's implementation of certain STL containers to elect to copy rather than move, only to fail when the copy constructor turned out to be unusable.

    To solve this problem, the copy constructor needed to be deleted, not merely unusable; and to do that, the uncopyable version of the inplace_function needed to be a specialization of the entire type, not just of specific functions. Thus, inplace_function.h now contains two inplace_function specializations, one copyable and one not, with the shared behavior factored out as much as possible into a separate impl. With this change, std::is_copy_constructible is able to correctly determine the copyability of inplace_functions, leading MSVC's STL to make the right decisions and allowing us to use uncopyable inplace_functions in dispatcher.h.

    opened by syntheticmagus 0
  • Add threadpool_scheduler support for Android/Apple/Unix

    Add threadpool_scheduler support for Android/Apple/Unix

    There is a stop gap solution for other platforms that doesn't actually use a threadpool for the threadpool_scheduler. This should be implemented for Android/Apple using platform specific APIs.

    opened by bghgary 3
  • Add suspend/resume capability to dispatcher

    Add suspend/resume capability to dispatcher

    Add the ability to suspend and resume execution from another thread by setting state (or taking a token or something) on a dispatcher, without having to interact directly with mutexes or locks.

    opened by syntheticmagus 1
  • Make UWP capabilities header-only

    Make UWP capabilities header-only

    Because Arcana's UWP offerings aren't header-only @syntheticmagus If memory serves, it shouldn't be too much work to make it header-only, which would also make it considerably more portable and easy to consume.

    Originally posted by @ryantrem in https://github.com/microsoft/arcana.cpp/pull/2#issuecomment-520673074

    opened by syntheticmagus 0
Owner
Microsoft
Open source projects and samples from Microsoft
Microsoft
Cpp-taskflow - Modern C++ Parallel Task Programming Library

Cpp-Taskflow A fast C++ header-only library to help you quickly write parallel programs with complex task dependencies Why Cpp-Taskflow? Cpp-Taskflow

null 4 Mar 30, 2021
Cpp-concurrency - cpp implementation of golang style concurrency

cpp-concurrency C++ implementation of golang style concurrency Usage Use existing single header concurrency.hpp or run script to merge multiple header

YoungJoong Kim 14 Aug 11, 2022
Task System presented in "Better Code: Concurrency - Sean Parent"

task_system task_system provides a task scheduler for modern C++. The scheduler manages an array of concurrent queues A task, when scheduled, is enque

Pranav 30 Sep 14, 2022
C++14 coroutine-based task library for games

SquidTasks Squid::Tasks is a header-only C++14 coroutine-based task library for games. Full project and source code available at https://github.com/we

Tim Ambrogi Saxon 64 Sep 1, 2022
OOX: Out-of-Order Executor library. Yet another approach to efficient and scalable tasking API and task scheduling.

OOX Out-of-Order Executor library. Yet another approach to efficient and scalable tasking API and task scheduling. Try it Requirements: Install cmake,

Intel Corporation 17 Aug 9, 2022
A General-purpose Parallel and Heterogeneous Task Programming System

Taskflow Taskflow helps you quickly write parallel and heterogeneous tasks programs in modern C++ Why Taskflow? Taskflow is faster, more expressive, a

Taskflow 7.3k Sep 16, 2022
A General-purpose Parallel and Heterogeneous Task Programming System

Taskflow Taskflow helps you quickly write parallel and heterogeneous task programs in modern C++ Why Taskflow? Taskflow is faster, more expressive, an

Taskflow 7.3k Sep 17, 2022
EnkiTS - A permissively licensed C and C++ Task Scheduler for creating parallel programs. Requires C++11 support.

Support development of enkiTS through Github Sponsors or Patreon enkiTS Master branch Dev branch enki Task Scheduler A permissively licensed C and C++

Doug Binks 1.3k Sep 14, 2022
A task scheduling framework designed for the needs of game developers.

Intel Games Task Scheduler (GTS) To the documentation. Introduction GTS is a C++ task scheduling framework for multi-processor platforms. It is design

null 419 Sep 14, 2022
A hybrid thread / fiber task scheduler written in C++ 11

Marl Marl is a hybrid thread / fiber task scheduler written in C++ 11. About Marl is a C++ 11 library that provides a fluent interface for running tas

Google 1.4k Sep 18, 2022
A header-only C++ library for task concurrency

transwarp Doxygen documentation transwarp is a header-only C++ library for task concurrency. It allows you to easily create a graph of tasks where eve

Christian Blume 588 Sep 15, 2022
Jobxx - Lightweight C++ task system

jobxx License Copyright (c) 2017 Sean Middleditch [email protected] This is free and unencumbered software released into the public domain. A

Sean Middleditch 77 May 28, 2022
Portable header-only C++ low level SIMD library

libsimdpp libsimdpp is a portable header-only zero-overhead C++ low level SIMD library. The library presents a single interface over SIMD instruction

Povilas Kanapickas 1k Sep 21, 2022
Single header asymmetric stackful cross-platform coroutine library in pure C.

minicoro Minicoro is single-file library for using asymmetric coroutines in C. The API is inspired by Lua coroutines but with C use in mind. The proje

Eduardo Bart 328 Sep 19, 2022
cross platform subprocess library for c++ similar to design of python subprocess

subprocess cross platform subprocess library for c++ similar to design of python subprocess. See subprocess documentation for further documentation. s

null 119 Aug 5, 2022
EAThread - EAThread implements a unified cross-platform interface for multithreaded programming.

EAThread EAThread implements a unified cross-platform interface for multithreaded programming on various platforms. Documentation Please see Introduct

Electronic Arts 253 Sep 18, 2022
Fiber - A header only cross platform wrapper of fiber API.

Fiber Header only cross platform wrapper of fiber API A fiber is a particularly lightweight thread of execution. Which is useful for implementing coro

Tony Wang 41 Jul 31, 2022
Rpmalloc - Public domain cross platform lock free thread caching 16-byte aligned memory allocator implemented in C

rpmalloc - General Purpose Memory Allocator This library provides a public domain cross platform lock free thread caching 16-byte aligned memory alloc

Mattias Jansson 1.6k Sep 22, 2022