[ { "path": ".drone/drone.sh", "content": "#!/bin/bash\n\n# Copyright 2020 Rene Rivera, Sam Darwin\n# Distributed under the Boost Software License, Version 1.0.\n# (See accompanying file LICENSE.txt or copy at http://boost.org/LICENSE_1_0.txt)\n\nset -e\nexport TRAVIS_BUILD_DIR=$(pwd)\nexport DRONE_BUILD_DIR=$(pwd)\nexport TRAVIS_BRANCH=$DRONE_BRANCH\nexport VCS_COMMIT_ID=$DRONE_COMMIT\nexport GIT_COMMIT=$DRONE_COMMIT\nexport REPO_NAME=$DRONE_REPO\nexport PATH=~/.local/bin:/usr/local/bin:$PATH\n\nif [ \"$DRONE_JOB_BUILDTYPE\" == \"boost\" ]; then\n\necho '==================================> INSTALL'\n\ncd ..\ngit clone -b master --depth 1 https://github.com/boostorg/boost.git boost-root\ncd boost-root\ngit submodule update --init tools/build\ngit submodule update --init tools/inspect\ngit submodule update --init libs/config\ngit submodule update --init tools/boostdep\nmkdir -p libs/leaf\ncp -r $TRAVIS_BUILD_DIR/* libs/leaf\npython tools/boostdep/depinst/depinst.py leaf -I example\n./bootstrap.sh\n./b2 headers\ncd libs/leaf\n\necho '==================================> SCRIPT'\n\necho \"using $TOOLSET : : $COMPILER ;\" > ~/user-config.jam\n../../b2 test toolset=$TOOLSET cxxstd=$CXXSTD variant=debug,release,leaf_debug_diag0,leaf_release_diag0 ${UBSAN:+cxxflags=-fsanitize=undefined cxxflags=-fno-sanitize-recover=undefined linkflags=-fsanitize=undefined debug-symbols=on} ${LINKFLAGS:+linkflags=$LINKFLAGS}\n../../b2 exception-handling=off rtti=off test toolset=$TOOLSET cxxstd=$CXXSTD variant=debug,release,leaf_debug_diag0,leaf_release_diag0 ${UBSAN:+cxxflags=-fsanitize=undefined cxxflags=-fno-sanitize-recover=undefined linkflags=-fsanitize=undefined debug-symbols=on} ${LINKFLAGS:+linkflags=$LINKFLAGS}\n../../b2 threading=single test toolset=$TOOLSET cxxstd=$CXXSTD variant=debug,release,leaf_debug_diag0,leaf_release_diag0 ${UBSAN:+cxxflags=-fsanitize=undefined cxxflags=-fno-sanitize-recover=undefined linkflags=-fsanitize=undefined debug-symbols=on} ${LINKFLAGS:+linkflags=$LINKFLAGS}\n../../b2 threading=single exception-handling=off rtti=off test toolset=$TOOLSET cxxstd=$CXXSTD variant=debug,release,leaf_debug_diag0,leaf_release_diag0 ${UBSAN:+cxxflags=-fsanitize=undefined cxxflags=-fno-sanitize-recover=undefined linkflags=-fsanitize=undefined debug-symbols=on} ${LINKFLAGS:+linkflags=$LINKFLAGS}\n\nfi\n" }, { "path": ".drone.star", "content": "# Use, modification, and distribution are\n# subject to the Boost Software License, Version 1.0. (See accompanying\n# file LICENSE.txt)\n#\n# Copyright Rene Rivera 2020.\n\n# For Drone CI we use the Starlark scripting language to reduce duplication.\n# As the yaml syntax for Drone CI is rather limited.\n#\n#\nglobalenv={}\nlinuxglobalimage=\"cppalliance/droneubuntu1404:1\"\nwindowsglobalimage=\"cppalliance/dronevs2019\"\n\ndef main(ctx):\n return [\n osx_cxx(\"UBSAN=1 TOOLSET=clang COMPILER=clang++ CXXSTD Job 1\", \"clang++\", packages=\"\", buildtype=\"boost\", buildscript=\"drone\", environment={'UBSAN': '1', 'TOOLSET': 'clang', 'COMPILER': 'clang++', 'CXXSTD': '11,14', 'UBSAN_OPTIONS': 'print_stacktrace=1', 'DRONE_JOB_UUID': '356a192b79'}, globalenv=globalenv),\n osx_cxx(\"UBSAN=1 TOOLSET=clang COMPILER=clang++ CXXSTD Job 2\", \"clang++\", packages=\"\", buildtype=\"boost\", buildscript=\"drone\", environment={'UBSAN': '1', 'TOOLSET': 'clang', 'COMPILER': 'clang++', 'CXXSTD': '1z,2a', 'UBSAN_OPTIONS': 'print_stacktrace=1', 'DRONE_JOB_UUID': 'da4b9237ba'}, globalenv=globalenv),\n osx_cxx(\"TOOLSET=clang COMPILER=clang++ CXXSTD=11,14,1 Job 3\", \"clang++\", packages=\"\", buildtype=\"boost\", buildscript=\"drone\", xcode_version=\"11.5\", environment={'TOOLSET': 'clang', 'COMPILER': 'clang++', 'CXXSTD': '11,14,1z', 'DRONE_JOB_UUID': '77de68daec'}, globalenv=globalenv),\n osx_cxx(\"TOOLSET=clang COMPILER=clang++ CXXSTD=11,14,1 Job 4\", \"clang++\", packages=\"\", buildtype=\"boost\", buildscript=\"drone\", xcode_version=\"11.4\", environment={'TOOLSET': 'clang', 'COMPILER': 'clang++', 'CXXSTD': '11,14,1z', 'DRONE_JOB_UUID': '1b64538924'}, globalenv=globalenv),\n osx_cxx(\"TOOLSET=clang COMPILER=clang++ CXXSTD=11,14,1 Job 5\", \"clang++\", packages=\"\", buildtype=\"boost\", buildscript=\"drone\", xcode_version=\"11.3\", environment={'TOOLSET': 'clang', 'COMPILER': 'clang++', 'CXXSTD': '11,14,1z', 'DRONE_JOB_UUID': 'ac3478d69a'}, globalenv=globalenv),\n osx_cxx(\"TOOLSET=clang COMPILER=clang++ CXXSTD=11,14,1 Job 6\", \"clang++\", packages=\"\", buildtype=\"boost\", buildscript=\"drone\", xcode_version=\"11.2\", environment={'TOOLSET': 'clang', 'COMPILER': 'clang++', 'CXXSTD': '11,14,1z', 'DRONE_JOB_UUID': 'c1dfd96eea'}, globalenv=globalenv),\n osx_cxx(\"TOOLSET=clang COMPILER=clang++ CXXSTD=11,14,1 Job 7\", \"clang++\", packages=\"\", buildtype=\"boost\", buildscript=\"drone\", xcode_version=\"11.1\", environment={'TOOLSET': 'clang', 'COMPILER': 'clang++', 'CXXSTD': '11,14,1z', 'DRONE_JOB_UUID': '902ba3cda1'}, globalenv=globalenv),\n osx_cxx(\"TOOLSET=clang COMPILER=clang++ CXXSTD=11,14,1 Job 8\", \"clang++\", packages=\"\", buildtype=\"boost\", buildscript=\"drone\", xcode_version=\"11\", environment={'TOOLSET': 'clang', 'COMPILER': 'clang++', 'CXXSTD': '11,14,1z', 'DRONE_JOB_UUID': 'fe5dbbcea5'}, globalenv=globalenv),\n osx_cxx(\"TOOLSET=clang COMPILER=clang++ CXXSTD=11,14,1 Job 9\", \"clang++\", packages=\"\", buildtype=\"boost\", buildscript=\"drone\", xcode_version=\"10.3\", environment={'TOOLSET': 'clang', 'COMPILER': 'clang++', 'CXXSTD': '11,14,1z', 'DRONE_JOB_UUID': '0ade7c2cf9'}, globalenv=globalenv),\n osx_cxx(\"TOOLSET=clang COMPILER=clang++ CXXSTD=11,14,1 Job 10\", \"clang++\", packages=\"\", buildtype=\"boost\", buildscript=\"drone\", xcode_version=\"10.2\", environment={'TOOLSET': 'clang', 'COMPILER': 'clang++', 'CXXSTD': '11,14,1z', 'DRONE_JOB_UUID': 'b1d5781111'}, globalenv=globalenv),\n osx_cxx(\"TOOLSET=clang COMPILER=clang++ CXXSTD=11,14,1 Job 11\", \"clang++\", packages=\"\", buildtype=\"boost\", buildscript=\"drone\", xcode_version=\"10.1\", environment={'TOOLSET': 'clang', 'COMPILER': 'clang++', 'CXXSTD': '11,14,1z', 'DRONE_JOB_UUID': '17ba079149'}, globalenv=globalenv),\n linux_cxx(\"UBSAN=1 TOOLSET=gcc COMPILER=g++-9 CXXSTD=11, Job 12\", \"g++-9\", packages=\"g++-9\", buildtype=\"boost\", buildscript=\"drone\", image=linuxglobalimage, environment={'UBSAN': '1', 'TOOLSET': 'gcc', 'COMPILER': 'g++-9', 'CXXSTD': '11,14', 'UBSAN_OPTIONS': 'print_stacktrace=1', 'LINKFLAGS': '-fuse-ld=gold', 'DRONE_JOB_UUID': '7b52009b64'}, globalenv=globalenv),\n linux_cxx(\"UBSAN=1 TOOLSET=gcc COMPILER=g++-9 CXXSTD=17, Job 13\", \"g++-9\", packages=\"g++-9\", buildtype=\"boost\", buildscript=\"drone\", image=linuxglobalimage, environment={'UBSAN': '1', 'TOOLSET': 'gcc', 'COMPILER': 'g++-9', 'CXXSTD': '17,2a', 'UBSAN_OPTIONS': 'print_stacktrace=1', 'LINKFLAGS': '-fuse-ld=gold', 'DRONE_JOB_UUID': 'bd307a3ec3'}, globalenv=globalenv),\n linux_cxx(\"TOOLSET=gcc COMPILER=g++-9 CXXSTD=11,14,17,2a Job 14\", \"g++-9\", packages=\"g++-9\", buildtype=\"boost\", buildscript=\"drone\", image=linuxglobalimage, environment={'TOOLSET': 'gcc', 'COMPILER': 'g++-9', 'CXXSTD': '11,14,17,2a', 'DRONE_JOB_UUID': 'fa35e19212'}, globalenv=globalenv),\n linux_cxx(\"TOOLSET=gcc COMPILER=g++-8 CXXSTD=11,14,17 Job 15\", \"g++-8\", packages=\"g++-8\", buildtype=\"boost\", buildscript=\"drone\", image=linuxglobalimage, environment={'TOOLSET': 'gcc', 'COMPILER': 'g++-8', 'CXXSTD': '11,14,17', 'DRONE_JOB_UUID': 'f1abd67035'}, globalenv=globalenv),\n linux_cxx(\"TOOLSET=gcc COMPILER=g++-7 CXXSTD=11,14 Job 16\", \"g++-7\", packages=\"g++-7\", buildtype=\"boost\", buildscript=\"drone\", image=linuxglobalimage, environment={'TOOLSET': 'gcc', 'COMPILER': 'g++-7', 'CXXSTD': '11,14', 'DRONE_JOB_UUID': '1574bddb75'}, globalenv=globalenv),\n linux_cxx(\"TOOLSET=gcc COMPILER=g++-6 CXXSTD=11,14 Job 17\", \"g++-6\", packages=\"g++-6\", buildtype=\"boost\", buildscript=\"drone\", image=linuxglobalimage, environment={'TOOLSET': 'gcc', 'COMPILER': 'g++-6', 'CXXSTD': '11,14', 'DRONE_JOB_UUID': '0716d9708d'}, globalenv=globalenv),\n linux_cxx(\"TOOLSET=gcc COMPILER=g++-5 CXXSTD=11,14 Job 18\", \"g++-5\", packages=\"g++-5\", buildtype=\"boost\", buildscript=\"drone\", image=linuxglobalimage, environment={'TOOLSET': 'gcc', 'COMPILER': 'g++-5', 'CXXSTD': '11,14', 'DRONE_JOB_UUID': '9e6a55b6b4'}, globalenv=globalenv),\n linux_cxx(\"TOOLSET=gcc COMPILER=g++-4.9 CXXSTD=11 Job 19\", \"g++-4.9\", packages=\"g++-4.9\", buildtype=\"boost\", buildscript=\"drone\", image=linuxglobalimage, environment={'TOOLSET': 'gcc', 'COMPILER': 'g++-4.9', 'CXXSTD': '11', 'DRONE_JOB_UUID': 'b3f0c7f6bb'}, globalenv=globalenv),\n linux_cxx(\"UBSAN=1 TOOLSET=clang COMPILER=clang++-8 CXXS Job 20\", \"clang++-8\", packages=\"clang-8\", llvm_os=\"trusty\", llvm_ver=\"8\", buildtype=\"boost\", buildscript=\"drone\", image=linuxglobalimage, environment={'UBSAN': '1', 'TOOLSET': 'clang', 'COMPILER': 'clang++-8', 'CXXSTD': '11,14', 'UBSAN_OPTIONS': 'print_stacktrace=1', 'DRONE_JOB_UUID': '91032ad7bb'}, globalenv=globalenv),\n linux_cxx(\"UBSAN=1 TOOLSET=clang COMPILER=clang++-8 CXXS Job 21\", \"clang++-8\", packages=\"clang-8\", llvm_os=\"trusty\", llvm_ver=\"8\", buildtype=\"boost\", buildscript=\"drone\", image=linuxglobalimage, environment={'UBSAN': '1', 'TOOLSET': 'clang', 'COMPILER': 'clang++-8', 'CXXSTD': '17,2a', 'UBSAN_OPTIONS': 'print_stacktrace=1', 'DRONE_JOB_UUID': '472b07b9fc'}, globalenv=globalenv),\n linux_cxx(\"TOOLSET=clang COMPILER=clang++-10 CXXSTD=11,1 Job 22\", \"clang++-10\", packages=\"clang-10\", llvm_os=\"xenial\", llvm_ver=\"10\", buildtype=\"boost\", buildscript=\"drone\", image=\"cppalliance/droneubuntu1604:1\", environment={'TOOLSET': 'clang', 'COMPILER': 'clang++-10', 'CXXSTD': '11,14,17,2a', 'DRONE_JOB_UUID': '12c6fc06c9'}, globalenv=globalenv),\n linux_cxx(\"TOOLSET=clang COMPILER=clang++-9 CXXSTD=11,14 Job 23\", \"clang++-9\", packages=\"clang-9\", llvm_os=\"xenial\", llvm_ver=\"9\", buildtype=\"boost\", buildscript=\"drone\", image=\"cppalliance/droneubuntu1604:1\", environment={'TOOLSET': 'clang', 'COMPILER': 'clang++-9', 'CXXSTD': '11,14,17,2a', 'DRONE_JOB_UUID': 'd435a6cdd7'}, globalenv=globalenv),\n linux_cxx(\"TOOLSET=clang COMPILER=clang++-8 CXXSTD=11,14 Job 24\", \"clang++-8\", packages=\"clang-8\", llvm_os=\"trusty\", llvm_ver=\"8\", buildtype=\"boost\", buildscript=\"drone\", image=linuxglobalimage, environment={'TOOLSET': 'clang', 'COMPILER': 'clang++-8', 'CXXSTD': '11,14,17,2a', 'DRONE_JOB_UUID': '4d134bc072'}, globalenv=globalenv),\n linux_cxx(\"TOOLSET=clang COMPILER=clang++-7 CXXSTD=11,14 Job 25\", \"clang++-7\", packages=\"clang-7\", llvm_os=\"trusty\", llvm_ver=\"7\", buildtype=\"boost\", buildscript=\"drone\", image=linuxglobalimage, environment={'TOOLSET': 'clang', 'COMPILER': 'clang++-7', 'CXXSTD': '11,14,17,2a', 'DRONE_JOB_UUID': 'f6e1126ced'}, globalenv=globalenv),\n linux_cxx(\"TOOLSET=clang COMPILER=clang++-6.0 CXXSTD=11, Job 26\", \"clang++-6.0\", packages=\"clang-6.0\", llvm_os=\"trusty\", llvm_ver=\"6.0\", buildtype=\"boost\", buildscript=\"drone\", image=linuxglobalimage, environment={'TOOLSET': 'clang', 'COMPILER': 'clang++-6.0', 'CXXSTD': '11,14,17', 'DRONE_JOB_UUID': '887309d048'}, globalenv=globalenv),\n linux_cxx(\"TOOLSET=clang COMPILER=clang++-5.0 CXXSTD=11, Job 27\", \"clang++-5.0\", packages=\"clang-5.0\", llvm_os=\"trusty\", llvm_ver=\"5.0\", buildtype=\"boost\", buildscript=\"drone\", image=linuxglobalimage, environment={'TOOLSET': 'clang', 'COMPILER': 'clang++-5.0', 'CXXSTD': '11,14,1z', 'DRONE_JOB_UUID': 'bc33ea4e26'}, globalenv=globalenv),\n linux_cxx(\"TOOLSET=clang COMPILER=clang++-4.0 CXXSTD=11, Job 28\", \"clang++-4.0\", packages=\"clang-4.0\", llvm_os=\"trusty\", llvm_ver=\"4.0\", buildtype=\"boost\", buildscript=\"drone\", image=linuxglobalimage, environment={'TOOLSET': 'clang', 'COMPILER': 'clang++-4.0', 'CXXSTD': '11,14,1z', 'DRONE_JOB_UUID': '0a57cb53ba'}, globalenv=globalenv),\n linux_cxx(\"TOOLSET=clang COMPILER=clang++-3.9 CXXSTD=11, Job 29\", \"clang++-3.9\", packages=\"clang-3.9 libstdc++-4.9-dev\", buildtype=\"boost\", buildscript=\"drone\", image=linuxglobalimage, environment={'TOOLSET': 'clang', 'COMPILER': 'clang++-3.9', 'CXXSTD': '11,14,1z', 'DRONE_JOB_UUID': '7719a1c782'}, globalenv=globalenv),\n linux_cxx(\"TOOLSET=clang COMPILER=clang++-3.8 CXXSTD=11, Job 30\", \"clang++-3.8\", packages=\"clang-3.8 libstdc++-4.9-dev\", buildtype=\"boost\", buildscript=\"drone\", image=linuxglobalimage, environment={'TOOLSET': 'clang', 'COMPILER': 'clang++-3.8', 'CXXSTD': '11,14,1z', 'DRONE_JOB_UUID': '22d200f867'}, globalenv=globalenv),\n linux_cxx(\"TOOLSET=clang COMPILER=clang++-3.7 CXXSTD=11, Job 31\", \"clang++-3.7\", packages=\"clang-3.7\", llvm_os=\"precise\", llvm_ver=\"3.7\", buildtype=\"boost\", buildscript=\"drone\", image=linuxglobalimage, environment={'TOOLSET': 'clang', 'COMPILER': 'clang++-3.7', 'CXXSTD': '11,14,1z', 'DRONE_JOB_UUID': '632667547e'}, globalenv=globalenv),\n linux_cxx(\"TOOLSET=clang COMPILER=clang++-3.6 CXXSTD=11, Job 32\", \"clang++-3.6\", packages=\"clang-3.6 libstdc++-4.9-dev\", buildtype=\"boost\", buildscript=\"drone\", image=linuxglobalimage, environment={'TOOLSET': 'clang', 'COMPILER': 'clang++-3.6', 'CXXSTD': '11,14,1z', 'DRONE_JOB_UUID': 'cb4e5208b4'}, globalenv=globalenv),\n linux_cxx(\"TOOLSET=clang COMPILER=clang++-3.5 CXXSTD=11, Job 33\", \"clang++-3.5\", packages=\"clang-3.5 libstdc++-4.9-dev\", buildtype=\"boost\", buildscript=\"drone\", image=linuxglobalimage, environment={'TOOLSET': 'clang', 'COMPILER': 'clang++-3.5', 'CXXSTD': '11,14,1z', 'DRONE_JOB_UUID': 'b6692ea5df'}, globalenv=globalenv),\n linux_cxx(\"TOOLSET=clang COMPILER=/usr/bin/clang++ CXXST Job 34\", \"/usr/bin/clang++\", packages=\"clang-3.4\", llvm_os=\"precise\", llvm_ver=\"3.8\", buildtype=\"boost\", buildscript=\"drone\", image=linuxglobalimage, environment={'TOOLSET': 'clang', 'COMPILER': '/usr/bin/clang++', 'CXXSTD': '11', 'DRONE_JOB_UUID': 'f1f836cb4e'}, globalenv=globalenv),\n linux_cxx(\"TOOLSET=clang COMPILER=/usr/bin/clang++ CXXST Job 35\", \"/usr/bin/clang++\", packages=\"clang-3.3\", llvm_os=\"precise\", llvm_ver=\"3.8\", buildtype=\"boost\", buildscript=\"drone\", image=linuxglobalimage, environment={'TOOLSET': 'clang', 'COMPILER': '/usr/bin/clang++', 'CXXSTD': '11', 'DRONE_JOB_UUID': '972a67c481'}, globalenv=globalenv),\n ]\n\n# from https://github.com/boostorg/boost-ci\nload(\"@boost_ci//ci/drone/:functions.star\", \"linux_cxx\",\"windows_cxx\",\"osx_cxx\",\"freebsd_cxx\")\n" }, { "path": ".gitattributes", "content": "* text=auto !eol svneol=native#text/plain\n*.gitattributes text svneol=native#text/plain\n\n# Scriptish formats\n*.bat text svneol=native#text/plain\n*.bsh text svneol=native#text/x-beanshell\n*.cgi text svneol=native#text/plain\n*.cmd text svneol=native#text/plain\n*.js text svneol=native#text/javascript\n*.php text svneol=native#text/x-php\n*.pl text svneol=native#text/x-perl\n*.pm text svneol=native#text/x-perl\n*.py text svneol=native#text/x-python\n*.sh eol=lf svneol=LF#text/x-sh\nconfigure eol=lf svneol=LF#text/x-sh\n\n# Image formats\n*.bmp binary svneol=unset#image/bmp\n*.gif binary svneol=unset#image/gif\n*.ico binary svneol=unset#image/ico\n*.jpeg binary svneol=unset#image/jpeg\n*.jpg binary svneol=unset#image/jpeg\n*.png binary svneol=unset#image/png\n*.tif binary svneol=unset#image/tiff\n*.tiff binary svneol=unset#image/tiff\n*.svg text svneol=native#image/svg%2Bxml\n\n# Data formats\n*.pdf binary svneol=unset#application/pdf\n*.avi binary svneol=unset#video/avi\n*.doc binary svneol=unset#application/msword\n*.dsp text svneol=crlf#text/plain\n*.dsw text svneol=crlf#text/plain\n*.eps binary svneol=unset#application/postscript\n*.gz binary svneol=unset#application/gzip\n*.mov binary svneol=unset#video/quicktime\n*.mp3 binary svneol=unset#audio/mpeg\n*.ppt binary svneol=unset#application/vnd.ms-powerpoint\n*.ps binary svneol=unset#application/postscript\n*.psd binary svneol=unset#application/photoshop\n*.rdf binary svneol=unset#text/rdf\n*.rss text svneol=unset#text/xml\n*.rtf binary svneol=unset#text/rtf\n*.sln text svneol=native#text/plain\n*.swf binary svneol=unset#application/x-shockwave-flash\n*.tgz binary svneol=unset#application/gzip\n*.vcproj text svneol=native#text/xml\n*.vcxproj text svneol=native#text/xml\n*.vsprops text svneol=native#text/xml\n*.wav binary svneol=unset#audio/wav\n*.xls binary svneol=unset#application/vnd.ms-excel\n*.zip binary svneol=unset#application/zip\n\n# Text formats\n.htaccess text svneol=native#text/plain\n*.bbk text svneol=native#text/xml\n*.cmake text svneol=native#text/plain\n*.css text svneol=native#text/css\n*.dtd text svneol=native#text/xml\n*.htm text svneol=native#text/html\n*.html text svneol=native#text/html\n*.ini text svneol=native#text/plain\n*.log text svneol=native#text/plain\n*.mak text svneol=native#text/plain\n*.qbk text svneol=native#text/plain\n*.rst text svneol=native#text/plain\n*.sql text svneol=native#text/x-sql\n*.txt text svneol=native#text/plain\n*.xhtml text svneol=native#text/xhtml%2Bxml\n*.xml text svneol=native#text/xml\n*.xsd text svneol=native#text/xml\n*.xsl text svneol=native#text/xml\n*.xslt text svneol=native#text/xml\n*.xul text svneol=native#text/xul\n*.yml text svneol=native#text/plain\nboost-no-inspect text svneol=native#text/plain\nCHANGES text svneol=native#text/plain\nCOPYING text svneol=native#text/plain\nINSTALL text svneol=native#text/plain\nJamfile text svneol=native#text/plain\nJamroot text svneol=native#text/plain\nJamfile.v2 text svneol=native#text/plain\nJamrules text svneol=native#text/plain\nMakefile* text svneol=native#text/plain\nREADME text svneol=native#text/plain\nTODO text svneol=native#text/plain\n\n# Code formats\n*.c text svneol=native#text/plain\n*.cpp text svneol=native#text/plain\n*.h text svneol=native#text/plain\n*.hpp text svneol=native#text/plain\n*.ipp text svneol=native#text/plain\n*.tpp text svneol=native#text/plain\n*.jam text svneol=native#text/plain\n*.java text svneol=native#text/plain\n" }, { "path": ".github/workflows/ci.yml", "content": "name: CI\n\non:\n pull_request:\n push:\n branches:\n - master\n - develop\n - feature/**\n\nenv:\n UBSAN_OPTIONS: print_stacktrace=1\n\njobs:\n posix:\n strategy:\n fail-fast: false\n matrix:\n include:\n - toolset: gcc-4.8\n cxxstd: \"11\"\n os: ubuntu-18.04\n install: g++-4.8\n - toolset: gcc-5\n cxxstd: \"11,14,1z\"\n os: ubuntu-18.04\n install: g++-5\n - toolset: gcc-6\n cxxstd: \"11,14,1z\"\n os: ubuntu-18.04\n install: g++-6\n - toolset: gcc-7\n cxxstd: \"11,14\"\n os: ubuntu-18.04\n - toolset: gcc-8\n cxxstd: \"11,14,17,2a\"\n os: ubuntu-18.04\n install: g++-8\n - toolset: gcc-9\n cxxstd: \"11,14,17,2a\"\n os: ubuntu-20.04\n - toolset: gcc-10\n cxxstd: \"11,14,17,2a\"\n os: ubuntu-20.04\n install: g++-10\n - toolset: gcc-11\n cxxstd: \"11,14,17,2a\"\n os: ubuntu-20.04\n install: g++-11\n - toolset: clang\n compiler: clang++-3.9\n cxxstd: \"11,14\"\n os: ubuntu-18.04\n install: clang-3.9\n - toolset: clang\n compiler: clang++-4.0\n cxxstd: \"11,14\"\n os: ubuntu-18.04\n install: clang-4.0\n - toolset: clang\n compiler: clang++-5.0\n cxxstd: \"11,14,1z\"\n os: ubuntu-18.04\n install: clang-5.0\n - toolset: clang\n compiler: clang++-6.0\n cxxstd: \"11,14,17\"\n os: ubuntu-18.04\n install: clang-6.0\n - toolset: clang\n compiler: clang++-7\n cxxstd: \"11,14,17\"\n os: ubuntu-18.04\n install: clang-7\n - toolset: clang\n compiler: clang++-8\n cxxstd: \"11,14,17\"\n os: ubuntu-20.04\n install: clang-8\n - toolset: clang\n compiler: clang++-9\n cxxstd: \"11,14,17,2a\"\n os: ubuntu-20.04\n install: clang-9\n - toolset: clang\n compiler: clang++-10\n cxxstd: \"11,14,17,2a\"\n os: ubuntu-20.04\n install: clang-10\n - toolset: clang\n compiler: clang++-11\n cxxstd: \"11,14,17,2a\"\n os: ubuntu-20.04\n install: clang-11\n - toolset: clang\n compiler: clang++-12\n cxxstd: \"11,14,17,2a\"\n os: ubuntu-20.04\n install: clang-12\n - toolset: clang\n cxxstd: \"11,14,17,2a\"\n os: macos-10.15\n\n runs-on: ${{matrix.os}}\n\n steps:\n - uses: actions/checkout@v2\n\n - name: Install packages\n if: matrix.install\n run: sudo apt install ${{matrix.install}}\n\n - name: Setup Boost\n run: |\n REF=${GITHUB_BASE_REF:-$GITHUB_REF}\n BOOST_BRANCH=develop && [ \"$REF\" == \"master\" ] && BOOST_BRANCH=master || true\n cd ..\n git clone -b $BOOST_BRANCH --depth 1 https://github.com/boostorg/boost.git boost-root\n cd boost-root\n cp -r $GITHUB_WORKSPACE/* libs/leaf\n git submodule update --init tools/boostdep\n python tools/boostdep/depinst/depinst.py --git_args \"--jobs 3\" leaf\n ./bootstrap.sh\n ./b2 -d0 headers\n\n - name: Create user-config.jam\n if: matrix.compiler\n run: |\n echo \"using ${{matrix.toolset}} : : ${{matrix.compiler}} ;\" > ~/user-config.jam\n\n - name: Generate headers\n run: |\n cd ../boost-root/libs/leaf\n python gen/generate_single_header.py -i include/boost/leaf/detail/all.hpp -p include -o test/leaf.hpp boost/leaf\n\n - name: Run tests\n run: |\n cd ../boost-root\n ./b2 -j3 libs/leaf/test toolset=${{matrix.toolset}} cxxstd=${{matrix.cxxstd}} link=shared,static variant=debug,release,leaf_debug_capture0,leaf_release_capture0,leaf_debug_diag0,leaf_release_diag0,leaf_debug_embedded,leaf_release_embedded,leaf_debug_leaf_hpp,leaf_release_leaf_hpp\n\n windows:\n strategy:\n fail-fast: false\n matrix:\n include:\n - toolset: msvc-14.2\n cxxstd: \"14,17,latest\"\n addrmd: 32,64\n os: windows-2019\n - toolset: gcc\n cxxstd: \"11,14,17,2a\"\n addrmd: 64\n os: windows-2019\n\n runs-on: ${{matrix.os}}\n\n steps:\n - uses: actions/checkout@v2\n\n - name: Setup Boost\n shell: cmd\n run: |\n if \"%GITHUB_BASE_REF%\" == \"\" set GITHUB_BASE_REF=%GITHUB_REF%\n set BOOST_BRANCH=develop\n if \"%GITHUB_BASE_REF%\" == \"master\" set BOOST_BRANCH=master\n cd ..\n git clone -b %BOOST_BRANCH% --depth 1 https://github.com/boostorg/boost.git boost-root\n cd boost-root\n xcopy /s /e /q %GITHUB_WORKSPACE% libs\\leaf\\\n git submodule update --init tools/boostdep\n python tools/boostdep/depinst/depinst.py --git_args \"--jobs 3\" leaf\n cmd /c bootstrap\n b2 -d0 headers\n\n - name: Generate headers\n run: |\n cd ../boost-root/libs/leaf\n python gen/generate_single_header.py -i include/boost/leaf/detail/all.hpp -p include -o test/leaf.hpp boost/leaf\n\n - name: Run tests\n shell: cmd\n run: |\n cd ../boost-root\n b2 -j3 libs/leaf/test toolset=${{matrix.toolset}} cxxstd=${{matrix.cxxstd}} address-model=${{matrix.addrmd}} variant=debug,release,leaf_debug_capture0,leaf_release_capture0,leaf_debug_diag0,leaf_release_diag0,leaf_debug_embedded,leaf_release_embedded,leaf_debug_leaf_hpp,leaf_release_leaf_hpp\n" }, { "path": ".github/workflows/gh-pages.yml", "content": "name: documentation\n\non:\n push:\n branches:\n - master\n\njobs:\n publish:\n runs-on: ubuntu-latest\n steps:\n - uses: actions/checkout@v2\n\n - name: Install packages\n run: |\n sudo gem install asciidoctor asciidoctor-pdf rouge\n\n - name: Setup Boost\n run: |\n REF=${GITHUB_BASE_REF:-$GITHUB_REF}\n BOOST_BRANCH=develop && [ \"$REF\" == \"master\" ] && BOOST_BRANCH=master || true\n cd ..\n git clone -b $BOOST_BRANCH --depth 1 https://github.com/boostorg/boost.git boost-root\n cd boost-root\n cp -r $GITHUB_WORKSPACE/* libs/leaf\n git submodule update --init tools/build\n git submodule update --init libs/config\n ./bootstrap.sh\n\n - name: Create user-config.jam\n run: |\n echo \"using asciidoctor ;\" > ~/user-config.jam\n\n - name: Build documentation\n run: |\n cd ../boost-root/libs/leaf/doc\n ../../../b2\n\n - name: Generate single header\n run: |\n REF=$(git show-ref $GITHUB_REF --hash)\n cd ../boost-root/libs/leaf\n python gen/generate_single_header.py -i include/boost/leaf/detail/all.hpp -p include -o doc/html/leaf.hpp boost/leaf --hash \"$REF\"\n\n - name: Deploy to GitHub Pages\n uses: JamesIves/github-pages-deploy-action@3.7.1\n with:\n GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}\n BRANCH: gh-pages\n FOLDER: ../boost-root/libs/leaf/doc/html\n" }, { "path": ".gitignore", "content": ".DS_Store\n.Trashes\n*.suo\n*.user\n*.log\n*.sdf\n*.opensdf\n*.db\n*.opendb\nbld/*\ndoc/html/*\nsnippets/*\nsubprojects/*/\n.vscode/ipch/*\n.vscode/settings.json\n.vscode/c_cpp_properties.json\nbenchmark/tl/*\ntest/leaf.hpp\ndoc/leaf.html\n" }, { "path": ".travis.yml", "content": "# Copyright 2016-2018 Peter Dimov\n# Copyright 2018-2022 Emil Dotchevski and Reverge Studios, Inc.\n# Distributed under the Boost Software License, Version 1.0.\n# (See accompanying file LICENSE_1_0.txt or copy at http://boost.org/LICENSE_1_0.txt)\n\nlanguage: cpp\n\nsudo: false\n\ndist: trusty\n\npython: \"2.7\"\n\nos:\n - linux\n - osx\n\nbranches:\n only:\n - master\n - develop\n - /^feature.*/\n\nenv:\n matrix:\n - BOGUS_JOB=true\n\naddons:\n apt:\n packages:\n - g++-4.9\n - g++-5\n - g++-6\n - clang-3.6\n - clang-3.7\n - clang-3.8\n - ruby-full\n - ninja-build\n\n sources:\n - ubuntu-toolchain-r-test\n - llvm-toolchain-precise\n - llvm-toolchain-precise-3.6\n - llvm-toolchain-precise-3.7\n - llvm-toolchain-precise-3.8\n\nmatrix:\n\n exclude:\n - env: BOGUS_JOB=true\n\n include:\n\n - os: linux\n env: DOC=1\n install:\n - gem install asciidoctor\n - gem install asciidoctor-pdf --pre\n - gem install rouge\n - cd ..\n - git clone -b master --depth 1 https://github.com/boostorg/boost.git boost-root\n - cd boost-root\n - git submodule update --init tools/build\n - git submodule update --init libs/config\n - mkdir -p libs/leaf\n - cp -r $TRAVIS_BUILD_DIR/* libs/leaf\n - ./bootstrap.sh\n - cd libs/leaf\n script:\n - |-\n echo \"using asciidoctor ;\" > ~/user-config.jam\n - ../../b2 doc\n deploy:\n local-dir: ../boost-root/libs/leaf/doc/html\n provider: pages\n skip-cleanup: true\n github-token: $GH_PAGES_TOKEN\n keep-history: false\n on:\n branch: master\n\n###################################\n\n - os: osx\n compiler: clang++\n env: UBSAN=1 TOOLSET=clang COMPILER=clang++ CXXSTD=11,14 UBSAN_OPTIONS=print_stacktrace=1\n\n - os: osx\n compiler: clang++\n env: UBSAN=1 TOOLSET=clang COMPILER=clang++ CXXSTD=1z,2a UBSAN_OPTIONS=print_stacktrace=1\n\n - os: osx\n osx_image: xcode11.5\n compiler: clang++\n env: TOOLSET=clang COMPILER=clang++ CXXSTD=11,14,1z\n\n - os: osx\n osx_image: xcode11.4\n compiler: clang++\n env: TOOLSET=clang COMPILER=clang++ CXXSTD=11,14,1z\n\n - os: osx\n osx_image: xcode11.3\n compiler: clang++\n env: TOOLSET=clang COMPILER=clang++ CXXSTD=11,14,1z\n\n - os: osx\n osx_image: xcode11.2\n compiler: clang++\n env: TOOLSET=clang COMPILER=clang++ CXXSTD=11,14,1z\n\n - os: osx\n osx_image: xcode11.1\n compiler: clang++\n env: TOOLSET=clang COMPILER=clang++ CXXSTD=11,14,1z\n\n - os: osx\n osx_image: xcode11\n compiler: clang++\n env: TOOLSET=clang COMPILER=clang++ CXXSTD=11,14,1z\n\n - os: osx\n osx_image: xcode10.3\n compiler: clang++\n env: TOOLSET=clang COMPILER=clang++ CXXSTD=11,14,1z\n\n - os: osx\n osx_image: xcode10.2\n compiler: clang++\n env: TOOLSET=clang COMPILER=clang++ CXXSTD=11,14,1z\n\n - os: osx\n osx_image: xcode10.1\n compiler: clang++\n env: TOOLSET=clang COMPILER=clang++ CXXSTD=11,14,1z\n\n###################################\n\n - os: linux\n compiler: g++-9\n env: UBSAN=1 TOOLSET=gcc COMPILER=g++-9 CXXSTD=11,14 UBSAN_OPTIONS=print_stacktrace=1 LINKFLAGS=-fuse-ld=gold\n addons:\n apt:\n packages:\n - g++-9\n sources:\n - ubuntu-toolchain-r-test\n\n - os: linux\n compiler: g++-9\n env: UBSAN=1 TOOLSET=gcc COMPILER=g++-9 CXXSTD=17,2a UBSAN_OPTIONS=print_stacktrace=1 LINKFLAGS=-fuse-ld=gold\n addons:\n apt:\n packages:\n - g++-9\n sources:\n - ubuntu-toolchain-r-test\n\n - os: linux\n compiler: g++-9\n env: TOOLSET=gcc COMPILER=g++-9 CXXSTD=11,14,17,2a\n addons:\n apt:\n packages:\n - g++-9\n sources:\n - ubuntu-toolchain-r-test\n\n - os: linux\n compiler: g++-8\n env: TOOLSET=gcc COMPILER=g++-8 CXXSTD=11,14,17\n addons:\n apt:\n packages:\n - g++-8\n sources:\n - ubuntu-toolchain-r-test\n\n - os: linux\n compiler: g++-7\n env: TOOLSET=gcc COMPILER=g++-7 CXXSTD=11,14\n addons:\n apt:\n packages:\n - g++-7\n sources:\n - ubuntu-toolchain-r-test\n\n - os: linux\n compiler: g++-6\n env: TOOLSET=gcc COMPILER=g++-6 CXXSTD=11,14\n addons:\n apt:\n packages:\n - g++-6\n sources:\n - ubuntu-toolchain-r-test\n\n - os: linux\n compiler: g++-5\n env: TOOLSET=gcc COMPILER=g++-5 CXXSTD=11,14\n addons:\n apt:\n packages:\n - g++-5\n sources:\n - ubuntu-toolchain-r-test\n\n - os: linux\n compiler: g++-4.9\n env: TOOLSET=gcc COMPILER=g++-4.9 CXXSTD=11\n addons:\n apt:\n packages:\n - g++-4.9\n sources:\n - ubuntu-toolchain-r-test\n\n###################################\n\n - os: linux\n compiler: clang++-8\n env: UBSAN=1 TOOLSET=clang COMPILER=clang++-8 CXXSTD=11,14 UBSAN_OPTIONS=print_stacktrace=1\n addons:\n apt:\n packages:\n - clang-8\n sources:\n - ubuntu-toolchain-r-test\n - llvm-toolchain-trusty-8\n\n - os: linux\n compiler: clang++-8\n env: UBSAN=1 TOOLSET=clang COMPILER=clang++-8 CXXSTD=17,2a UBSAN_OPTIONS=print_stacktrace=1\n addons:\n apt:\n packages:\n - clang-8\n sources:\n - ubuntu-toolchain-r-test\n - llvm-toolchain-trusty-8\n\n - os: linux\n dist: xenial\n compiler: clang++-10\n env: TOOLSET=clang COMPILER=clang++-10 CXXSTD=11,14,17,2a\n addons:\n apt:\n packages:\n - clang-10\n sources:\n - ubuntu-toolchain-r-test\n - sourceline: 'deb https://apt.llvm.org/xenial/ llvm-toolchain-xenial-10 main'\n key_url: 'https://apt.llvm.org/llvm-snapshot.gpg.key'\n\n - os: linux\n dist: xenial\n compiler: clang++-9\n env: TOOLSET=clang COMPILER=clang++-9 CXXSTD=11,14,17,2a\n addons:\n apt:\n packages:\n - clang-9\n sources:\n - ubuntu-toolchain-r-test\n - sourceline: 'deb https://apt.llvm.org/xenial/ llvm-toolchain-xenial-9 main'\n key_url: 'https://apt.llvm.org/llvm-snapshot.gpg.key'\n\n - os: linux\n compiler: clang++-8\n env: TOOLSET=clang COMPILER=clang++-8 CXXSTD=11,14,17,2a\n addons:\n apt:\n packages:\n - clang-8\n sources:\n - ubuntu-toolchain-r-test\n - llvm-toolchain-trusty-8\n\n - os: linux\n compiler: clang++-7\n env: TOOLSET=clang COMPILER=clang++-7 CXXSTD=11,14,17,2a\n addons:\n apt:\n packages:\n - clang-7\n sources:\n - ubuntu-toolchain-r-test\n - llvm-toolchain-trusty-7\n\n - os: linux\n compiler: clang++-6.0\n env: TOOLSET=clang COMPILER=clang++-6.0 CXXSTD=11,14,17\n addons:\n apt:\n packages:\n - clang-6.0\n sources:\n - ubuntu-toolchain-r-test\n - llvm-toolchain-trusty-6.0\n\n - os: linux\n compiler: clang++-5.0\n env: TOOLSET=clang COMPILER=clang++-5.0 CXXSTD=11,14,1z\n addons:\n apt:\n packages:\n - clang-5.0\n sources:\n - ubuntu-toolchain-r-test\n - llvm-toolchain-trusty-5.0\n\n - os: linux\n compiler: clang++-4.0\n env: TOOLSET=clang COMPILER=clang++-4.0 CXXSTD=11,14,1z\n addons:\n apt:\n packages:\n - clang-4.0\n sources:\n - ubuntu-toolchain-r-test\n - llvm-toolchain-trusty-4.0\n\n - os: linux\n compiler: clang++-3.9\n env: TOOLSET=clang COMPILER=clang++-3.9 CXXSTD=11,14,1z\n addons:\n apt:\n packages:\n - clang-3.9\n - libstdc++-4.9-dev\n sources:\n - ubuntu-toolchain-r-test\n\n - os: linux\n compiler: clang++-3.8\n env: TOOLSET=clang COMPILER=clang++-3.8 CXXSTD=11,14,1z\n addons:\n apt:\n packages:\n - clang-3.8\n - libstdc++-4.9-dev\n sources:\n - ubuntu-toolchain-r-test\n\n - os: linux\n compiler: clang++-3.7\n env: TOOLSET=clang COMPILER=clang++-3.7 CXXSTD=11,14,1z\n addons:\n apt:\n packages:\n - clang-3.7\n sources:\n - ubuntu-toolchain-r-test\n - llvm-toolchain-precise-3.7\n\n - os: linux\n compiler: clang++-3.6\n env: TOOLSET=clang COMPILER=clang++-3.6 CXXSTD=11,14,1z\n addons:\n apt:\n packages:\n - clang-3.6\n - libstdc++-4.9-dev\n sources:\n - ubuntu-toolchain-r-test\n\n - os: linux\n compiler: clang++-3.5\n env: TOOLSET=clang COMPILER=clang++-3.5 CXXSTD=11,14,1z\n addons:\n apt:\n packages:\n - clang-3.5\n - libstdc++-4.9-dev\n sources:\n - ubuntu-toolchain-r-test\n\n - os: linux\n compiler: /usr/bin/clang++\n env: TOOLSET=clang COMPILER=/usr/bin/clang++ CXXSTD=11\n addons:\n apt:\n packages:\n - clang-3.4\n\n - os: linux\n compiler: /usr/bin/clang++\n env: TOOLSET=clang COMPILER=/usr/bin/clang++ CXXSTD=11\n addons:\n apt:\n packages:\n - clang-3.3\n\n###################################\n\ninstall:\n - cd ..\n - git clone -b master --depth 1 https://github.com/boostorg/boost.git boost-root\n - cd boost-root\n - git submodule update --init tools/build\n - git submodule update --init tools/inspect\n - git submodule update --init libs/config\n - git submodule update --init tools/boostdep\n - mkdir -p libs/leaf\n - cp -r $TRAVIS_BUILD_DIR/* libs/leaf\n - python tools/boostdep/depinst/depinst.py leaf -I example\n - ./bootstrap.sh\n - ./b2 headers\n - cd libs/leaf\n\nscript:\n - |-\n echo \"using $TOOLSET : : $COMPILER ;\" > ~/user-config.jam\n - ../../b2 test toolset=$TOOLSET cxxstd=$CXXSTD variant=debug,release,leaf_debug_diag0,leaf_release_diag0 ${UBSAN:+cxxflags=-fsanitize=undefined cxxflags=-fno-sanitize-recover=undefined linkflags=-fsanitize=undefined debug-symbols=on} ${LINKFLAGS:+linkflags=$LINKFLAGS}\n - ../../b2 exception-handling=off rtti=off test toolset=$TOOLSET cxxstd=$CXXSTD variant=debug,release,leaf_debug_diag0,leaf_release_diag0 ${UBSAN:+cxxflags=-fsanitize=undefined cxxflags=-fno-sanitize-recover=undefined linkflags=-fsanitize=undefined debug-symbols=on} ${LINKFLAGS:+linkflags=$LINKFLAGS}\n - ../../b2 threading=single test toolset=$TOOLSET cxxstd=$CXXSTD variant=debug,release,leaf_debug_diag0,leaf_release_diag0 ${UBSAN:+cxxflags=-fsanitize=undefined cxxflags=-fno-sanitize-recover=undefined linkflags=-fsanitize=undefined debug-symbols=on} ${LINKFLAGS:+linkflags=$LINKFLAGS}\n - ../../b2 threading=single exception-handling=off rtti=off test toolset=$TOOLSET cxxstd=$CXXSTD variant=debug,release,leaf_debug_diag0,leaf_release_diag0 ${UBSAN:+cxxflags=-fsanitize=undefined cxxflags=-fno-sanitize-recover=undefined linkflags=-fsanitize=undefined debug-symbols=on} ${LINKFLAGS:+linkflags=$LINKFLAGS}\n\nnotifications:\n email:\n on_success: always\n" }, { "path": ".vscode/launch.json", "content": "{\n // Use IntelliSense to learn about possible attributes.\n // Hover to view descriptions of existing attributes.\n // For more information, visit: https://go.microsoft.com/fwlink/?linkid=830387\n \"version\": \"0.2.0\",\n \"configurations\": [\n {\n \"name\": \"(lldb) Launch\",\n \"type\": \"cppdbg\",\n \"request\": \"launch\",\n \"program\": \"${workspaceFolder}/bld/debug/capture_exception_async_test\",\n \"args\": [ ],\n \"cwd\": \"${workspaceFolder}\",\n \"stopAtEntry\": false,\n \"externalConsole\": false,\n \"MIMode\": \"lldb\"\n }\n ]\n}\n" }, { "path": ".vscode/tasks.json", "content": "{\n // See https://go.microsoft.com/fwlink/?LinkId=733558\n // for the documentation about the tasks.json format\n \"version\": \"2.0.0\",\n \"tasks\": [\n {\n \"label\": \"Configure Meson build directories\",\n \"type\": \"shell\",\n \"command\": \"cd ${workspaceRoot} && meson -D leaf_boost_examples=true -D leaf_lua_examples=true bld/debug && meson -D leaf_boost_examples=true -D leaf_lua_examples=true -D leaf_hpp=true bld/debug_leaf_hpp && meson -D leaf_boost_examples=true -D leaf_lua_examples=true bld/release --buildtype release && meson -D leaf_boost_examples=true -D leaf_lua_examples=true -D leaf_hpp=true bld/release_leaf_hpp --buildtype release && meson -D leaf_diagnostics=0 -D cpp_eh=none -D b_ndebug=true -D b_lto=true -D leaf_enable_benchmarks=true bld/benchmark --buildtype release\",\n \"problemMatcher\": []\n },\n {\n \"label\": \"Configure Meson build directories (no Boost)\",\n \"type\": \"shell\",\n \"command\": \"cd ${workspaceRoot} && meson -D leaf_lua_examples=true bld/debug && meson -D leaf_lua_examples=true -D leaf_hpp=true bld/debug_leaf_hpp && meson -D leaf_lua_examples=true bld/release --buildtype release && meson -D leaf_lua_examples=true -D leaf_hpp=true bld/release_leaf_hpp --buildtype release\",\n \"problemMatcher\": []\n },\n {\n \"label\": \"Generate leaf.hpp\",\n \"type\": \"shell\",\n \"command\": \"cd ${workspaceRoot} && python gen/generate_single_header.py -i include/boost/leaf/detail/all.hpp -p ${workspaceRoot}/include -o ${workspaceRoot}/test/leaf.hpp boost/leaf\",\n \"problemMatcher\": []\n },\n {\n \"group\": {\n \"kind\": \"build\",\n \"isDefault\": true\n },\n \"label\": \"Build all unit tests and examples (debug)\",\n \"type\": \"shell\",\n \"command\": \"cd ${workspaceRoot}/bld/debug && ninja\",\n \"problemMatcher\": {\n \"base\": \"$gcc\",\n \"fileLocation\": [\n \"relative\",\n \"${workspaceRoot}/bld/debug\"\n ]\n }\n },\n {\n \"group\": \"test\",\n \"label\": \"Run all unit tests (debug)\",\n \"type\": \"shell\",\n \"dependsOn\": [\n \"Generate leaf.hpp\"\n ],\n \"command\": \"cd ${workspaceRoot}/bld/debug_leaf_hpp && ninja && meson test && cd ${workspaceRoot}/bld/debug && ninja && meson test\",\n \"problemMatcher\": {\n \"base\": \"$gcc\",\n \"fileLocation\": [\n \"relative\",\n \"${workspaceRoot}/bld/debug\"\n ]\n }\n },\n {\n \"group\": \"test\",\n \"label\": \"Run all unit tests (release)\",\n \"type\": \"shell\",\n \"dependsOn\": [\n \"Generate leaf.hpp\"\n ],\n \"command\": \"cd ${workspaceRoot}/bld/release && ninja && meson test && cd ${workspaceRoot}/bld/release_leaf_hpp && ninja && meson test\",\n \"problemMatcher\": {\n \"base\": \"$gcc\",\n \"fileLocation\": [\n \"relative\",\n \"${workspaceRoot}/bld/release\"\n ]\n }\n },\n {\n \"group\": \"test\",\n \"label\": \"Run all unit tests (b2, all configurations)\",\n \"type\": \"shell\",\n \"dependsOn\": [\n \"Generate leaf.hpp\"\n ],\n \"command\": \"../../b2 test link=shared,static variant=debug,release,leaf_debug_diag0,leaf_release_diag0,leaf_debug_leaf_hpp,leaf_release_leaf_hpp exception-handling=on,off cxxstd=11,14,1z,17 && ../../b2 test link=shared,static variant=debug,release,leaf_debug_diag0,leaf_release_diag0,leaf_debug_leaf_hpp,leaf_release_leaf_hpp,leaf_debug_embedded,leaf_release_embedded exception-handling=off rtti=off cxxstd=11,14,1z,17\",\n \"windows\": {\n \"command\": \"..\\\\..\\\\b2 test link=shared,static variant=debug,release,leaf_debug_diag0,leaf_release_diag0,leaf_debug_leaf_hpp,leaf_release_leaf_hpp exception-handling=on,off cxxstd=14,17,latest && ..\\\\..\\\\b2 test link=shared,static variant=debug,release,leaf_debug_diag0,leaf_release_diag0,leaf_debug_leaf_hpp,leaf_release_leaf_hpp,leaf_debug_embedded,leaf_release_embedded exception-handling=off rtti=off cxxstd=14,17,latest\",\n },\n \"problemMatcher\": {\n \"base\": \"$gcc\",\n \"fileLocation\": [\n \"relative\",\n \"${workspaceRoot}/bld/release\"\n ]\n }\n },\n {\n \"group\": {\n \"kind\": \"test\",\n \"isDefault\": true\n },\n \"label\": \"Test current editor file\",\n \"type\": \"shell\",\n \"command\": \"cd ${workspaceRoot}/bld/debug && ninja && { meson test ${fileBasenameNoExtension} || cat ./meson-logs/testlog.txt }\",\n \"problemMatcher\": {\n \"base\": \"$gcc\",\n \"fileLocation\": [\n \"relative\",\n \"${workspaceRoot}/bld/debug\"\n ]\n }\n }\n ]\n}\n" }, { "path": "CMakeLists.txt", "content": "# Generated by `boostdep --cmake leaf`\n# Copyright 2020 Peter Dimov\n# Distributed under the Boost Software License, Version 1.0.\n# https://www.boost.org/LICENSE_1_0.txt\n\ncmake_minimum_required(VERSION 3.5...3.16)\n\nproject(boost_leaf VERSION \"${BOOST_SUPERPROJECT_VERSION}\" LANGUAGES CXX)\n\nadd_library(boost_leaf INTERFACE)\nadd_library(Boost::leaf ALIAS boost_leaf)\n\ntarget_include_directories(boost_leaf INTERFACE include)\n\nif(BUILD_TESTING AND EXISTS \"${CMAKE_CURRENT_SOURCE_DIR}/test/CMakeLists.txt\")\n\n add_subdirectory(test)\n\nendif()\n\n" }, { "path": "LICENSE_1_0.txt", "content": "Boost Software License - Version 1.0 - August 17th, 2003\n\nPermission is hereby granted, free of charge, to any person or organization\nobtaining a copy of the software and accompanying documentation covered by\nthis license (the \"Software\") to use, reproduce, display, distribute,\nexecute, and transmit the Software, and to prepare derivative works of the\nSoftware, and to permit third-parties to whom the Software is furnished to\ndo so, all subject to the following:\n\nThe copyright notices in the Software and this entire statement, including\nthe above license grant, this restriction and the following disclaimer,\nmust be included in all copies of the Software, in whole or in part, and\nall derivative works of the Software, unless such copies or derivative\nworks are solely in the form of machine-executable object code generated by\na source language processor.\n\nTHE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR\nIMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,\nFITNESS FOR A PARTICULAR PURPOSE, TITLE AND NON-INFRINGEMENT. IN NO EVENT\nSHALL THE COPYRIGHT HOLDERS OR ANYONE DISTRIBUTING THE SOFTWARE BE LIABLE\nFOR ANY DAMAGES OR OTHER LIABILITY, WHETHER IN CONTRACT, TORT OR OTHERWISE,\nARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER\nDEALINGS IN THE SOFTWARE.\n" }, { "path": "README.md", "content": "# LEAF\n\n> A lightweight error handling library for C++11.\n\n## Documentation\n\nhttps://boostorg.github.io/leaf/\n\n## Features\n\n* Portable single-header format, no dependencies.\n* Tiny code size when configured for embedded development.\n* No dynamic memory allocations, even with very large payloads.\n* Deterministic unbiased efficiency on the \"happy\" path and the \"sad\" path.\n* Error objects are handled in constant time, independent of call stack depth.\n* Can be used with or without exception handling.\n\n## Support\n\n* [cpplang on Slack](https://Cpplang.slack.com) (use the `#boost` channel)\n* [Boost Users Mailing List](https://lists.boost.org/mailman/listinfo.cgi/boost-users)\n* [Boost Developers Mailing List](https://lists.boost.org/mailman/listinfo.cgi/boost)\n\n## Distribution\n\nBesides GitHub, there are two other distribution channels:\n\n* LEAF is included in official [Boost](https://www.boost.org/) releases, starting with Boost 1.75.\n* For maximum portability, the library is also available in single-header format: simply download [leaf.hpp](https://boostorg.github.io/leaf/leaf.hpp) (direct download link).\n\nCopyright 2018-2022 Emil Dotchevski and Reverge Studios, Inc. Distributed under the http://www.boost.org/LICENSE_1_0.txt[Boost Software License, Version 1.0].\n" }, { "path": "appveyor.yml", "content": "# Copyright 2016, 2017 Peter Dimov\n# Copyright 2018-2022 Emil Dotchevski and Reverge Studios, Inc.\n# Distributed under the Boost Software License, Version 1.0.\n# (See accompanying file LICENSE_1_0.txt or copy at http://boost.org/LICENSE_1_0.txt)\n\nversion: 1.0.{build}-{branch}\n\nshallow_clone: true\n\nbranches:\n only:\n - master\n - develop\n\nenvironment:\n matrix:\n - APPVEYOR_BUILD_WORKER_IMAGE: Visual Studio 2017\n TOOLSET: msvc-14.1,clang-win\n CXXSTD: 14,17\n - APPVEYOR_BUILD_WORKER_IMAGE: Visual Studio 2019\n TOOLSET: msvc-14.2\n CXXSTD: 14,17\n\ninstall:\n - set BOOST_BRANCH=develop\n - if \"%APPVEYOR_REPO_BRANCH%\" == \"master\" set BOOST_BRANCH=master\n - cd ..\n - git clone -b %BOOST_BRANCH% --depth 1 https://github.com/boostorg/boost.git boost-root\n - cd boost-root\n - git submodule update --init tools/build\n - git submodule update --init tools/boost_install\n - git submodule update --init libs/config\n - git submodule update --init libs/headers\n - git submodule update --init tools/boostdep\n - xcopy /s /e /q %APPVEYOR_BUILD_FOLDER% libs\\leaf\\\n - python tools/boostdep/depinst/depinst.py leaf\n - cmd /c bootstrap\n - b2 headers\n\nbuild: off\n\ntest_script:\n - if not \"%CXXSTD%\" == \"\" set CXXSTD=cxxstd=%CXXSTD%\n - b2 -j3 libs/leaf/test toolset=%TOOLSET% exception-handling=on,off variant=debug,release,leaf_debug_diag0,leaf_release_diag0 define=_CRT_SECURE_NO_WARNINGS %CXXSTD%\n" }, { "path": "benchmark/b.bat", "content": "ninja\ndel benchmark.csv\ndeep_stack_leaf\ndeep_stack_tl\ndeep_stack_result\ndeep_stack_outcome\n" }, { "path": "benchmark/b.sh", "content": "ninja\nrm benchmark.csv\n./deep_stack_leaf\n./deep_stack_tl\n./deep_stack_result\n./deep_stack_outcome\n" }, { "path": "benchmark/benchmark.md", "content": "# Benchmark\n\nThe LEAF github repository contains two similar benchmarking programs, one using LEAF, the other configurable to use `tl::expected` or Boost Outcome, that simulate transporting error objects across 10 levels of stack frames, measuring the performance of the three libraries.\n\nLinks:\n* LEAF: https://boostorg.github.io/leaf\n* `tl::expected`: https://github.com/TartanLlama/expected\n* Boost Outcome V2: https://www.boost.org/doc/libs/release/libs/outcome/doc/html/index.html\n\n## Library design considerations\n\nLEAF serves a similar purpose to other error handling libraries, but its design is very different. The benchmarks are comparing apples and oranges.\n\nThe main design difference is that when using LEAF, error objects are not communicated in return values. In case of a failure, the `leaf::result` object transports only an `int`, the unique error ID.\n\nError objects skip the error neutral functions in the call stack and get moved directly to the the error handling scope that needs them. This mechanism does not depend on RVO or any other optimization: as soon as the program passes an error object to LEAF, it moves it to the correct error handling scope.\n\nOther error handling libraries instead couple the static type of the return value of *all* error neutral functions with the error type an error reporting function may return. This approach suffers from the same problems as statically-enforced exception specifications:\n\n* It's difficult to use in polymorphic function calls, and\n* It impedes interoperability between the many different error types any non-trivial program must handle.\n\n(The Boost Outcome library is also capable of avoiding such excessive coupling, by passing for the third `P` argument in the `outcome` template a pointer that erases the exact static type of the object being transported. However, this would require a dynamic memory allocation).\n\n## Syntax\n\nThe most common check-only use case looks almost identically in LEAF and in Boost Outcome (`tl::expected` lacks a similar macro):\n\n```c++\n// Outcome\n{\n BOOST_OUTCOME_TRY(v, f()); // Check for errors, forward failures to the caller\n // If control reaches here, v is the successful result (the call succeeded).\n}\n```\n\n```c++\n// LEAF\n{\n BOOST_LEAF_AUTO(v, f()); // Check for errors, forward failures to the caller\n // If control reaches here, v is the successful result (the call succeeded).\n}\n```\n\nWhen we want to handle failures, in Boost Outcome and in `tl::expected`, accessing the error object (which is always stored in the return value) is a simple continuation of the error check:\n\n```c++\n// Outcome, tl::expected\nif( auto r = f() )\n{\n auto v = r.value();\n // No error, use v\n}\nelse\n{ // Error!\n switch( r.error() )\n {\n error_enum::error1:\n /* handle error_enum::error1 */\n break;\n\n error_enum::error2:\n /* handle error_enum::error2 */\n break;\n\n default:\n /* handle any other failure */\n }\n}\n```\n\nWhen using LEAF, we must explicitly state our intention to handle errors, not just check for failures:\n\n```c++\n// LEAF\nleaf::try_handle_all\n\n []() -> leaf::result\n {\n BOOST_LEAF_AUTO(v, f());\n // No error, use v\n },\n\n []( leaf::match )\n {\n /* handle error_enum::error1 */\n },\n\n []( leaf::match )\n {\n /* handle error_enum::error2 */\n },\n\n []\n {\n /* handle any other failure */\n } );\n```\n\nThe use of `try_handle_all` reserves storage on the stack for the error object types being handled (in this case, `error_enum`). If the failure is either `error_enum::error1` or `error_enum::error2`, the matching error handling lambda is invoked.\n\n## Code generation considerations\n\nBenchmarking C++ programs is tricky, because we want to prevent the compiler from optimizing out things it shouldn't normally be able to optimize in a real program, yet we don't want to interfere with \"legitimate\" optimizations.\n\nThe primary approach we use to prevent the compiler from optimizing everything out to nothing is to base all computations on a call to `std::rand()`.\n\nWhen benchmarking error handling, it makes sense to measure the time it takes to return a result or error across multiple stack frames. This calls for disabling inlining.\n\nThe technique used to disable inlining in this benchmark is to mark functions with `__attribute__((noinline))`. This is imperfect, because optimizers can still peek into the body of the function and optimize things out, as is seen in this example:\n\n```c++\n__attribute__((noinline)) int val() {return 42;}\n\nint main()\n{\n return val();\n}\n```\n\nWhich on clang 9 outputs:\n\n```x86asm\nval():\n mov eax, 42\n ret\nmain:\n mov eax, 42\n ret\n```\n\nIt does not appear that anything like this is occurring in our case, but it is still a possibility.\n\n> NOTES:\n>\n> - The benchmarks are compiled with exception handling disabled.\n> - LEAF is able to work with external `result<>` types. The benchmark uses `leaf::result`.\n\n## Show me the code!\n\nThe following source:\n\n```C++\nleaf::result f();\n\nleaf::result g()\n{\n BOOST_LEAF_AUTO(x, f());\n return x+1;\n}\n```\n\nGenerates this code on clang ([Godbolt](https://godbolt.org/z/v58drTPhq)):\n\n```x86asm\ng(): # @g()\n push rbx\n sub rsp, 32\n mov rbx, rdi\n lea rdi, [rsp + 8]\n call f()\n mov eax, dword ptr [rsp + 24]\n mov ecx, eax\n and ecx, 3\n cmp ecx, 3\n jne .LBB0_1\n mov eax, dword ptr [rsp + 8]\n add eax, 1\n mov dword ptr [rbx], eax\n mov eax, 3\n jmp .LBB0_3\n.LBB0_1:\n cmp ecx, 2\n jne .LBB0_3\n mov rax, qword ptr [rsp + 8]\n mov qword ptr [rbx], rax\n mov rax, qword ptr [rsp + 16]\n mov qword ptr [rbx + 8], rax\n mov eax, 2\n.LBB0_3:\n mov dword ptr [rbx + 16], eax\n mov rax, rbx\n add rsp, 32\n pop rbx\n ret\n```\n\n> Description:\n>\n> * The happy path can be recognized by the `add eax, 1` instruction generated for `x + 1`.\n>\n> * `.LBB0_3`: Regular failure; the returned `result` object holds only the `int` discriminant.\n>\n> * `.LBB0_1`: Failure; the returned `result` holds the `int` discriminant and a `std::shared_ptr` (used to hold error objects transported from another thread).\n\nNote that `f` is undefined, hence the `call` instruction. Predictably, if we provide a trivial definition for `f`:\n\n```C++\nleaf::result f()\n{\n return 42;\n}\n\nleaf::result g()\n{\n BOOST_LEAF_AUTO(x, f());\n return x+1;\n}\n```\n\nWe get:\n\n```x86asm\ng(): # @g()\n mov rax, rdi\n mov dword ptr [rdi], 43\n mov dword ptr [rdi + 16], 3\n ret\n```\n\nWith a less trivial definition of `f`:\n\n```C++\nleaf::result f()\n{\n if( rand()%2 )\n return 42;\n else\n return leaf::new_error();\n}\n\nleaf::result g()\n{\n BOOST_LEAF_AUTO(x, f());\n return x+1;\n}\n```\n\nWe get ([Godbolt](https://godbolt.org/z/87Kezzrs4)):\n\n```x86asm\ng(): # @g()\n push rbx\n mov rbx, rdi\n call rand\n test al, 1\n jne .LBB1_2\n mov eax, 4\n lock xadd dword ptr [rip + boost::leaf::leaf_detail::id_factory::counter], eax\n add eax, 4\n mov dword ptr fs:[boost::leaf::leaf_detail::id_factory::current_id@TPOFF], eax\n and eax, -4\n or eax, 1\n mov dword ptr [rbx + 16], eax\n mov rax, rbx\n pop rbx\n ret\n.LBB1_2:\n mov dword ptr [rbx], 43\n mov eax, 3\n mov dword ptr [rbx + 16], eax\n mov rax, rbx\n pop rbx\n ret\n```\n\nAbove, the call to `f()` is inlined:\n\n* `.LBB1_2`: Success\n* The atomic `add` is from the initial error reporting machinery in LEAF, generating a unique error ID for the error being reported.\n\n## Benchmark matrix dimensions\n\nThe benchmark matrix has 2 dimensions:\n\n1. Error object type:\n\n a. The error object transported in case of a failure is of type `e_error_code`, which is a simple `enum`.\n\n b. The error object transported in case of a failure is of type `struct e_system_error { e_error_code value; std::string what; }`.\n\n c. The error object transported in case of a failure is of type `e_heavy_payload`, a `struct` of size 4096.\n\n2. Error rate: 2%, 98%\n\nNow, transporting a large error object might seem unusual, but this is only because it is impractical to return a large object as *the* return value in case of an error. LEAF has two features that make communicating any, even large error objects, practical:\n\n* The return type of error neutral functions is not coupled with the error object types that may be reported. This means that in case of a failure, any function can easily contribute any error information it has available.\n\n* LEAF will only bother with transporting a given error object if an active error handling scope needs it. This means that library functions can and should contribute any and all relevant information when reporting a failure, because if the program doesn't need it, it will simply be discarded.\n\n## Source code\n\n[deep_stack_leaf.cpp](deep_stack_leaf.cpp)\n\n[deep_stack_other.cpp](deep_stack_other.cpp)\n\n## Godbolt\n\nGodbolt has built-in support for Boost (Outcome/LEAF), but `tl::expected` both provide a single header, which makes it very easy to use them online as well. To see the generated code for the benchmark program, you can copy and paste the following into Godbolt:\n\n`leaf::result` ([godbolt](https://godbolt.org/z/1hqqnfhMf))\n\n```c++\n#include \"https://raw.githubusercontent.com/boostorg/leaf/master/benchmark/deep_stack_leaf.cpp\"\n```\n\n`tl::expected` ([godbolt](https://godbolt.org/z/6dfcdsPcc))\n\n```c++\n#include \"https://raw.githubusercontent.com/TartanLlama/expected/master/include/tl/expected.hpp\"\n#include \"https://raw.githubusercontent.com/boostorg/leaf/master/benchmark/deep_stack_other.cpp\"\n```\n\n`outcome::result` ([godbolt](https://godbolt.org/z/jMEfGMrW9))\n\n```c++\n#define BENCHMARK_WHAT 1\n#include \"https://raw.githubusercontent.com/boostorg/leaf/master/benchmark/deep_stack_other.cpp\"\n```\n\n## Build options\n\nTo build both versions of the benchmark program, the compilers are invoked using the following command line options:\n\n* `-std=c++17`: Required by other libraries (LEAF only requires C++11);\n* `-fno-exceptions`: Disable exception handling;\n* `-O3`: Maximum optimizations;\n* `-DNDEBUG`: Disable asserts.\n\nIn addition, the LEAF version is compiled with:\n\n* `-DBOOST_LEAF_CFG_DIAGNOSTICS=0`: Disable diagnostic information for error objects not recognized by the program. This is a debugging feature, see [Configuration Macros](https://boostorg.github.io/leaf/#configuration).\n\n## Results\n\nBelow is the output the benchmark programs running on an old MacBook Pro. The tables show the elapsed time for 10,000,000 iterations of returning a result across 10 stack frames, depending on the error type and the rate of failures. In addition, the programs generate a `benchmark.csv` file in the current working directory.\n\n### gcc 9.2.0:\n\n`leaf::result`:\n\nError type | 2% (μs) | 98% (μs)\n----------------|---------:|--------:\ne_error_code | 594965 | 545882\ne_system_error | 614688 | 1203154\ne_heavy_payload | 736701 | 7397756\n\n`tl::expected`:\n\nError type | 2% (μs) | 98% (μs)\n----------------|---------:|--------:\ne_error_code | 921410 | 820757\ne_system_error | 670191 | 5593513\ne_heavy_payload | 1331724 | 31560432\n\n`outcome::result`:\n\nError type | 2% (μs) | 98% (μs)\n----------------|---------:|--------:\ne_error_code | 1080512 | 773206\ne_system_error | 577403 | 1201693\ne_heavy_payload | 13222387 | 32104693\n\n`outcome::outcome`:\n\nError type | 2% (μs) | 98% (μs)\n----------------|---------:|--------:\ne_error_code | 832916 | 1170731\ne_system_error | 947298 | 2330392\ne_heavy_payload | 13342292 | 33837583\n\n### clang 11.0.0:\n\n`leaf::result`:\n\nError type | 2% (μs) | 98% (μs)\n----------------|---------:|--------:\ne_error_code | 570847 | 493538\ne_system_error | 592685 | 982799\ne_heavy_payload | 713966 | 5144523\n\n`tl::expected`:\n\nError type | 2% (μs) | 98% (μs)\n----------------|---------:|--------:\ne_error_code | 461639 | 312849\ne_system_error | 620479 | 3534689\ne_heavy_payload | 1037434 | 16078669\n\n`outcome::result`:\n\nError type | 2% (μs) | 98% (μs)\n----------------|---------:|--------:\ne_error_code | 431219 | 446854\ne_system_error | 589456 | 1712739\ne_heavy_payload | 12387405 | 16216894\n\n`outcome::outcome`:\n\nError type | 2% (μs) | 98% (μs)\n----------------|---------:|--------:\ne_error_code | 711412 | 1477505\ne_system_error | 835691 | 2374919\ne_heavy_payload | 13289404 | 29785353\n\n### msvc 19.24.28314:\n\n`leaf::result`:\n\nError type | 2% (μs) | 98% (μs)\n----------------|---------:|--------:\ne_error_code | 1205327 | 1449117\ne_system_error | 1290277 | 2332414\ne_heavy_payload | 1503103 | 13682308\n\n`tl::expected`:\n\nError type | 2% (μs) | 98% (μs)\n----------------|---------:|--------:\ne_error_code | 938839 | 867296\ne_system_error | 1455627 | 8943881\ne_heavy_payload | 2637494 | 49212901\n\n`outcome::result`:\n\nError type | 2% (μs) | 98% (μs)\n----------------|---------:|--------:\ne_error_code | 935331 | 1202475\ne_system_error | 1228944 | 2269680\ne_heavy_payload | 15239084 | 55618460\n\n`outcome::outcome`:\n\nError type | 2% (μs) | 98% (μs)\n----------------|---------:|--------:\ne_error_code | 1472035 | 2529057\ne_system_error | 1997971 | 4004965\ne_heavy_payload | 16027423 | 64572924\n\n## Charts\n\nThe charts below are generated from the results from the previous section, converted from elapsed time in microseconds to millions of calls per second.\n\n### gcc 9.2.0:\n\n![](gcc_e_error_code.png)\n\n![](gcc_e_system_error.png)\n\n![](gcc_e_heavy_payload.png)\n\n### clang 11.0.0:\n\n![](clang_e_error_code.png)\n\n![](clang_e_system_error.png)\n\n![](clang_e_heavy_payload.png)\n\n### msvc 19.24.28314:\n\n![](msvc_e_error_code.png)\n\n![](msvc_e_system_error.png)\n\n![](msvc_e_heavy_payload.png)\n\n## Thanks\n\nThanks for the valuable feedback: Peter Dimov, Glen Fernandes, Sorin Fetche, Niall Douglas, Ben Craig, Vinnie Falco, Jason Dictos\n" }, { "path": "benchmark/deep_stack_leaf.cpp", "content": "// Copyright 2018-2022 Emil Dotchevski and Reverge Studios, Inc.\n\n// Distributed under the Boost Software License, Version 1.0. (See accompanying\n// file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)\n\n// See benchmark.md\n\n#include \n\n#ifndef BOOST_LEAF_NO_EXCEPTIONS\n# error Please disable exception handling.\n#endif\n\n#if BOOST_LEAF_CFG_DIAGNOSTICS\n# error Please disable diagnostics.\n#endif\n\n#ifdef _MSC_VER\n# define NOINLINE __declspec(noinline)\n# define ALWAYS_INLINE __forceinline\n#else\n# define NOINLINE __attribute__((noinline))\n# define ALWAYS_INLINE __attribute__((always_inline)) inline\n#endif\n\n#include \n#include \n#include \n#include \n#include \n#include \n#include \n#include \n#include \n#include \n#include \n\nnamespace boost\n{\n [[noreturn]] void throw_exception( std::exception const & e )\n {\n std::cerr << \"Terminating due to a C++ exception under BOOST_LEAF_NO_EXCEPTIONS: \" << e.what();\n std::terminate();\n }\n\n struct source_location;\n [[noreturn]] void throw_exception( std::exception const & e, boost::source_location const & )\n {\n throw_exception(e);\n }\n}\n\n//////////////////////////////////////\n\nnamespace leaf = boost::leaf;\n\n#define USING_RESULT_TYPE \"leaf::result\"\n\n//////////////////////////////////////\n\nenum class e_error_code\n{\n ec0, ec1, ec2, ec3\n};\n\nstruct e_system_error\n{\n int value;\n std::string what;\n};\n\nstruct e_heavy_payload\n{\n std::array value;\n};\n\ntemplate \nleaf::error_id make_error() noexcept;\n\ntemplate <>\ninline leaf::error_id make_error() noexcept\n{\n switch(std::rand()%4)\n {\n default: return leaf::new_error(e_error_code::ec0);\n case 1: return leaf::new_error(e_error_code::ec1);\n case 2: return leaf::new_error(e_error_code::ec2);\n case 3: return leaf::new_error(e_error_code::ec3);\n }\n}\n\ntemplate <>\ninline leaf::error_id make_error() noexcept\n{\n return std::error_code(std::rand(), std::system_category());\n}\n\ntemplate <>\ninline leaf::error_id make_error() noexcept\n{\n return leaf::new_error( e_system_error { std::rand(), std::string(std::rand()%32, ' ') } );\n}\n\ntemplate <>\ninline leaf::error_id make_error() noexcept\n{\n e_heavy_payload e;\n std::fill(e.value.begin(), e.value.end(), std::rand());\n return leaf::new_error(e);\n}\n\ninline bool should_fail( int failure_rate ) noexcept\n{\n assert(failure_rate>=0);\n assert(failure_rate<=100);\n return (std::rand()%100) < failure_rate;\n}\n\ninline int handle_error( e_error_code e ) noexcept\n{\n return int(e);\n}\n\ninline int handle_error( std::error_code const & e ) noexcept\n{\n return e.value();\n}\n\ninline int handle_error( e_system_error const & e ) noexcept\n{\n return e.value + e.what.size();\n}\n\ninline int handle_error( e_heavy_payload const & e ) noexcept\n{\n return std::accumulate(e.value.begin(), e.value.end(), 0);\n}\n\n//////////////////////////////////////\n\n// This is used to change the \"success\" type at each level.\n// Generally, functions return values of different types.\ntemplate \nstruct select_result_type;\n\ntemplate \nstruct select_result_type\n{\n using type = leaf::result; // Does not depend on E\n};\n\ntemplate \nstruct select_result_type\n{\n using type = leaf::result; // Does not depend on E\n};\n\ntemplate \nusing select_result_t = typename select_result_type::type;\n\n//////////////////////////////////////\n\ntemplate \nstruct benchmark\n{\n using e_type = E;\n\n NOINLINE static select_result_t f( int failure_rate ) noexcept\n {\n BOOST_LEAF_AUTO(x, (benchmark::f(failure_rate)));\n return x+1;\n }\n};\n\ntemplate \nstruct benchmark<1, E>\n{\n using e_type = E;\n\n NOINLINE static select_result_t<1, E> f( int failure_rate ) noexcept\n {\n if( should_fail(failure_rate) )\n return make_error();\n else\n return std::rand();\n }\n};\n\n//////////////////////////////////////\n\ntemplate \nNOINLINE int runner( int failure_rate ) noexcept\n{\n return leaf::try_handle_all(\n [=]\n {\n return Benchmark::f(failure_rate);\n },\n []( typename Benchmark::e_type const & e )\n {\n return handle_error(e);\n },\n []\n {\n return -1;\n } );\n}\n\n//////////////////////////////////////\n\nstd::fstream append_csv()\n{\n if( FILE * f = fopen(\"benchmark.csv\",\"rb\") )\n {\n fclose(f);\n return std::fstream(\"benchmark.csv\", std::fstream::out | std::fstream::app);\n }\n else\n {\n std::fstream fs(\"benchmark.csv\", std::fstream::out | std::fstream::app);\n fs << \"\\\"Result Type\\\",2%,98%\\n\";\n return fs;\n }\n}\n\ntemplate \nint print_elapsed_time( int iteration_count, F && f )\n{\n auto start = std::chrono::steady_clock::now();\n int val = 0;\n for( int i = 0; i!=iteration_count; ++i )\n val += std::forward(f)();\n auto stop = std::chrono::steady_clock::now();\n int elapsed = std::chrono::duration_cast(stop-start).count();\n std::cout << std::right << std::setw(9) << elapsed;\n append_csv() << ',' << elapsed;\n return val;\n}\n\n//////////////////////////////////////\n\ntemplate \nint benchmark_type( char const * type_name, int iteration_count )\n{\n int x=0;\n append_csv() << \"\\\"\" USING_RESULT_TYPE \"\\\"\";\n std::cout << '\\n' << std::left << std::setw(16) << type_name << '|';\n std::srand(0);\n x += print_elapsed_time( iteration_count, [] { return runner>(2); } );\n std::cout << \" |\";\n std::srand(0);\n x += print_elapsed_time( iteration_count, [] { return runner>(98); } );\n append_csv() << '\\n';\n return x;\n}\n\n//////////////////////////////////////\n\nint main()\n{\n int const depth = 10;\n int const iteration_count = 10000000;\n std::cout <<\n iteration_count << \" iterations, call depth \" << depth << \", sizeof(e_heavy_payload) = \" << sizeof(e_heavy_payload) << \"\\n\"\n USING_RESULT_TYPE \"\\n\"\n \"Error type | 2% (μs) | 98% (μs)\\n\"\n \"----------------|----------|---------\";\n int r = 0;\n r += benchmark_type(\"e_error_code\", iteration_count);\n r += benchmark_type(\"std::error_code\", iteration_count);\n r += benchmark_type(\"e_system_error\", iteration_count);\n r += benchmark_type(\"e_heavy_payload\", iteration_count);\n std::cout << '\\n';\n // std::cout << std::rand() << '\\n';\n return r;\n}\n" }, { "path": "benchmark/deep_stack_other.cpp", "content": "// Copyright 2018-2022 Emil Dotchevski and Reverge Studios, Inc.\n\n// Distributed under the Boost Software License, Version 1.0. (See accompanying\n// file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)\n\n// See benchmark.md\n\n#ifndef BENCHMARK_WHAT\n# define BENCHMARK_WHAT 0\n#endif\n\n#if BENCHMARK_WHAT == 0\n\n# ifndef TL_EXPECTED_HPP\n# include \"tl/expected.hpp\"\n# endif\n# define BENCHMARK_SUCCESS(e) e\n# define BENCHMARK_FAILURE(e) tl::make_unexpected(e)\n# define BENCHMARK_TRY(v,r)\\\n auto && _r_##v = r;\\\n if( !_r_##v )\\\n return BENCHMARK_FAILURE(_r_##v.error());\\\n auto && v = _r_##v.value()\n\n#else\n\n# include \n# include \n# define BENCHMARK_SUCCESS(e) boost::outcome_v2::success(e)\n# define BENCHMARK_FAILURE(e) boost::outcome_v2::failure(e)\n# define BENCHMARK_TRY BOOST_OUTCOME_TRY\n# ifndef BOOST_NO_EXCEPTIONS\n# error Please disable exception handling.\n# endif\n\n#endif\n\n#ifdef _MSC_VER\n# define NOINLINE __declspec(noinline)\n# define ALWAYS_INLINE __forceinline\n#else\n# define NOINLINE __attribute__((noinline))\n# define ALWAYS_INLINE __attribute__((always_inline)) inline\n#endif\n\n#include \n#include \n#include \n#include \n#include \n#include \n#include \n#include \n#include \n#include \n#include \n\nnamespace boost\n{\n void throw_exception( std::exception const & e )\n {\n std::cerr << \"Terminating due to a C++ exception under BOOST_NO_EXCEPTIONS: \" << e.what();\n std::terminate();\n }\n\n struct source_location;\n void throw_exception( std::exception const & e, boost::source_location const & )\n {\n throw_exception(e);\n }\n}\n\n//////////////////////////////////////\n\n#if BENCHMARK_WHAT == 0 // tl::expected\n\n# define USING_RESULT_TYPE \"tl::expected\"\n\n template \n using result = tl::expected;\n\n#elif BENCHMARK_WHAT == 1 // outcome::result\n\n# define USING_RESULT_TYPE \"outcome::result\"\n\n template \n using result = boost::outcome_v2::std_result;\n\n#elif BENCHMARK_WHAT == 2 // outcome::outcome\n\n# define USING_RESULT_TYPE \"outcome::outcome\"\n\n template \n using result = boost::outcome_v2::std_outcome;\n\n#else\n# error Benchmark what?\n#endif\n\n//////////////////////////////////////\n\nenum class e_error_code\n{\n ec0, ec1, ec2, ec3\n};\n\nstruct e_system_error\n{\n int value;\n std::string what;\n};\n\nstruct e_heavy_payload\n{\n std::array value;\n};\n\ntemplate \nE make_error() noexcept;\n\ntemplate <>\ninline e_error_code make_error() noexcept\n{\n switch(std::rand()%4)\n {\n default: return e_error_code::ec0;\n case 1: return e_error_code::ec1;\n case 2: return e_error_code::ec2;\n case 3: return e_error_code::ec3;\n }\n}\n\ntemplate <>\ninline std::error_code make_error() noexcept\n{\n return std::error_code(std::rand(), std::system_category());\n}\n\ntemplate <>\ninline e_system_error make_error() noexcept\n{\n return { std::rand(), std::string(std::rand()%32, ' ') };\n}\n\ntemplate <>\ninline e_heavy_payload make_error() noexcept\n{\n e_heavy_payload e;\n std::fill(e.value.begin(), e.value.end(), std::rand());\n return e;\n}\n\ninline bool should_fail( int failure_rate ) noexcept\n{\n assert(failure_rate>=0);\n assert(failure_rate<=100);\n return (std::rand()%100) < failure_rate;\n}\n\ninline int handle_error( e_error_code e ) noexcept\n{\n return int(e);\n}\n\ninline int handle_error( std::error_code const & e ) noexcept\n{\n return e.value();\n}\n\ninline int handle_error( e_system_error const & e ) noexcept\n{\n return e.value + e.what.size();\n}\n\ninline int handle_error( e_heavy_payload const & e ) noexcept\n{\n return std::accumulate(e.value.begin(), e.value.end(), 0);\n}\n\n//////////////////////////////////////\n\n// This is used to change the \"success\" type at each level.\n// Generally, functions return values of different types.\ntemplate \nstruct select_result_type;\n\ntemplate \nstruct select_result_type\n{\n using type = result;\n};\n\ntemplate \nstruct select_result_type\n{\n using type = result;\n};\n\ntemplate \nusing select_result_t = typename select_result_type::type;\n\n//////////////////////////////////////\n\ntemplate \nstruct benchmark\n{\n using e_type = E;\n\n NOINLINE static select_result_t f( int failure_rate ) noexcept\n {\n BENCHMARK_TRY(x, (benchmark::f(failure_rate)));\n return BENCHMARK_SUCCESS(x+1);\n }\n};\n\ntemplate \nstruct benchmark<1, E>\n{\n using e_type = E;\n\n NOINLINE static select_result_t<1, E> f( int failure_rate ) noexcept\n {\n if( should_fail(failure_rate) )\n return BENCHMARK_FAILURE(make_error());\n else\n return BENCHMARK_SUCCESS(std::rand());\n }\n};\n\n//////////////////////////////////////\n\ntemplate \nNOINLINE int runner( int failure_rate ) noexcept\n{\n if( auto r = Benchmark::f(failure_rate) )\n return r.value();\n else\n return handle_error(r.error());\n}\n\n//////////////////////////////////////\n\nstd::fstream append_csv()\n{\n if( FILE * f = fopen(\"benchmark.csv\",\"rb\") )\n {\n fclose(f);\n return std::fstream(\"benchmark.csv\", std::fstream::out | std::fstream::app);\n }\n else\n {\n std::fstream fs(\"benchmark.csv\", std::fstream::out | std::fstream::app);\n fs << \"\\\"Result Type\\\",2%,98%\\n\";\n return fs;\n }\n}\n\ntemplate \nint print_elapsed_time( int iteration_count, F && f )\n{\n auto start = std::chrono::steady_clock::now();\n int val = 0;\n for( int i = 0; i!=iteration_count; ++i )\n val += std::forward(f)();\n auto stop = std::chrono::steady_clock::now();\n int elapsed = std::chrono::duration_cast(stop-start).count();\n std::cout << std::right << std::setw(9) << elapsed;\n append_csv() << ',' << elapsed;\n return val;\n}\n\n//////////////////////////////////////\n\ntemplate \nint benchmark_type( char const * type_name, int iteration_count )\n{\n int x=0;\n append_csv() << \"\\\"\" USING_RESULT_TYPE \"\\\"\";\n std::cout << '\\n' << std::left << std::setw(16) << type_name << '|';\n std::srand(0);\n x += print_elapsed_time( iteration_count, [] { return runner>(2); } );\n std::cout << \" |\";\n std::srand(0);\n x += print_elapsed_time( iteration_count, [] { return runner>(98); } );\n append_csv() << '\\n';\n return x;\n}\n\n//////////////////////////////////////\n\nint main()\n{\n int const depth = 10;\n int const iteration_count = 10000000;\n std::cout <<\n iteration_count << \" iterations, call depth \" << depth << \", sizeof(e_heavy_payload) = \" << sizeof(e_heavy_payload) << \"\\n\"\n USING_RESULT_TYPE \"\\n\"\n \"Error type | 2% (μs) | 98% (μs)\\n\"\n \"----------------|----------|---------\";\n int r = 0;\n r += benchmark_type(\"e_error_code\", iteration_count);\n r += benchmark_type(\"std::error_code\", iteration_count);\n r += benchmark_type(\"e_system_error\", iteration_count);\n r += benchmark_type(\"e_heavy_payload\", iteration_count);\n std::cout << '\\n';\n // std::cout << std::rand() << '\\n';\n return r;\n}\n" }, { "path": "conanfile.py", "content": "from conan import ConanFile\nfrom conan.tools.files import copy\nfrom conan.tools.layout import basic_layout\nfrom conan.tools.build import check_min_cppstd\nfrom conan.errors import ConanInvalidConfiguration\nimport os\n\n\nrequired_conan_version = \">=1.50.0\"\n\n\nclass BoostLEAFConan(ConanFile):\n name = \"boost-leaf\"\n version = \"1.81.0\"\n license = \"BSL-1.0\"\n url = \"https://github.com/conan-io/conan-center-index\"\n homepage = \"https://github.com/boostorg/leaf\"\n description = (\"Lightweight Error Augmentation Framework\")\n topics = (\"multi-platform\", \"multi-threading\", \"cpp11\", \"error-handling\",\n \"header-only\", \"low-latency\", \"no-dependencies\", \"single-header\")\n settings = \"os\", \"compiler\", \"arch\", \"build_type\"\n exports_sources = \"include/*\", \"LICENSE_1_0.txt\"\n no_copy_source = True\n\n def package_id(self):\n self.info.clear()\n\n @property\n def _min_cppstd(self):\n return \"11\"\n\n @property\n def _compilers_minimum_version(self):\n return {\n \"gcc\": \"4.8\",\n \"Visual Studio\": \"17\",\n \"msvc\": \"141\",\n \"clang\": \"3.9\",\n \"apple-clang\": \"10.0.0\"\n }\n\n def requirements(self):\n pass\n\n def validate(self):\n if self.settings.get_safe(\"compiler.cppstd\"):\n check_min_cppstd(self, self._min_cppstd)\n\n def lazy_lt_semver(v1, v2):\n lv1 = [int(v) for v in v1.split(\".\")]\n lv2 = [int(v) for v in v2.split(\".\")]\n min_length = min(len(lv1), len(lv2))\n return lv1[:min_length] < lv2[:min_length]\n\n compiler = str(self.settings.compiler)\n version = str(self.settings.compiler.version)\n minimum_version = self._compilers_minimum_version.get(compiler, False)\n\n if minimum_version and lazy_lt_semver(version, minimum_version):\n raise ConanInvalidConfiguration(\n f\"{self.name} {self.version} requires C++{self._min_cppstd}, which your compiler ({compiler}-{version}) does not support\")\n\n def layout(self):\n basic_layout(self)\n\n def package(self):\n copy(self, \"LICENSE_1_0.txt\", dst=os.path.join(\n self.package_folder, \"licenses\"), src=self.source_folder)\n copy(self, \"*.h\", dst=os.path.join(self.package_folder, \"include\"),\n src=os.path.join(self.source_folder, \"include\"))\n copy(self, \"*.hpp\", dst=os.path.join(self.package_folder,\n \"include\"), src=os.path.join(self.source_folder, \"include\"))\n\n def package_info(self):\n self.cpp_info.set_property(\"cmake_target_name\", \"boost::leaf\")\n\n self.cpp_info.bindirs = []\n self.cpp_info.frameworkdirs = []\n self.cpp_info.libdirs = []\n self.cpp_info.resdirs = []\n" }, { "path": "doc/Jamfile", "content": "# Copyright 2017 Peter Dimov\n# Copyright 2018-2022 Emil Dotchevski and Reverge Studios, Inc.\n#\n# Distributed under the Boost Software License, Version 1.0.\n# (See accompanying file LICENSE_1_0.txt or copy at\n# http://www.boost.org/LICENSE_1_0.txt)\n\nproject doc/leaf ;\nimport asciidoctor ;\n\nhtml index.html : leaf.adoc : stylesheet=zajo-dark.css linkcss ;\ninstall html_ : index.html LEAF-1.png LEAF-2.png skin.png zajo-dark.css zajo-light.css rouge-github.css : html ;\n\npdf leaf.pdf : leaf.adoc : book pdf-themesdir=. pdf-theme=leaf ;\ninstall pdf_ : leaf.pdf : html ;\n\nalias boostdoc ;\nexplicit boostdoc ;\nalias boostrelease : html_ ;\nexplicit boostrelease ;\n" }, { "path": "doc/docinfo.html", "content": "\n\n\n\n" }, { "path": "doc/leaf-theme.yml", "content": "extends: default\nbase:\n font:\n color: #404040\nliteral:\n font:\n family: Courier\n color: #000000\nadmonition:\n icon:\n note:\n stroke-color: #000000\n tip:\n stroke-color: #000000\n warning:\n stroke-color: #FF5100\n important:\n stroke-color: #FF5100\n caution:\n stroke-color: #FF5100\nconum:\n font:\n glyphs: circled\n color: #000000\nlink:\n text-decoration: underline\n text-decoration-width: 0.5\n font-color: #000000\n" }, { "path": "doc/leaf.adoc", "content": ":last-update-label!:\n:icons: font\n:prewrap!:\n:docinfo: shared\n:stylesheet: zajo-dark.css\n:source-highlighter: rouge\n\nifdef::backend-pdf[]\n= LEAF\nendif::[]\nifndef::backend-pdf[]\n= LEAFpass:[
]\nendif::[]\nLightweight Error Augmentation Framework written in {CPP}11 | Emil Dotchevski\nifndef::backend-pdf[]\n:toc: left\n:toclevels: 3\n:toc-title:\n\n[.text-right]\nhttps://github.com/boostorg/leaf[GitHub] | https://boostorg.github.io/leaf/leaf.pdf[PDF]\nendif::[]\n\n[abstract]\n== Abstract\n\nBoost LEAF is a lightweight error handling library for {CPP}11. Features:\n\n====\n* Portable single-header format, no dependencies.\n\n* Tiny code size when configured for embedded development.\n\n* No dynamic memory allocations, even with very large payloads.\n\n* Deterministic unbiased efficiency on the \"happy\" path and the \"sad\" path.\n\n* Error objects are handled in constant time, independent of call stack depth.\n\n* Can be used with or without exception handling.\n====\n\nifndef::backend-pdf[]\n[grid=none, frame=none]\n|====\n| <> \\| <> \\| https://github.com/boostorg/leaf/blob/master/doc/whitepaper.md[Whitepaper] \\| https://github.com/boostorg/leaf/blob/master/benchmark/benchmark.md[Benchmark] >| Reference: <> \\| <> \\| <> \\| <> \\| <>\n|====\nendif::[]\n\n[[support]]\n== Support\n\n* https://Cpplang.slack.com[cpplang on Slack] (use the `#boost` channel)\n* https://lists.boost.org/mailman/listinfo.cgi/boost-users[Boost Users Mailing List]\n* https://lists.boost.org/mailman/listinfo.cgi/boost[Boost Developers Mailing List]\n* https://github.com/boostorg/leaf/issues[Report issues] on GitHub\n\n[[distribution]]\n== Distribution\n\nLEAF is distributed under the http://www.boost.org/LICENSE_1_0.txt[Boost Software License, Version 1.0].\n\nThere are three distribution channels:\n\n* LEAF is included in official https://www.boost.org/[Boost] releases (starting with Boost 1.75), and therefore available via most package managers.\n* The source code is hosted on https://github.com/boostorg/leaf[GitHub].\n* For maximum portability, the latest LEAF release is also available in single-header format: simply download link:https://raw.githubusercontent.com/boostorg/leaf/gh-pages/leaf.hpp[leaf.hpp] (direct download link).\n\nNOTE: LEAF does not depend on Boost or other libraries.\n\n[[tutorial]]\n== Tutorial\n\nWhat is a failure? It is simply the inability of a function to return a valid result, instead producing an error object describing the reason for the failure.\n\nA typical design is to return a variant type, e.g. `result`. Internally, such variant types must store a discriminant (in this case a boolean) to indicate whether the object holds a `T` or an `E`.\n\nThe design of LEAF is informed by the observation that the immediate caller must have access to the discriminant in order to determine the availability of a valid `T`, but otherwise it rarely needs to access the `E`. The error object is only needed once an error handling scope is reached.\n\nTherefore what would have been a `result` becomes `result`, which stores the discriminant and (optionally) a `T`, while the `E` is communicated directly to the error handling scope where it is needed.\n\nThe benefit of this decomposition is that `result` becomes extremely lightweight, as it is not coupled with error types; further, error objects are communicated in constant time (independent of the call stack depth). Even very large objects are handled efficiently without dynamic memory allocation.\n\n=== Reporting Errors\n\nA function that reports an error is pretty straight-forward:\n\n[source,c++]\n----\nenum class err1 { e1, e2, e3 };\n\nleaf::result f()\n{\n ....\n if( error_detected )\n return leaf::new_error( err1::e1 ); // Pass an error object of any type\n\n // Produce and return a T.\n}\n----\n[.text-right]\n<> | <>\n\n'''\n\n[[checking_for_errors]]\n=== Checking for Errors\n\nChecking for errors communicated by a `leaf::result` works as expected:\n\n[source,c++]\n----\nleaf::result g()\n{\n leaf::result r = f();\n if( !r )\n return r.error();\n\n T const & v = r.value();\n // Use v to produce a valid U\n}\n----\n[.text-right]\n<>\n\nTIP: The the result of `r.error()` is compatible with any instance of the `leaf::result` template. In the example above, note that `g` returns a `leaf::result`, while `r` is of type `leaf::result`.\n\nThe boilerplate `if` statement can be avoided using `BOOST_LEAF_AUTO`:\n\n[source,c++]\n----\nleaf::result g()\n{\n BOOST_LEAF_AUTO(v, f()); // Bail out on error\n\n // Use v to produce a valid U\n}\n----\n[.text-right]\n<>\n\n`BOOST_LEAF_AUTO` can not be used with `void` results; in that case, to avoid the boilerplate `if` statement, use `BOOST_LEAF_CHECK`:\n\n[source,c++]\n----\nleaf::result f();\n\nleaf::result g()\n{\n BOOST_LEAF_CHECK(f()); // Bail out on error\n return 42;\n}\n----\n[.text-right]\n<>\n\nOn implementations that define `pass:[__GNUC__]` (e.g. GCC/clang), the `BOOST_LEAF_CHECK` macro definition takes advantage of https://gcc.gnu.org/onlinedocs/gcc/Statement-Exprs.html[GNU C statement expressions]. In this case, in addition to its portable usage with `result`, `BOOST_LEAF_CHECK` can be used in expressions with non-`void` result types:\n\n[source,c++]\n----\nleaf::result f();\n\nfloat g(int x);\n\nleaf::result t()\n{\n return g( BOOST_LEAF_CHECK(f()) );\n}\n----\n\nThe following is the portable alternative:\n\n[source,c++]\n----\nleaf::result t()\n{\n BOOST_LEAF_AUTO(x, f());\n return g(x);\n}\n----\n\n'''\n\n[[tutorial-error_handling]]\n=== Error Handling\n\nError handling scopes must use a special syntax to indicate that they need to access error objects. The following excerpt attempts several operations and handles errors of type `err1`:\n\n[source,c++]\n----\nleaf::result r = leaf::try_handle_some(\n\n []() -> leaf::result\n {\n BOOST_LEAF_AUTO(v1, f1());\n BOOST_LEAF_AUTO(v2, f2());\n\n return g(v1, v2);\n },\n\n []( err1 e ) -> leaf::result\n {\n if( e == err1::e1 )\n .... // Handle err1::e1\n else\n .... // Handle any other err1 value\n } );\n----\n[.text-right]\n<> | <> | <>\n\nThe first lambda passed to `try_handle_some` is executed first; it attempts to produce a `result`, but it may fail.\n\nThe second lambda is an error handler: it will be called iff the first lambda fails and an error object of type `err1` was communicated to LEAF. That object is stored on the stack, local to the `try_handle_some` function (LEAF knows to allocate this storage because we gave it an error handler that takes an `err1`). Error handlers passed to `leaf::try_handle_some` can return a valid `leaf::result` but are allowed to fail.\n\nIt is possible for an error handler to specify that it can only deal with some values of a given error type:\n\n[source,c++]\n----\nleaf::result r = leaf::try_handle_some(\n\n []() -> leaf::result\n {\n BOOST_LEAF_AUTO(v1, f1());\n BOOST_LEAF_AUTO(v2, f2());\n\n return g(v1. v2);\n },\n\n []( leaf::match ) -> leaf::result\n {\n // Handle err::e1 or err1::e3\n },\n\n []( err1 e ) -> leaf::result\n {\n // Handle any other err1 value\n } );\n----\n[.text-right]\n<> | <> | <> | <>\n\nLEAF considers the provided error handlers in order, and calls the first one for which it can supply arguments, based on the error objects currently being communicated. Above:\n\n* The first error handler uses the predicate `leaf::match` to specify that it should only be considered if an error object of type `err1` is available, and its value is either `err1::e1` or `err1::e3`.\n\n* Otherwise the second error handler will be called if an error object of type `err1` is available, regardless of its value.\n\n* Otherwise `leaf::try_handle_some` fails.\n\nIt is possible for an error handler to conditionally leave the current failure unhandled:\n\n[source,c++]\n----\nleaf::result r = leaf::try_handle_some(\n\n []() -> leaf::result\n {\n BOOST_LEAF_AUTO(v1, f1());\n BOOST_LEAF_AUTO(v2, f2());\n\n return g(v1. v2);\n },\n\n []( err1 e, leaf::error_info const & ei ) -> leaf::result\n {\n if( <> )\n return valid_U;\n else\n return ei.error();\n } );\n----\n[.text-right]\n<> | <> | <> | <>\n\nAny error handler can take an argument of type `leaf::error_info const &` to get access to generic information about the error being handled; in this case we use the `error` member function, which returns the unique <> of the current error; we use it to initialize the returned `leaf::result`, effectively propagating the current error out of `try_handle_some`.\n\nTIP: If we wanted to signal a new error (rather than propagating the current error), in the `return` statement we would invoke the `leaf::new_error` function.\n\nIf we want to ensure that all possible failures are handled, we use `leaf::try_handle_all` instead of `leaf::try_handle_some`:\n\n[source,c++]\n----\nU r = leaf::try_handle_all(\n\n []() -> leaf::result\n {\n BOOST_LEAF_AUTO(v1, f1());\n BOOST_LEAF_AUTO(v2, f2());\n\n return g(v1. v2);\n },\n\n []( leaf::match ) -> U\n {\n // Handle err::e1\n },\n\n []( err1 e ) -> U\n {\n // Handle any other err1 value\n },\n\n []() -> U\n {\n // Handle any other failure\n } );\n----\n[.text-right]\n<>\n\nThe `leaf::try_handle_all` function enforces at compile time that at least one of the supplied error handlers takes no arguments (and therefore is able to handle any failure). In addition, all error handlers are forced to return a valid `U`, rather than a `leaf::result`, so that `leaf::try_handle_all` is guaranteed to succeed, always.\n\n'''\n\n=== Working with Different Error Types\n\nIt is of course possible to provide different handlers for different error types:\n\n[source,c++]\n----\nenum class err1 { e1, e2, e3 };\nenum class err2 { e1, e2 };\n\n....\n\nleaf::result r = leaf::try_handle_some(\n\n []() -> leaf::result\n {\n BOOST_LEAF_AUTO(v1, f1());\n BOOST_LEAF_AUTO(v2, f2());\n\n return g(v1, v2);\n },\n\n []( err1 e ) -> leaf::result\n {\n // Handle errors of type `err1`.\n },\n\n []( err2 e ) -> leaf::result\n {\n // Handle errors of type `err2`.\n } );\n----\n[.text-right]\n<> | <> | <>\n\nRecall that error handlers are always considered in order:\n\n* The first error handler will be used if an error object of type `err1` is available;\n* otherwise, the second error handler will be used if an error object of type `err2` is available;\n* otherwise, `leaf::try_handle_some` fails.\n\n'''\n\n=== Working with Multiple Error Objects\n\nThe `leaf::new_error` function can be invoked with multiple error objects, for example to communicate an error code and the relevant file name:\n\n[source,c++]\n----\nenum class io_error { open_error, read_error, write_error };\n\nstruct e_file_name { std::string value; }\n\nleaf::result open_file( char const * name )\n{\n ....\n if( open_failed )\n return leaf::new_error(io_error::open_error, e_file_name {name});\n ....\n}\n----\n[.text-right]\n<> | <>\n\nSimilarly, error handlers may take multiple error objects as arguments:\n\n[source,c++]\n----\nleaf::result r = leaf::try_handle_some(\n\n []() -> leaf::result\n {\n BOOST_LEAF_AUTO(f, open_file(fn));\n ....\n },\n\n []( io_error ec, e_file_name fn ) -> leaf::result\n {\n // Handle I/O errors when a file name is available.\n },\n\n []( io_error ec ) -> leaf::result\n {\n // Handle I/O errors when no file name is available.\n } );\n----\n[.text-right]\n<> | <> | <>\n\nOnce again, error handlers are considered in order:\n\n* The first error handler will be used if an error object of type `io_error` _and_ and error_object of type `e_file_name` are available;\n* otherwise, the second error handler will be used if an error object of type `io_error` is avaliable;\n* otherwise, `leaf_try_handle_some` fails.\n \nAn alternative way to write the above is to provide a single error handler that takes the `e_file_name` argument as a pointer:\n\n[source,c++]\n----\nleaf::result r = leaf::try_handle_some(\n\n []() -> leaf::result\n {\n BOOST_LEAF_AUTO(f, open_file(fn));\n ....\n },\n\n []( io_error ec, e_file_name const * fn ) -> leaf::result\n {\n if( fn )\n .... // Handle I/O errors when a file name is available.\n else\n .... // Handle I/O errors when no file name is available.\n } );\n----\n[.text-right]\n<> | <> | <>\n\nAn error handler is never dropped for lack of error objects of types which the handler takes as pointers; in this case LEAF simply passes `0` for these arguments.\n\nTIP: Error handlers can take arguments by value, by (`const`) reference or as a (`const`) pointer. It the latter case, changes to the error object state will be propagated up the call stack if the failure is not handled.\n\n[[tutorial-augmenting_errors]]\n=== Augmenting Errors\n\nLet's say we have a function `parse_line` which could fail due to an `io_error` or a `parse_error`:\n\n[source,c++]\n----\nenum class io_error { open_error, read_error, write_error };\n\nenum class parse_error { bad_syntax, bad_range };\n\nleaf::result parse_line( FILE * f );\n----\n\nThe `leaf::on_error` function can be used to automatically associate additional error objects with any failure that is \"in flight\":\n\n[source,c++]\n----\nstruct e_line { int value; };\n\nleaf::result process_file( FILE * f )\n{\n for( int current_line = 1; current_line != 10; ++current_line )\n {\n auto load = leaf::on_error( e_line {current_line} );\n\n BOOST_LEAF_AUTO(v, parse_line(f));\n\n // use v\n }\n}\n----\n[.text-right]\n<> | <>\n\nBecause `process_file` does not handle errors, it remains neutral to failures, except to attach the `current_line` if something goes wrong. The object returned by `on_error` holds a copy of the `current_line` wrapped in `struct e_line`. If `parse_line` succeeds, the `e_line` object is simply discarded; but if it fails, the `e_line` object will be automatically \"attached\" to the failure.\n\nSuch failures can then be handled like so:\n\n[source,c++]\n----\nleaf::result r = leaf::try_handle_some(\n\n [&]() -> leaf::result\n {\n BOOST_LEAF_CHECK( process_file(f) );\n },\n\n []( parse_error e, e_line current_line )\n {\n std::cerr << \"Parse error at line \" << current_line.value << std::endl;\n },\n\n []( io_error e, e_line current_line )\n {\n std::cerr << \"I/O error at line \" << current_line.value << std::endl;\n },\n\n []( io_error e )\n {\n std::cerr << \"I/O error\" << std::endl;\n } );\n----\n[.text-right]\n<> | <>\n\nThe following is equivalent, and perhaps simpler:\n\n[source,c++]\n----\nleaf::result r = leaf::try_handle_some(\n\n []() -> leaf::result\n {\n BOOST_LEAF_CHECK( process_file(f) );\n },\n\n []( parse_error e, e_line current_line )\n {\n std::cerr << \"Parse error at line \" << current_line.value << std::endl;\n },\n\n []( io_error e, e_line const * current_line )\n {\n std::cerr << \"Parse error\";\n if( current_line )\n std::cerr << \" at line \" << current_line->value;\n std::cerr << std::endl;\n } );\n----\n\n'''\n\n[[tutorial-exception_handling]]\n=== Exception Handling\n\nWhat happens if an operation throws an exception? Not to worry, both `try_handle_some` and `try_handle_all` catch exceptions and are able to pass them to any compatible error handler:\n\n[source,c++]\n----\nleaf::result r = leaf::try_handle_some(\n\n []() -> leaf::result\n {\n BOOST_LEAF_CHECK( process_file(f) );\n },\n\n []( std::bad_alloc const & )\n {\n std::cerr << \"Out of memory!\" << std::endl;\n },\n\n []( parse_error e, e_line l )\n {\n std::cerr << \"Parse error at line \" << l.value << std::endl;\n },\n\n []( io_error e, e_line const * l )\n {\n std::cerr << \"Parse error\";\n if( l )\n std::cerr << \" at line \" << l.value;\n std::cerr << std::endl;\n } );\n----\n[.text-right]\n<> | <> | <>\n\nAbove, we have simply added an error handler that takes a `std::bad_alloc`, and everything \"just works\" as expected: LEAF will dispatch error handlers correctly no matter if failures are communicated via `leaf::result` or by an exception.\n\nOf course, if we use exception handling exclusively, we do not need `leaf::result` at all. In this case we use `leaf::try_catch`:\n\n[source,c++]\n----\nleaf::try_catch(\n\n []\n {\n process_file(f);\n },\n\n []( std::bad_alloc const & )\n {\n std::cerr << \"Out of memory!\" << std::endl;\n },\n\n []( parse_error e, e_line l )\n {\n std::cerr << \"Parse error at line \" << l.value << std::endl;\n },\n\n []( io_error e, e_line const * l )\n {\n std::cerr << \"Parse error\";\n if( l )\n std::cerr << \" at line \" << l.value;\n std::cerr << std::endl;\n } );\n----\n[.text-right]\n<>\n\nRemarkably, we did not have to change the error handlers! But how does this work? What kind of exceptions does `process_file` throw?\n\nLEAF enables a novel technique of exception handling, which does not use an exception type hierarchy to classify failures and does not carry data in exception objects. Recall that when failures are communicated via `leaf::result`, we call `leaf::new_error` in a `return` statement, passing any number of error objects which are sent directly to the correct error handling scope:\n\n[source,c++]\n----\nenum class err1 { e1, e2, e3 };\nenum class err2 { e1, e2 };\n\n....\n\nleaf::result f()\n{\n ....\n if( error_detected )\n return leaf::new_error(err1::e1, err2::e2);\n\n // Produce and return a T.\n}\n----\n[.text-right]\n<> | <>\n\nWhen using exception handling this becomes:\n\n[source,c++]\n----\nenum class err1 { e1, e2, e3 };\nenum class err2 { e1, e2 };\n\nT f()\n{\n if( error_detected )\n leaf::throw_exception(err1::e1, err2::e2);\n\n // Produce and return a T.\n}\n----\n[.text-right]\n<>\n\nThe `leaf::throw_exception` function handles the passed error objects just like `leaf::new_error` does, and then throws an object of a type that derives from `std::exception`. Using this technique, the exception type is not important: `leaf::try_catch` catches all exceptions, then goes through the usual LEAF error handler selection procedure.\n\nIf instead we want to use the legacy convention of throwing different types to indicate different failures, we simply pass an exception object (that is, an object of a type that derives from `std::exception`) as the first argument to `leaf::throw_exception`:\n\n[source,c++]\n----\nleaf::throw_exception(std::runtime_error(\"Error!\"), err1::e1, err2::e2);\n----\n\nIn this case the returned object will be of type that derives from `std::runtime_error`, rather than from `std::exception`.\n\nFinally, `leaf::on_error` \"just works\" as well. Here is our `process_file` function rewritten to work with exceptions, rather than return a `leaf::result` (see <>):\n\n[source,c++]\n----\nint parse_line( FILE * f ); // Throws\n\nstruct e_line { int value; };\n\nvoid process_file( FILE * f )\n{\n for( int current_line = 1; current_line != 10; ++current_line )\n {\n auto load = leaf::on_error( e_line {current_line} );\n int v = parse_line(f);\n\n // use v\n }\n}\n----\n[.text-right]\n<>\n\n'''\n\n=== Using External `result` Types\n\nStatic type checking creates difficulties in error handling interoperability in any non-trivial project. Using exception handling alleviates this problem somewhat because in that case error types are not burned into function signatures, so errors easily punch through multiple layers of APIs; but this doesn't help {CPP} in general because the community is fractured on the issue of exception handling. That debate notwithstanding, the reality is that {CPP} programs need to handle errors communicated through multiple layers of APIs via a plethora of error codes, `result` types and exceptions.\n\nLEAF enables application developers to shake error objects out of each individual library's `result` type and send them to error handling scopes verbatim. Here is an example:\n\n[source,c++]\n----\nlib1::result foo();\nlib2::result bar();\n\nint g( int a, int b );\n\nleaf::result f()\n{\n auto a = foo();\n if( !a )\n return leaf::new_error( a.error() );\n\n auto b = bar();\n if( !b )\n return leaf::new_error( b.error() );\n\n return g( a.value(), b.value() );\n}\n----\n[.text-right]\n<> | <>\n\nLater we simply call `leaf::try_handle_some` passing an error handler for each type:\n\n[source,c++]\n----\nleaf::result r = leaf::try_handle_some(\n\n []() -> leaf::result\n {\n return f();\n },\n\n []( lib1::error_code ec ) -> leaf::result\n {\n // Handle lib1::error_code\n },\n\n []( lib2::error_code ec ) -> leaf::result\n {\n // Handle lib2::error_code\n } );\n}\n----\n[.text-right]\n<> | <>\n\nA possible complication is that we might not have the option to return `leaf::result` from `f`: a third party API may impose a specific signature on it, forcing it to return a library-specific `result` type. This would be the case when `f` is intended to be used as a callback:\n\n[source,c++]\n----\nvoid register_callback( std::function()> const & callback );\n----\n\nCan we use LEAF in this case? Actually we can, as long as `lib3::result` is able to communicate a `std::error_code`. We just have to let LEAF know, by specializing the `is_result_type` template:\n\n[source,c++]\n----\nnamespace boost { namespace leaf {\n\ntemplate \nstruct is_result_type>: std::true_type;\n\n} }\n----\n[.text-right]\n<>\n\nWith this in place, `f` works as before, even though `lib3::result` isn't capable of transporting `lib1` errors or `lib2` errors:\n\n[source,c++]\n----\nlib1::result foo();\nlib2::result bar();\n\nint g( int a, int b );\n\nlib3::result f()\n{\n auto a = foo();\n if( !a )\n return leaf::new_error( a.error() );\n\n auto b = bar();\n if( !b )\n return leaf::new_error( b.error() );\n\n return g( a.value(), b.value() );\n}\n----\n[.text-right]\n<>\n\nThe object returned by `leaf::new_error` converts implicitly to `std::error_code`, using a LEAF-specific `error_category`, which makes `lib3::result` compatible with `leaf::try_handle_some` (and with `leaf::try_handle_all`):\n\n[source,c++]\n----\nlib3::result r = leaf::try_handle_some(\n\n []() -> lib3::result\n {\n return f();\n },\n\n []( lib1::error_code ec ) -> lib3::result\n {\n // Handle lib1::error_code\n },\n\n []( lib2::error_code ec ) -> lib3::result\n {\n // Handle lib2::error_code\n } );\n}\n----\n[.text-right]\n<>\n\n'''\n\n[[tutorial-model]]\n=== Error Communication Model\n\n==== `noexcept` API\n\nThe following figure illustrates how error objects are transported when using LEAF without exception handling:\n\n.LEAF noexcept Error Communication Model\nimage::LEAF-1.png[]\n\nThe arrows pointing down indicate the call stack order for the functions `f1` through `f5`: higher level functions calling lower level functions.\n\nNote the call to `on_error` in `f3`: it caches the passed error objects of types `E1` and `E3` in the returned object `load`, where they stay ready to be communicated in case any function downstream from `f3` reports an error. Presumably these objects are relevant to any such failure, but are conveniently accessible only in this scope.\n\n_Figure 1_ depicts the condition where `f5` has detected an error. It calls `leaf::new_error` to create a new, unique `error_id`. The passed error object of type `E2` is immediately loaded in the first active `context` object that provides static storage for it, found in any calling scope (in this case `f1`), and is associated with the newly-generated `error_id` (solid arrow);\n\nThe `error_id` itself is returned to the immediate caller `f4`, usually stored in a `result` object `r`. That object takes the path shown by dashed arrows, as each error neutral function, unable to handle the failure, forwards it to its immediate caller in the returned value -- until an error handling scope is reached.\n\nWhen the destructor of the `load` object in `f3` executes, it detects that `new_error` was invoked after its initialization, loads the cached objects of types `E1` and `E3` in the first active `context` object that provides static storage for them, found in any calling scope (in this case `f1`), and associates them with the last generated `error_id` (solid arrow).\n\nWhen the error handling scope `f1` is reached, it probes `ctx` for any error objects associated with the `error_id` it received from `f2`, and processes a list of user-provided error handlers, in order, until it finds a handler with arguments that can be supplied using the available (in `ctx`) error objects. That handler is called to deal with the failure.\n\n==== Exception Handling API\n\nThe following figure illustrates the slightly different error communication model used when errors are reported by throwing exceptions:\n\n.LEAF Error Communication Model Using Exception Handling\nimage::LEAF-2.png[]\n\nThe main difference is that the call to `new_error` is implicit in the call to the function template `leaf::throw_exception`, which in this case takes an exception object of type `Ex`, and throws an exception object of unspecified type that derives publicly from `Ex`.\n\n[[tutorial-interoperability]]\n==== Interoperability\n\nIdeally, when an error is detected, a program using LEAF would always call <>, ensuring that each encountered failure is definitely assigned a unique <>, which then is reliably delivered, by an exception or by a `result` object, to the appropriate error handling scope.\n\nAlas, this is not always possible.\n\nFor example, the error may need to be communicated through uncooperative 3rd-party interfaces. To facilitate this transmission, a error ID may be encoded in a `std::error_code`. As long as a 3rd-party interface is able to transport a `std::error_code`, it should be compatible with LEAF.\n\nFurther, it is sometimes necessary to communicate errors through an interface that does not even use `std::error_code`. An example of this is when an external lower-level library throws an exception, which is unlikely to be able to carry an `error_id`.\n\nTo support this tricky use case, LEAF provides the function <>, which returns the error ID returned by the most recent call (from this thread) to <>. One possible approach to solving the problem is to use the following logic (implemented by the <> type):\n\n. Before calling the uncooperative API, call <> and cache the returned value.\n. Call the API, then call `current_error` again:\n.. If this returns the same value as before, pass the error objects to `new_error` to associate them with a new `error_id`;\n.. else, associate the error objects with the `error_id` value returned by the second call to `current_error`.\n\nNote that if the above logic is nested (e.g. one function calling another), `new_error` will be called only by the inner-most function, because that call guarantees that all calling functions will hit the `else` branch.\n\nFor a detailed tutorial see <>.\n\nTIP: To avoid ambiguities, whenever possible, use the <> function template to throw exceptions, to ensure that the exception object transports a unique `error_id`; better yet, use the <> macro, which in addition will capture `pass:[__FILE__]` and `pass:[__LINE__]`.\n\n'''\n\n[[tutorial-loading]]\n=== Loading of Error Objects\n\nTo load an error object is to move it into an active <>, usually local to a <>, a <> or a <> scope in the calling thread, where it becomes uniquely associated with a specific <> -- or discarded if storage is not available.\n\nVarious LEAF functions take a list of error objects to load. As an example, if a function `copy_file` that takes the name of the input file and the name of the output file as its arguments detects a failure, it could communicate an error code `ec`, plus the two relevant file names using <>:\n\n[source,c++]\n----\nreturn leaf::new_error(ec, e_input_name{n1}, e_output_name{n2});\n----\n\nAlternatively, error objects may be loaded using a `result` that is already communicating an error. This way they become associated with that error, rather than with a new error:\n\n[source,c++]\n----\nleaf::result f() noexcept;\n\nleaf::result g( char const * fn ) noexcept\n{\n if( leaf::result r = f() )\n { <1>\n ....;\n return { };\n }\n else\n {\n return r.load( e_file_name{fn} ); <2>\n }\n}\n----\n[.text-right]\n<> | <>\n\n<1> Success! Use `r.value()`.\n<2> `f()` has failed; here we associate an additional `e_file_name` with the error. However, this association occurs iff in the call stack leading to `g` there are error handlers that take an `e_file_name` argument. Otherwise, the object passed to `load` is discarded. In other words, the passed objects are loaded iff the program actually uses them to handle errors.\n\nBesides error objects, `load` can take function arguments:\n\n* If we pass a function that takes no arguments, it is invoked, and the returned error object is loaded.\n+\nConsider that if we pass to `load` an error object that is not needed by any error handler, it will be discarded. If the object is expensive to compute, it would be better if the computation can be skipped as well. Passing a function with no arguments to `load` is an excellent way to achieve this behavior:\n+\n[source,c++]\n----\nstruct info { .... };\n\ninfo compute_info() noexcept;\n\nleaf::result operation( char const * file_name ) noexcept\n{\n if( leaf::result r = try_something() )\n { <1>\n ....\n return { };\n }\n else\n {\n return r.load( <2>\n [&]\n {\n return compute_info();\n } );\n }\n}\n----\n[.text-right]\n<> | <>\n+\n<1> Success! Use `r.value()`.\n<2> `try_something` has failed; `compute_info` will only be called if an error handler exists which takes a `info` argument.\n+\n* If we pass a function that takes a single argument of type `E &`, LEAF calls the function with the object of type `E` currently loaded in an active `context`, associated with the error. If no such object is available, a new one is default-initialized and then passed to the function.\n+\nFor example, if an operation that involves many different files fails, a program may provide for collecting all relevant file names in a `e_relevant_file_names` object:\n+\n[source,c++]\n----\nstruct e_relevant_file_names\n{\n std::vector value;\n};\n\nleaf::result operation( char const * file_name ) noexcept\n{\n if( leaf::result r = try_something() )\n { <1>\n ....\n return { };\n }\n else\n {\n return r.load( <2>\n [&](e_relevant_file_names & e)\n {\n e.value.push_back(file_name);\n } );\n }\n}\n----\n[.text-right]\n<> | <>\n+\n<1> Success! Use `r.value()`.\n<2> `try_something` has failed -- add `file_name` to the `e_relevant_file_names` object, associated with the `error_id` communicated in `r`. Note, however, that the passed function will only be called iff in the call stack there are error handlers that take an `e_relevant_file_names` object.\n\n'''\n\n[[tutorial-on_error]]\n=== Using `on_error`\n\nIt is not typical for an error reporting function to be able to supply all of the data needed by a suitable error handling function in order to recover from the failure. For example, a function that reports `FILE` failures may not have access to the file name, yet an error handling function needs it in order to print a useful error message.\n\nOf course the file name is typically readily available in the call stack leading to the failed `FILE` operation. Below, while `parse_info` can't report the file name, `parse_file` can and does:\n\n[source,c++]\n----\nleaf::result parse_info( FILE * f ) noexcept; <1>\n\nleaf::result parse_file( char const * file_name ) noexcept\n{\n auto load = leaf::on_error(leaf::e_file_name{file_name}); <2>\n\n if( FILE * f = fopen(file_name,\"r\") )\n {\n auto r = parse_info(f);\n fclose(f);\n return r;\n }\n else\n return leaf::new_error( error_enum::file_open_error );\n}\n----\n\n[.text-right]\n<> | <> | <>\n\n<1> `parse_info` parses `f`, communicating errors using `result`.\n<2> Using `on_error` ensures that the file name is included with any error reported out of `parse_file`. All we need to do is hold on to the returned object `load`; when it expires, if an error is being reported, the passed `e_file_name` value will be automatically associated with it.\n\nTIP: `on_error` -- like `load` -- can be passed any number of arguments.\n\nWhen we invoke `on_error`, we can pass three kinds of arguments:\n\n. Actual error objects (like in the example above);\n. Functions that take no arguments and return an error object;\n. Functions that take an error object by mutable reference.\n\nIf we want to use `on_error` to capture `errno`, we can't just pass <> to it, because at that time it hasn't been set (yet). Instead, we'd pass a function that returns it:\n\n[source,c++]\n----\nvoid read_file(FILE * f) {\n\n auto load = leaf::on_error([]{ return e_errno{errno}; });\n\n ....\n size_t nr1=fread(buf1,1,count1,f);\n if( ferror(f) )\n leaf::throw_exception();\n\n size_t nr2=fread(buf2,1,count2,f);\n if( ferror(f) )\n leaf::throw_exception();\n\n size_t nr3=fread(buf3,1,count3,f);\n if( ferror(f) )\n leaf::throw_exception();\n ....\n}\n----\n\nAbove, if `throw_exception` is called, LEAF will invoke the function passed to `on_error` and associate the returned `e_errno` object with the exception.\n\nThe final argument type that can be passed to `on_error` is a function that takes a single mutable error object reference. In this case, `on_error` uses it similarly to how such functions are used by `load`; see <>.\n\n'''\n\n[[tutorial-predicates]]\n=== Using Predicates to Handle Errors\n\nUsually, LEAF error handlers are selected based on the type of the arguments they take and the type of the available error objects. When an error handler takes a predicate type as an argument, the <> is able to also take into account the _value_ of the available error objects.\n\nConsider this error code enum:\n\n[source,c++]\n----\nenum class my_error\n{\n e1=1,\n e2,\n e3\n};\n----\n\nWe could handle `my_error` errors like so:\n\n[source,c++]\n----\nreturn leaf::try_handle_some(\n\n []\n {\n return f(); // returns leaf::result\n },\n\n []( my_error e )\n { <1>\n switch(e)\n {\n case my_error::e1:\n ....; <2>\n break;\n case my_error::e2:\n case my_error::e3:\n ....; <3>\n break;\n default:\n ....; <4>\n break;\n } );\n----\n<1> This handler will be selected if we've got a `my_error` object.\n<2> Handle `e1` errors.\n<3> Handle `e2` and `e3` errors.\n<4> Handle bad `my_error` values.\n\nIf `my_error` object is available, LEAF will call our error handler. If not, the failure will be forwarded to our caller.\n\nThis can be rewritten using the <> predicate to organize the different cases in different error handlers. The following is equivalent:\n\n[source,c++]\n----\nreturn leaf::try_handle_some(\n\n []\n {\n return f(); // returns leaf::result\n },\n\n []( leaf::match m )\n { <1>\n assert(m.matched == my_error::e1);\n ....;\n },\n\n []( leaf::match m )\n { <2>\n assert(m.matched == my_error::e2 || m.matched == my_error::e3);\n ....;\n },\n\n []( my_error e )\n { <3>\n ....;\n } );\n----\n<1> We've got a `my_error` object that compares equal to `e1`.\n<2> We`ve got a `my_error` object that compares equal to either `e2` or `e3`.\n<3> Handle bad `my_error` values.\n\nThe first argument to the `match` template generally specifies the type `E` of the error object `e` that must be available for the error handler to be considered at all. Typically, the rest of the arguments are values. The error handler is dropped if `e` does not compare equal to any of them.\n\nIn particular, `match` works great with `std::error_code`. The following handler is designed to handle `ENOENT` errors:\n\n[source,c++]\n----\n[]( leaf::match )\n{\n}\n----\n\nThis, however, requires {CPP}17 or newer, because it is impossible to infer the type of the error enum (in this case, `std::errc`) from the specified type `std::error_code`, and {CPP}11 does not allow `auto` template arguments. LEAF provides the following workaround, compatible with {CPP}11:\n\n[source,c++]\n----\n[]( leaf::match, std::errc::no_such_file_or_directory> )\n{\n}\n----\n\nIn addition, it is possible to select a handler based on `std::error_category`. The following handler will match any `std::error_code` of the `std::generic_category` (requires {CPP}17 or newer):\n\n[source,c++]\n----\n[]( std::error_code, leaf::category> )\n{\n}\n----\n\nTIP: See <> for more examples.\n\nThe following predicates are available:\n\n* <>: as described above.\n* <>: where `match` compares the object `e` of type `E` with the values `V...`, `match_value` compare `e.value` with the values `V...`.\n* <>: similar to `match_value`, but takes a pointer to the data member to compare; that is, `match_member<&E::value, V...>` is equvialent to `match_value`. Note, however, that `match_member` requires {CPP}17 or newer, while `match_value` does not.\n* `<>`: Similar to `match`, but checks whether the caught `std::exception` object can be `dynamic_cast` to any of the `Ex` types.\n* <> is a special predicate that takes any other predicate `Pred` and requires that an error object of type `E` is available and that `Pred` evaluates to `false`. For example, `if_not>` requires that an object `e` of type `E` is available, and that it does not compare equal to any of the specified `V...`.\n\nFinally, the predicate system is easily extensible, see <>.\n\nNOTE: See also <>.\n\n'''\n\n[[tutorial-binding_handlers]]\n=== Binding Error Handlers in a `std::tuple`\n\nConsider this snippet:\n\n[source,c++]\n----\nleaf::try_handle_all(\n\n [&]\n {\n return f(); // returns leaf::result\n },\n\n [](my_error_enum x)\n {\n ...\n },\n\n [](read_file_error_enum y, e_file_name const & fn)\n {\n ...\n },\n\n []\n {\n ...\n });\n----\n\n[.text-right]\n<> | <>\n\nLooks pretty simple, but what if we need to attempt a different set of operations yet use the same handlers? We could repeat the same thing with a different function passed as `TryBlock` for `try_handle_all`:\n\n[source,c++]\n----\nleaf::try_handle_all(\n\n [&]\n {\n return g(); // returns leaf::result\n },\n\n [](my_error_enum x)\n {\n ...\n },\n\n [](read_file_error_enum y, e_file_name const & fn)\n {\n ...\n },\n\n []\n {\n ...\n });\n----\n\nThat works, but it is better to bind our error handlers in a `std::tuple`:\n\n[source,c++]\n----\nauto error_handlers = std::make_tuple(\n\n [](my_error_enum x)\n {\n ...\n },\n\n [](read_file_error_enum y, e_file_name const & fn)\n {\n ...\n },\n\n []\n {\n ...\n });\n----\n\nThe `error_handlers` tuple can later be used with any error handling function:\n\n[source,c++]\n----\nleaf::try_handle_all(\n\n [&]\n {\n // Operations which may fail <1>\n },\n\n error_handlers );\n\nleaf::try_handle_all(\n\n [&]\n {\n // Different operations which may fail <2>\n },\n\n error_handlers ); <3>\n----\n[.text-right]\n<> | <>\n\n<1> One set of operations which may fail...\n<2> A different set of operations which may fail...\n<3> ... both using the same `error_handlers`.\n\nError handling functions accept a `std::tuple` of error handlers in place of any error handler. The behavior is as if the tuple is unwrapped in-place.\n\n'''\n\n[[tutorial-async]]\n=== Transporting Error Objects Between Threads\n\nError objects are stored on the stack in an instance of the <> class template in the scope of e.g. <>, <> or <> functions. When using concurrency, we need a mechanism to collect error objects in one thread, then use them to handle errors in another thread.\n\nLEAF offers two interfaces for this purpose, one using `result`, and another designed for programs that use exception handling.\n\n[[tutorial-async_result]]\n==== Using `result`\n\nLet's assume we have a `task` that we want to launch asynchronously, which produces a `task_result` but could also fail:\n\n[source,c++]\n----\nleaf::result task();\n----\n\nBecause the task will run asynchronously, in case of a failure we need it to capture the relevant error objects but not handle errors. To this end, in the main thread we bind our error handlers in a `std::tuple`, which we will later use to handle errors from each completed asynchronous task (see <>):\n\n[source,c++]\n----\nauto error_handlers = std::make_tuple(\n\n [](E1 e1, E2 e2)\n {\n //Deal with E1, E2\n ....\n return { };\n },\n\n [](E3 e3)\n {\n //Deal with E3\n ....\n return { };\n } );\n----\n\nWhy did we start with this step? Because we need to create a <> object to collect the error objects we need. We could just instantiate the `context` template with `E1`, `E2` and `E3`, but that would be prone to errors, since it could get out of sync with the handlers we use. Thankfully LEAF can deduce the types we need automatically, we just need to show it our `error_handlers`:\n\n[source,c++]\n----\nstd::shared_ptr ctx = leaf::make_shared_context(error_handlers);\n----\n\nThe `polymorphic_context` type is an abstract base class that has the same members as any instance of the `context` class template, allowing us to erase its exact type. In this case what we're holding in `ctx` is a `context`, where `E1`, `E2` and `E3` were deduced automatically from the `error_handlers` tuple we passed to `make_shared_context`.\n\nWe're now ready to launch our asynchronous task:\n\n[source,c++]\n----\nstd::future> launch_task() noexcept\n{\n return std::async(\n std::launch::async,\n [&]\n {\n std::shared_ptr ctx = leaf::make_shared_context(error_handlers);\n return leaf::capture(ctx, &task);\n } );\n}\n----\n\n[.text-right]\n<> | <> | <>\n\nThat's it! Later when we `get` the `std::future`, we can process the returned `result` in a call to <>, using the `error_handlers` tuple we created earlier:\n\n[source,c++]\n----\n//std::future> fut;\nfut.wait();\n\nreturn leaf::try_handle_some(\n\n [&]() -> leaf::result\n {\n BOOST_LEAF_AUTO(r, fut.get());\n //Success!\n return { }\n },\n\n error_handlers );\n----\n\n[.text-right]\n<> | <> | <>\n\nThe reason this works is that in case the `leaf::result` communicates a failure, it is able to hold a `shared_ptr` object. That is why earlier instead of calling `task()` directly, we called `leaf::capture`: it calls the passed function and, in case that fails, it stores the `shared_ptr` we created in the returned `result`, which now doesn't just communicate the fact that an error has occurred, but also holds the `context` object that `try_handle_some` needs in order to supply a suitable handler with arguments.\n\nNOTE: Follow this link to see a complete example program: https://github.com/boostorg/leaf/blob/master/example/capture_in_result.cpp?ts=4[capture_in_result.cpp].\n\n[[tutorial-async_eh]]\n==== Using Exception Handling\n\nLet's assume we have an asynchronous `task` which produces a `task_result` but could also throw:\n\n[source,c++]\n----\ntask_result task();\n----\n\nJust like we saw in <>, first we will bind our error handlers in a `std::tuple`:\n\n[source,c++]\n----\nauto handle_errors = std::make_tuple(\n\n [](E1 e1, E2 e2)\n {\n //Deal with E1, E2\n ....\n return { };\n },\n\n [](E3 e3)\n {\n //Deal with E3\n ....\n return { };\n } );\n----\n\nLaunching the task looks the same as before, except that we don't use `result`:\n\n[source,c++]\n----\nstd::future launch_task()\n{\n return std::async(\n std::launch::async,\n [&]\n {\n std::shared_ptr ctx = leaf::make_shared_context(&handle_error);\n return leaf::capture(ctx, &task);\n } );\n}\n----\n\n[.text-right]\n<> | <>\n\nThat's it! Later when we `get` the `std::future`, we can process the returned `task_result` in a call to <>, using the `error_handlers` we saved earlier, as if it was generated locally:\n\n[source,c++]\n----\n//std::future fut;\nfut.wait();\n\nreturn leaf::try_catch(\n\n [&]\n {\n task_result r = fut.get(); // Throws on error\n //Success!\n },\n\n error_handlers );\n----\n\n[.text-right]\n<>\n\nThis works similarly to using `result`, except that the `std::shared_ptr` is transported in an exception object (of unspecified type which <> recognizes and then automatically unwraps the original exception).\n\nNOTE: Follow this link to see a complete example program: https://github.com/boostorg/leaf/blob/master/example/capture_in_exception.cpp?ts=4[capture_in_exception.cpp].\n\n'''\n\n[[tutorial-classification]]\n=== Classification of Failures\n\nIt is common for an interface to define an `enum` that lists all possible error codes that the API reports. The benefit of this approach is that the list is complete and usually well documented:\n\n[source,c++]\n----\nenum error_code\n{\n ....\n read_error,\n size_error,\n eof_error,\n ....\n};\n----\n\nThe disadvantage of such flat enums is that they do not support handling of a whole class of failures. Consider the following LEAF error handler:\n\n[source,c++]\n----\n....\n[](leaf::match, leaf::e_file_name const & fn)\n{\n std::cerr << \"Failed to access \" << fn.value << std::endl;\n},\n....\n----\n[.text-right]\n<> | <>\n\nIt will get called if the value of the `error_code` enum communicated with the failure is one of `size_error`, `read_error` or `eof_error`. In short, the idea is to handle any input error.\n\nBut what if later we add support for detecting and reporting a new type of input error, e.g. `permissions_error`? It is easy to add that to our `error_code` enum; but now our input error handler won't recognize this new input error -- and we have a bug.\n\nIf we can use exceptions, the situation is better because exception types can be organized in a hierarchy in order to classify failures:\n\n[source,c++]\n----\nstruct input_error: std::exception { };\nstruct read_error: input_error { };\nstruct size_error: input_error { };\nstruct eof_error: input_error { };\n----\n\nIn terms of LEAF, our input error exception handler now looks like this:\n\n[source,c++]\n----\n[](input_error &, leaf::e_file_name const & fn)\n{\n std::cerr << \"Failed to access \" << fn.value << std::endl;\n},\n----\n\nThis is future-proof, but still not ideal, because it is not possible to refine the classification of the failure after the exception object has been thrown.\n\nLEAF supports a novel style of error handling where the classification of failures does not use error code values or exception type hierarchies. Instead of our `error_code` enum, we could define:\n\n[source,c++]\n----\n....\nstruct input_error { };\nstruct read_error { };\nstruct size_error { };\nstruct eof_error { };\n....\n----\n\nWith this in place, we could define a function `file_read`:\n\n[source,c++]\n----\nleaf::result file_read( FILE & f, void * buf, int size )\n{\n int n = fread(buf, 1, size, &f);\n\n if( ferror(&f) )\n return leaf::new_error(input_error{}, read_error{}, leaf::e_errno{errno}); <1>\n\n if( n!=size )\n return leaf::new_error(input_error{}, eof_error{}); <2>\n\n return { };\n}\n----\n[.text-right]\n<> | <> | <>\n\n<1> This error is classified as `input_error` and `read_error`.\n<2> This error is classified as `input_error` and `eof_error`.\n\nOr, even better:\n\n[source,c++]\n----\nleaf::result file_read( FILE & f, void * buf, int size )\n{\n auto load = leaf::on_error(input_error{}); <1>\n\n int n = fread(buf, 1, size, &f);\n\n if( ferror(&f) )\n return leaf::new_error(read_error{}, leaf::e_errno{errno}); <2>\n\n if( n!=size )\n return leaf::new_error(eof_error{}); <3>\n\n return { };\n}\n----\n[.text-right]\n<> | <> | <> | <>\n\n<1> Any error escaping this scope will be classified as `input_error`\n<2> In addition, this error is classified as `read_error`.\n<3> In addition, this error is classified as `eof_error`.\n\nThis technique works just as well if we choose to use exception handling, we just call `leaf::throw_exception` instead of `leaf::new_error`:\n\n[source,c++]\n----\nvoid file_read( FILE & f, void * buf, int size )\n{\n auto load = leaf::on_error(input_error{});\n\n int n = fread(buf, 1, size, &f);\n\n if( ferror(&f) )\n leaf::throw_exception(read_error{}, leaf::e_errno{errno});\n\n if( n!=size )\n leaf::throw_exception(eof_error{});\n}\n----\n[.text-right]\n<> | <> | <>\n\nNOTE: If the type of the first argument passed to `leaf::throw_exception` derives from `std::exception`, it will be used to initialize the thrown exception object. Here this is not the case, so the function returns a default-initialized `std::exception` object, while the first (and any other) argument is associated with the failure.\n\nNow we can write a future-proof handler for any `input_error`:\n\n[source,c++]\n----\n....\n[](input_error, leaf::e_file_name const & fn)\n{\n std::cerr << \"Failed to access \" << fn.value << std::endl;\n},\n....\n----\n\nRemarkably, because the classification of the failure does not depend on error codes or on exception types, this error handler can be used with `try_catch` if we use exception handling, or with `try_handle_some`/`try_handle_all` if we do not.\n\n'''\n\n[[tutorial-exception_to_result]]\n=== Converting Exceptions to `result`\n\nIt is sometimes necessary to catch exceptions thrown by a lower-level library function, and report the error through different means, to a higher-level library which may not use exception handling.\n\nTIP: Error handlers that take arguments of types that derive from `std::exception` work correctly -- regardless of whether the error object itself is thrown as an exception, or <> into a <>. The technique described here is only needed when the exception must be communicated through functions which are not exception-safe, or are compiled with exception handling disabled.\n\nSuppose we have an exception type hierarchy and a function `compute_answer_throws`:\n\n[source,c++]\n----\nclass error_base: public std::exception { };\nclass error_a: public error_base { };\nclass error_b: public error_base { };\nclass error_c: public error_base { };\n\nint compute_answer_throws()\n{\n switch( rand()%4 )\n {\n default: return 42;\n case 1: throw error_a();\n case 2: throw error_b();\n case 3: throw error_c();\n }\n}\n----\n\nWe can write a simple wrapper using `exception_to_result`, which calls `compute_answer_throws` and switches to `result` for error handling:\n\n[source,c++]\n----\nleaf::result compute_answer() noexcept\n{\n return leaf::exception_to_result(\n []\n {\n return compute_answer_throws();\n } );\n}\n----\n\n[.text-right]\n<> | <>\n\nThe `exception_to_result` template takes any number of exception types. All exception types thrown by the passed function are caught, and an attempt is made to convert the exception object to each of the specified types. Each successfully-converted slice of the caught exception object, as well as the return value of `std::current_exception`, are copied and <>, and in the end the exception is converted to a `<>` object.\n\n(In our example, `error_a` and `error_b` slices as communicated as error objects, but `error_c` exceptions will still be captured by `std::exception_ptr`).\n\nHere is a simple function which prints successfully computed answers, forwarding any error (originally reported by throwing an exception) to its caller:\n\n[source,c++]\n----\nleaf::result print_answer() noexcept\n{\n BOOST_LEAF_AUTO(answer, compute_answer());\n std::cout << \"Answer: \" << answer << std::endl;\n return { };\n}\n----\n\n[.text-right]\n<> | <>\n\nFinally, here is a scope that handles the errors -- it will work correctly regardless of whether `error_a` and `error_b` objects are thrown as exceptions or not.\n\n[source,c++]\n----\nleaf::try_handle_all(\n\n []() -> leaf::result\n {\n BOOST_LEAF_CHECK(print_answer());\n return { };\n },\n\n [](error_a const & e)\n {\n std::cerr << \"Error A!\" << std::endl;\n },\n\n [](error_b const & e)\n {\n std::cerr << \"Error B!\" << std::endl;\n },\n\n []\n {\n std::cerr << \"Unknown error!\" << std::endl;\n } );\n----\n\n[.text-right]\n<> | <> | <>\n\nNOTE: The complete program illustrating this technique is available https://github.com/boostorg/leaf/blob/master/example/exception_to_result.cpp?ts=4[here].\n\n'''\n\n[[tutorial-on_error_in_c_callbacks]]\n=== Using `error_monitor` to Report Arbitrary Errors from C-callbacks\n\nCommunicating information pertaining to a failure detected in a C callback is tricky, because C callbacks are limited to a specific static signature, which may not use {CPP} types.\n\nLEAF makes this easy. As an example, we'll write a program that uses Lua and reports a failure from a {CPP} function registered as a C callback, called from a Lua program. The failure will be propagated from {CPP}, through the Lua interpreter (written in C), back to the {CPP} function which called it.\n\nC/{CPP} functions designed to be invoked from a Lua program must use the following signature:\n\n[source,c]\n----\nint do_work( lua_State * L ) ;\n----\n\nArguments are passed on the Lua stack (which is accessible through `L`). Results too are pushed onto the Lua stack.\n\nFirst, let's initialize the Lua interpreter and register a function, `do_work`, as a C callback available for Lua programs to call:\n\n[source,c++]\n----\nstd::shared_ptr init_lua_state() noexcept\n{\n std::shared_ptr L(lua_open(), &lua_close); //<1>\n\n lua_register(&*L, \"do_work\", &do_work); //<2>\n\n luaL_dostring(&*L, \"\\ //<3>\n\\n function call_do_work()\\\n\\n return do_work()\\\n\\n end\");\n\n return L;\n}\n----\n<1> Create a new `lua_State`. We'll use `std::shared_ptr` for automatic cleanup.\n<2> Register the `do_work` {CPP} function as a C callback, under the global name `do_work`. With this, calls from Lua programs to `do_work` will land in the `do_work` {CPP} function.\n<3> Pass some Lua code as a `C` string literal to Lua. This creates a global Lua function called `call_do_work`, which we will later ask Lua to execute.\n\nNext, let's define our `enum` used to communicate `do_work` failures:\n\n[source,c++]\n----\nenum do_work_error_code\n{\n ec1=1,\n ec2\n};\n----\n\nWe're now ready to define the `do_work` callback function:\n\n[source,c++]\n----\nint do_work( lua_State * L ) noexcept\n{\n bool success = rand() % 2; <1>\n if( success )\n {\n lua_pushnumber(L, 42); <2>\n return 1;\n }\n else\n {\n (void) leaf::new_error(ec1); <3>\n return luaL_error(L, \"do_work_error\"); <4>\n }\n}\n----\n[.text-right]\n<> | <>\n\n<1> \"Sometimes\" `do_work` fails.\n<2> In case of success, push the result on the Lua stack, return back to Lua.\n<3> Generate a new `error_id` and associate a `do_work_error_code` with it. Normally, we'd return this in a `leaf::result`, but the `do_work` function signature (required by Lua) does not permit this.\n<4> Tell the Lua interpreter to abort the Lua program.\n\nNow we'll write the function that calls the Lua interpreter to execute the Lua function `call_do_work`, which in turn calls `do_work`. We'll return `<>`, so that our caller can get the answer in case of success, or an error:\n\n[source,c++]\n----\nleaf::result call_lua( lua_State * L )\n{\n lua_getfield(L, LUA_GLOBALSINDEX, \"call_do_work\");\n\n error_monitor cur_err;\n if( int err = lua_pcall(L, 0, 1, 0) ) <1>\n {\n auto load = leaf::on_error(e_lua_error_message{lua_tostring(L,1)}); <2>\n lua_pop(L,1);\n\n return cur_err.assigned_error_id().load(e_lua_pcall_error{err}); <3>\n }\n else\n {\n int answer = lua_tonumber(L, -1); <4>\n lua_pop(L, 1);\n return answer;\n }\n}\n----\n[.text-right]\n<> | <> | <>\n\n<1> Ask the Lua interpreter to call the global Lua function `call_do_work`.\n<2> `on_error` works as usual.\n<3> `load` will use the `error_id` generated in our Lua callback. This is the same `error_id` the `on_error` uses as well.\n<4> Success! Just return the `int` answer.\n\nFinally, here is the `main` function which exercises `call_lua`, each time handling any failure:\n\n[source,c++]\n----\nint main() noexcept\n{\n std::shared_ptr L=init_lua_state();\n\n for( int i=0; i!=10; ++i )\n {\n leaf::try_handle_all(\n\n [&]() -> leaf::result\n {\n BOOST_LEAF_AUTO(answer, call_lua(&*L));\n std::cout << \"do_work succeeded, answer=\" << answer << '\\n'; <1>\n return { };\n },\n\n [](do_work_error_code e) <2>\n {\n std::cout << \"Got do_work_error_code = \" << e << \"!\\n\";\n },\n\n [](e_lua_pcall_error const & err, e_lua_error_message const & msg) <3>\n {\n std::cout << \"Got e_lua_pcall_error, Lua error code = \" << err.value << \", \" << msg.value << \"\\n\";\n },\n\n [](leaf::error_info const & unmatched)\n {\n std::cerr <<\n \"Unknown failure detected\" << std::endl <<\n \"Cryptic diagnostic information follows\" << std::endl <<\n unmatched;\n } );\n }\n----\n[.text-right]\n<> | <> | <> | <>\n\n<1> If the call to `call_lua` succeeded, just print the answer.\n<2> Handle `do_work` failures.\n<3> Handle all other `lua_pcall` failures.\n\nNOTE: Follow this link to see the complete program: https://github.com/boostorg/leaf/blob/master/example/lua_callback_result.cpp?ts=4[lua_callback_result.cpp].\n\nTIP: When using Lua with {CPP}, we need to protect the Lua interpreter from exceptions that may be thrown from {CPP} functions installed as `lua_CFunction` callbacks. Here is the program from this section rewritten to use a {CPP} exception to safely communicate errors out of the `do_work` function: https://github.com/boostorg/leaf/blob/master/example/lua_callback_eh.cpp?ts=4[lua_callback_eh.cpp].\n\n''''\n\n[[tutorial-diagnostic_information]]\n=== Diagnostic Information\n\nLEAF is able to automatically generate diagnostic messages that include information about all error objects available to error handlers:\n\n[source,c++]\n----\nenum class error_code\n{\n read_error,\n write_error\n};\n\n....\n\nleaf::try_handle_all(\n\n []() -> leaf::result <1>\n {\n ...\n return leaf::new_error( error_code::write_error, leaf::e_file_name{ \"file.txt\" } );\n },\n\n []( leaf::match ) <2>\n {\n std::cerr << \"Read error!\" << std::endl;\n },\n\n []( leaf::verbose_diagnostic_info const & info ) <3>\n {\n std::cerr << \"Unrecognized error detected, cryptic diagnostic information follows.\\n\" << info;\n } );\n----\n<1> We handle all failures that occur in this try block.\n<2> One or more error handlers that should handle all possible failures.\n<3> The \"catch all\" error handler is required by `try_handle_all`. It will be called if LEAF is unable to use another error handler.\n\nThe `verbose_diagnostic_info` output for the snippet above tells us that we got an `error_code` with value `1` (`write_error`), and an object of type `e_file_name` with `\"file.txt\"` stored in its `.value`:\n\n----\nUnrecognized error detected, cryptic diagnostic information follows.\nleaf::verbose_diagnostic_info for Error ID = 1:\n[with Name = error_code]: 1\nUnhandled error objects:\n[with Name = boost::leaf::e_file_name]: file.txt\n----\n\nTo print each error object, LEAF attempts to bind an unqualified call to `operator<<`, passing a `std::ostream` and the error object. If that fails, it will also attempt to bind `operator<<` that takes the `.value` of the error type. If that also does not compile, the error object value will not appear in diagnostic messages, though LEAF will still print its type.\n\nEven with error types that define a printable `.value`, the user may still want to overload `operator<<` for the enclosing `struct`, e.g.:\n\n[source,c++]\n----\nstruct e_errno\n{\n int value;\n\n friend std::ostream & operator<<( std::ostream & os, e_errno const & e )\n {\n return os << \"errno = \" << e.value << \", \\\"\" << strerror(e.value) << '\"';\n }\n};\n----\n\nThe `e_errno` type above is designed to hold `errno` values. The defined `operator<<` overload will automatically include the output from `strerror` when `e_errno` values are printed (LEAF defines `e_errno` in ``, together with other commonly-used error types).\n\nUsing `verbose_diagnostic_info` comes at a cost. Normally, when the program attempts to communicate error objects of types which are not used in any error handling scope in the current call stack, they are discarded, which saves cycles. However, if an error handler is provided that takes `verbose_diagnostic_info` argument, before such objects are discarded, they are printed and appended to a `std::string` (this is the case with `e_file_name` in our example above). Such objects appear under `Unhandled error objects` in the output from `verbose_diagnostic_info`.\n\nIf handling `verbose_diagnostic_info` is considered too costly, use `diagnostic_info` instead:\n\n[source,c++]\n----\nleaf::try_handle_all(\n\n []() -> leaf::result\n {\n ...\n return leaf::new_error( error_code::write_error, leaf::e_file_name{ \"file.txt\" } );\n },\n\n []( leaf::match )\n {\n std::cerr << \"Read error!\" << std::endl;\n },\n\n []( leaf::diagnostic_info const & info )\n {\n std::cerr << \"Unrecognized error detected, cryptic diagnostic information follows.\\n\" << info;\n } );\n----\n\nIn this case, the output may look like this:\n\n----\nUnrecognized error detected, cryptic diagnostic information follows.\nleaf::diagnostic_info for Error ID = 1:\n[with Name = error_code]: 1\nDetected 1 attempt to communicate an unexpected error object of type [with Name = boost::leaf::e_file_name]\n----\n\nNotice how the diagnostic information for `e_file_name` changed: LEAF no longer prints it before discarding it, and so `diagnostic_info` can only inform about the type of the discarded object, but not its value.\n\nTIP: The automatically-generated diagnostic messages are developer-friendly, but not user-friendly. Therefore, `operator<<` overloads for error types should only print technical information in English, and should not attempt to localize strings or to format a user-friendly message; this should be done in error handling functions specifically designed for that purpose.\n\n'''\n\n[[tutorial-std_error_code]]\n=== Working with `std::error_code`, `std::error_condition`\n\n==== Introduction\n\nThe relationship between `std::error_code` and `std::error_condition` is not easily understood from reading the standard specifications. This section explains how they're supposed to be used, and how LEAF interacts with them.\n\nThe idea behind `std::error_code` is to encode both an integer value representing an error code, as well as the domain of that value. The domain is represented by a `std::error_category` [underline]#reference#. Conceptually, a `std::error_code` is like a `pair`.\n\nLet's say we have this `enum`:\n\n[source,c++]\n----\nenum class libfoo_error\n{\n e1 = 1,\n e2,\n e3\n};\n----\n\nWe want to be able to transport `libfoo_error` values in `std::error_code` objects. This erases their static type, which enables them to travel freely across API boundaries. To this end, we must define a `std::error_category` that represents our `libfoo_error` type:\n\n[source,c++]\n----\nstd::error_category const & libfoo_error_category()\n{\n struct category: std::error_category\n {\n char const * name() const noexcept override\n {\n return \"libfoo\";\n }\n\n std::string message(int code) const override\n {\n switch( libfoo_error(code) )\n {\n case libfoo_error::e1: return \"e1\";\n case libfoo_error::e2: return \"e2\";\n case libfoo_error::e3: return \"e3\";\n default: return \"error\";\n }\n }\n };\n\n static category c;\n return c;\n}\n----\n\nWe also need to inform the standard library that `libfoo_error` is compatible with `std::error_code`, and provide a factory function which can be used to make `std::error_code` objects out of `libfoo_error` values:\n\n[source,c++]\n----\nnamespace std\n{\n template <>\n struct is_error_code_enum: std::true_type\n {\n };\n}\n\nstd::error_code make_error_code(libfoo_error e)\n{\n return std::error_code(int(e), libfoo_error_category());\n}\n----\n\nWith this in place, if we receive a `std::error_code`, we can easily check if it represents some of the `libfoo_error` values we're interested in:\n\n[source,c++]\n----\nstd::error_code f();\n\n....\nauto ec = f();\nif( ec == libfoo_error::e1 || ec == libfoo_error::e2 )\n{\n // We got either a libfoo_error::e1 or a libfoo_error::e2\n}\n----\n\nThis works because the standard library detects that `std::is_error_code_enum::value` is `true`, and then uses `make_error_code` to create a `std::error_code` object it actually uses to compare to `ec`.\n\nSo far so good, but remember, the standard library defines another type also, `std::error_condition`. The first confusing thing is that in terms of its physical representation, `std::error_condition` is identical to `std::error_code`; that is, it is also like a pair of `std::error_category` reference and an `int`. Why do we need two different types which use identical physical representation?\n\nThe key to answering this question is to understand that `std::error_code` objects are designed to be returned from functions to indicate failures. In contrast, `std::error_condition` objects are [underline]#never# supposed to be communicated; their purpose is to interpret the `std::error_code` values being communicated. The idea is that in a given program there may be multiple different \"physical\" (maybe platform-specific) `std::error_code` values which all indicate the same \"logical\" `std::error_condition`.\n\nThis leads us to the second confusing thing about `std::error_condition`: it uses the same `std::error_category` type, but for a completely different purpose: to specify what `std::error_code` values are equivalent to what `std::error_condition` values.\n\nLet's say that in addition to `libfoo`, our program uses another library, `libbar`, which communicates failures in terms of `std::error_code` with a different error category. Perhaps `libbar_error` looks like this:\n\n[source,c++]\n----\nenum class libbar_error\n{\n e1 = 1,\n e2,\n e3,\n e4\n};\n\n// Boilerplate omitted:\n// - libbar_error_category()\n// - specialization of std::is_error_code_enum\n// - make_error_code factory function for libbar_error.\n----\n\nWe can now use `std::error_condition` to define the _logical_ error conditions represented by the `std::error_code` values communicated by `libfoo` and `libbar`:\n\n[source,c++]\n----\nenum class my_error_condition <1>\n{\n c1 = 1,\n c2\n};\n\nstd::error_category const & libfoo_error_category() <2>\n{\n struct category: std::error_category\n {\n char const * name() const noexcept override\n {\n return \"my_error_condition\";\n }\n\n std::string message(int cond) const override\n {\n switch( my_error_condition(code) )\n {\n case my_error_condition::c1: return \"c1\";\n case my_error_condition::c2: return \"c2\";\n default: return \"error\";\n }\n }\n\n bool equivalent(std::error_code const & code, int cond) const noexcept\n {\n switch( my_error_condition(cond) )\n {\n case my_error_condition::c1: <3>\n return\n code == libfoo_error::e1 ||\n code == libbar_error::e3 ||\n code == libbar_error::e4;\n case my_error_condition::c2: <4>\n return\n code == libfoo_error::e2 ||\n code == libbar_error::e1 ||\n code == libbar_error::e2;\n default:\n return false;\n }\n }\n };\n\n static category c;\n return c;\n}\n\nnamespace std\n{\n template <> <5>\n class is_error_condition_enum: std::true_type\n {\n };\n}\n\nstd::error_condition make_error_condition(my_error_condition e) <6>\n{\n return std::error_condition(int(e), my_error_condition_error_category());\n}\n----\n<1> Enumeration of the two logical error conditions, `c1` and `c2`.\n<2> Define the `std::error_category` for `std::error_condition` objects that represent a `my_error_condition`.\n<3> Here we specify that any of `libfoo:error::e1`, `libbar_error::e3` and `libbar_error::e4` are logically equivalent to `my_error_condition::c1`, and that...\n<4> ...any of `libfoo:error::e2`, `libbar_error::e1` and `libbar_error::e2` are logically equivalent to `my_error_condition::c2`.\n<5> This specialization tells the standard library that the `my_error_condition` enum is designed to be used with `std::error_condition`.\n<6> The factory function to make `std::error_condition` objects out of `my_error_condition` values.\n\nPhew!\n\nNow, if we have a `std::error_code` object `ec`, we can easily check if it is equivalent to `my_error_condition::c1` like so:\n\n[source,c++]\n----\nif( ec == my_error_condition::c1 )\n{\n // We have a c1 in our hands\n}\n----\n\nAgain, remember that beyond defining the `std::error_category` for `std::error_condition` objects initialized with a `my_error_condition` value, we don't need to interact with the actual `std::error_condition` instances: they're created when needed to compare to a `std::error_code`, and that's pretty much all they're good for.\n\n==== Support in LEAF\n\nThe `match` predicate can be used as an argument to a LEAF error handler to match a `std::error_code` with a given error condition. For example, to handle `my_error_condition::c1` (see above), we could use:\n\n[source,c++]\n----\nleaf::try_handle_some(\n\n []\n {\n return f(); // returns leaf::result\n },\n\n []( leaf::match m )\n {\n assert(m.matched == my_error_condition::c1);\n ....\n } );\n----\n\nSee <> for more examples.\n\n'''\n\n[[tutorial-boost_exception_integration]]\n=== Boost Exception Integration\n\nInstead of the https://www.boost.org/doc/libs/release/libs/exception/doc/get_error_info.html[`boost::get_error_info`] API defined by Boost Exception, it is possible to use LEAF error handlers directly. Consider the following use of `boost::get_error_info`:\n\n[source,c++]\n----\ntypedef boost::error_info my_info;\n\nvoid f(); // Throws using boost::throw_exception\n\nvoid g()\n{\n try\n {\n f();\n },\n catch( boost::exception & e )\n {\n if( int const * x = boost::get_error_info(e) )\n std::cerr << \"Got my_info with value = \" << *x;\n } );\n}\n----\n\nWe can rewrite `g` to access `my_info` using LEAF:\n\n[source,c++]\n----\n#include \n\nvoid g()\n{\n leaf::try_catch(\n\n []\n {\n f();\n },\n\n []( my_info x )\n {\n std::cerr << \"Got my_info with value = \" << x.value();\n } );\n}\n----\n[.text-right]\n<>\n\nTaking `my_info` means that the handler will only be selected if the caught exception object carries `my_info` (which LEAF accesses via `boost::get_error_info`).\n\nThe use of <> is also supported:\n\n[source,c++]\n----\nvoid g()\n{\n leaf::try_catch(\n\n []\n {\n f();\n },\n\n []( leaf::match_value )\n {\n std::cerr << \"Got my_info with value = 42\";\n } );\n}\n----\n\nAbove, the handler will be selected if the caught exception object carries `my_info` with `.value()` equal to 42.\n\n[[example]]\n== Examples\n\nSee https://github.com/boostorg/leaf/tree/master/example[github].\n\n[[synopsis]]\n== Synopsis\n\nThis section lists each public header file in LEAF, documenting the definitions it provides.\n\nLEAF headers are designed to minimize coupling:\n\n* Headers needed to report or forward but not handle errors are lighter than headers providing error handling functionality.\n* Headers that provide exception handling or throwing functionality are separate from headers that provide error handling or reporting but do not use exceptions.\n\nA standalone single-header option is available; please see <>.\n\n'''\n\n[[synopsis-reporting]]\n=== Error Reporting\n\n[[error.hpp]]\n==== `error.hpp`\n\n====\n.#include \n[source,c++]\n----\nnamespace boost { namespace leaf {\n\n class error_id\n {\n public:\n\n error_id() noexcept;\n\n template \n error_id( Enum e, typename std::enable_if::value, Enum>::type * = 0 ) noexcept;\n\n error_id( std::error_code const & ec ) noexcept;\n\n int value() const noexcept;\n explicit operator bool() const noexcept;\n\n std::error_code to_error_code() const noexept;\n\n friend bool operator==( error_id a, error_id b ) noexcept;\n friend bool operator!=( error_id a, error_id b ) noexcept;\n friend bool operator<( error_id a, error_id b ) noexcept;\n\n template \n error_id load( Item && ... item ) const noexcept;\n\n friend std::ostream & operator<<( std::ostream & os, error_id x );\n };\n\n bool is_error_id( std::error_code const & ec ) noexcept;\n\n template \n error_id new_error( Item && ... item ) noexcept;\n\n error_id current_error() noexcept;\n\n //////////////////////////////////////////\n\n class polymorphic_context\n {\n protected:\n\n polymorphic_context() noexcept = default;\n ~polymorphic_context() noexcept = default;\n\n public:\n\n virtual void activate() noexcept = 0;\n virtual void deactivate() noexcept = 0;\n virtual bool is_active() const noexcept = 0;\n\n virtual void propagate( error_id ) noexcept = 0;\n\n virtual void print( std::ostream & ) const = 0;\n };\n\n //////////////////////////////////////////\n\n template \n class context_activator\n {\n context_activator( context_activator const & ) = delete;\n context_activator & operator=( context_activator const & ) = delete;\n\n public:\n\n explicit context_activator( Ctx & ctx ) noexcept;\n context_activator( context_activator && ) noexcept;\n ~context_activator() noexcept;\n };\n\n template \n context_activator activate_context( Ctx & ctx ) noexcept;\n\n template \n struct is_result_type: std::false_type\n {\n };\n\n template \n struct is_result_type: is_result_type\n {\n };\n\n} }\n\n#define BOOST_LEAF_ASSIGN(v, r)\\\n auto && <> = r;\\\n if( !<> )\\\n return <>.error();\\\n v = std::forward>)>(<>).value()\n\n#define BOOST_LEAF_AUTO(v, r)\\\n BOOST_LEAF_ASSIGN(auto v, r)\n\n#define BOOST_LEAF_CHECK(r)\\\n auto && <> = r;\\\n if( <> )\\\n ;\\\n else\\\n return <>.error()\n\n#define BOOST_LEAF_NEW_ERROR <>\n----\n\n[.text-right]\nReference: <> | <> | <> | <> | <> | <> | <> | <> | <> | <> | <> | <>\n====\n\n[[common.hpp]]\n==== `common.hpp`\n\n====\n.#include \n[source,c++]\n----\nnamespace boost { namespace leaf {\n\n struct e_api_function { char const * value; };\n\n struct e_file_name { std::string value; };\n\n struct e_type_info_name { char const * value; };\n\n struct e_at_line { int value; };\n\n struct e_errno\n {\n int value;\n explicit e_errno(int value=errno);\n friend std::ostream & operator<<(std::ostream &, e_errno const &);\n };\n\n namespace windows\n {\n struct e_LastError\n {\n unsigned value;\n\n explicit e_LastError(unsigned value);\n\n#if BOOST_LEAF_CFG_WIN32\n e_LastError();\n friend std::ostream & operator<<(std::ostream &, e_LastError const &);\n#endif\n };\n }\n\n} }\n----\n\n[.text-right]\nReference: <> | <> | <> | <> | <> | <> | <>\n====\n\n[[result.hpp]]\n==== `result.hpp`\n\n====\n.#include \n[source,c++]\n----\nnamespace boost { namespace leaf {\n\n template \n class result\n {\n public:\n\n result() noexcept;\n result( T && v ) noexcept;\n result( T const & v );\n\n template \n result( U && u, <> );\n\n result( error_id err ) noexcept;\n result( std::shared_ptr && ctx ) noexcept;\n\n template \n result( Enum e, typename std::enable_if::value, Enum>::type * = 0 ) noexcept;\n\n result( std::error_code const & ec ) noexcept;\n\n result( result && r ) noexcept;\n\n template \n result( result && r ) noexcept;\n\n result & operator=( result && r ) noexcept;\n\n template \n result & operator=( result && r ) noexcept;\n\n bool has_value() const noexcept;\n bool has_error() const noexcept;\n explicit operator bool() const noexcept;\n\n T const & value() const;\n T & value();\n\n T const * operator->() const noexcept;\n T * operator->() noexcept;\n\n T const & operator*() const noexcept;\n T & operator*() noexcept;\n\n <> error() noexcept;\n\n template \n error_id load( Item && ... item ) noexcept;\n };\n\n template <>\n class result\n {\n public:\n\n result() noexcept;\n\n result( error_id err ) noexcept;\n result( std::shared_ptr && ctx ) noexcept;\n\n template \n result( Enum e, typename std::enable_if::value, Enum>::type * = 0 ) noexcept;\n\n result( std::error_code const & ec ) noexcept;\n\n result( result && r ) noexcept;\n\n template \n result( result && r ) noexcept;\n\n result & operator=( result && r ) noexcept;\n\n template \n result & operator=( result && r ) noexcept;\n\n explicit operator bool() const noexcept;\n\n void value() const;\n\n <> error() noexcept;\n\n template \n error_id load( Item && ... item ) noexcept;\n };\n\n struct bad_result: std::exception { };\n\n template \n struct is_result_type>: std::true_type\n {\n };\n\n} }\n----\n\n[.text-right]\nReference: <> | <>\n====\n\n[[on_error.hpp]]\n==== `on_error.hpp`\n\n====\n[source,c++]\n.#include \n----\nnamespace boost { namespace leaf {\n\n template \n <> on_error( Item && ... e ) noexcept;\n\n class error_monitor\n {\n public:\n\n error_monitor() noexcept;\n\n error_id check() const noexcept;\n error_id assigned_error_id() const noexcept;\n };\n\n} }\n----\n\n[.text-right]\nReference: <> | <>\n====\n\n[[exception.hpp]]\n==== `exception.hpp`\n\n====\n.#include \n[source,c++]\n----\nnamespace boost { namespace leaf {\n\n template <1>\n [[noreturn]] void throw_exception( Ex &&, E && ... );\n\n template <2>\n [[noreturn]] void throw_exception( E1 &&, E && ... );\n\n [[noreturn]] void throw_exception();\n\n template <1>\n [[noreturn]] void throw_exception( error_id id, Ex &&, E && ... );\n\n template <2>\n [[noreturn]] void throw_exception( error_id id, E1 &&, E && ... );\n\n [[noreturn]] void throw_exception( error_id id );\n\n template \n <-deduced>> exception_to_result( F && f ) noexcept;\n\n} }\n\n#define BOOST_LEAF_THROW_EXCEPTION <>\n----\n\n[.text-right]\nReference: <> | <>\n\n<1> Only enabled if std::is_base_of::value.\n<2> Only enabled if !std::is_base_of::value.\n====\n\n==== `capture.hpp`\n\n====\n[source,c++]\n.#include \n----\nnamespace boost { namespace leaf {\n\n template \n decltype(std::declval()(std::forward(std::declval())...))\n capture(std::shared_ptr && ctx, F && f, A... a);\n\n} }\n----\n\n[.text-right]\nReference: <> | <>\n====\n\n'''\n\n[[tutorial-handling]]\n\n=== Error Handling\n\n[[context.hpp]]\n==== `context.hpp`\n\n====\n.#include \n[source,c++]\n----\nnamespace boost { namespace leaf {\n\n template \n class context\n {\n context( context const & ) = delete;\n context & operator=( context const & ) = delete;\n\n public:\n\n context() noexcept;\n context( context && x ) noexcept;\n ~context() noexcept;\n\n void activate() noexcept;\n void deactivate() noexcept;\n bool is_active() const noexcept;\n\n void propagate( error_id ) noexcept;\n\n void print( std::ostream & os ) const;\n\n template \n R handle_error( R &, H && ... ) const;\n };\n\n //////////////////////////////////////////\n\n template \n using context_type_from_handlers = typename <>::type;\n\n template \n BOOST_LEAF_CONSTEXPR context_type_from_handlers make_context() noexcept;\n\n template \n BOOST_LEAF_CONSTEXPR context_type_from_handlers make_context( H && ... ) noexcept;\n\n template \n context_ptr make_shared_context() noexcept;\n\n template \n context_ptr make_shared_context( H && ... ) noexcept;\n\n} }\n----\n\n[.text-right]\nReference: <> | <> | <> | <>\n====\n\n[[handle_errors.hpp]]\n==== `handle_errors.hpp`\n\n====\n.#include \n[source,c++]\n----\nnamespace boost { namespace leaf {\n\n template \n typename std::decay()().value())>::type\n try_handle_all( TryBlock && try_block, H && ... h );\n\n template \n typename std::decay()())>::type\n try_handle_some( TryBlock && try_block, H && ... h );\n\n template \n typename std::decay()())>::type\n try_catch( TryBlock && try_block, H && ... h );\n\n //////////////////////////////////////////\n\n class error_info\n {\n //No public constructors\n\n public:\n\n error_id error() const noexcept;\n\n bool exception_caught() const noexcept;\n std::exception const * exception() const noexcept;\n\n friend std::ostream & operator<<( std::ostream & os, error_info const & x );\n };\n\n class diagnostic_info: public error_info\n {\n //No public constructors\n\n friend std::ostream & operator<<( std::ostream & os, diagnostic_info const & x );\n };\n\n class verbose_diagnostic_info: public error_info\n {\n //No public constructors\n\n friend std::ostream & operator<<( std::ostream & os, diagnostic_info const & x );\n };\n\n} }\n----\n\n[.text-right]\nReference: <> | <> | <> | <> | <> | <>\n====\n\n[[handle_errors.hpp]]\n==== `to_variant.hpp`\n\n====\n.#include \n[source,c++]\n----\nnamespace boost { namespace leaf {\n\n // Requires at least C++17\n template \n std::variant<\n typename std::decay()().value())>::type\n std::tuple<\n std::optional...>>\n to_variant( TryBlock && try_block );\n\n} }\n----\n\n[.text-right]\nReference: <>\n====\n\n[[pred.hpp]]\n==== `pred.hpp`\n\n====\n.#include \n[source,c++]\n----\nnamespace boost { namespace leaf {\n\n template \n struct is_predicate: std::false_type\n {\n };\n\n template \n struct match\n {\n E matched;\n\n // Other members not specified\n };\n\n template \n struct is_predicate>: std::true_type\n {\n };\n\n template \n struct match_value\n {\n E matched;\n\n // Other members not specified\n };\n\n template \n struct is_predicate>: std::true_type\n {\n };\n\n template \n struct match_member;\n\n template \n struct member\n {\n E matched;\n\n // Other members not specified\n };\n\n template \n struct is_predicate>: std::true_type\n {\n };\n\n template \n struct catch_\n {\n std::exception const & matched;\n\n // Other members not specified\n };\n\n template \n struct catch_\n {\n Ex const & matched;\n\n // Other members not specified\n };\n\n template \n struct is_predicate>: std::true_type\n {\n };\n\n template \n struct if_not\n {\n E matched;\n\n // Other members not specified\n };\n\n template \n struct is_predicate>: std::true_type\n {\n };\n\n template \n bool category( std::error_code const & ec ) noexcept;\n\n template \n struct condition;\n\n} }\n----\n\n[.text-right]\nReference: <> | <> | <> | <> | <> | <> | <>\n====\n\n[[functions]]\n== Reference: Functions\n\nTIP: The contents of each Reference section are organized alphabetically.\n\n'''\n\n[[activate_context]]\n=== `activate_context`\n\n.#include \n[source,c++]\n----\nnamespace boost { namespace leaf {\n\n template \n context_activator activate_context( Ctx & ctx ) noexcept\n {\n return context_activator(ctx);\n }\n\n} }\n----\n\n[.text-right]\n<>\n\n.Example:\n[source,c++]\n----\nleaf::context ctx;\n\n{\n auto active_context = activate_context(ctx); <1>\n} <2>\n----\n<1> Activate `ctx`.\n<2> Automatically deactivate `ctx`.\n\n'''\n\n[[capture]]\n=== `capture`\n\n.#include \n[source,c++]\n----\nnamespace boost { namespace leaf {\n\n template \n decltype(std::declval()(std::forward(std::declval())...))\n capture(std::shared_ptr && ctx, F && f, A... a);\n\n} }\n----\n\n[.text-right]\n<>\n\nThis function can be used to capture error objects stored in a <> in one thread and transport them to a different thread for handling, either in a `<>` object or in an exception.\n\nReturns: :: The same type returned by `F`.\n\nEffects: :: Uses an internal <> to <> `*ctx`, then invokes `std::forward(f)(std::forward(a)...)`. Then:\n+\n--\n* If the returned value `r` is not a `result` type (see <>), it is forwarded to the caller.\n* Otherwise:\n** If `!r`, the return value of `capture` is initialized with `ctx`;\n+\nNOTE: An object of type `leaf::<>` can be initialized with a `std::shared_ptr`.\n+\n** otherwise, it is initialized with `r`.\n--\n+\nIn case `f` throws, `capture` catches the exception in a `std::exception_ptr`, and throws a different exception of unspecified type that transports both the `std::exception_ptr` as well as `ctx`. This exception type is recognized by <>, which automatically unpacks the original exception and propagates the contents of `*ctx` (presumably, in a different thread).\n\nTIP: See also <> from the Tutorial.\n\n'''\n\n[[context_type_from_handlers]]\n=== `context_type_from_handlers`\n\n.#include \n[source,c++]\n----\nnamespace boost { namespace leaf {\n\n template \n using context_type_from_handlers = typename <>::type;\n\n} }\n----\n\n.Example:\n[source,c++]\n----\nauto error_handlers = std::make_tuple(\n\n [](e_this const & a, e_that const & b)\n {\n ....\n },\n\n [](leaf::diagnostic_info const & info)\n {\n ....\n },\n .... );\n\nleaf::context_type_from_handlers ctx; <1>\n----\n<1> `ctx` will be of type `context`, deduced automatically from the specified error handlers.\n\nTIP: Alternatively, a suitable context may be created by calling <>, or allocated dynamically by calling <>.\n\n'''\n\n[[current_error]]\n=== `current_error`\n\n.#include \n[source,c++]\n----\nnamespace boost { namespace leaf {\n\n error_id current_error() noexcept;\n\n} }\n----\n\nReturns: :: The `error_id` value returned the last time <> was invoked from the calling thread.\n\nTIP: See also <>.\n\n'''\n\n[[exception_to_result]]\n=== `exception_to_result`\n\n[source,c++]\n.#include \n----\nnamespace boost { namespace leaf {\n\n template \n <-deduced>> exception_to_result( F && f ) noexcept;\n\n} }\n----\n\nThis function can be used to catch exceptions from a lower-level library and convert them to `<>`.\n\nReturns: :: Where `f` returns a type `T`, `exception_to_result` returns `leaf::result`.\n\nEffects: ::\n\n. Catches all exceptions, then captures `std::current_exception` in a `std::exception_ptr` object, which is <> with the returned `result`.\n. Attempts to convert the caught exception, using `dynamic_cast`, to each type `Ex~i~` in `Ex...`. If the cast to `Ex~i~` succeeds, the `Ex~i~` slice of the caught exception is loaded with the returned `result`.\n\nTIP: An error handler that takes an argument of an exception type (that is, of a type that derives from `std::exception`) will work correctly whether the object is thrown as an exception or communicated via <> (or converted using `exception_to_result`).\n\n.Example:\n[source,c++]\n----\nint compute_answer_throws();\n\n//Call compute_answer, convert exceptions to result\nleaf::result compute_answer()\n{\n return leaf::exception_to_result(compute_answer_throws());\n}\n----\n\nAt a later time we can invoke <> / <> as usual, passing handlers that take `ex_type1` or `ex_type2`, for example by reference:\n\n[source,c++]\n----\nreturn leaf::try_handle_some(\n\n [] -> leaf::result\n {\n BOOST_LEAF_AUTO(answer, compute_answer());\n //Use answer\n ....\n return { };\n },\n\n [](ex_type1 & ex1)\n {\n //Handle ex_type1\n ....\n return { };\n },\n\n [](ex_type2 & ex2)\n {\n //Handle ex_type2\n ....\n return { };\n },\n\n [](std::exception_ptr const & p)\n {\n //Handle any other exception from compute_answer.\n ....\n return { };\n } );\n----\n\n[.text-right]\n<> | <> | <>\n\nWARNING: When a handler takes an argument of an exception type (that is, a type that derives from `std::exception`), if the object is thrown, the argument will be matched dynamically (using `dynamic_cast`); otherwise (e.g. after being converted by `exception_to_result`) it will be matched based on its static type only (which is the same behavior used for types that do not derive from `std::exception`).\n\nTIP: See also <> from the tutorial.\n\n'''\n\n[[make_context]]\n=== `make_context`\n\n.#include \n[source,c++]\n----\nnamespace boost { namespace leaf {\n\n template \n context_type_from_handlers make_context() noexcept\n {\n return { };\n }\n\n template \n context_type_from_handlers make_context( H && ... ) noexcept\n {\n return { };\n }\n\n} }\n----\n\n[.text-right]\n<>\n\n.Example:\n[source,c++]\n----\nauto ctx = leaf::make_context( <1>\n []( e_this ) { .... },\n []( e_that ) { .... } );\n----\n<1> `decltype(ctx)` is `leaf::context`.\n\n'''\n\n[[make_shared_context]]\n=== `make_shared_context`\n\n.#include \n[source,c++]\n----\nnamespace boost { namespace leaf {\n\n template \n context_ptr make_shared_context() noexcept\n {\n return std::make_shared>>();\n }\n\n template \n context_ptr make_shared_context( H && ... ) noexcept\n {\n return std::make_shared>>();\n }\n\n} }\n----\n\n[.text-right]\n<>\n\nTIP: See also <> from the tutorial.\n\n'''\n\n[[new_error]]\n=== `new_error`\n\n.#include \n[source,c++]\n----\nnamespace boost { namespace leaf {\n\n template \n error_id new_error(Item && ... item) noexcept;\n\n} }\n----\n\nRequires: :: Each of the `Item...` types must be no-throw movable.\n\nEffects: :: As if:\n+\n[source,c++]\n----\nerror_id id = <>;\nreturn id.load(std::forward(item)...);\n----\n\nReturns: :: A new `error_id` value, which is unique across the entire program.\n\nEnsures: :: `id.value()!=0`, where `id` is the returned `error_id`.\n\nNOTE: `new_error` discards error objects which are not used in any active error handling calling scope.\n\nCAUTION: When loaded into a `context`, an error object of a type `E` will overwrite the previously loaded object of type `E`, if any.\n\n'''\n\n[[on_error]]\n=== `on_error`\n\n.#include \n[source,c++]\n----\nnamespace boost { namespace leaf {\n\n template \n <> on_error(Item && ... item) noexcept;\n\n} }\n----\n\nRequires: :: Each of the `Item...` types must be no-throw movable.\n\nEffects: :: All `item...` objects are forwarded and stored, together with the value returned from `std::unhandled_exceptions`, into the returned object of unspecified type, which should be captured by `auto` and kept alive in the calling scope. When that object is destroyed, if an error has occurred since `on_error` was invoked, LEAF will process the stored items to obtain error objects to be associated with the failure.\n+\nOn error, LEAF first needs to deduce an `error_id` value `err` to associate error objects with. This is done using the following logic:\n+\n--\n* If <> was invoked (by the calling thread) since the object returned by `on_error` was created, `err` is initialized with the value returned by <>;\n* Otherwise, if `std::unhandled_exceptions` returns a greater value than it returned during initialization, `err` is initialized with the value returned by <>;\n* Otherwise, the stored `item...` objects are discarded and no further action is taken (no error has occurred).\n--\n+\nNext, LEAF proceeds similarly to:\n+\n[source,c++]\n----\nerr.load(std::forward(item)...);\n----\n+\nThe difference is that unlike <>, `on_error` will not overwrite any error objects already associated with `err`.\n\nTIP: See <> from the Tutorial.\n\n'''\n\n[[throw_exception]]\n=== `throw_exception`\n\n[source,c++]\n.#include \n----\nnamespace boost { namespace leaf {\n\n template <1>\n [[noreturn]] void throw_exception( Ex && ex, E && ... e );\n\n template <2>\n [[noreturn]] void throw_exception( E1 && e1, E && ... e );\n\n [[noreturn]] void throw_exception(); <3>\n\n template <4>\n [[noreturn]] void throw_exception( error_id id, Ex && ex, E && ... e );\n\n template <5>\n [[noreturn]] void throw_exception( error_id id, E1 && e1, E && ... e );\n\n [[noreturn]] void throw_exception( error_id id ); <6>\n\n} }\n----\nThe `throw_exception` function is overloaded: it can be invoked with no arguments, or else there are several alternatives, selected using `std::enable_if` based on the type of the passed arguments. All overloads throw an exception:\n\n<1> Selected if the first argument is not of type `error_id` and is an exception object, that is, iff `Ex` derives publicly from `std::exception`. In this case the thrown exception is of unspecified type which derives publicly from `Ex` *and* from class <>, such that:\n* its `Ex` subobject is initialized by `std::forward(ex)`;\n* its `error_id` subobject is initialized by `<>(std::forward(e)...`).\n\n<2> Selected if the first argument is not of type `error_id` and is not an exception object. In this case the thrown exception is of unspecified type which derives publicly from `std::exception` *and* from class `error_id`, such that:\n** its `std::exception` subobject is default-initialized;\n** its `error_id` subobject is initialized by `<>(std::forward(e1), std::forward(e)...`).\n\n<3> If the fuction is invoked without arguments, the thrown exception is of unspecified type which derives publicly from `std::exception` *and* from class `error_id`, such that:\n** its `std::exception` subobject is default-initialized;\n** its `error_id` subobject is initialized by `<>()`.\n\n<4> Selected if the first argument is of type `error_id` and the second argument is an exception object, that is, iff `Ex` derives publicly from `std::exception`. In this case the thrown exception is of unspecified type which derives publicly from `Ex` *and* from class <>, such that:\n** its `Ex` subobject is initialized by `std::forward(ex)`;\n** its `error_id` subobject is initialized by `id.<>(std::forward(e)...)`.\n\n<5> Selected if the first argument is of type `error_id` and the second argument is not an exception object. In this case the thrown exception is of unspecified type which derives publicly from `std::exception` *and* from class `error_id`, such that:\n** its `std::exception` subobject is default-initialized;\n** its `error_id` subobject is initialized by `id.<>(std::forward(e1), std::forward(e)...`).\n\n<6> If `exception` is invoked with just an `error_id` object, the thrown exception is of unspecified type which derives publicly from `std::exception` *and* from class `error_id`, such that:\n** its `std::exception` subobject is default-initialized;\n** its `error_id` subobject is initialized by copying from `id`.\n\nNOTE: The first three overloads throw an exception object that is associated with a new `error_id`. The second three overloads throw an exception object that is associated with the specified `error_id`.\n\n.Example 1:\n[source,c++]\n----\nstruct my_exception: std::exception { };\n\nleaf::throw_exception(my_exception{}); <1>\n----\n<1> Throws an exception of a type that derives from `error_id` and from `my_exception` (because `my_exception` derives from `std::exception`).\n\n.Example 2:\n[source,c++]\n----\nenum class my_error { e1=1, e2, e3 }; <1>\n\nleaf::throw_exception(my_error::e1);\n----\n<1> Throws an exception of a type that derives from `error_id` and from `std::exception` (because `my_error` does not derive from `std::exception`).\n\nNOTE: To automatically capture `pass:[__FILE__]`, `pass:[__LINE__]` and `pass:[__FUNCTION__]` with the returned object, use <> instead of `leaf::throw_exception`.\n\n'''\n\n[[to_variant]]\n=== `to_variant`\n\n.#include \n[source,c++]\n----\nnamespace boost { namespace leaf {\n\n template \n std::variant<\n typename std::decay()().value())>::type\n std::tuple<\n std::optional...>>\n to_variant( TryBlock && try_block );\n\n} }\n----\n\nRequires: ::\n\n* This function is only available under {CPP}-17 or newer.\n* The `try_block` function may not take any arguments.\n* The type returned by the `try_block` function must be a `result` type (see <>). It is valid for the `try_block` to return `leaf::<>`, however this is not a requirement.\n\nThe `to_variant` function uses <> internally to invoke the `try_block` and capture the result in a `std::variant`. On success, the variant contains the `T` object from the produced `result`. Otherwise, the variant contains a `std::tuple` where each `std::optional` element contains an object of type `E~i~` from the user-supplied sequence `E...`, or is empty if the failure did not produce an error object of that type.\n\n.Example:\n[source,c++]\n----\nenum class E1 { e11, e12, e13 };\nenum class E2 { e21, e22, e23 };\nenum class E3 { e31, e32, e33 };\n\n....\n\nauto v = leaf::to_variant(\n []() -> leaf::result\n {\n return leaf::new_error( E1::e12, E3::e33 );\n } );\n\nassert(v.index() == 1); <1>\nauto t = std::get<1>(v); <2>\n\nassert(std::get<0>(t).value() == E1::e12); <3>\nassert(!std::get<1>(t).has_value()); <4>\nassert(std::get<2>(t).value() == E3::e33); <3>\n----\n<1> We report a failure, so the variant must contain the error object tuple, rather than an `int`.\n<2> Grab the error tuple.\n<3> We communicated an `E1` and an `E3` error object...\n<4> ...but not an `E2` error object.\n\n'''\n\n[[try_catch]]\n=== `try_catch`\n\n.#include \n[source,c++]\n----\nnamespace boost { namespace leaf {\n\n template \n typename std::decay()())>::type\n try_catch( TryBlock && try_block, H && ... h );\n\n} }\n----\n\nThe `try_catch` function works similarly to <>, except that it does not use or understand the semantics of `result` types; instead:\n\n* It assumes that the `try_block` throws to indicate a failure, in which case `try_catch` will attempt to find a suitable handler among `h...`;\n* If a suitable handler isn't found, the original exception is re-thrown using `throw;`.\n\nTIP: See <>.\n\n'''\n\n[[try_handle_all]]\n=== `try_handle_all`\n\n.#include \n[source,c++]\n----\nnamespace boost { namespace leaf {\n\n template \n typename std::decay()().value())>::type\n try_handle_all( TryBlock && try_block, H && ... h );\n\n} }\n----\n\nThe `try_handle_all` function works similarly to <>, except:\n\n* In addition, it requires that at least one of `h...` can be used to handle any error (this requirement is enforced at compile time);\n* If the `try_block` returns some `result` type, it must be possible to initialize a value of type `T` with the value returned by each of `h...`, and\n* Because it is required to handle all errors, `try_handle_all` unwraps the `result` object `r` returned by the `try_block`, returning `r.value()` instead of `r`.\n\nTIP: See <>.\n\n'''\n\n[[try_handle_some]]\n=== `try_handle_some`\n\n.#include \n\n[source,c++]\n----\nnamespace boost { namespace leaf {\n\n template \n typename std::decay()())>::type\n try_handle_some( TryBlock && try_block, H && ... h );\n\n} }\n----\n\nRequires: ::\n* The `try_block` function may not take any arguments.\n* The type `R` returned by the `try_block` function must be a `result` type (see <>). It is valid for the `try_block` to return `leaf::<>`, however this is not a requirement.\n* Each of the `h...` functions:\n** must return a type that can be used to initialize an object of the type `R`; in case R is a `result` (that is, in case of success it does not communicate a value), handlers that return `void` are permitted. If such a handler is selected, the `try_handle_some` return value is initialized by `{}`;\n** may take any error objects, by value, by (`const`) reference, or as pointer (to `const`);\n** may take arguments, by value, of any predicate type: <>, <>, <>, <>, <>, or of any user-defined predicate type `Pred` for which `<>::value` is `true`;\n** may take an <> argument by `const &`;\n** may take a <> argument by `const &`;\n** may take a <> argument by `const &`.\n\nEffects: ::\n\n* Creates a local `<>` object `ctx`, where the `E...` types are automatically deduced from the types of arguments taken by each of `h...`, which guarantees that `ctx` is able to store all of the types required to handle errors.\n* Invokes the `try_block`:\n** if the returned object `r` indicates success [.underline]#and# the `try_block` did not throw, `r` is forwarded to the caller.\n** otherwise, LEAF considers each of the `h...` handlers, in order, until it finds one that it can supply with arguments using the error objects currently stored in `ctx`, associated with `r.error()`. The first such handler is invoked and its return value is used to initialize the return value of `try_handle_some`, which can indicate success if the handler was able to handle the error, or failure if it was not.\n+\n** if `try_handle_some` is unable to find a suitable handler, it returns `r`.\n\nNOTE: `try_handle_some` is exception-neutral: it does not throw exceptions, however the `try_block` and any of `h...` are permitted to throw.\n\n[[handler_selection_procedure]]\nHandler Selection Procedure: ::\n+\nA handler `h` is suitable to handle the failure reported by `r` iff `try_handle_some` is able to produce values to pass as its arguments, using the error objects currently available in `ctx`, associated with the error ID obtained by calling `r.error()`. As soon as it is determined that an argument value can not be produced, the current handler is dropped and the selection process continues with the next handler, if any.\n+\nThe return value of `r.error()` must be implicitly convertible to <>. Naturally, the `leaf::result` template satisfies this requirement. If an external `result` type is used instead, usually `r.error()` would return a `std::error_code`, which is able to communicate LEAF error IDs; see <>.\n+\nIf `err` is the `error_id` obtained from `r.error()`, each argument `a~i~` taken by the handler currently under consideration is produced as follows:\n+\n* If `a~i~` is of type `A~i~`, `A~i~ const&` or `A~i~&`:\n+\n--\n** If an error object of type `A~i~`, associated with `err`, is currently available in `ctx`, `a~i~` is initialized with a reference to that object; otherwise\n** If `A~i~` derives from `std::exception`, and the `try_block` throws an object `ex` of type that derives from `std::exception`, LEAF obtains `A~i~* p = dynamic_cast(&ex)`. The handler is dropped if `p` is null, otherwise `a~i~` is initialized with `*p`.\n** Otherwise the handler is dropped.\n--\n+\n.Example:\n[source,c++]\n----\n....\nauto r = leaf::try_handle_some(\n\n []() -> leaf::result\n {\n return f();\n },\n\n [](leaf::e_file_name const & fn) <1>\n {\n std::cerr << \"File Name: \\\"\" << fn.value << '\"' << std::endl; <2>\n\n return 1;\n } );\n----\n+\n[.text-right]\n<> | <>\n+\n<1> In case the `try_block` indicates a failure, this handler will be selected if `ctx` stores an `e_file_name` associated with the error. Because this is the only supplied handler, if an `e_file_name` is not available, `try_handle_some` will return the `leaf::result` returned by `f`.\n<2> Print the file name, handle the error.\n+\n* If `a~i~` is of type `A~i~` `const*` or `A~i~*`, `try_handle_some` is always able to produce it: first it attempts to produce it as if it is taken by reference; if that fails, rather than dropping the handler, `a~i~` is initialized with `0`.\n+\n.Example:\n[source,c++]\n----\n....\ntry_handle_some(\n\n []() -> leaf::result\n {\n return f();\n },\n\n [](leaf::e_file_name const * fn) <1>\n {\n if( fn ) <2>\n std::cerr << \"File Name: \\\"\" << fn->value << '\"' << std::endl;\n\n return 1;\n } );\n}\n----\n+\n[.text-right]\n<> | <>\n+\n<1> This handler can be selected to handle any error, because it takes `e_file_name` as a `const *` (and nothing else).\n<2> If an `e_file_name` is available with the current error, print it.\n+\n* If `a~i~` is of a predicate type `Pred` (for which `<>::value` is `true`), `E` is deduced as `typename Pred::error_type`, and then:\n** If `E` is not `void`, and an error object `e` of type `E`, associated with `err`, is not currently stored in `ctx`, the handler is dropped; otherwise the handler is dropped if the expression `Pred::evaluate(e)` returns `false`.\n** if `E` is `void`, and a `std::exception` was not caught, the handler is dropped; otherwise the handler is dropped if the expression `Pred::evaluate(e)`, where `e` is of type `std::exception const &`, returns `false`.\n** To invoke the handler, the `Pred` argument `a~i~` is initialized with `Pred{e}`.\n+\nNOTE: See also: <>.\n+\n* If `a~i~` is of type `error_info const &`, `try_handle_some` is always able to produce it.\n+\n.Example:\n[source,c++]\n----\n....\ntry_handle_some(\n\n []\n {\n return f(); // returns leaf::result\n },\n\n [](leaf::error_info const & info) <1>\n {\n std::cerr << \"leaf::error_info:\" << std::endl << info; <2>\n return info.error(); <3>\n } );\n----\n+\n[.text-right]\n<> | <>\n+\n<1> This handler matches any error.\n<2> Print error information.\n<3> Return the original error, which will be returned out of `try_handle_some`.\n+\n* If `a~i~` is of type `diagnostic_info const &`, `try_handle_some` is always able to produce it.\n+\n.Example:\n[source,c++]\n----\n....\ntry_handle_some(\n\n []\n {\n return f(); // throws\n },\n\n [](leaf::diagnostic_info const & info) <1>\n {\n std::cerr << \"leaf::diagnostic_information:\" << std::endl << info; <2>\n return info.error(); <3>\n } );\n----\n+\n[.text-right]\n<> | <>\n+\n<1> This handler matches any error.\n<2> Print diagnostic information, including limited information about dropped error objects.\n<3> Return the original error, which will be returned out of `try_handle_some`.\n+\n* If `a~i~` is of type `verbose_diagnostic_info const &`, `try_handle_some` is always able to produce it.\n+\n.Example:\n[source,c++]\n----\n....\ntry_handle_some(\n\n []\n {\n return f(); // throws\n },\n\n [](leaf::verbose_diagnostic_info const & info) <1>\n {\n std::cerr << \"leaf::verbose_diagnostic_information:\" << std::endl << info; <2>\n return info.error(); <3>\n } );\n----\n+\n[.text-right]\n<> | <>\n+\n<1> This handler matches any error.\n<2> Print verbose diagnostic information, including values of dropped error objects.\n<3> Return the original error, which will be returned out of `try_handle_some`.\n\n[[types]]\n\n== Reference: Types\n\nTIP: The contents of each Reference section are organized alphabetically.\n\n'''\n\n[[context]]\n=== `context`\n\n.#include \n[source,c++]\n----\nnamespace boost { namespace leaf {\n\n template \n class context\n {\n context( context const & ) = delete;\n context & operator=( context const & ) = delete;\n\n public:\n\n context() noexcept;\n context( context && x ) noexcept;\n ~context() noexcept;\n\n void activate() noexcept;\n void deactivate() noexcept;\n bool is_active() const noexcept;\n\n void propagate( error_id ) noexcept;\n\n void print( std::ostream & os ) const;\n\n template \n R handle_error( error_id, H && ... ) const;\n\n };\n\n template \n using context_type_from_handlers = typename <>::type;\n\n} }\n----\n[.text-right]\n<> | <> | <> | <> | <> | <> | <> | <>\n\nThe `context` class template provides storage for each of the specified `E...` types. Typically, `context` objects are not used directly; they're created internally when the <>, <> or <> functions are invoked, instantiated with types that are automatically deduced from the types of the arguments of the passed handlers.\n\nIndependently, users can create `context` objects if they need to capture error objects and then transport them, by moving the `context` object itself.\n\nEven in that case it is recommended that users do not instantiate the `context` template by explicitly listing the `E...` types they want it to be able to store. Instead, use <> or call the <> function template, which deduce the correct `E...` types from a captured list of handler function objects.\n\nTo be able to load up error objects in a `context` object, it must be activated. Activating a `context` object `ctx` binds it to the calling thread, setting thread-local pointers of the stored `E...` types to point to the corresponding storage within `ctx`. It is possible, even likely, to have more than one active `context` in any given thread. In this case, activation/deactivation must happen in a LIFO manner. For this reason, it is best to use a <>, which relies on RAII to activate and deactivate a `context`.\n\nWhen a `context` is deactivated, it detaches from the calling thread, restoring the thread-local pointers to their pre-`activate` values. Typically, at this point the stored error objects, if any, are either discarded (by default) or moved to corresponding storage in other `context` objects active in the calling thread (if available), by calling <>.\n\nWhile error handling typically uses <>, <> or <>, it is also possible to handle errors by calling the member function <>. It takes an <>, and attempts to select an error handler based on the error objects stored in `*this`, associated with the passed `error_id`.\n\nTIP: `context` objects can be moved, as long as they aren't active.\n\nWARNING: Moving an active `context` results in undefined behavior.\n\n'''\n\n[[context::context]]\n==== Constructors\n\n.#include \n[source,c++]\n----\nnamespace boost { namespace leaf {\n\n template \n context::context() noexcept;\n\n template \n context::context( context && x ) noexcept;\n\n} }\n----\n\nThe default constructor initializes an empty `context` object: it provides storage for, but does not contain any error objects.\n\nThe move constructor moves the stored error objects from one `context` to the other.\n\nWARNING: Moving an active `context` object results in undefined behavior.\n\n'''\n\n[[context::activate]]\n==== `activate`\n\n.#include \n[source,c++]\n----\nnamespace boost { namespace leaf {\n\n template \n void context::activate() noexcept;\n\n} }\n----\n\nRequires: :: `!<>()`.\n\nEffects: :: Associates `*this` with the calling thread.\n\nEnsures: :: `<>()`.\n\nWhen a context is associated with a thread, thread-local pointers are set to point each `E...` type in its store, while the previous value of each such pointer is preserved in the `context` object, so that the effect of `activate` can be undone by calling `deactivate`.\n\nWhen an error object is <>, it is moved in the last activated (in the calling thread) `context` object that provides storage for its type (note that this may or may not be the last activated `context` object). If no such storage is available, the error object is discarded.\n\n'''\n\n[[context::deactivate]]\n==== `deactivate`\n\n.#include \n[source,c++]\n----\nnamespace boost { namespace leaf {\n\n template \n void context::deactivate() noexcept;\n\n} }\n----\n\nRequires: ::\n* `<>()`;\n* `*this` must be the last activated `context` object in the calling thread.\n\nEffects: :: Un-associates `*this` with the calling thread.\n\nEnsures: :: `!<>()`.\n\nWhen a context is deactivated, the thread-local pointers that currently point to each individual error object storage in it are restored to their original value prior to calling <>.\n\n'''\n\n[[context::handle_error]]\n==== `handle_error`\n\n[source,c++]\n.#include \n----\nnamespace boost { namespace leaf {\n\n template \n template \n R context::handle_error( error_id err, H && ... h ) const;\n\n} }\n----\n\nThis function works similarly to <>, but rather than calling a `try_block` and obtaining the <> from a returned `result` type, it matches error objects (stored in `*this`, associated with `err`) with a suitable error handler from the `h...` pack.\n\nNOTE: The caller is required to specify the return type `R`. This is because in general the supplied handlers may return different types (which must all be convertible to `R`).\n\n'''\n\n[[context::is_active]]\n==== `is_active`\n\n[source,c++]\n.#include \n----\nnamespace boost { namespace leaf {\n\n template \n bool context::is_active() const noexcept;\n\n} }\n----\n\nReturns: :: `true` if the `*this` is active in any thread, `false` otherwise.\n\n'''\n\n[[context::print]]\n==== `print`\n\n.#include \n[source,c++]\n----\nnamespace boost { namespace leaf {\n\n template \n void context::print( std::ostream & os ) const;\n\n} }\n----\n\nEffects: :: Prints all error objects currently stored in `*this`, together with the unique error ID each individual error object is associated with.\n\n'''\n\n[[context::propagate]]\n==== `propagate`\n\n.#include \n[source,c++]\n----\nnamespace boost { namespace leaf {\n\n template \n void context::propagate( error_id id ) noexcept;\n\n} }\n----\n\nRequires: ::\n`!<>()`.\n\nEffects: ::\n\nEach stored error object of some type `E` is moved into another `context` object active in the call stack that provides storage for objects of type `E`, if any, or discarded. Target objects are not overwritten if they are associated with the specified `id`, except if `id.value() == 0`.\n\n'''\n\n[[context_activator]]\n=== `context_activator`\n.#include \n[source,c++]\n----\nnamespace boost { namespace leaf {\n\n template \n class context_activator\n {\n context_activator( context_activator const & ) = delete;\n context_activator & operator=( context_activator const & ) = delete;\n\n public:\n\n explicit context_activator( Ctx & ctx ) noexcept;\n context_activator( context_activator && ) noexcept;\n ~context_activator() noexcept;\n };\n\n} }\n----\n\n`context_activator` is a simple class that activates and deactivates a <> using RAII:\n\nIf `<>`() is `true` at the time the `context_activator` is initialized, the constructor and the destructor have no effects. Otherwise:\n\n* The constructor stores a reference to `ctx` in `*this` and calls `<>`().\n* The destructor:\n** Has no effects if `ctx.is_active()` is `false` (that is, it is valid to call <> manually, before the `context_activator` object expires);\n** Otherwise, calls `<>`().\n\nFor automatic deduction of `Ctx`, use <>.\n\n'''\n\n[[diagnostic_info]]\n=== `diagnostic_info`\n\n.#include \n[source,c++]\n----\nnamespace boost { namespace leaf {\n\n class diagnostic_info: public error_info\n {\n //Constructors unspecified\n\n friend std::ostream & operator<<( std::ostream & os, diagnostic_info const & x );\n };\n\n} }\n----\n\nHandlers passed to <>, <> or <> may take an argument of type `diagnostic_info const &` if they need to print diagnostic information about the error.\n\nThe message printed by `operator<<` includes the message printed by `error_info`, followed by basic information about error objects that were communicated to LEAF (to be associated with the error) for which there was no storage available in any active <> (these error objects were discarded by LEAF, because no handler needed them).\n\nThe additional information is limited to the type name of the first such error object, as well as their total count.\n\n[NOTE]\n--\nThe behavior of `diagnostic_info` (and <>) is affected by the value of the macro `BOOST_LEAF_CFG_DIAGNOSTICS`:\n\n* If it is 1 (the default), LEAF produces `diagnostic_info` but only if an active error handling context on the call stack takes an argument of type `diagnostic_info`;\n* If it is 0, the `diagnostic_info` functionality is stubbed out even for error handling contexts that take an argument of type `diagnostic_info`. This could shave a few cycles off the error path in some programs (but it is probably not worth it).\n--\n\n'''\n\n[[error_id]]\n=== `error_id`\n\n.#include \n[source,c++]\n----\nnamespace boost { namespace leaf {\n\n class error_id\n {\n public:\n\n error_id() noexcept;\n\n template \n result( Enum e, typename std::enable_if::value, Enum>::type * = 0 ) noexcept;\n\n error_id( std::error_code const & ec ) noexcept;\n\n int value() const noexcept;\n explicit operator bool() const noexcept;\n\n std::error_code to_error_code() const noexcept;\n\n friend bool operator==( error_id a, error_id b ) noexcept;\n friend bool operator!=( error_id a, error_id b ) noexcept;\n friend bool operator<( error_id a, error_id b ) noexcept;\n\n template \n error_id load( Item && ... item ) const noexcept;\n\n friend std::ostream & operator<<( std::ostream & os, error_id x );\n };\n\n bool is_error_id( std::error_code const & ec ) noexcept;\n\n template \n error_id new_error( E && ... e ) noexcept;\n\n error_id current_error() noexcept;\n\n} }\n----\n\n[.text-right]\n<> | <> | <> | <> | <> | <> | <> | <> | <>\n\nValues of type `error_id` identify a specific occurrence of a failure across the entire program. They can be copied, moved, assigned to, and compared to other `error_id` objects. They're as efficient as an `int`.\n\n'''\n\n[[error_id::error_id]]\n==== Constructors\n\n.#include \n[source,c++]\n----\nnamespace boost { namespace leaf {\n\n error_id::error_id() noexcept = default;\n\n template \n error_id::error_id( Enum e, typename std::enable_if::value, Enum>::type * = 0 ) noexcept;\n\n error_id::error_id( std::error_code const & ec ) noexcept;\n\n} }\n----\n\nA default-initialized `error_id` object does not represent a specific failure. It compares equal to any other default-initialized `error_id` object. All other `error_id` objects identify a specific occurrence of a failure.\n\nCAUTION: When using an object of type `error_id` to initialize a `result` object, it will be initialized in error state, even when passing a default-initialized `error_id` value.\n\nConverting an `error_id` object to `std::error_code` uses an unspecified `std::error_category` which LEAF recognizes. This allows an `error_id` to be transported through interfaces that work with `std::error_code`. The `std::error_code` constructor allows the original `error_id` to be restored.\n\nTIP: To check if a given `std::error_code` is actually carrying an `error_id`, use <>.\n\nTypically, users create new `error_id` objects by invoking <>. The constructor that takes `std::error_code`, and the one that takes a type `Enum` for which `std::is_error_code_enum::value` is `true`, have the following effects:\n\n* If `ec.value()` is `0`, the effect is the same as using the default constructor.\n* Otherwise, if `<>(ec)` is `true`, the original `error_id` value is used to initialize `*this`;\n* Otherwise, `*this` is initialized by the value returned by <>, while `ec` is passed to `load`, which enables handlers used with `try_handle_some`, `try_handle_all` or `try_catch` to receive it as an argument of type `std::error_code`.\n\n'''\n\n[[is_error_id]]\n==== `is_error_id`\n\n.#include \n[source,c++]\n----\nnamespace boost { namespace leaf {\n\n bool is_error_id( std::error_code const & ec ) noexcept;\n\n} }\n----\n\nReturns: :: `true` if `ec` uses the LEAF-specific `std::error_category` that identifies it as carrying an error ID rather than another error code; otherwise returns `false`.\n\n'''\n\n[[error_id::load]]\n==== `load`\n\n.#include \n[source,c++]\n----\nnamespace boost { namespace leaf {\n\n template \n error_id error_id::load( Item && ... item ) const noexcept;\n\n} }\n----\n\nRequires: :: Each of the `Item...` types must be no-throw movable.\n\nEffects: ::\n* If `value()==0`, all of `item...` are discarded and no further action is taken.\n* Otherwise, what happens with each `item` depends on its type:\n** If it is a function that takes a single argument of some type `E &`, that function is called with the object of type `E` currently associated with `*this`. If no such object exists, a default-initialized object is associated with `*this` and then passed to the function.\n** If it is a function that takes no arguments, than function is called to obtain an error object, which is associated with `*this`.\n** Otherwise, the `item` itself is assumed to be an error object, which is associated with `*this`.\n\nReturns: :: `*this`.\n\nNOTE: `load` discards error objects which are not used in any active error handling calling scope.\n\nCAUTION: When loaded into a `context`, an error object of a type `E` will overwrite the previously loaded object of type `E`, if any.\n\nSee also: :: <>.\n\n'''\n\n[[error_id::comparison_operators]]\n==== `operator==`, `!=`, `<`\n\n.#include \n[source,c++]\n----\nnamespace boost { namespace leaf {\n\n friend bool operator==( error_id a, error_id b ) noexcept;\n friend bool operator!=( error_id a, error_id b ) noexcept;\n friend bool operator<( error_id a, error_id b ) noexcept;\n\n} }\n----\n\nThese functions have the usual semantics, comparing `a.value()` and `b.value()`.\n\nNOTE: The exact strict weak ordering implemented by `operator<` is not specified. In particular, if for two `error_id` objects `a` and `b`, `a < b` is true, it does not follow that the failure identified by `a` ocurred earlier than the one identified by `b`.\n\n'''\n\n[[error_id::operator_bool]]\n==== `operator bool`\n\n.#include \n[source,c++]\n----\nnamespace boost { namespace leaf {\n\n explicit error_id::operator bool() const noexcept;\n\n} }\n----\n\nEffects: :: As if `return value()!=0`.\n\n'''\n\n[[error_id::to_error_code]]\n==== `to_error_code`\n\n.#include \n[source,c++]\n----\nnamespace boost { namespace leaf {\n\n std::error_code error_id::to_error_code() const noexcept;\n\n} }\n----\n\nEffects: :: Returns a `std::error_code` with the same `value()` as `*this`, using an unspecified `std::error_category`.\n\nNOTE: The returned object can be used to initialize an `error_id`, in which case the original `error_id` value will be restored.\n\nTIP: Use <> to check if a given `std::error_code` carries an `error_id`.\n\n'''\n\n[[error_id::value]]\n==== `value`\n\n.#include \n[source,c++]\n----\nnamespace boost { namespace leaf {\n\n int error_id::value() const noexcept;\n\n} }\n----\n\nEffects: ::\n* If `*this` was initialized using the default constructor, returns 0.\n* Otherwise returns an `int` that is guaranteed to not be 0: a program-wide unique identifier of the failure.\n\n'''\n\n[[error_monitor]]\n=== `error_monitor`\n\n.#include \n[source,c++]\n----\nnamespace boost { namespace leaf {\n\n class error_monitor\n {\n public:\n\n error_monitor() noexcept;\n\n error_id check() const noexcept;\n\n error_id assigned_error_id( E && ... e ) const noexcept;\n };\n\n} }\n----\n\nThis class helps obtain an <> to associate error objects with, when augmenting failures communicated using LEAF through uncooperative APIs that do not use LEAF to report errors (and therefore do not return an `error_id` on error).\n\nThe common usage of this class is as follows:\n\n[source,c++]\n----\nerror_code compute_value( int * out_value ) noexcept; <1>\n\nleaf::error augmenter() noexcept\n{\n leaf::error_monitor cur_err; <2>\n\n int val;\n auto ec = compute_value(&val);\n\n if( failure(ec) )\n return cur_err.assigned_error_id().load(e1, e2, ...); <3>\n else\n return val; <4>\n}\n----\n<1> Uncooperative third-party API that does not use LEAF, but may result in calling a user callback that does use LEAF. In case our callback reports a failure, we'll augment it with error objects available in the calling scope, even though `compute_value` can not communicate an <>.\n<2> Initialize an `error_monitor` object.\n<3> The call to `compute_value` has failed:\n- If <> was invoked (by the calling thread) after the `augment` object was initialized, `assigned_error_id` returns the last `error_id` returned by `new_error`. This would be the case if the failure originates in our callback (invoked internally by `compute_value`).\n- Else, `assigned_error_id` invokes `new_error` and returns that `error_id`.\n<4> The call was successful, return the computed value.\n\nThe `check` function works similarly, but instead of invoking `new_error` it returns a default-initialized `error_id`.\n\nTIP: See <>.\n\n'''\n\n[[e_api_function]]\n=== `e_api_function`\n\n.#include \n[source,c++]\n----\nnamespace boost { namespace leaf {\n\n struct e_api_function {char const * value;};\n\n} }\n----\n\n\nThe `e_api_function` type is designed to capture the name of the API function that failed. For example, if you're reporting an error from `fread`, you could use `leaf::e_api_function {\"fread\"}`.\n\nWARNING: The passed value is stored as a C string (`char const *`), so `value` should only be initialized with a string literal.\n\n'''\n\n[[e_at_line]]\n=== `e_at_line`\n\n.#include \n[source,c++]\n----\nnamespace boost { namespace leaf {\n\n struct e_at_line { int value; };\n\n} }\n----\n\n`e_at_line` can be used to communicate the line number when reporting errors (for example parse errors) about a text file.\n\n'''\n\n[[e_errno]]\n=== `e_errno`\n\n.#include \n[source,c++]\n----\nnamespace boost { namespace leaf {\n\n struct e_errno\n {\n int value;\n explicit e_errno(int value=errno);\n friend std::ostream & operator<<( std::ostream & os, e_errno const & err );\n };\n\n} }\n----\n\nBy default, the constructor initializes `value` with `errno`, but the caller can pass a specific error code instead. When printed in automatically-generated diagnostic messages, `e_errno` objects use `strerror` to convert the error code to string.\n\n'''\n\n[[e_file_name]]\n=== `e_file_name`\n\n.#include \n[source,c++]\n----\nnamespace boost { namespace leaf {\n\n struct e_file_name { std::string value; };\n\n} }\n----\n\nWhen a file operation fails, you could use `e_file_name` to store the name of the file.\n\nTIP: It is probably better to define your own file name wrappers to avoid clashes if different modules all use `leaf::e_file_name`. It is best to use a descriptive name that clarifies what kind of file name it is (e.g. `e_source_file_name`, `e_destination_file_name`), or at least define `e_file_name` in a given module's namespace.\n\n'''\n\n[[e_LastError]]\n=== `e_LastError`\n\n.#include \n[source,c++]\n----\nnamespace boost { namespace leaf {\n\n namespace windows\n {\n struct e_LastError\n {\n unsigned value;\n\n explicit e_LastError(unsigned value);\n\n#if BOOST_LEAF_CFG_WIN32\n e_LastError();\n friend std::ostream & operator<<(std::ostream &, e_LastError const &);\n#endif\n };\n }\n\n} }\n----\n\n`e_LastError` is designed to communicate `GetLastError()` values on Windows. The default constructor initializes `value` via `GetLastError()`. See <>.\n\n'''\n\n[[e_source_location]]\n=== `e_source_location`\n\n.#include \n[source,c++]\n----\nnamespace boost { namespace leaf {\n\n struct e_source_location\n {\n char const * file;\n int line;\n char const * function;\n\n friend std::ostream & operator<<( std::ostream & os, e_source_location const & x );\n };\n\n} }\n----\n\nThe <> and <> macros capture `pass:[__FILE__]`, `pass:[__LINE__]` and `pass:[__FUNCTION__]` into a `e_source_location` object.\n\n'''\n\n[[e_type_info_name]]\n=== `e_type_info_name`\n\n.#include \n[source,c++]\n----\nnamespace boost { namespace leaf {\n\n struct e_type_info_name { char const * value; };\n\n} }\n----\n\n`e_type_info_name` is designed to store the return value of `std::type_info::name`.\n\n'''\n\n[[error_info]]\n=== `error_info`\n\n.#include \n[source,c++]\n----\nnamespace boost { namespace leaf {\n\n class error_info\n {\n //Constructors unspecified\n\n public:\n\n error_id error() const noexcept;\n\n bool exception_caught() const noexcept;\n std::exception const * exception() const noexcept;\n\n friend std::ostream & operator<<( std::ostream & os, error_info const & x );\n };\n\n} }\n----\n\nHandlers passed to error handling functions such as <>, <> or <> may take an argument of type `error_info const &` to receive generic information about the error being handled.\n\nThe `error` member function returns the program-wide unique <> of the error.\n\nThe `exception_caught` member function returns `true` if the handler that received `*this` is being invoked to handle an exception, `false` otherwise.\n\nIf handling an exception, the `exception` member function returns a pointer to the `std::exception` subobject of the caught exception, or `0` if that exception could not be converted to `std::exception`.\n\nWARNING: It is illegal to call the `exception` member function unless `exception_caught()` is `true`.\n\nThe `operator<<` overload prints diagnostic information about each error object currently stored in the <> local to the <>, <> or <> scope that invoked the handler, but only if it is associated with the <> returned by `error()`.\n\n'''\n\n[[polymorphic_context]]\n=== `polymorphic_context`\n\n.#include \n[source,c++]\n----\nnamespace boost { namespace leaf {\n\n class polymorphic_context\n {\n protected:\n\n polymorphic_context() noexcept;\n ~polymorphic_context() noexcept;\n\n public:\n\n virtual void activate() noexcept = 0;\n virtual void deactivate() noexcept = 0;\n virtual bool is_active() const noexcept = 0;\n\n virtual void propagate( error_id ) noexcept = 0;\n\n virtual void print( std::ostream & ) const = 0;\n };\n\n} }\n----\n\nThe `polymorphic_context` class is an abstract base type which can be used to erase the type of the exact instantiation of the <> class template used. See <>.\n\n'''\n\n[[result]]\n=== `result`\n\n.#include \n[source,c++]\n----\nnamespace boost { namespace leaf {\n\n template \n class result\n {\n public:\n\n result() noexcept;\n result( T && v ) noexcept;\n result( T const & v );\n\n template \n result( U &&, <> );\n\n result( error_id err ) noexcept;\n result( std::shared_ptr && ctx ) noexcept;\n\n template \n result( Enum e, typename std::enable_if::value, Enum>::type * = 0 ) noexcept;\n\n result( std::error_code const & ec ) noexcept;\n\n result( result && r ) noexcept;\n\n template \n result( result && r ) noexcept;\n\n result & operator=( result && r ) noexcept;\n\n template \n result & operator=( result && r ) noexcept;\n\n bool has_value() const noexcept;\n bool has_error() const noexcept;\n explicit operator bool() const noexcept;\n\n T const & value() const;\n T & value();\n\n T const * operator->() const noexcept;\n T * operator->() noexcept;\n\n T const & operator*() const noexcept;\n T & operator*() noexcept;\n\n <> error() noexcept;\n\n template \n error_id load( Item && ... item ) noexcept;\n };\n\n template <>\n class result\n {\n public:\n\n result() noexcept;\n\n result( error_id err ) noexcept;\n result( std::shared_ptr && ctx ) noexcept;\n\n template \n result( Enum e, typename std::enable_if::value, Enum>::type * = 0 ) noexcept;\n\n result( std::error_code const & ec ) noexcept;\n\n result( result && r ) noexcept;\n\n template \n result( result && r ) noexcept;\n\n result & operator=( result && r ) noexcept;\n\n template \n result & operator=( result && r ) noexcept;\n\n bool has_value() const noexcept;\n bool has_error() const noexcept;\n explicit operator bool() const noexcept;\n\n void value() const;\n\n <> error() noexcept;\n\n template \n error_id load( Item && ... item ) noexcept;\n };\n\n struct bad_result: std::exception { };\n\n} }\n----\n[.text-right]\n<> | <> | <> | <> | <> | <> | <> | <> | <> | <>\n\nThe `result` type can be returned by functions which produce a value of type `T` but may fail doing so.\n\nRequires: :: `T` must be movable, and its move constructor may not throw.\n\nInvariant: :: A `result` object is in one of three states:\n* Value state, in which case it contains an object of type `T`, and <>/<>/<> can be used to access the contained value.\n* Error state, in which case it contains an error ID, and calling <> throws `leaf::bad_result`.\n* Error capture state, which is the same as the Error state, but in addition to the error ID, it holds a `std::shared_ptr<<>>`.\n\n`result` objects are nothrow-moveable but are not copyable.\n\n'''\n\n[[result::result]]\n==== Constructors\n\n--\n.#include \n[source,c++]\n----\nnamespace boost { namespace leaf {\n\n template \n result::result() noexcept;\n\n template \n result::result( T && v ) noexcept; <1>\n\n template \n result::result( T const & v ); <1>\n\n template \n result::result( U && u, <> ); <2>\n\n template \n result::result( leaf::error_id err ) noexcept;\n\n template \n template \n result::result( Enum e, typename std::enable_if::value, Enum>::type * = 0 ) noexcept;\n\n template \n result::result( std::error_code const & ec ) noexcept;\n\n template \n result::result( std::shared_ptr && ctx ) noexcept;\n\n template \n result::result( result && ) noexcept;\n\n template \n template \n result::result( result && ) noexcept;\n\n} }\n----\n<1> Not available if `T` is `void`.\n<2> Available if an object of type `T` can be initialized with `std::forward(u)`. This is to enable e.g. `result` to be initialized with a string literal.\n--\n\nRequires: :: `T` must be movable, and its move constructor may not throw; or `void`.\n\nEffects: ::\n\nEstablishes the `result` invariant:\n+\n--\n* To get a `result` in <>, initialize it with an object of type `T` or use the default constructor.\n* To get a `result` in <>, initialize it with:\n** an <> object.\n+\nCAUTION: Initializing a `result` with a default-initialized `error_id` object (for which `.value()` returns `0`) will still result in <>!\n+\n** a `std::error_code` object.\n** an object of type `Enum` for which `std::is_error_code_enum::value` is `true`.\n* To get a `result` in <>, initialize it with a `std::shared_ptr<<>>` (which can be obtained by calling e.g. <>).\n--\n+\nWhen a `result` object is initialized with a `std::error_code` object, it is used to initialize an `error_id` object, then the behavior is the same as if initialized with `error_id`.\n\nThrows: ::\n* Initializing the `result` in Value state may throw, depending on which constructor of `T` is invoked;\n* Other constructors do not throw.\n\nTIP: A `result` that is in value state converts to `true` in boolean contexts. A `result` that is not in value state converts to `false` in boolean contexts.\n\nNOTE: `result` objects are nothrow-moveable but are not copyable.\n\n'''\n\n[[result::error]]\n==== `error`\n\n.#include \n[source,c++]\n----\nnamespace boost { namespace leaf {\n\n template \n <> result::error() noexcept;\n\n} }\n----\n\nReturns: A proxy object of unspecified type, implicitly convertible to any instance of the `result` class template, as well as to <>.\n\n* If the proxy object is converted to some `result`:\n** If `*this` is in <>, returns `result(error_id())`.\n** Otherwise the state of `*this` is moved into the returned `result`.\n* If the proxy object is converted to an `error_id`:\n** If `*this` is in <>, returns a default-initialized <> object.\n** If `*this` is in <>, all captured error objects are <> in the calling thread, and the captured `error_id` value is returned.\n** If `*this` is in <>, returns the stored `error_id`.\n* If the proxy object is not used, the state of `*this` is not modified.\n\nWARNING: The returned proxy object refers to `*this`; avoid holding on to it.\n\n'''\n\n[[result::load]]\n==== `load`\n\n.#include \n[source,c++]\n----\nnamespace boost { namespace leaf {\n\n template \n template \n error_id result::load( Item && ... item ) noexcept;\n\n} }\n----\n\nThis member function is designed for use in `return` statements in functions that return `result` to forward additional error objects to the caller.\n\nEffects: :: As if `error_id(thispass:[->]error()).load(std::forward(item)...)`.\n\nReturns: :: `*this`.\n\n'''\n\n[[result::operator_eq]]\n==== `operator=`\n\n.#include \n[source,c++]\n----\nnamespace boost { namespace leaf {\n\n template \n result & result::operator=( result && ) noexcept;\n\n template \n template \n result & result::operator=( result && ) noexcept;\n\n} }\n----\n\nEffects: :: Destroys `*this`, then re-initializes it as if using the appropriate `result` constructor. Basic exception-safety guarantee.\n\n'''\n\n[[result::has_value]]\n==== `has_value`\n\n.#include \n[source,c++]\n----\nnamespace boost { namespace leaf {\n\n template \n bool result::has_value() const noexcept;\n\n} }\n----\n\nReturns: :: If `*this` is in <>, returns `true`, otherwise returns `false`.\n\n'''\n\n[[result::has_error]]\n==== `has_error`\n\n.#include \n[source,c++]\n----\nnamespace boost { namespace leaf {\n\n template \n bool result::has_error() const noexcept;\n\n} }\n----\n\nReturns: :: If `*this` is in <>, returns `false`, otherwise returns `true`.\n\n'''\n\n[[result::operator_bool]]\n==== `operator bool`\n\n.#include \n[source,c++]\n----\nnamespace boost { namespace leaf {\n\n template \n result::operator bool() const noexcept;\n\n} }\n----\n\nReturns: :: If `*this` is in <>, returns `true`, otherwise returns `false`.\n\n'''\n\n[[result::value]]\n==== `value`\n\n.#include \n[source,c++]\n----\nnamespace boost { namespace leaf {\n\n void result::value() const;\n\n template \n T const & result::value() const;\n\n template \n T & result::value();\n\n struct bad_result: std::exception { };\n\n} }\n----\n\n[[result::bad_result]]\nEffects: :: If `*this` is in <>, returns a reference to the stored value, otherwise throws `bad_result`.\n\n'''\n\n[[result::operator_ptr]]\n==== `operatorpass:[->]`\n\n.#include \n[source,c++]\n----\nnamespace boost { namespace leaf {\n\n template \n T const * result::operator->() const noexcept;\n\n template \n T * result::operator->() noexcept;\n\n} }\n----\n\nReturns :: If `*this` is in <>, returns a pointer to the stored value; otherwise returns 0.\n\n'''\n\n[[result::operator_deref]]\n==== `operator*`\n\n.#include \n[source,c++]\n----\nnamespace boost { namespace leaf {\n\n template \n T const & result::operator*() const noexcept;\n\n template \n T & result::operator*() noexcept;\n\n} }\n----\n\nRequires: :: `*this` must be in <>.\n\nReturns :: a reference to the stored value.\n\n'''\n\n[[verbose_diagnostic_info]]\n=== `verbose_diagnostic_info`\n\n.#include \n[source,c++]\n----\nnamespace boost { namespace leaf {\n\n class verbose_diagnostic_info: public error_info\n {\n //Constructors unspecified\n\n friend std::ostream & operator<<( std::ostream & os, verbose_diagnostic_info const & x );\n };\n\n} }\n----\n\nHandlers passed to error handling functions such as <>, <> or <> may take an argument of type `verbose_diagnostic_info const &` if they need to print diagnostic information about the error.\n\nThe message printed by `operator<<` includes the message printed by `error_info`, followed by information about error objects that were communicated to LEAF (to be associated with the error) for which there was no storage available in any active <> (these error objects were discarded by LEAF, because no handler needed them).\n\nThe additional information includes the types and the values of all such error objects.\n\n[NOTE]\n--\nThe behavior of `verbose_diagnostic_info` (and <>) is affected by the value of the macro `BOOST_LEAF_CFG_DIAGNOSTICS`:\n\n* If it is 1 (the default), LEAF produces `verbose_diagnostic_info` but only if an active error handling context on the call stack takes an argument of type `verbose_diagnostic_info`;\n* If it is 0, the `verbose_diagnostic_info` functionality is stubbed out even for error handling contexts that take an argument of type `verbose_diagnostic_info`. This could save some cycles on the error path in some programs (but is probably not worth it).\n--\n\nWARNING: Using `verbose_diagnostic_info` may allocate memory dynamically, but only if an active error handler takes an argument of type `verbose_diagnostic_info`.\n\n[[predicates]]\n== Reference: Predicates\n\nTIP: The contents of each Reference section are organized alphabetically.\n\nA predicate is a special type of error handler argument which enables the <> to consider the _value_ of available error objects, not only their type; see <>.\n\nThe following predicates are available:\n\n* <>\n* <>\n* <>\n* <>\n* <>\n\nIn addition, any user-defined type `Pred` for which `<>::value` is `true` is treated as a predicate. In this case, it is required that:\n\n* `Pred` defines an accessible member type `error_type` to specify the error object type it requires;\n* `Pred` defines an accessible static member function `evaluate`, which returns a boolean type, and can be invoked with an object of type `error_type const &`;\n* A `Pred` instance can be initialized with an object of type `error_type`.\n\nWhen an error handler takes an argument of a predicate type `Pred`, the <> drops the handler if an error object `e` of type `Pred::error_type` is not available. Otherwise, the handler is dropped if `Pred::evaluate(e)` returns `false`. If the handler is invoked, the `Pred` argument is initialized with `Pred{e}`.\n\nNOTE: Predicates are evaluated before the error handler is invoked, and so they may not access dynamic state (of course the error handler itself can access dynamic state, e.g. by means of lambda expression captures).\n\n.Example 1:\n[source,c++]\n----\nenum class my_error { e1 = 1, e2, e3 };\n\nstruct my_pred\n{\n using error_type = my_error; <1>\n\n static bool evaluate(my_error) noexcept; <2>\n\n my_error matched; <3>\n}\n\nnamespace boost { namespace leaf {\n\n template <>\n struct is_predicate: std::true_type\n {\n };\n\n} }\n----\n<1> This predicate requires an error object of type `my_error`.\n<2> The handler selection procedure will call this function with an object `e` of type `my_error` to evaluate the predicate...\n<3> ...and if successful, initialize the `my_pred` error handler argument with `my_pred{e}`.\n\n.Example 2:\n[source,c++]\n----\nstruct my_pred\n{\n using error_type = leaf::e_errno; <1>\n\n static bool evaluate(leaf::e_errno const &) noexcept; <2>\n\n leaf::e_errno const & matched; <3>\n}\n\nnamespace boost { namespace leaf {\n\n template <>\n struct is_predicate: std::true_type\n {\n };\n\n} }\n----\n<1> This predicate requires an error object of type <>.\n<2> The handler selection procedure will call this function with an object `e` of type `e_errno` to evaluate the predicate...\n<3> ...and if successful, initialize the `my_pred` error handler argument with `my_pred{e}`.\n\n'''\n\n[[catch_]]\n=== `catch_`\n\n.#include \n[source,c++]\n----\nnamespace boost { namespace leaf {\n\n template \n struct catch_\n {\n std::exception const & matched;\n\n // Other members not specified\n };\n\n template \n struct catch_\n {\n Ex const & matched;\n\n // Other members not specified\n };\n\n template \n struct is_predicate>: std::true_type\n {\n };\n\n} }\n----\n[.text-right]\n<>\n\nWhen an error handler takes an argument of type that is an instance of the `catch_` template, the <> first checks if a `std::exception` was caught. If not, the handler is dropped. Otherwise, the handler is dropped if the caught `std::exception` can not be `dynamic_cast` to any of the specified types `Ex...`.\n\nIf the error handler is invoked, the `matched` member can be used to access the exception object.\n\nNOTE: See also: <>.\n\nTIP: While `catch_` requires that the caught exception object is of type that derives from `std::exception`, it is not required that the `Ex...` types derive from `std::exception`.\n\n.Example 1:\n[source,c++]\n----\nstruct ex1: std::exception { };\nstruct ex2: std::exception { };\n\nleaf::try_catch(\n\n []\n {\n return f(); // throws\n },\n\n [](leaf::catch_ c)\n { <1>\n assert(dynamic_cast(&c.matched) || dynamic_cast(&c.matched));\n ....\n } );\n----\n<1> The handler is selected if `f` throws an exception of type `ex1` or `ex2`.\n\n.Example 2:\n[source,c++]\n----\nstruct ex1: std::exception { };\n\nleaf::try_handle_some(\n\n []\n {\n return f(); // returns leaf::result\n },\n\n [](ex1 & e)\n { <1>\n ....\n } );\n----\n<1> The handler is selected if `f` throws an exception of type `ex1`. Notice that if we're interested in only one exception type, as long as that type derives from `std::exception`, the use of `catch_` is not required.\n\n'''\n\n[[if_not]]\n=== `if_not`\n\n.#include \n[source,c++]\n----\nnamespace boost { namespace leaf {\n\n template \n struct if_not\n {\n <> matched;\n\n // Other members not specified\n };\n\n template \n struct is_predicate>: std::true_type\n {\n };\n\n} }\n----\n[.text-right]\n<>\n\n\nWhen an error handler takes an argument of type `if_not

`, where `P` is another predicate type, the <> first checks if an error object of the type `E` required by `P` is available. If not, the handler is dropped. Otherwise, the handler is dropped if `P` evaluates to `true`.\n\nIf the error handler is invoked, `matched` can be used to access the matched object `E`.\n\nNOTE: See also <>.\n\n.Example:\n[source,c++]\n----\nenum class my_enum { e1, e2, e3 };\n\nleaf::try_handle_some(\n\n []\n {\n return f(); // returns leaf::result\n },\n\n []( leaf::if_not> )\n { <1>\n ....\n } );\n----\n\n[.text-right]\n<> | <>\n\n<1> The handler is selected if an object of type `my_enum`, which [.underline]#*does not*# compare equal to `e1` or to `e2`, [.underline]#*is*# associated with the detected error.\n\n'''\n\n[[match]]\n=== `match`\n\n.#include \n[source,c++]\n----\nnamespace boost { namespace leaf {\n\n template \n class match\n {\n <> matched;\n\n // Other members not specified\n };\n\n template \n struct is_predicate>: std::true_type\n {\n };\n\n} }\n----\n[.text-right]\n<>\n\n\nWhen an error handler takes an argument of type `match`, the <> first checks if an error object `e` of type `E` is available. If it is not available, the handler is dropped. Otherwise, the handler is dropped if the following condition is not met:\n\n[.text-center]\n`p~1~ || p~2~ || ... p~n~`.\n\nWhere `p~i~` is equivalent to `e == V~i~`, except if `V~i~` is pointer to a function\n\n[.text-center]\n`bool (*V~i~)(T x)`.\n\nIn this case it is required that `V~i~ != 0` and that `x` can be initialized with `E const &`, and then `p~i~` is equivalent to:\n\n[.text-center]\n`V~i~(e)`.\n\n[[category]]\nIn particular, it is valid to pass pointer to the function `leaf::category` for any `V~i~`, where:\n\n[.text-center]\n`std::is_error_code_enum::value || std::is_error_condition_enum::value`.\n\nIn this case, `p~i~` is equivalent to:\n\n[.text-center]\n`&e.category() == &std::error_code(Enum{}).category()`.\n\nIf the error handler is invoked, `matched` can be used to access `e`.\n\nNOTE: See also <>.\n\n.Example 1: Handling of a subset of enum values.\n[source,c++]\n----\nenum class my_enum { e1, e2, e3 };\n\nleaf::try_handle_some(\n\n []\n {\n return f(); // returns leaf::result\n },\n\n []( leaf::match m )\n { <1>\n static_assert(std::is_same::value);\n assert(m.matched == my_enum::e1 || m.matched == my_enum::e2);\n ....\n } );\n----\n<1> The handler is selected if an object of type `my_enum`, which compares equal to `e1` or to `e2`, is associated with the detected error.\n\n.Example 2: Handling of a subset of std::error_code enum values (requires at least {CPP}17, see Example 4 for a {CPP}11-compatible workaround).\n[source,c++]\n----\nenum class my_enum { e1=1, e2, e3 };\n\nnamespace std\n{\n template <> struct is_error_code_enum: std::true_type { };\n}\n\nleaf::try_handle_some(\n\n []\n {\n return f(); // returns leaf::result\n },\n\n []( leaf::match m )\n { <1>\n static_assert(std::is_same::value);\n assert(m.matched == my_enum::e1 || m.matched == my_enum::e2);\n ....\n } );\n----\n<1> The handler is selected if an object of type `std::error_code`, which compares equal to `e1` or to `e2`, is associated with the detected error.\n\n.Example 3: Handling of a specific std::error_code::category (requires at least {CPP}17).\n[source,c++]\n----\nenum class enum_a { a1=1, a2, a3 };\nenum class enum_b { b1=1, b2, b3 };\n\nnamespace std\n{\n template <> struct is_error_code_enum: std::true_type { };\n template <> struct is_error_code_enum: std::true_type { };\n}\n\nleaf::try_handle_some(\n\n []\n {\n return f(); // returns leaf::result\n },\n\n []( leaf::match, enum_b::b2> m )\n { <1>\n static_assert(std::is_same::value);\n assert(&m.matched.category() == &std::error_code(enum_{}).category() || m.matched == enum_b::b2);\n ....\n } );\n----\n<1> The handler is selected if an object of type `std::error_code`, which either has the same `std::error_category` as that of `enum_a` or compares equal to `enum_b::b2`, is associated with the detected error.\n\n[[condition]]\nThe use of the `leaf::category` template requires automatic deduction of the type of each `V~i~`, which in turn requires {CPP}17 or newer. The same applies to the use of `std::error_code` as `E`, but LEAF provides a compatible {CPP}11 workaround for this case, using the template `condition`. The following is equivalent to Example 2:\n\n.Example 4: Handling of a subset of std::error_code enum values using the {CPP}11-compatible API.\n[source,c++]\n----\nenum class my_enum { e1=1, e2, e3 };\n\nnamespace std\n{\n template <> struct is_error_code_enum: std::true_type { };\n}\n\nleaf::try_handle_some(\n\n []\n {\n return f(); // returns leaf::result\n },\n\n []( leaf::match, my_enum::e1, my_enum::e2> m )\n {\n static_assert(std::is_same::value);\n assert(m.matched == my_enum::e1 || m.matched == my_enum::e2);\n ....\n } );\n----\n\nInstead of a set of values, the `match` template can be given pointers to functions that implement a custom comparison. In the following example, we define a handler which will be selected to handle any error that communicates an object of the user-defined type `severity` with value greater than 4:\n\n.Example 5: Handling of failures with severity::value greater than a specified threshold (requires at least {CPP}17).\n[source,c++]\n----\nstruct severity { int value; }\n\ntemplate \nconstexpr bool severity_greater_than( severity const & e ) noexcept\n{\n return e.value > S;\n}\n\nleaf::try_handle_some(\n\n []\n {\n return f(); // returns leaf::result\n },\n\n []( leaf::match> m )\n {\n static_assert(std::is_same::value);\n assert(m.matched.value > 4);\n ....\n } );\n\n----\n\n'''\n\n[[match_member]]\n=== `match_member`\n\n.#include \n[source,c++]\n----\nnamespace boost { namespace leaf {\n\n template \n struct match_member;\n\n template \n struct match_member\n {\n E const & matched;\n\n // Other members not specified\n };\n\n template \n struct is_predicate>: std::true_type\n {\n };\n\n} }\n----\n[.text-right]\n<>\n\n\nThis predicate is similar to <>, but able to bind any accessible data member of `E`; e.g. `match_member<&E::value, V...>` is equivalent to `match_value`.\n\nNOTE: See also <>.\n\nWARNING: `match_member` requires at least {CPP}17, whereas `match_value` does not.\n\n'''\n\n[[match_value]]\n=== `match_value`\n\n.#include \n[source,c++]\n----\nnamespace boost { namespace leaf {\n\n template \n struct match_value\n {\n E const & matched;\n\n // Other members not specified\n };\n\n template \n struct is_predicate>: std::true_type\n {\n };\n\n} }\n----\n[.text-right]\n<>\n\n\nThis predicate is similar to <>, but where `match` compares the available error object `e` of type `E` to the specified values `V...`, `match_value` works with `e.value`.\n\nNOTE: See also <>.\n\n.Example:\n[source,c++]\n----\nstruct e_errno { int value; }\n\nleaf::try_handle_some(\n\n []\n {\n return f(); // returns leaf::result\n },\n\n []( leaf::match_value m )\n { <1>\n static_assert(std::is_same::value);\n assert(m.matched.value == ENOENT);\n ....\n } );\n----\n<1> The handler is selected if an object of type <>, with `.value` equal to `ENOENT`, is associated with the detected error.\n\n[[traits]]\n== Reference: Traits\n\nTIP: The contents of each Reference section are organized alphabetically.\n\n[[is_predicate]]\n=== `is_predicate`\n\n[source,c++]\n.#include >\n----\nnamespace boost { namespace leaf {\n\n template \n struct is_predicate: std::false_type\n {\n };\n\n} }\n----\n\nThe `is_predicate` template is used by the <> to detect predicate types. See <>.\n\n'''\n\n[[is_result_type]]\n=== `is_result_type`\n\n[source,c++]\n.#include >\n----\nnamespace boost { namespace leaf {\n\n template \n struct is_result_type: std::false_type\n {\n };\n\n} }\n----\n\nThe error handling functionality provided by <> and <> -- including the ability to <> error objects of arbitrary types -- is compatible with any external `result` type R, as long as for a given object `r` of type `R`:\n\n* If `bool(r)` is `true`, `r` indicates success, in which case it is valid to call `r.value()` to recover the `T` value.\n* Otherwise `r` indicates a failure, in which case it is valid to call `r.error()`. The returned value is used to initialize an `error_id` (note: `error_id` can be initialized by `std::error_code`).\n\nTo use an external `result` type R, you must specialize the `is_result_type` template so that `is_result_type::value` evaluates to `true`.\n\nNaturally, the provided `leaf::<>` class template satisfies these requirements. In addition, it allows error objects to be transported across thread boundaries, using a `std::shared_ptr<<>>`.\n\n[[macros]]\n== Reference: Macros\n\nTIP: The contents of each Reference section are organized alphabetically.\n\n'''\n\n[[BOOST_LEAF_ASSIGN]]\n=== `BOOST_LEAF_ASSIGN`\n\n.#include \n[source,c++]\n----\n#define BOOST_LEAF_ASSIGN(v, r)\\\n auto && <> = r;\\\n if( !<> )\\\n return <>.error();\\\n v = std::forward>)>(<>).value()\n----\n\n`BOOST_LEAF_ASSIGN` is useful when calling a function that returns `result` (other than `result`), if the desired behavior is to forward any errors to the caller verbatim.\n\nIn case of success, the result `value()` of type `T` is assigned to the specified variable `v`, which must have been declared prior to invoking `BOOST_LEAF_ASSIGN`. However, it is possible to use `BOOST_LEAF_ASSIGN` to declare a new variable, by passing in `v` its type together with its name, e.g. `BOOST_LEAF_ASSIGN(auto && x, f())` calls `f`, forwards errors to the caller, while capturing successful values in `x`.\n\nNOTE: See also <>.\n\n'''\n\n[[BOOST_LEAF_AUTO]]\n=== `BOOST_LEAF_AUTO`\n\n.#include \n[source,c++]\n----\n#define BOOST_LEAF_AUTO(v, r)\\\n BOOST_LEAF_ASSIGN(auto v, r)\n----\n[.text-right]\n<>\n\n`BOOST_LEAF_AUTO` is useful when calling a function that returns `result` (other than `result`), if the desired behavior is to forward any errors to the caller verbatim.\n\n.Example:\n[source,c++]\n----\nleaf::result compute_value();\n\nleaf::result add_values()\n{\n BOOST_LEAF_AUTO(v1, compute_value()); <1>\n BOOST_LEAF_AUTO(v2, compute_value()); <2>\n return v1 + v2;\n}\n----\n<1> Call `compute_value`, bail out on failure, define a local variable `v1` on success.\n<2> Call `compute_value` again, bail out on failure, define a local variable `v2` on success.\n\nOf course, we could write `add_value` without using `BOOST_LEAF_AUTO`. This is equivalent:\n\n----\nleaf::result add_values()\n{\n auto v1 = compute_value();\n if( !v1 )\n return v1.error();\n\n auto v2 = compute_value();\n if( !v2 )\n return v2.error();\n\n return v1.value() + v2.value();\n}\n----\n\nNOTE: See also <>.\n\n'''\n\n[[BOOST_LEAF_CHECK]]\n=== `BOOST_LEAF_CHECK`\n\n.#include \n[source,c++]\n----\n#if BOOST_LEAF_CFG_GNUC_STMTEXPR\n\n#define BOOST_LEAF_CHECK(r)\\\n ({\\\n auto && <> = (r);\\\n if( !<> )\\\n return <>.error();\\\n std::move(<>);\\\n }).value()\n\n#else\n\n#define BOOST_LEAF_CHECK(r)\\\n {\\\n auto && <> = (r);\\\n if( !<> )\\\n return <>.error();\\\n }\n\n#endif\n----\n\n`BOOST_LEAF_CHECK` is useful when calling a function that returns `result`, if the desired behavior is to forward any errors to the caller verbatim.\n\n.Example:\n[source,c++]\n----\nleaf::result send_message( char const * msg );\n\nleaf::result compute_value();\n\nleaf::result say_hello_and_compute_value()\n{\n BOOST_LEAF_CHECK(send_message(\"Hello!\")); <1>\n return compute_value();\n}\n----\n\n<1> Try to send a message, then compute a value, report errors using BOOST_LEAF_CHECK.\n\nEquivalent implementation without `BOOST_LEAF_CHECK`:\n\n----\nleaf::result add_values()\n{\n auto r = send_message(\"Hello!\");\n if( !r )\n return r.error();\n\n return compute_value();\n}\n----\n\nIf `BOOST_LEAF_CFG_GNUC_STMTEXPR` is `1` (which is the default under `pass:[__GNUC__]`), `BOOST_LEAF_CHECK` expands to a https://gcc.gnu.org/onlinedocs/gcc/Statement-Exprs.html[GNU C statement expression], which allows its use with non-`void` result types in any expression; see <>.\n\n'''\n\n[[BOOST_LEAF_THROW_EXCEPTION]]\n=== `BOOST_LEAF_THROW_EXCEPTION`\n\n[source,c++]\n.#include \n----\n#define BOOST_LEAF_THROW_EXCEPTION <>\n----\n\nEffects: :: `BOOST_LEAF_THROW_EXCEPTION(e...)` is equivalent to `leaf::<>(e...)`, except the current source location is automatically communicated with the thrown exception, in a `<>` object (in addition to all `e...` objects).\n\n'''\n\n[[BOOST_LEAF_NEW_ERROR]]\n=== `BOOST_LEAF_NEW_ERROR`\n\n.#include \n[source,c++]\n----\n#define BOOST_LEAF_NEW_ERROR <>\n----\n\nEffects: :: `BOOST_LEAF_NEW_ERROR(e...)` is equivalent to `leaf::<>(e...)`, except the current source location is automatically passed, in a `<>` object (in addition to all `e...` objects).\n\n[[rationale]]\n== Design\n\n=== Rationale\n\nDefinition: :: Objects that carry information about error conditions are called error objects. For example, objects of type `std::error_code` are error objects.\n\nNOTE: The following reasoning is independent of the mechanism used to transport error objects, whether it is exception handling or anything else.\n\nDefinition: :: Depending on their interaction with error objects, functions can be classified as follows:\n* *Error initiating*: functions that initiate error conditions by creating new error objects.\n* *Error neutral*: functions that forward to the caller error objects communicated by lower-level functions they call.\n* *Error handling*: functions that dispose of error objects they have received, recovering normal program operation.\n\nA crucial observation is that _error initiating_ functions are typically low-level functions that lack any context and can not determine, much less dictate, the correct program behavior in response to the errors they may initiate. Error conditions which (correctly) lead to termination in some programs may (correctly) be ignored in others; yet other programs may recover from them and resume normal operation.\n\nThe same reasoning applies to _error neutral_ functions, but in this case there is the additional issue that the errors they need to communicate, in general, are initiated by functions multiple levels removed from them in the call chain, functions which usually are -- and should be treated as -- implementation details. An _error neutral_ function should not be coupled with error object types communicated by _error initiating_ functions, for the same reason it should not be coupled with any other aspect of their interface.\n\nFinally, _error handling_ functions, by definition, have the full context they need to deal with at least some, if not all, failures. In their scope it is an absolute necessity that the author knows exactly what information must be communicated by lower level functions in order to recover from each error condition. Specifically, none of this necessary information can be treated as implementation details; in this case, the coupling which is to be avoided in _error neutral_ functions is in fact desirable.\n\nWe're now ready to define our\n\nDesign goals: ::\n* *Error initiating* functions should be able to communicate [underline]#all# information available to them that is relevant to the failure being reported.\n* *Error neutral* functions should not be coupled with error types communicated by lower-level _error initiating_ functions. They should be able to augment any failure with additional relevant information available to them.\n* *Error handling* functions should be able to access all the information communicated by _error initiating_ or _error neutral_ functions that is needed in order to deal with failures.\n\nThe design goal that _error neutral_ functions are not coupled with the static type of error objects that pass through them seems to require dynamic polymorphism and therefore dynamic memory allocations (the Boost Exception library meets this design goal at the cost of dynamic memory allocation).\n\nAs it turns out, dynamic memory allocation is not necessary due to the following\n\nFact: ::\n* *Error handling* functions \"know\" which of the information _error initiating_ and _error neutral_ functions are [.underline]#able# to communicate is [.underline]#actually needed# in order to deal with failures in a particular program. Ideally, no resources should be [.line-through]#used# wasted storing or communicating information which is not currently needed to handle errors, [.underline]#even if it is relevant to the failure#.\n\nFor example, if a library function is able to communicate an error code but the program does not need to know the exact error code, then that information may be ignored at the time the library function attempts to communicate it. On the other hand, if an _error handling_ function needs that information, the memory needed to store it can be reserved statically in its scope.\n\nThe LEAF functions <>, <> and <> implement this idea. Users provide error handling lambda functions, each taking arguments of the types it needs in order to recover from a particular error condition. LEAF simply provides the space needed to store these types (in the form of a `std::tuple`, using automatic storage duration) until they are passed to a suitable handler.\n\nAt the time this space is reserved in the scope of an error handling function, `thread_local` pointers of the required error types are set to point to the corresponding objects within it. Later on, _error initiating_ or _error neutral_ functions wanting to communicate an error object of a given type `E` use the corresponding `thread_local` pointer to detect if there is currently storage available for this type:\n\n* If the pointer is not null, storage is available and the object is moved into the pointed storage, exactly once -- regardless of how many levels of function calls must unwind before an _error handling_ function is reached.\n* If the pointer is null, storage is not available and the error object is discarded, since no error handling function makes any use of it in this program -- saving resources.\n\nThis almost works, except we need to make sure that _error handling_ functions are protected from accessing stale error objects stored in response to previous failures, which would be a serious logic error. To this end, each occurrence of an error is assigned a unique <>. Each of the `E...` objects stored in error handling scopes is assigned an `error_id` as well, permanently associating it with a particular failure.\n\nThus, to handle a failure we simply match the available error objects (associated with its unique `error_id`) with the argument types required by each user-provided error handling function. In terms of {CPP} exception handling, it is as if we could write something like:\n\n[source,c++]\n----\ntry\n{\n auto r = process_file();\n\n //Success, use r:\n ....\n}\n\ncatch(file_read_error &, e_file_name const & fn, e_errno const & err)\n{\n std::cerr <<\n \"Could not read \" << fn << \", errno=\" << err << std::endl;\n}\n\ncatch(file_read_error &, e_errno const & err)\n{\n std::cerr <<\n \"File read error, errno=\" << err << std::endl;\n}\n\ncatch(file_read_error &)\n{\n std::cerr << \"File read error!\" << std::endl;\n}\n----\n\nOf course this syntax is not valid, so LEAF uses lambda functions to express the same idea:\n\n[source,c++]\n----\nleaf::try_catch(\n\n []\n {\n auto r = process_file(); //Throws in case of failure, error objects stored inside the try_catch scope\n\n //Success, use r:\n ....\n }\n\n [](file_read_error &, e_file_name const & fn, e_errno const & err)\n {\n std::cerr <<\n \"Could not read \" << fn << \", errno=\" << err << std::endl;\n },\n\n [](file_read_error &, e_errno const & err)\n {\n std::cerr <<\n \"File read error, errno=\" << err << std::endl;\n },\n\n [](file_read_error &)\n {\n std::cerr << \"File read error!\" << std::endl;\n } );\n----\n\n[.text-right]\n<> | <> | <>\n\nSimilar syntax works without exception handling as well. Below is the same snippet, written using `<>`:\n\n[source,c++]\n----\nreturn leaf::try_handle_some(\n\n []() -> leaf::result\n {\n BOOST_LEAF_AUTO(r, process_file()); //In case of errors, error objects are stored inside the try_handle_some scope\n\n //Success, use r:\n ....\n\n return { };\n }\n\n [](leaf::match, e_file_name const & fn, e_errno const & err)\n {\n std::cerr <<\n \"Could not read \" << fn << \", errno=\" << err << std::endl;\n },\n\n [](leaf::match, e_errno const & err)\n {\n std::cerr <<\n \"File read error, errno=\" << err << std::endl;\n },\n\n [](leaf::match)\n {\n std::cerr << \"File read error!\" << std::endl;\n } );\n----\n\n[.text-right]\n<> | <> | <> | <> | <>\n\nNOTE: Please post questions and feedback on the Boost Developers Mailing List.\n\n'''\n\n[[exception_specifications]]\n=== Critique 1: Error Types Do Not Participate in Function Signatures\n\nA knee-jerk critique of the LEAF design is that it does not statically enforce that each possible error condition is recognized and handled by the program. One idea I've heard from multiple sources is to add `E...` parameter pack to `result`, essentially turning it into `expected`, so we could write something along these lines:\n\n[source,c++]\n----\nexpected f() noexcept; <1>\n\nexpected g() noexcept <2>\n{\n if( expected r = f() )\n {\n return r; //Success, return the T\n }\n else\n {\n return r.handle_error( [] ( .... ) <3>\n {\n ....\n } );\n }\n}\n----\n<1> `f` may only return error objects of type `E1`, `E2`, `E3`.\n<2> `g` narrows that to only `E1` and `E3`.\n<3> Because `g` may only return error objects of type `E1` and `E3`, it uses `handle_error` to deal with `E2`. In case `r` contains `E1` or `E3`, `handle_error` simply returns `r`, narrowing the error type parameter pack from `E1, E2, E3` down to `E1, E3`. If `r` contains an `E2`, `handle_error` calls the supplied lambda, which is required to return one of `E1`, `E3` (or a valid `T`).\n\nThe motivation here is to help avoid bugs in functions that handle errors that pop out of `g`: as long as the programmer deals with `E1` and `E3`, he can rest assured that no error is left unhandled.\n\nCongratulations, we've just discovered exception specifications. The difference is that exception specifications, before being removed from {CPP}, were enforced dynamically, while this idea is equivalent to statically-enforced exception specifications, like they are in Java.\n\nWhy not use the equivalent of exception specifications, even if they are enforced statically?\n\n\"The short answer is that nobody knows how to fix exception specifications in any language, because the dynamic enforcement {CPP} chose has only different (not greater or fewer) problems than the static enforcement Java chose. ... When you go down the Java path, people love exception specifications until they find themselves all too often encouraged, or even forced, to add `throws Exception`, which immediately renders the exception specification entirely meaningless. (Example: Imagine writing a Java generic that manipulates an arbitrary type `T`).footnote:[https://herbsutter.com/2007/01/24/questions-about-exception-specifications/]\"\n-- Herb Sutter\n\nConsider again the example above: assuming we don't want important error-related information to be lost, values of type `E1` and/or `E3` must be able to encode any `E2` value dynamically. But like Sutter points out, in generic contexts we don't know what errors may result in calling a user-supplied function. The only way around that is to specify a single type (e.g. `std::error_code`) that can communicate any and all errors, which ultimately defeats the idea of using static type checking to enforce correct error handling.\n\nThat said, in every program there are certain _error handling_ functions (e.g. `main`) which are required to handle any error, and it is highly desirable to be able to enforce this requirement at compile-time. In LEAF, the `try_handle_all` function implements this idea: if the user fails to supply at least one handler that will match any error, the result is a compile error. This guarantees that the scope invoking `try_handle_all` is prepared to recover from any failure.\n\n'''\n\n[[translation]]\n=== Critique 2: LEAF Does Not Facilitate Mapping Between Different Error Types\n\nMost {CPP} programs use multiple C and {CPP} libraries, and each library may provide its own system of error codes. But because it is difficult to define static interfaces that can communicate arbitrary error code types, a popular idea is to map each library-specific error code to a common program-wide enum.\n\nFor example, if we have --\n\n[source,c++,options=\"nowrap\"]\n----\nnamespace lib_a\n{\n enum error\n {\n ok,\n ec1,\n ec2,\n ....\n };\n}\n----\n\n[source,c++,options=\"nowrap\"]\n----\nnamespace lib_b\n{\n enum error\n {\n ok,\n ec1,\n ec2,\n ....\n };\n}\n----\n\n-- we could define:\n\n[source,c++]\n----\nnamespace program\n{\n enum error\n {\n ok,\n lib_a_ec1,\n lib_a_ec2,\n ....\n lib_b_ec1,\n lib_b_ec2,\n ....\n };\n}\n----\n\nAn error handling library could provide conversion API that uses the {CPP} static type system to automate the mapping between the different error enums. For example, it may define a class template `result` with value-or-error variant semantics, so that:\n\n* `lib_a` errors are transported in `result`,\n* `lib_b` errors are transported in `result`,\n* then both are automatically mapped to `result` once control reaches the appropriate scope.\n\nThere are several problems with this idea:\n\n* It is prone to errors, both during the initial implementation as well as under maintenance.\n\n* It does not compose well. For example, if both of `lib_a` and `lib_b` use `lib_c`, errors that originate in `lib_c` would be obfuscated by the different APIs exposed by each of `lib_a` and `lib_b`.\n\n* It presumes that all errors in the program can be specified by exactly one error code, which is false.\n\nTo elaborate on the last point, consider a program that attempts to read a configuration file from three different locations: in case all of the attempts fail, it should communicate each of the failures. In theory `result` handles this case well:\n\n[source,c++]\n----\nstruct attempted_location\n{\n std::string path;\n error ec;\n};\n\nstruct config_error\n{\n attempted_location current_dir, user_dir, app_dir;\n};\n\nresult read_config();\n----\n\nThis looks nice, until we realize what the `config_error` type means for the automatic mapping API we wanted to define: an `enum` can not represent a `struct`. It is a fact that we can not assume that all error conditions can be fully specified by an `enum`; an error handling library must be able to transport arbitrary static types efficiently.\n\n[[errors_are_not_implementation_details]]\n=== Critique 3: LEAF Does Not Treat Low Level Error Types as Implementation Details\n\nThis critique is a combination of <> and <>, but it deserves special attention. Let's consider this example using LEAF:\n\n[source,c++]\n----\nleaf::result read_line( reader & r );\n\nleaf::result parse_line( std::string const & line );\n\nleaf::result read_and_parse_line( reader & r )\n{\n BOOST_LEAF_AUTO(line, read_line(r)); <1>\n BOOST_LEAF_AUTO(parsed, parse_line(line)); <2>\n return parsed;\n}\n----\n[.text-right]\n<> | <>\n\n<1> Read a line, forward errors to the caller.\n<2> Parse the line, forward errors to the caller.\n\nThe objection is that LEAF will forward verbatim the errors that are detected in `read_line` or `parse_line` to the caller of `read_and_parse_line`. The premise of this objection is that such low-level errors are implementation details and should be treated as such. Under this premise, `read_and_parse_line` should act as a translator of sorts, in both directions:\n\n* When called, it should translate its own arguments to call `read_line` and `parse_line`;\n* If an error is detected, it should translate the errors from the error types returned by `read_line` and `parse_line` to a higher-level type.\n\nThe motivation is to isolate the caller of `read_and_parse_line` from its implementation details `read_line` and `parse_line`.\n\nThere are two possible ways to implement this translation:\n\n*1)* `read_and_parse_line` understands the semantics of *all possible failures* that may be reported by both `read_line` and `parse_line`, implementing a non-trivial mapping which both _erases_ information that is considered not relevant to its caller, as well as encodes _different_ semantics in the error it reports. In this case `read_and_parse_line` assumes full responsibility for describing precisely what went wrong, using its own type specifically designed for the job.\n\n*2)* `read_and_parse_line` returns an error object that essentially indicates which of the two inner functions failed, and also transports the original error object without understanding its semantics and without any loss of information, wrapping it in a new error type.\n\nThe problem with *1)* is that typically the caller of `read_and_parse_line` is not going to handle the error, but it does need to forward it to its caller. In our attempt to protect the *one* error handling function from \"implementation details\", we've coupled the interface of *all* intermediate error neutral functions with the static types of errors they do not understand and do not handle.\n\nConsider the case where `read_line` communicates `errno` in its errors. What is `read_and_parse_line` supposed to do with e.g. `EACCESS`? Turn it into `READ_AND_PARSE_LINE_EACCESS`? To what end, other than to obfuscate the original (already complex and platform-specific) semantics of `errno`?\n\nAnd what if the call to `read` is polymorphic, which is also typical? What if it involves a user-supplied function object? What kinds of errors does it return and why should `read_and_parse_line` care?\n\nTherefore, we're left with *2)*. There's almost nothing wrong with this option, since it passes any and all error-related information from lower level functions without any loss. However, using a wrapper type to grant (presumably dynamic) access to any lower-level error type it may be transporting is cumbersome and (like Niall Douglas <>) in general probably requires dynamic allocations. It is better to use independent error types that communicate the additional information not available in the original error object, while error handlers rely on LEAF to provide efficient access to any and all low-level error types, as needed.\n\n== Alternatives to LEAF\n\n* https://www.boost.org/doc/libs/release/libs/exception/doc/boost-exception.html[Boost Exception]\n* https://ned14.github.io/outcome[Boost Outcome]\n* https://github.com/TartanLlama/expected[`tl::expected`]\n\nBelow we offer a comparison of Boost LEAF to Boost Exception and to Boost Outcome.\n\n[[boost_exception]]\n=== Comparison to Boost Exception\n\nWhile LEAF can be used without exception handling, in the use case when errors are communicated by throwing exceptions, it can be viewed as a better, more efficient alternative to Boost Exception. LEAF has the following advantages over Boost Exception:\n\n* LEAF does not allocate memory dynamically;\n* LEAF does not waste system resources communicating error objects not used by specific error handling functions;\n* LEAF does not store the error objects in the exception object, and therefore it is able to augment exceptions thrown by external libraries (Boost Exception can only augment exceptions of types that derive from `boost::exception`).\n\nThe following tables outline the differences between the two libraries which should be considered when code that uses Boost Exception is refactored to use LEAF instead.\n\nNOTE: It is possible to access Boost Exception error information using the LEAF error handling interface. See <>.\n\n.Defining a custom type for transporting values of type T\n[cols=\"1a,1a\",options=\"header\",stripes=none]\n|====\n| Boost Exception | LEAF\n|\n[source,c++,options=\"nowrap\"]\n----\ntypedef error_info my_info;\n----\n[.text-right]\nhttps://www.boost.org/doc/libs/release/libs/exception/doc/error_info.html[`boost::error_info`]\n|\n[source,c++,options=\"nowrap\"]\n----\nstruct my_info { T value; };\n----\n|====\n\n.Passing arbitrary info at the point of the throw\n[cols=\"1a,1a\",options=\"header\",stripes=none]\n|====\n| Boost Exception | LEAF\n|\n[source,c++,options=\"nowrap\"]\n----\nthrow my_exception() <<\n my_info(x) <<\n my_info(y);\n----\n[.text-right]\nhttps://www.boost.org/doc/libs/release/libs/exception/doc/exception_operator_shl.html[`operator<<`]\n|\n[source,c++,options=\"nowrap\"]\n----\nleaf::throw_exception( my_exception(),\n my_info{x},\n my_info{y} );\n----\n[.text-right]\n<>\n|====\n\n.Augmenting exceptions in error neutral contexts\n[cols=\"1a,1a\",options=\"header\",stripes=none]\n|====\n| Boost Exception | LEAF\n|\n[source,c++,options=\"nowrap\"]\n----\ntry\n{\n f();\n}\ncatch( boost::exception & e )\n{\n e << my_info(x);\n throw;\n}\n----\n[.text-right]\nhttps://www.boost.org/doc/libs/release/libs/exception/doc/exception.html[`boost::exception`] \\| https://www.boost.org/doc/libs/release/libs/exception/doc/exception_operator_shl.html[`operator<<`]\n|\n[source,c++,options=\"nowrap\"]\n----\nauto load = leaf::on_error( my_info{x} );\n\nf();\n----\n[.text-right]\n<>\n|====\n\n.Obtaining arbitrary info at the point of the catch\n[cols=\"1a,1a\",options=\"header\",stripes=none]\n|====\n| Boost Exception | LEAF\n|\n[source,c++,options=\"nowrap\"]\n----\ntry\n{\n f();\n}\ncatch( my_exception & e )\n{\n if( T * v = get_error_info(e) )\n {\n //my_info is available in e.\n }\n}\n----\n[.text-right]\nhttps://www.boost.org/doc/libs/release/libs/exception/doc/get_error_info.html[`boost::get_error_info`]\n|\n[source,c++,options=\"nowrap\"]\n----\nleaf::try_catch(\n []\n {\n f(); // throws\n }\n [](my_exception &, my_info const & x)\n {\n //my_info is available with\n //the caught exception.\n } );\n----\n[.text-right]\n<>\n|====\n\n.Transporting of error objects\n[cols=\"1a,1a\",options=\"header\",stripes=none]\n|====\n| Boost Exception | LEAF\n| All supplied https://www.boost.org/doc/libs/release/libs/exception/doc/error_info.html[`boost::error_info`] objects are allocated dynamically and stored in the https://www.boost.org/doc/libs/release/libs/exception/doc/exception.html[`boost::exception`] subobject of exception objects.\n| User-defined error objects are stored statically in the scope of <>, but only if their types are needed to handle errors; otherwise they are discarded.\n|====\n\n.Transporting of error objects across thread boundaries\n[cols=\"1a,1a\",options=\"header\",stripes=none]\n|====\n| Boost Exception | LEAF\n| https://www.boost.org/doc/libs/release/libs/exception/doc/exception_ptr.html[`boost::exception_ptr`] automatically captures https://www.boost.org/doc/libs/release/libs/exception/doc/error_info.html[`boost::error_info`] objects stored in a `boost::exception` and can transport them across thread boundaries.\n| Transporting error objects across thread boundaries requires the use of <>.\n|====\n\n.Printing of error objects in automatically-generated diagnostic information messages\n[cols=\"1a,1a\",options=\"header\",stripes=none]\n|====\n| Boost Exception | LEAF\n| `boost::error_info` types may define conversion to `std::string` by providing `to_string` overloads *or* by overloading `operator<<` for `std::ostream`.\n| LEAF does not use `to_string`. Error types may define `operator<<` overloads for `std::ostream`.\n|====\n\n[WARNING]\n====\nThe fact that Boost Exception stores all supplied `boost::error_info` objects -- while LEAF discards them if they aren't needed -- affects the completeness of the message we get when we print `leaf::<>` objects, compared to the string returned by https://www.boost.org/doc/libs/release/libs/exception/doc/diagnostic_information.html[`boost::diagnostic_information`].\n\nIf the user requires a complete diagnostic message, the solution is to use `leaf::<>`. In this case, before unused error objects are discarded by LEAF, they are converted to string and printed. Note that this allocates memory dynamically.\n====\n\n'''\n\n[[boost_outcome]]\n=== Comparison to Boost Outcome\n\n==== Design Differences\n\nLike LEAF, the https://ned14.github.io/outcome[Boost Outcome] library is designed to work in low latency environments. It provides two class templates, `result<>` and `outcome<>`:\n\n* `result` can be used as the return type in `noexcept` functions which may fail, where `T` specifies the type of the return value in case of success, while `EC` is an \"error code\" type. Semantically, `result` is similar to `std::variant`. Naturally, `EC` defaults to `std::error_code`.\n* `outcome` is similar to `result<>`, but in case of failure, in addition to the \"error code\" type `EC` it can hold a \"pointer\" object of type `EP`, which defaults to `std::exception_ptr`.\n\nNOTE: `NVP` is a policy type used to customize the behavior of `.value()` when the `result<>` or the `outcome<>` object contains an error.\n\nThe idea is to use `result<>` to communicate failures which can be fully specified by an \"error code\", and `outcome<>` to communicate failures that require additional information.\n\nAnother way to describe this design is that `result<>` is used when it suffices to return an error object of some static type `EC`, while `outcome<>` can also transport a polymorphic error object, using the pointer type `EP`.\n\nNOTE: In the default configuration of `outcome` the additional information -- or the additional polymorphic object -- is an exception object held by `std::exception_ptr`. This targets the use case when an exception thrown by a lower-level library function needs to be transported through some intermediate contexts that are not exception-safe, to a higher-level context able to handle it. LEAF directly supports this use as well, see <>.\n\nSimilar reasoning drives the design of LEAF as well. The difference is that while both libraries recognize the need to transport \"something else\" in addition to an \"error code\", LEAF provides an efficient solution to this problem, while Outcome shifts this burden to the user.\n\nThe `leaf::result<>` template deletes both `EC` and `EP`, which decouples it from the type of the error objects that are transported in case of a failure. This enables lower-level functions to freely communicate anything and everything they \"know\" about the failure: error code, even multiple error codes, file names, URLs, port numbers, etc. At the same time, the higher-level error handling functions control which of this information is needed in a specific client program and which is not. This is ideal, because:\n\n* Authors of lower-level library functions lack context to determine which of the information that is both relevant to the error _and_ naturally available to them needs to be communicated in order for a particular client program to recover from that error;\n* Authors of higher-level error handling functions can easily and confidently make this determination, which they communicate naturally to LEAF, by simply writing the different error handlers. LEAF will transport the needed error objects while discarding the ones handlers don't care to use, saving resources.\n\nTIP: The LEAF examples include an adaptation of the program from the https://ned14.github.io/outcome/tutorial/essential/result/[Boost Outcome `result<>` tutorial]. You can https://github.com/boostorg/leaf/blob/master/example/print_half.cpp?ts=4[view it on GitHub].\n\nNOTE: Programs using LEAF for error handling are not required to use `leaf::result`; for example, it is possible to use `outcome::result` with LEAF.\n\n[[interoperability]]\n==== The Interoperability Problem\n\nThe Boost Outcome documentation discusses the important problem of bringing together multiple libraries -- each using its own error reporting mechanism -- and incorporating them in a robust error handling infrastructure in a client program.\n\nUsers are advised that whenever possible they should use a common error handling system throughout their entire codebase, but because this is not practical, both the `result<>` and the `outcome<>` templates can carry user-defined \"payloads\".\n\nThe following analysis is from the Boost Outcome documentation:\n====\nIf library A uses `result`, and library B uses `result` and so on, there becomes a problem for the application writer who is bringing in these third party dependencies and tying them together into an application. As a general rule, each third party library author will not have built in explicit interoperation support for unknown other third party libraries. The problem therefore lands with the application writer.\n\nThe application writer has one of three choices:\n\n. In the application, the form of result used is `result>` where `E1, E2 …` are the failure types for every third party library in use in the application. This has the advantage of preserving the original information exactly, but comes with a certain amount of use inconvenience and maybe excessive coupling between high level layers and implementation detail.\n\n. One can translate/map the third party’s failure type into the application’s failure type at the point of the failure exiting the third party library and entering the application. One might do this, say, with a C preprocessor macro wrapping every invocation of the third party API from the application. This approach may lose the original failure detail, or mis-map under certain circumstances if the mapping between the two systems is not one-one.\n\n. One can type erase the third party’s failure type into some application failure type, which can later be reconstituted if necessary. *This is the cleanest solution with the least coupling issues and no problems with mis-mapping*, but it almost certainly requires the use of `malloc` which the previous two did not.\n====\n\nThe analysis above (emphasis added) is clear and precise, but LEAF and Boost Outcome tackle the interoperability problem differently:\n\n* The Boost Outcome design asserts that the \"cleanest\" solution based on type-erasure is suboptimal (\"almost certainly requires the use of `malloc`pass:[]\"), and instead provides a system for injecting custom converters into the `outcome::convert` namespace, used to translate between library-specific and program-wide error types, even though this approach \"may lose the original failure detail\".\n\n* The LEAF design asserts that coupling the signatures of <> functions with the static types of the error objects they need to forward to the caller <>, and instead transports error objects directly to error handling scopes where they are stored statically, effectively implementing the third choice outlined above (without the use of `malloc`).\n\nFurther, consider that Outcome aims to hopefully become _the_ one error handling API all libraries would use, and in theory everyone would benefit from uniformity and standardization. But the reality is that this is wishful thinking. In fact, that reality is reflected in the design of `outcome::result<>`, in its lack of commitment to using `std::error_code` for its intended purpose: to be _the_ standard type for transporting error codes. The fact is that `std::error_code` became _yet another_ error code type programmers need to understand and support.\n\nIn contrast, the design of LEAF acknowledges that {CPP} programmers don't even agree on what a string is. If your project uses 10 different libraries, this probably means 15 different ways to report errors, sometimes across uncooperative interfaces (e.g. C APIs). LEAF helps you get the job done.\n\n== Benchmark\n\nhttps://github.com/boostorg/leaf/blob/master/benchmark/benchmark.md[This benchmark] compares the performance of LEAF, Boost Outcome and `tl::expected`.\n\n== Running the Unit Tests\n\nThe unit tests can be run with https://mesonbuild.com[Meson Build] or with Boost Build. To run the unit tests:\n\n=== Meson Build\n\nClone LEAF into any local directory and execute:\n\n[source,sh]\n----\ncd leaf\nmeson bld/debug\ncd bld/debug\nmeson test\n----\n\nSee `meson_options.txt` found in the root directory for available build options.\n\n=== Boost Build\n\nAssuming the current working directory is `/libs/leaf`:\n\n[source,sh]\n----\n../../b2 test\n----\n\n[[configuration]]\n== Configuration\n\nThe following configuration macros are recognized:\n\n* `BOOST_LEAF_CFG_DIAGNOSTICS`: Defining this macro as `0` stubs out both <> and <> (if the macro is left undefined, LEAF defines it as `1`).\n\n* `BOOST_LEAF_CFG_STD_SYSTEM_ERROR`: Defining this macro as `0` disables the `std::error_code` / `std::error_condition` integration. In this case LEAF does not `#include `, which may be too heavy for embedded platforms (if the macro is left undefined, LEAF defines it as `1`).\n\n* `BOOST_LEAF_CFG_STD_STRING`: Defining this macro as `0` disables all use of `std::string` (this requires `BOOST_LEAF_CFG_DIAGNOSTICS=0` as well). In this case LEAF does not `#include ` which may be too heavy for embedded platforms (if the macro is left undefined, LEAF defines it as `1`).\n\n* `BOOST_LEAF_CFG_CAPTURE`: Defining this macro as `0` disables the ability of `leaf::result` to transport errors between threads. In this case LEAF does not `#include `, which may be too heavy for embedded platforms (if the macro is left undefined, LEAF defines it as `1`).\n\n* `BOOST_LEAF_CFG_GNUC_STMTEXPR`: This macro controls whether or not <> is defined in terms of a https://gcc.gnu.org/onlinedocs/gcc/Statement-Exprs.html[GNU C statement expression], which enables its use to check for errors similarly to how the questionmark operator works in some languages (see <>). By default the macro is defined as `1` under `pass:[__GNUC__]`, otherwise as `0`.\n\n* `BOOST_LEAF_CFG_WIN32`: Defining this macro as 1 enables the default constructor in <>, and the automatic conversion to string (via `FormatMessageA`) when <> is printed. If the macro is left undefined, LEAF defines it as `0` (even on windows, since including `windows.h` is generally not desirable). Note that the `e_LastError` type itself is available on all platforms, there is no need for conditional compilation in error handlers that use it.\n\n* `BOOST_LEAF_NO_EXCEPTIONS`: Disables all exception handling support. If left undefined, LEAF defines it automatically based on the compiler configuration (e.g. `-fno-exceptions`).\n\n* `BOOST_LEAF_NO_THREADS`: Disables all thread safety in LEAF.\n\n[[configuring_tls_access]]\n=== Configuring TLS Access\n\nLEAF requires support for thread-local `void` pointers. By default, this is implemented by means of the {CPP}11 `thread_local` keyword, but in order to support <>, it is possible to configure LEAF to use an array of thread local pointers instead, by defining `BOOST_LEAF_USE_TLS_ARRAY`. In this case, the user is required to define the following two functions to implement the required TLS access:\n\n[source,c++]\n----\nnamespace boost { namespace leaf {\n\nnamespace tls\n{\n void * read_void_ptr( int tls_index ) noexcept;\n void write_void_ptr( int tls_index, void * p ) noexcept;\n}\n\n} }\n----\n\nTIP: For efficiency, `read_void_ptr` and `write_void_ptr` should be defined `inline`.\n\nUnder `BOOST_LEAF_USE_TLS_ARRAY` the following additional configuration macros are recognized:\n\n* `BOOST_LEAF_CFG_TLS_ARRAY_START_INDEX` specifies the start TLS array index available to LEAF (if the macro is left undefined, LEAF defines it as `0`).\n\n* `BOOST_LEAF_CFG_TLS_ARRAY_SIZE` may be defined to specify the size of the TLS array. In this case TLS indices are validated via `BOOST_LEAF_ASSERT` before being passed to `read_void_ptr` / `write_void_ptr`.\n\n* `BOOST_LEAF_CFG_TLS_INDEX_TYPE` may be defined to specify the integral type used to store assigned TLS indices (if the macro is left undefined, LEAF defines it as `unsigned char`).\n\nTIP: Reporting error objects of types that are not used by the program to handle failures does not consume TLS pointers. The minimum size of the TLS pointer array required by LEAF is the total number of different types used as arguments to error handlers (in the entire program), plus one.\n\nWARNING: Beware of `read_void_ptr`/`write_void_ptr` accessing thread local pointers beyond the static boundaries of the thread local pointer array; this will likely result in undefined behavior.\n\n[[embedded_platforms]]\n=== Embedded Platforms\n\nDefining `BOOST_LEAF_EMBEDDED` is equivalent to the following:\n\n[source,c++]\n----\n#ifndef BOOST_LEAF_CFG_DIAGNOSTICS\n# define BOOST_LEAF_CFG_DIAGNOSTICS 0\n#endif\n\n#ifndef BOOST_LEAF_CFG_STD_SYSTEM_ERROR\n# define BOOST_LEAF_CFG_STD_SYSTEM_ERROR 0\n#endif\n\n#ifndef BOOST_LEAF_CFG_STD_STRING\n# define BOOST_LEAF_CFG_STD_STRING 0\n#endif\n\n#ifndef BOOST_LEAF_CFG_CAPTURE\n# define BOOST_LEAF_CFG_CAPTURE 0\n#endif\n----\n\nLEAF supports FreeRTOS out of the box, please define `BOOST_LEAF_TLS_FREERTOS` (in which case LEAF automatically defines `BOOST_LEAF_EMBEDDED`, if it is not defined already).\n\nFor other embedded platforms, please define `BOOST_LEAF_USE_TLS_ARRAY`, see <>.\n\nIf your program does not use concurrency at all, simply define `BOOST_LEAF_NO_THREADS`, which requires no TLS support at all (but is NOT thread-safe).\n\n[[portability]]\n== Portability\n\nThe source code is compatible with {CPP}11 or newer.\n\nLEAF uses thread-local storage (only for pointers). By default, this is implemented via the {CPP}11 `thread_local` storage class specifier, but the library is easily configurable to use any platform-specific TLS API instead (it ships with built-in support for FreeRTOS). See <>.\n\n== Limitations\n\nWhen using dynamic linking, it is required that error types are declared with `default` visibility, e.g.:\n\n[source,c++]\n----\nstruct __attribute__ ((visibility (\"default\"))) my_error_info\n{\n int value;\n};\n----\n\nThis works as expected except on Windows, where thread-local storage is not shared between the individual binary modules. For this reason, to transport error objects across DLL boundaries, it is required that they're captured in a <>, just like when <>.\n\nTIP: When using dynamic linking, it is always best to define module interfaces in terms of C (and implement them in {CPP} if appropriate).\n\n== Acknowledgements\n\nSpecial thanks to Peter Dimov and Sorin Fetche.\n\nIvo Belchev, Sean Palmer, Jason King, Vinnie Falco, Glen Fernandes, Augustín Bergé -- thanks for the valuable feedback.\n\nDocumentation rendered by https://asciidoctor.org/[Asciidoctor] with https://github.com/zajo/asciidoctor_skin[these customizations].\n" }, { "path": "doc/rouge-github.css", "content": ".highlight table td { padding: 5px; }\n.highlight table pre { margin: 0; }\n.highlight .cm {\n color: #999988;\n font-style: italic;\n}\n.highlight .cp {\n color: #999999;\n font-weight: bold;\n}\n.highlight .c1 {\n color: #999988;\n font-style: italic;\n}\n.highlight .cs {\n color: #999999;\n font-weight: bold;\n font-style: italic;\n}\n.highlight .c, .highlight .cd {\n color: #999988;\n font-style: italic;\n}\n.highlight .err {\n}\n.highlight .gd {\n color: #000000;\n background-color: #ffdddd;\n}\n.highlight .ge {\n color: #000000;\n font-style: italic;\n}\n.highlight .gr {\n color: #aa0000;\n}\n.highlight .gh {\n color: #999999;\n}\n.highlight .gi {\n color: #000000;\n background-color: #ddffdd;\n}\n.highlight .go {\n color: #888888;\n}\n.highlight .gp {\n color: #555555;\n}\n.highlight .gs {\n font-weight: bold;\n}\n.highlight .gu {\n color: #aaaaaa;\n}\n.highlight .gt {\n color: #aa0000;\n}\n.highlight .kc {\n font-weight: bold;\n}\n.highlight .kd {\n font-weight: bold;\n}\n.highlight .kn {\n font-weight: bold;\n}\n.highlight .kp {\n font-weight: bold;\n}\n.highlight .kr {\n font-weight: bold;\n}\n.highlight .kt {\n color: #445588;\n font-weight: bold;\n}\n.highlight .k, .highlight .kv {\n font-weight: bold;\n}\n.highlight .mf {\n color: #009999;\n}\n.highlight .mh {\n color: #009999;\n}\n.highlight .il {\n color: #009999;\n}\n.highlight .mi {\n color: #009999;\n}\n.highlight .mo {\n color: #009999;\n}\n.highlight .m, .highlight .mb, .highlight .mx {\n color: #009999;\n}\n.highlight .sb {\n color: #d14;\n}\n.highlight .sc {\n color: #d14;\n}\n.highlight .sd {\n color: #d14;\n}\n.highlight .s2 {\n color: #d14;\n}\n.highlight .se {\n color: #d14;\n}\n.highlight .sh {\n color: #d14;\n}\n.highlight .si {\n color: #d14;\n}\n.highlight .sx {\n color: #d14;\n}\n.highlight .sr {\n color: #009926;\n}\n.highlight .s1 {\n color: #d14;\n}\n.highlight .ss {\n color: #990073;\n}\n.highlight .s {\n color: #d14;\n}\n.highlight .na {\n color: #008080;\n}\n.highlight .bp {\n color: #999999;\n}\n.highlight .nb {\n color: #0086B3;\n}\n.highlight .nc {\n color: #445588;\n font-weight: bold;\n}\n.highlight .no {\n color: #008080;\n}\n.highlight .nd {\n color: #3c5d5d;\n font-weight: bold;\n}\n.highlight .ni {\n color: #800080;\n}\n.highlight .ne {\n color: #990000;\n font-weight: bold;\n}\n.highlight .nf {\n color: #990000;\n font-weight: bold;\n}\n.highlight .nl {\n color: #990000;\n font-weight: bold;\n}\n.highlight .nn {\n color: #555555;\n}\n.highlight .nt {\n color: #000080;\n}\n.highlight .vc {\n color: #008080;\n}\n.highlight .vg {\n color: #008080;\n}\n.highlight .vi {\n color: #008080;\n}\n.highlight .nv {\n color: #008080;\n}\n.highlight .ow {\n font-weight: bold;\n}\n.highlight .o {\n font-weight: bold;\n}\n.highlight .o {\n font-weight: bold;\n}\n.highlight .w {\n color: #bbbbbb;\n}\n" }, { "path": "doc/whitepaper.md", "content": "# Error Handling Principles and Practices\n\n## Abstract\n\nError handling is an important part of language design and programming in general. We deconstruct the problem domain in an attempt to derive an objective understanding of the pros and cons of the various approaches to error handling. While we use C++ throughout this paper, our reasoning applies to any statically-typed language.\n\nWe present, with implementation, a novel method for communication of error objects of arbitrary types safely, without using dynamic memory allocation. In addition, we analyze the effect of aggressive inlining on the overhead of exception handling in C++, without a need to change the standard or the ABIs.\n\n## 1. The semantics of a failure\n\nProgrammers have an intuitive understanding of the nature of error handling: while coding, we naturally reason in terms of \"what if something goes wrong\". One way to express this reasoning is to return from functions which may fail some `expected` variant type, which holds a `T` in case of success or an `E` in case of failure. For example:\n\n```c++\nexpected compute_value();\n```\n\nAbove, `compute_value` produces an `int`, but if that fails, it would communicate an object of type `error_code`, which would indicate the reason for the failure.\n\nBut here is an interesting question: what happens if the type we pass for `T` to `expected` is itself a variant type? Of course this isn't a problem:\n\n```c++\nexpected, error_code> compute_value(); // (A)\n```\n\nWhat makes the above function interesting is that syntactically, it returns an `int`, or a `float`, or an `error_code`; and since we're already returning a variant, could we ditch `expected` altogether? We most definitely could:\n\n```c++\nvariant compute_value(); // (B)\n```\n\nAre the two functions (A) and (B) semantically equivalent? It appears that any algorithm working with the result from (A) can be transformed to handle a call to (B) without any loss of functionality. This follows directly form the fact that either way there are three distinct outcomes, so the differences should be purely mechanical rather than in logic.\n\nIn fact there is one subtle but critical difference: (A) encodes explicitly in the return object an additional bit of information -- \"success-or-error\" -- while in (B) that knowledge is implicit: we have to keep it in mind as we write the caller function, but it is not reflected in the program state.\n\n> **Definition:** The one bit of information that indicates whether a function has failed is called the *failure flag*.\n\nTherefore it is not true that any algorithm working with the result from (A) can be transformed to handle a call to (B): the exception is algorithms that respond generically to any error, based solely on observing the *failure flag* being set. The ability to implement such algorithms is the reason why explicitly encoding this extra bit of information in (A) is not pure overhead, compared to (B).\n\nOf course, this reasoning applies in general: if a function reports a failure, it is important for the caller to be able to react to it without further semantic understanding of each possible error condition; that is, it is a good idea to optimize error handling for this relatively common use case.\n\n## 2. Classification of functions based on their affinity to errors\n\n> **Definition:** Functions that create error objects and initiate error handling are called *error initiating* functions.\n\nThese are functions which, based on the semantics of the operations they perform, flag certain outcomes as failures, reporting the causes to their caller.\n\n> **Definition:** Functions which forward to the caller error information communicated by lower-level functions are called *error neutral* functions.\n\nThese functions react solely based on the [*failure flag*](#1-the-semantics-of-a-failure) indicated by a lower-level function, forwarding failures to the caller without understanding the semantics of the error (\"something went wrong\").\n\nFor example, an *error initiating* function may initialize a new `std::error_code` object to describe a failure, while an *error neutral* function may just forward the `std::error_code` returned by a lower-level function to its own caller.\n\nOf course, *error neutral* functions may contribute additional error information. The key difference between *error initiating* and *error neutral* functions is that the latter do not understand the semantics of lower-level failures, they simply react based on the value of the *failure flag*.\n\n> **Definition:**\n> Functions which dispose of error objects they have received and recover normal program operation are called *error handling* functions.\n\nAll information communicated by *error initiating* and *error neutral* functions in case of a failure targets an *error handling* function found up the call stack. In order to take appropriate action to resume normal program operation, that function must understand the semantics of at least some possible error conditions that may occur in lower-level functions (the exception is functions that act as catch-all handlers, which are designed to recover from any and all error conditions, possibly after logging all available relevant information.)\n\nNote that an *error handling* function may act as *error neutral* as well, by forwarding to its caller some failures it does not recognize and therefore can not recover from.\n\n## 3. Types of error information based on context\n\nConsider a function which opens a file using [`open()`](http://man7.org/linux/man-pages/man2/open.2.html), reads it then parses it. If it fails, we need to know what failed:\n\n* Did the file fail to open?\n* Was the file opened successfully but the attempt to read it failed?\n* Was there a parsing error after the file was successfully read?\n\nSuch simple booleans may be sufficient sometimes, but usually they are not. Reasonably, we need to respond differently depending on whether the call to `open()` resulted in `ENOENT` vs. `EACCESS` -- and if we got `EEXIST`, that would be a logic error. Therefore we need to know the relevant `errno` also.\n\nSecondly, if the file failed to open, we need to know the `pathname` passed to `open()`, in case it happens to be incorrect. But what if it is correct and yet `open()` failed? Right, we probably need to know the `flags` argument passed to `open()` as well.\n\nSimilar reasoning applies to the reading step, except there is an additional complication: in the function that reads the file we use the `int` handle to identify the file, and therefore we don't have access to the `pathname` to report in case the call to [`read()`](http://man7.org/linux/man-pages/man2/read.2.html) fails. And if the failure is detected in the parsing step, the file may be closed already, so we may not even have the handle available.\n\nIs it important to know the name of the file which we failed to read or parse? It sure is. What got us on the error handling path (*error neutral* functions forwarding the failure to their caller, until an *error handling* scope is reached) may be a failure to read or parse the file, but once we reach a scope where the `pathname` is available, we should be able to report it in addition to the initial error information.\n\n## 4. Handling of error information\n\nIn the previous section we weren't concerned with how the error information (`errno`, `pathname`, etc.) is handled, we were only reasoning about what we need to know in case a failure occurs. But the question remains: yes, the `pathname` and `flags` passed to `open()` are relevant to any failure in any operation related to that file, but what are we supposed to do with them?\n\nThere are several options:\n\n* Don't bother with any error information beyond a basic error code.\n* Print the information in a log.\n* Convert relevant error information to string and store that in the object returned in case of failure.\n* Store them, in a type-safe manner, in the object returned in case of failure.\n\nWe'll examine each option in more detail below.\n\n### 4.1. Communicating an error code and nothing more\n\nThis approach is actually perfect for low-level libraries. The burden of transporting additional necessary information is shifted to the caller, which is arguably where it should be in this case: all relevant information leading to failures detected in a low-level function is available in the calling scopes. For example, it would be inappropriate if a function like `read()` tries to log anything or return error information beyond an error code, because all other relevant information is available in the various scopes leading to the failure.\n\nHowever, this approach does not compose: as the error code bubbles up, each scope may hold additional relevant information that needs to be communicated or lost forever as that scope is exited; and that can't be done with a simple error code. For example, it may be difficult to deal with `ENOENT` without knowing the relevant `pathname` -- and if we're aborting a scope where that information is available, we should communicate it at that point.\n\n### 4.2. Communicating an error code, logging other relevant information\n\nThis approach offers the simplicity of communicating just an error code, but it is usable in higher-level libraries. If a low-level function reports a failure, we log any relevant information we have, then return an error code to the caller, and the process repeats until an *error handling* function is reached. Alternatively, the logging may be done as a matter of routine, not only in case a failure is detected.\n\nThere are several problems with this approach:\n\n* It couples us with a logging system, which may not be a problem in the domain of a particular project, but certainly is not ideal for a universal library.\n* Depending on the use case, it may be too costly to hit the file system or some other logging target while handling errors.\n* The information in the log is developer-friendly, but not user-friendly. There are many projects where this is not a problem (for example, internet servers), but generally it is not appropriate to present a wall of cryptic diagnostic information to a user in hopes he will find clues in it to help fix the problem. But even a developer-facing command line utility has to print error information in plain English -- and the typical user-friendly app has to be able to use different languages.\n\n### 4.3. Communicating an error code + a string\n\nThe main appeal of this approach is that like logging error information, it composes nicely: if a lower level function communicates an error code, we can easily convert it to string, together with any other information available in our scope (e.g. the `pathname`), then return the string plus an error code to the caller. And of course this can be repeated in each calling scope: concatenate relevant information to the string and pass it on together with an(other) error code.\n\nWhat's more, in C++ the conversion of any type of error information to string is easy to define in terms of `std::ostream` `operator<<` overloads, so at each level we can process lower-level failures generically. In the end, the error handling function gets an error code (so it knows what went wrong), plus a string with relevant information that can be presented (or even logged) as \"the reason\" for the failure.\n\nWhile this is similar to writing the relevant error information in a log, this approach is arguably better because we don't depend on a logging system; but other downsides remain:\n\n* The result of the automatic conversion to string is not user-friendly.\n* The ability to concatenate strings usually requires dynamic memory allocations, which may be too slow in some cases.\n* Dynamic allocations may also fail, which is especially problematic during error handling.\n\n### 4.4. Communicating all error information with type-safety\n\nThe error handling strategies we discussed so far work well as long as automatically-printed (or logged) error information is sufficient. And while there are many problem domains where this is true, we still need a solution for the case when error handling code has to react to failures intelligently and to understand the available error information, rather than just print it for a developer to analyze. This requires that the various error objects delivered to an *error handling* function retain their static type even as they cross library boundaries; for example, in case of errors, the `flags` argument passed to `open()` should be communicated as an `int` rather than a `std::string`.\n\nMore generally, this is known as \"The Interoperability Problem\". The following analysis is from Niall Douglas:[1](#reference)\n\n>If library A uses `result`, and library B uses `result` and so on, there becomes a problem for the application writer who is bringing in these third party dependencies and tying them together into an application. As a general rule, each third party library author will not have built in explicit interoperation support for unknown other third party libraries. The problem therefore lands with the application writer.\n>\n>The application writer has one of three choices:\n>\n>1. In the application, the form of result used is `result>` where `E1`, `E2` … are the failure types for every third party library in use in the application. This has the advantage of preserving the original information exactly, but comes with a certain amount of use inconvenience and maybe excessive coupling between high level layers and implementation detail.\n>\n>2. One can translate/map the third party’s failure type into the application’s failure type at the point of the failure exiting the third party library and entering the application. One might do this, say, with a C preprocessor macro wrapping every invocation of the third party API from the application. This approach may lose the original failure detail, or mis-map under certain circumstances if the mapping between the two systems is not one-one.\n>\n>3. One can type erase the third party’s failure type into some application failure type, which can later be reconstituted if necessary. This is the cleanest solution with the least coupling issues and no problems with mis-mapping, but it almost certainly requires the use of `malloc` which the previous two did not.\n\nAn interesting observation is that the excessive coupling mentioned in the first point above is very similar to exception specifications. For example, if we have:\n\n```c++\nstruct error_info\n{\n int error_code;\n std::string file_name;\n};\n```\n\nAnd then:\n\n```c++\nexpected compute_value(....); // (A)\n```\n\nThis is very similar to:\n\n```c++\nint compute_value(....) throw(error_info); // (B)\n```\n\nThe difference, of course, is that in (A) the compatibility with the caller is enforced statically, while C++ exception specifications were enforced dynamically (\"were\", because they are now removed from the language). So, in truth, (A) is equivalent not to (B), but to statically-enforced exception specifications, as they are in Java.\n\nWhat is the problem with statically-enforced exception specifications? Herb Sutter explains:[2](#reference)\n\n> The short answer is that nobody knows how to fix exception specifications in any language, because the dynamic enforcement C++ chose has only different (not greater or fewer) problems than the static enforcement Java chose. …​ When you go down the Java path, people love exception specifications until they find themselves all too often encouraged, or even forced, to add throws Exception, which immediately renders the exception specification entirely meaningless. (Example: Imagine writing a Java generic that manipulates an arbitrary type `T`).\n\nIn other words, in the presence of dynamic or static polymorphism, it is impractical to force a user-supplied function to conform to a specific set of error types. For example, at the point of a polymorphic call to a `read()` function, we can not reasonably predict or statically specify all the error objects it may need to communicate.\n\nBut what about non-generic contexts? Is the equivalent of statically-enforced exception specifications a good idea in that case? We'll discuss this important question next.\n\n## 5. Error handling and function signatures\n\nDesigners of any programming language, but especially statically-typed languages, take care to provide for compile-time checks to ensure that function calls work as intended. For example, the compiler itself should be able to automatically detect bugs where the caller provides the wrong number or type of arguments.\n\nIn turn, the programmer would use the principle of encapsulation to logically decouple the caller of each function from the interface of lower level functions (A.K.A. implementation details). This is desirable because, assuming the interface of each function is correct, as long as *what* it does doesn't change, we can easily modify *how* it is done, with minimal disruption.\n\nThis results in tight coupling between a caller and a callee: in order to call a function, we must understand its semantics and the semantics of each of its arguments; it's preconditions and postconditions, etc. Of course, this is not a problem, in fact this coupling is the reason why the compiler is able to detect many errors before the program even runs.\n\nOn the other hand, not all objects a function needs to use should be passed through the narrow interface specified by its signature. For example, it is possible to pass a logger object as one of the arguments of each function which may need to print diagnostic information, but this is almost never done in practice; instead, the logging system is accessible globally. If we require that the logger is passed down as an argument, this would create difficulties for intermediate functions which don't need it: they would be coupled with an object they do not necessarily understand, only so they can pass it down to another function which may actually use it, but possibly just to pass it down to yet another function.\n\nWhen an object must be communicated down the call stack to a function several levels removed from the one that initiates the call, it is usually desirable to decouple the signature of all intermediate functions from that object, because their interface has nothing to do with it.\n\nThe same reasoning applies to *error neutral* functions with regards to failures originating in lower-level functions. While it is possible to couple the signatures of intermediate functions with the static type of all the [error information they may need to communicate](#4-handling-of-error-information), this essentially destroys their neutrality towards failures. That's because, in order for each function to define a specific type to report all possible error objects statically, it must understand the exact semantics of all lower level error types. This turns what would have been a chain of calls to *error neutral* functions into a game of telephone, requiring each node to both understand and correctly re-encode each communicated failure.\n\n## 6. Alternative mechanisms for transporting of error objects\n\nSo far we established that in general it is not a good idea to couple return values (or function signatures) of *error neutral* functions with the static type of all error objects they may need to communicate. In this section we'll discuss the alternative approaches.\n\n### 6.1. `GetLastError` / `errno`\n\nA typical classical approach is to only communicate the *failure flag* in the return value, while additional information is delivered through a separate mechanism. Here is an example from the Windows API:\n\n```c\nBOOL DeleteFileW(\n LBCWSTR lpFileName\n);\n```\n\nIf the function succeeds, the return value is non-zero. If the function fails, the return value is zero. In case of failure, the user can call `GetLastError()` to obtain an error code:\n\n```c\nDWORD GetLastError();\n```\n\nThis approach is appealing because it frees the return value from the burden of transporting any error information beyond the *failure flag*, a single bit. For example:\n\n```c\nHANDLE CreateFileW(\n LPCWSTR lpFileName,\n DWORD dwDesiredAccess,\n DWORD dwShareMode,\n LPSECURITY_ATTRIBUTES lpSecurityAttributes,\n DWORD dwCreationDisposition,\n DWORD dwFlagsAndAttributes,\n HANDLE hTemplateFile\n);\n```\n\nHad the above function returned an error code, it would have to take one more argument to output the `HANDLE` in case of success. Instead, the return value *is* the file handle, reserving the special `INVALID_HANDLE_VALUE` to indicate a failure, while additional error information is obtained by calling `GetLastError()`.\n\nThis same approach is used in many POSIX APIs, for example `open()`:\n\n```c\nint open(const char *pathname, int flags);\n```\n\nThe function attempts to open the file, returning the file handle or the special value `-1` to indicate a failure. In this case, the caller inspects `errno` for the error code.\n\nBut there is another important benefit to this approach which is easy to overlook: it is specifically designed to facilitate the implementation of *error neutral* functions:\n\n```c\nfloat read_data_and_compute_value(const char *pathname)\n{\n // Open the file, return INVALID_VALUE in case that fails:\n int fh = open(pathname, O_RDONLY);\n if (fh == -1)\n return INVALID_VALUE;\n\n // Read data, compute the value\n ....\n}\n```\n\nThe above function computes a `float` value based on the contents of the specified file, reserving a single `INVALID_VALUE` (possibly a NaN) to allow the caller to effectively inspect the *failure flag*.\n\nIn case of failure to `open()`, our function stays out of the way: the error code is communicated from `open()` (which sets the `errno`) *directly* to an *error handling* function up the call stack (which examines the `errno` in order to understand the failure), while the return value of each intermediate function needs only communicate a single bit of data (the *failure flag*).\n\nThe major drawback of this appoach is that the *failure flag* is not communicated uniformly, which means that *error neutral* functions can't check for errors generically (e.g. each layer needs to know about the different `INVALID_VALUE`s).\n\n### 6.2. C++ Exceptions\n\nIn C++, the default mechanism for dealing with failures is exception handling. In this case, the check for errors is not only generic but completely automated: *by default*, if a function fails, the error will be communicated to the caller. Literally, the programmer can't forget to check the *failure flag*.\n\nThe drawback of virtually all implementations is overhead, both in terms of space and speed. Below we'll analyze the reasons for this overhead, and point out ways to alleviate them.\n\n#### 6.2.1. Contemporary ABIs\n\nContemporary C++ exception handling is notorious for overhead[3](#reference). There are two major flavors of exception handling implementations: frame-based and table-based:\n\n* **Frame-based** implementations (e.g. x86) add to the cost of stack frames (that is, function calls), which is already not insignificant in performance-critical parts of the program. The added cost affects both the happy and the sad path: function calls become a bit more expensive even if no exception is thrown.\n\n* **Table-based** implementations (e.g. Itanium, x64) add to the cost of stack frames but only on the sad path. In fact, the performance of the happy path is often improved. However, if an exception is thrown and stack unwinding must commence, the table-based approach leads to a reduction in speed, compared to frame-based implementations.\n\nTable-based exception handling has been designed based on the questionable assumption that it is critical to eliminate speed overhead in programs that don't `throw`. I'm saying questionable, because in practice such programs are compiled with `-fno-exceptions`.\n\nIronically, the (older and less sophisticated) frame-based approach is preferable when we need to better control the cost of exception handling. The reason is that the overhead added to the happy path can be easily eliminated by inlining -- which is what we do anyway to deal with all other function-call overhead. This leaves only the cost of the sad path, which is also much more predictable, compared to the table-based approach.\n\n#### 6.2.2. Communicating the *failure flag*\n\nCurrent implementations do not communicate the *failure flag* explicitly. Instead, when throwing an exception, the compiler uses some form of automatic stack unwinding (possibly similar to `longjmp`) to reach the appropriate `catch` block, and to know which destructors to call.\n\nA much better approach would be for functions which may throw to communicate the *failure flag* explicitly, hopefully in the registers rather than spilling it to memory. This would allow each exception-neutral function to implement the error check, as well as to call the correct destructors in case of an error, with very little overhead.\n\n#### 6.2.3. Allocation of exception objects\n\nConsider the following exception type:\n\n```c++\nstruct my_error: std::exception {};\n```\n\nA catch statement designed to handle `my_error` exceptions:\n\n```c++\ntry\n{\n f();\n}\ncatch(my_error & e)\n{\n ....\n}\n```\n\nIf the above `catch` was only required to match objects of type `my_error`, they could be allocated on the stack, in the error handling scope, using automatic storage duration. However, `catch` must also match objects of any type that derives from `my_error`, and therefore the size of the exception object can not in general be known in this scope. For this reason, contemporary implementations allocate the memory for exception objects dynamically.\n\nA better approach[4](#reference) is to pre-allocate a stack-based buffer of some generally sufficient static size, leaving the option to allocate very large exception objects dynamically, similarly to the way `std::string` is typically implemented using small string optimization.\n\n#### 6.2.4. We do not need a new language (not even a new ABI)\n\nThere are several ongoing efforts to improve the performance of exception handling[5](#reference), however most of them propose (and require) changes to the C++ language definition. Here we offer an alternative idea which does not, and will likely significantly alleviate the need for further improvements.\n\nConsider the following program:\n\n```c++\n#include \n\nint main()\n{\n try\n {\n throw std::exception();\n }\n catch(std::exception & e)\n {\n }\n return 0;\n}\n```\n\nAnd here is the generated code ([Godbolt](https://godbolt.org/z/_a8eg9)):\n\n```x86asm\nmain:\n push rcx\n mov edi, 8\n call __cxa_allocate_exception\n mov edx, OFFSET FLAT:_ZNSt9exceptionD1Ev\n mov esi, OFFSET FLAT:_ZTISt9exception\n mov QWORD PTR [rax], OFFSET FLAT:_ZTVSt9exception+16\n mov rdi, rax\n call __cxa_throw\n mov rdi, rax\n dec rdx\n je .L3\n call _Unwind_Resume\n.L3:\n call __cxa_begin_catch\n call __cxa_end_catch\n xor eax, eax\n pop rdx\n ret\n```\n\nBluntly, this is not acceptable, since it is trivial to determine at compile time that the `throw`/`catch` pair is noop. What if the generated code is improved _only_ in this simple use case, where the `throw` and the matching `catch` are in the same stack frame? Under this condition, there is no need to invoke the ABI machinery to allocate an exception object or navigate the unwind tables; the analysis of the control flow can and should happen at compile time. We'd end up with simply\n\n```x86asm\nmain:\n xor eax, eax\n ret\n```\n\nWhy is optimizing this simplest of use cases important? Because this leads to complete and total elimination of exception handling overhead whenever function inlining occurs; and in C++ the critical path is already heavily reliant on inlining, because the function call overhead is not insignificant even if exception handling is disabled.\n\n### 6.3. Boost LEAF\n\nBoost LEAF[6](#reference) is a universal error handling library for C++ which works with or without exception handling. It provides a low-cost alternative to transporting error objects in return values.\n\nUsing LEAF, *error handling* functions match error objects similarly to the way `catch` matches exceptions, with two important differences:\n\n* Each handler can specify multiple objects to be matched by type, rather than only one.\n* The error objects are matched dynamically, but solely based on their static type. This allows *all* error objects to be allocated on the stack, using automatic storage duration.\n\nWhithout exception handling, this is achieved using the following syntax:\n\n```c++\nleaf::handle_all(\n\n // The first function passed to handle_all is akin to a try-block.\n []() -> leaf::result\n {\n // Operations which may fail, returning a T in case of success.\n // If case of an error, any number of error objects of arbitrary\n // types can be associated with the returned result object.\n },\n\n // The handler below is invoked if both an object of type my_error\n // and an object of another_type are associated with the error returned\n // by the try-block (above).\n [](my_error const & e1, another_type const & e2)\n {\n ....\n },\n\n // This handler is invoked if an object of type my_error is associated\n // with the error returned by the try-block.\n [](my_error const & e1)\n {\n ....\n },\n\n // This handler is invoked in all other cases, similarly to catch(...)\n []\n {\n ....\n }\n\n);\n```\n\nWith exception handling:\n\n```c++\nleaf::try_catch(\n\n // The first function passed to handle_all is akin to a try-block.\n []() -> T\n {\n // Operations which may fail, returning a T in case of success.\n // If case of an error, any number of error objects of arbitrary\n // types can be associated with the thrown exception object.\n },\n\n // The handler below is invoked if both an object of type my_error\n // and an object of another_type are associated with the exception\n // thrown by the try-block (above).\n [](my_error const & e1, another_type const & e2)\n {\n ....\n },\n\n // This handler is invoked if an object of type my_error is associated\n // with the exception thrown by the try-block.\n [](my_error const & e1)\n {\n ....\n },\n\n // This handler is invoked in all other cases, similarly to catch(...)\n []\n {\n ....\n }\n\n);\n```\n\nIn LEAF, error objects are allocated using automatic duration, stored in a `std::tuple` in the scope of `leaf::handle_all` (or `leaf::try_catch`). The type arguments of the `std::tuple` template are automatically deduced from the types of the arguments of the error handling lambdas. If the try-block attempts to communicate error objects of any other type, these objects are discarded, since no error handler can make any use of them.\n\nThe `leaf::result` template can be used as a return value for functions that may fail to produce a `T`. It carries the [*failure flag*](#1-the-semantics-of-a-failure) and, in case it is set, an integer serial number of the failure, while actual error objects are immediately moved into the matching storage reserved in the scope of an error handling function (e.g. `handle_all`) found in the call stack.\n\n## 7. Exception-safety vs. failure-safety\n\nMany programmers dread C++ exception-safety[7](#reference): the ability of C++ programs to respond correctly to a function call that results in throwing an exception. This fear is well founded, though it shouldn't be limited to throwing exceptions, but to all error handling, regardless of the underlying mechanism.\n\nIn \"Exception Safety: Concepts and Techniques\"[8](#reference) Bjarne Stroustrup explains:\n\n> An operation on an object is said to be exception safe if that operation leaves the object in a valid state when the operation is terminated by throwing an exception. This valid state could be an error state requiring cleanup, but it must be well defined so that reasonable error handling code can be written for the object.\n\nConsider the following edits:\n\n> An operation on an object is said to be ~~exception-safe~~ failure-safe if that operation leaves the object in a valid state when the operation ~~is terminated by throwing an exception~~ fails. This valid state could be an error state requiring cleanup, but it must be well defined so that reasonable error handling code can be written for the object.\n\nWithout limiting the discussion to exception throwing, the second definition remains entirely correct. With this in mind, let's continue with Stroustrup's explanation of safety-guarantees of operations on standard library components after ~~an exception is thrown~~ a failure has occurred:\n\n> * *Basic guarantee for all operations:* The basic invariants of the standard library are maintained, and no resources, such as memory, are leaked.\n>\n> * *Strong guarantee for key operations:* In addition to providing the basic guarantee, either the operation succeeds, or has no effects. This guarantee is provided for key library operations, such as `push_back()`, single-element `insert()` on a list, and `uninitialized_copy()`\n>\n> * *~~Nothrow~~ No-fail guarantee for some operations:* In addition to providing the basic guarantee, some operations are guaranteed not to ~~throw an exception~~ fail. This guarantee is provided for a few simple operations, such as `swap()` and `pop_back()`.\n\nDoes this generalization make sense? Is there a marked difference in safety-guarantees when throwing exceptions vs. any other error reporting mechanism?\n\nThe answer depends on how *error neutral* functions respond to failures. For example, Boost Outcome offers the macro `OUTCOME_TRY`, which can be invoked with two arguments, like so:\n\n```c++\nOUTCOME_TRY(i, BigInt::fromString(text));\n```\n\nThe above expands to something like:\n\n```c++\nauto&& __result = BigInt::fromString(text);\nif (!__result)\n return __result.as_failure();\nauto&& i = __result.value();\n```\n\nThe idea of `OUTCOME_TRY` is to support generic response to failures in *error neutral* functions. It relies on two things:\n\n1. That the [*failure flag* can be observed generically](#1-the-semantics-of-a-failure), and\n2. That it is safe to simply return from an [*error neutral* function](#2-classification-of-functions-based-on-their-affinity-to-errors) in case of a failure, forwarding error objects to the caller.\n\nLogically, this behavior is equivalent to the compiler-generated code when calling a function which may throw an exception. Consequently, all reasoning applicable to object invariants when throwing exceptions applies equally when using `OUTCOME_TRY` (or the [LEAF](https://boostorg.github.io/leaf) analog, `BOOST_LEAF_AUTO`).\n\n> **NOTE:** Lately there seems to be a debate in the C++ community whether the *basic guarantee* should be the minimum requirement for all user-defined types, that is, whether it should be required that even when operations fail, the basic object invariants are in place. Arguably this is beyond the scope of this paper, but the previous paragraph holds regardless: *safety-guarantees* are equally applicable, with or without exception handling.\n\n## Summary\n\n* We examined several [different approaches to error handling](#4-handling-of-error-information), as well as several mechanisms for [transporting of error objects of arbitrary static types safely](#44-communicating-all-error-information-with-type-safety).\n\n* We demonstrated that [generally](#44-communicating-all-error-information-with-type-safety) it is not a good idea to [couple function signatures with the types of all error objects they need to communicate](#5-error-handling-and-function-signatures).\n\n* We presented a novel method for transporting of error objects of arbitrary static types without using dynamic memory allocation, implemented by the [Boost LEAF library](#63-boost-leaf).\n\n* We described an [alternative approach to implementing C++ exception handling](#62-c-exceptions) which would eliminate most overhead in practice.\n\n* We showed that the three formal safety guarantees (*Basic*, *Strong*, *~~Nothrow~~ No-fail*) are useful when reasoning about object invariants, [regardless of how errors are communicated](#7-exception-safety-vs-failure-safety).\n\n## Conclusions\n\n* Error handling is a dynamic process, so the static type system is of limited assistance; for example, `ENOENT` is a *value* and not a *type*, and therefore the appropriate error handler has to be matched dynamically rather than statically.\n\n* Because most of the functions in a program are *error neutral*, the ability to automatically (e.g. when using exception handling) or at least generically (e.g. `OUTCOME_TRY`, `BOOST_LEAF_AUTO`) forward errors to the caller is critical for correctness.\n\n* The formal ~~exception-safety~~ failure-safety guarantees are applicable to *error neutral* functions responding to failures generically, even when not using exception handling.\n\n* Exception-handling overhead can be virtually eliminated by ABI changes that require no changes in the C++ standard; in the case when exception-neutral functions are inlined, all overhead may be removed even without ABI changes.\n\n## Reference\n\n[1](#44-communicating-all-error-information-with-type-safety). Niall Douglas\\\nIncommensurate E types (Outcome library documentation)\\\nhttps://ned14.github.io/outcome/tutorial/advanced/interop/problem\n\n[2](#44-communicating-all-error-information-with-type-safety). Herb Sutter\\\nQuestions About Exception Specifications (Sutter's Mill)\\\nhttps://herbsutter.com/2007/01/24/questions-about-exception-specifications\n\n[3](#621-contemporary-abis). Ben Craig\\\nError speed benchmarking\\\nhttp://www.open-std.org/jtc1/sc22/wg21/docs/papers/2019/p1886r0.html\n\n[4](#623-allocation-of-exception-objects). James Renwick, Tom Spink, Björn Franke\\\nLow-Cost Deterministic C++ Exceptions for Embedded Systems\\\nhttps://www.research.ed.ac.uk/portal/files/78829292/low_cost_deterministic_C_exceptions_for_embedded_systems.pdf\n\n[5](#624-we-do-not-need-a-new-language-not-even-a-new-abi-). Herb Sutter\\\nZero-overhead deterministic exceptions: Throwing values\\\nhttp://www.open-std.org/jtc1/sc22/wg21/docs/papers/2018/p0709r1.pdf\n\n[6](#63-leaf). Emil Dotchevski\\\nLightweight Error Augmentation Framework (library documentation)\\\nhttps://boostorg.github.io/leaf\n\n[7](#7-exception-safety-vs-failure-safety). David Abrahams\\\nException-Safety in Generic Components\\\nhttps://www.boost.org/community/exception_safety.html\n\n[8](#7-exception-safety-vs-failure-safety). Bjarne Stroustrup\\\nException Safety: Concepts and Techniques\\\nhttp://www.stroustrup.com/except.pdf\n" }, { "path": "doc/zajo-dark.css", "content": "/* Asciidoctor default stylesheet | MIT License | http://asciidoctor.org */\n/* Uncomment @import statement below to use as custom stylesheet */\n/*@import \"https://fonts.googleapis.com/css?family=Open+Sans:300,300italic,400,400italic,600,600italic%7CNoto+Serif:400,400italic,700,700italic%7CDroid+Sans+Mono:400,700\";*/\n\n/* Zajo's custom font import. The rest of the customizations are at the bottom of this css file, which is otherwise kept unchanged */\n@import \"https://fonts.googleapis.com/css?family=Anonymous+Pro|Istok+Web|Quicksand|Poiret+One\";\n\narticle,aside,details,figcaption,figure,footer,header,hgroup,main,nav,section,summary{display:block}\naudio,canvas,video{display:inline-block}\naudio:not([controls]){display:none;height:0}\nscript{display:none!important}\nhtml{font-family:sans-serif;-ms-text-size-adjust:100%;-webkit-text-size-adjust:100%}\na{background:transparent}\na:focus{outline:thin dotted}\na:active,a:hover{outline:0}\nh1{font-size:2em;margin:.67em 0}\nabbr[title]{border-bottom:1px dotted}\nb,strong{font-weight:bold}\ndfn{font-style:italic}\nhr{-moz-box-sizing:content-box;box-sizing:content-box;height:0}\nmark{background:#ff0;color:#000}\ncode,kbd,pre,samp{font-family:monospace;font-size:1em}\npre{white-space:pre-wrap}\nq{quotes:\"\\201C\" \"\\201D\" \"\\2018\" \"\\2019\"}\nsmall{font-size:80%}\nsub,sup{font-size:75%;line-height:0;position:relative;vertical-align:baseline}\nsup{top:-.5em}\nsub{bottom:-.25em}\nimg{border:0}\nsvg:not(:root){overflow:hidden}\nfigure{margin:0}\nfieldset{border:1px solid silver;margin:0 2px;padding:.35em .625em .75em}\nlegend{border:0;padding:0}\nbutton,input,select,textarea{font-family:inherit;font-size:100%;margin:0}\nbutton,input{line-height:normal}\nbutton,select{text-transform:none}\nbutton,html input[type=\"button\"],input[type=\"reset\"],input[type=\"submit\"]{-webkit-appearance:button;cursor:pointer}\nbutton[disabled],html input[disabled]{cursor:default}\ninput[type=\"checkbox\"],input[type=\"radio\"]{box-sizing:border-box;padding:0}\nbutton::-moz-focus-inner,input::-moz-focus-inner{border:0;padding:0}\ntextarea{overflow:auto;vertical-align:top}\ntable{border-collapse:collapse;border-spacing:0}\n*,*::before,*::after{-moz-box-sizing:border-box;-webkit-box-sizing:border-box;box-sizing:border-box}\nhtml,body{font-size:100%}\nbody{background:#fff;color:rgba(0,0,0,.8);padding:0;margin:0;font-family:\"Noto Serif\",\"DejaVu Serif\",serif;font-weight:400;font-style:normal;line-height:1;position:relative;cursor:auto;tab-size:4;-moz-osx-font-smoothing:grayscale;-webkit-font-smoothing:antialiased}\na:hover{cursor:pointer}\nimg,object,embed{max-width:100%;height:auto}\nobject,embed{height:100%}\nimg{-ms-interpolation-mode:bicubic}\n.left{float:left!important}\n.right{float:right!important}\n.text-left{text-align:left!important}\n.text-right{text-align:right!important}\n.text-center{text-align:center!important}\n.text-justify{text-align:justify!important}\n.hide{display:none}\nimg,object,svg{display:inline-block;vertical-align:middle}\ntextarea{height:auto;min-height:50px}\nselect{width:100%}\n.center{margin-left:auto;margin-right:auto}\n.stretch{width:100%}\n.subheader,.admonitionblock td.content>.title,.audioblock>.title,.exampleblock>.title,.imageblock>.title,.listingblock>.title,.literalblock>.title,.stemblock>.title,.openblock>.title,.paragraph>.title,.quoteblock>.title,table.tableblock>.title,.verseblock>.title,.videoblock>.title,.dlist>.title,.olist>.title,.ulist>.title,.qlist>.title,.hdlist>.title{line-height:1.45;color:#7a2518;font-weight:400;margin-top:0;margin-bottom:.25em}\ndiv,dl,dt,dd,ul,ol,li,h1,h2,h3,#toctitle,.sidebarblock>.content>.title,h4,h5,h6,pre,form,p,blockquote,th,td{margin:0;padding:0;direction:ltr}\na{color:#2156a5;text-decoration:underline;line-height:inherit}\na:hover,a:focus{color:#1d4b8f}\na img{border:none}\np{font-family:inherit;font-weight:400;font-size:1em;line-height:1.6;margin-bottom:1.25em;text-rendering:optimizeLegibility}\np aside{font-size:.875em;line-height:1.35;font-style:italic}\nh1,h2,h3,#toctitle,.sidebarblock>.content>.title,h4,h5,h6{font-family:\"Open Sans\",\"DejaVu Sans\",sans-serif;font-weight:300;font-style:normal;color:#ba3925;text-rendering:optimizeLegibility;margin-top:1em;margin-bottom:.5em;line-height:1.0125em}\nh1 small,h2 small,h3 small,#toctitle small,.sidebarblock>.content>.title small,h4 small,h5 small,h6 small{font-size:60%;color:#e99b8f;line-height:0}\nh1{font-size:2.125em}\nh2{font-size:1.6875em}\nh3,#toctitle,.sidebarblock>.content>.title{font-size:1.375em}\nh4,h5{font-size:1.125em}\nh6{font-size:1em}\nhr{border:solid #dddddf;border-width:1px 0 0;clear:both;margin:1.25em 0 1.1875em;height:0}\nem,i{font-style:italic;line-height:inherit}\nstrong,b{font-weight:bold;line-height:inherit}\nsmall{font-size:60%;line-height:inherit}\ncode{font-family:\"Droid Sans Mono\",\"DejaVu Sans Mono\",monospace;font-weight:400;color:rgba(0,0,0,.9)}\nul,ol,dl{font-size:1em;line-height:1.6;margin-bottom:1.25em;list-style-position:outside;font-family:inherit}\nul,ol{margin-left:1.5em}\nul li ul,ul li ol{margin-left:1.25em;margin-bottom:0;font-size:1em}\nul.square li ul,ul.circle li ul,ul.disc li ul{list-style:inherit}\nul.square{list-style-type:square}\nul.circle{list-style-type:circle}\nul.disc{list-style-type:disc}\nol li ul,ol li ol{margin-left:1.25em;margin-bottom:0}\ndl dt{margin-bottom:.3125em;font-weight:bold}\ndl dd{margin-bottom:1.25em}\nabbr,acronym{text-transform:uppercase;font-size:90%;color:rgba(0,0,0,.8);border-bottom:1px dotted #ddd;cursor:help}\nabbr{text-transform:none}\nblockquote{margin:0 0 1.25em;padding:.5625em 1.25em 0 1.1875em;border-left:1px solid #ddd}\nblockquote cite{display:block;font-size:.9375em;color:rgba(0,0,0,.6)}\nblockquote cite::before{content:\"\\2014 \\0020\"}\nblockquote cite a,blockquote cite a:visited{color:rgba(0,0,0,.6)}\nblockquote,blockquote p{line-height:1.6;color:rgba(0,0,0,.85)}\n@media screen and (min-width:768px){h1,h2,h3,#toctitle,.sidebarblock>.content>.title,h4,h5,h6{line-height:1.2}\nh1{font-size:2.75em}\nh2{font-size:2.3125em}\nh3,#toctitle,.sidebarblock>.content>.title{font-size:1.6875em}\nh4{font-size:1.4375em}}\ntable{background:#fff;margin-bottom:1.25em;border:solid 1px #dedede}\ntable thead,table tfoot{background:#f7f8f7}\ntable thead tr th,table thead tr td,table tfoot tr th,table tfoot tr td{padding:.5em .625em .625em;font-size:inherit;color:rgba(0,0,0,.8);text-align:left}\ntable tr th,table tr td{padding:.5625em .625em;font-size:inherit;color:rgba(0,0,0,.8)}\ntable tr.even,table tr.alt,table tr:nth-of-type(even){background:#f8f8f7}\ntable thead tr th,table tfoot tr th,table tbody tr td,table tr td,table tfoot tr td{display:table-cell;line-height:1.6}\nh1,h2,h3,#toctitle,.sidebarblock>.content>.title,h4,h5,h6{line-height:1.2;word-spacing:-.05em}\nh1 strong,h2 strong,h3 strong,#toctitle strong,.sidebarblock>.content>.title strong,h4 strong,h5 strong,h6 strong{font-weight:400}\n.clearfix::before,.clearfix::after,.float-group::before,.float-group::after{content:\" \";display:table}\n.clearfix::after,.float-group::after{clear:both}\n*:not(pre)>code{font-size:.9375em;font-style:normal!important;letter-spacing:0;padding:.1em .5ex;word-spacing:-.15em;background-color:#f7f7f8;-webkit-border-radius:4px;border-radius:4px;line-height:1.45;text-rendering:optimizeSpeed;word-wrap:break-word}\n*:not(pre)>code.nobreak{word-wrap:normal}\n*:not(pre)>code.nowrap{white-space:nowrap}\npre,pre>code{line-height:1.45;color:rgba(0,0,0,.9);font-family:\"Droid Sans Mono\",\"DejaVu Sans Mono\",monospace;font-weight:400;text-rendering:optimizeSpeed}\nem em{font-style:normal}\nstrong strong{font-weight:400}\n.keyseq{color:rgba(51,51,51,.8)}\nkbd{font-family:\"Droid Sans Mono\",\"DejaVu Sans Mono\",monospace;display:inline-block;color:rgba(0,0,0,.8);font-size:.65em;line-height:1.45;background-color:#f7f7f7;border:1px solid #ccc;-webkit-border-radius:3px;border-radius:3px;-webkit-box-shadow:0 1px 0 rgba(0,0,0,.2),0 0 0 .1em white inset;box-shadow:0 1px 0 rgba(0,0,0,.2),0 0 0 .1em #fff inset;margin:0 .15em;padding:.2em .5em;vertical-align:middle;position:relative;top:-.1em;white-space:nowrap}\n.keyseq kbd:first-child{margin-left:0}\n.keyseq kbd:last-child{margin-right:0}\n.menuseq,.menuref{color:#000}\n.menuseq b:not(.caret),.menuref{font-weight:inherit}\n.menuseq{word-spacing:-.02em}\n.menuseq b.caret{font-size:1.25em;line-height:.8}\n.menuseq i.caret{font-weight:bold;text-align:center;width:.45em}\nb.button::before,b.button::after{position:relative;top:-1px;font-weight:400}\nb.button::before{content:\"[\";padding:0 3px 0 2px}\nb.button::after{content:\"]\";padding:0 2px 0 3px}\np a>code:hover{color:rgba(0,0,0,.9)}\n#header,#content,#footnotes,#footer{width:100%;margin-left:auto;margin-right:auto;margin-top:0;margin-bottom:0;max-width:62.5em;*zoom:1;position:relative;padding-left:.9375em;padding-right:.9375em}\n#header::before,#header::after,#content::before,#content::after,#footnotes::before,#footnotes::after,#footer::before,#footer::after{content:\" \";display:table}\n#header::after,#content::after,#footnotes::after,#footer::after{clear:both}\n#content{margin-top:1.25em}\n#content::before{content:none}\n#header>h1:first-child{color:rgba(0,0,0,.85);margin-top:2.25rem;margin-bottom:0}\n#header>h1:first-child+#toc{margin-top:8px;border-top:1px solid #dddddf}\n#header>h1:only-child,body.toc2 #header>h1:nth-last-child(2){border-bottom:1px solid #dddddf;padding-bottom:8px}\n#header .details{border-bottom:1px solid #dddddf;line-height:1.45;padding-top:.25em;padding-bottom:.25em;padding-left:.25em;color:rgba(0,0,0,.6);display:-ms-flexbox;display:-webkit-flex;display:flex;-ms-flex-flow:row wrap;-webkit-flex-flow:row wrap;flex-flow:row wrap}\n#header .details span:first-child{margin-left:-.125em}\n#header .details span.email a{color:rgba(0,0,0,.85)}\n#header .details br{display:none}\n#header .details br+span::before{content:\"\\00a0\\2013\\00a0\"}\n#header .details br+span.author::before{content:\"\\00a0\\22c5\\00a0\";color:rgba(0,0,0,.85)}\n#header .details br+span#revremark::before{content:\"\\00a0|\\00a0\"}\n#header #revnumber{text-transform:capitalize}\n#header #revnumber::after{content:\"\\00a0\"}\n#content>h1:first-child:not([class]){color:rgba(0,0,0,.85);border-bottom:1px solid #dddddf;padding-bottom:8px;margin-top:0;padding-top:1rem;margin-bottom:1.25rem}\n#toc{border-bottom:1px solid #e7e7e9;padding-bottom:.5em}\n#toc>ul{margin-left:.125em}\n#toc ul.sectlevel0>li>a{font-style:italic}\n#toc ul.sectlevel0 ul.sectlevel1{margin:.5em 0}\n#toc ul{font-family:\"Open Sans\",\"DejaVu Sans\",sans-serif;list-style-type:none}\n#toc li{line-height:1.3334;margin-top:.3334em}\n#toc a{text-decoration:none}\n#toc a:active{text-decoration:underline}\n#toctitle{color:#7a2518;font-size:1.2em}\n@media screen and (min-width:768px){#toctitle{font-size:1.375em}\nbody.toc2{padding-left:15em;padding-right:0}\n#toc.toc2{margin-top:0!important;background-color:#f8f8f7;position:fixed;width:15em;left:0;top:0;border-right:1px solid #e7e7e9;border-top-width:0!important;border-bottom-width:0!important;z-index:1000;padding:1.25em 1em;height:100%;overflow:auto}\n#toc.toc2 #toctitle{margin-top:0;margin-bottom:.8rem;font-size:1.2em}\n#toc.toc2>ul{font-size:.9em;margin-bottom:0}\n#toc.toc2 ul ul{margin-left:0;padding-left:1em}\n#toc.toc2 ul.sectlevel0 ul.sectlevel1{padding-left:0;margin-top:.5em;margin-bottom:.5em}\nbody.toc2.toc-right{padding-left:0;padding-right:15em}\nbody.toc2.toc-right #toc.toc2{border-right-width:0;border-left:1px solid #e7e7e9;left:auto;right:0}}\n@media screen and (min-width:1280px){body.toc2{padding-left:20em;padding-right:0}\n#toc.toc2{width:20em}\n#toc.toc2 #toctitle{font-size:1.375em}\n#toc.toc2>ul{font-size:.95em}\n#toc.toc2 ul ul{padding-left:1.25em}\nbody.toc2.toc-right{padding-left:0;padding-right:20em}}\n#content #toc{border-style:solid;border-width:1px;border-color:#e0e0dc;margin-bottom:1.25em;padding:1.25em;background:#f8f8f7;-webkit-border-radius:4px;border-radius:4px}\n#content #toc>:first-child{margin-top:0}\n#content #toc>:last-child{margin-bottom:0}\n#footer{max-width:100%;background-color:rgba(0,0,0,.8);padding:1.25em}\n#footer-text{color:rgba(255,255,255,.8);line-height:1.44}\n#content{margin-bottom:.625em}\n.sect1{padding-bottom:.625em}\n@media screen and (min-width:768px){#content{margin-bottom:1.25em}\n.sect1{padding-bottom:1.25em}}\n.sect1:last-child{padding-bottom:0}\n.sect1+.sect1{border-top:1px solid #e7e7e9}\n#content h1>a.anchor,h2>a.anchor,h3>a.anchor,#toctitle>a.anchor,.sidebarblock>.content>.title>a.anchor,h4>a.anchor,h5>a.anchor,h6>a.anchor{position:absolute;z-index:1001;width:1.5ex;margin-left:-1.5ex;display:block;text-decoration:none!important;visibility:hidden;text-align:center;font-weight:400}\n#content h1>a.anchor::before,h2>a.anchor::before,h3>a.anchor::before,#toctitle>a.anchor::before,.sidebarblock>.content>.title>a.anchor::before,h4>a.anchor::before,h5>a.anchor::before,h6>a.anchor::before{content:\"\\00A7\";font-size:.85em;display:block;padding-top:.1em}\n#content h1:hover>a.anchor,#content h1>a.anchor:hover,h2:hover>a.anchor,h2>a.anchor:hover,h3:hover>a.anchor,#toctitle:hover>a.anchor,.sidebarblock>.content>.title:hover>a.anchor,h3>a.anchor:hover,#toctitle>a.anchor:hover,.sidebarblock>.content>.title>a.anchor:hover,h4:hover>a.anchor,h4>a.anchor:hover,h5:hover>a.anchor,h5>a.anchor:hover,h6:hover>a.anchor,h6>a.anchor:hover{visibility:visible}\n#content h1>a.link,h2>a.link,h3>a.link,#toctitle>a.link,.sidebarblock>.content>.title>a.link,h4>a.link,h5>a.link,h6>a.link{color:#ba3925;text-decoration:none}\n#content h1>a.link:hover,h2>a.link:hover,h3>a.link:hover,#toctitle>a.link:hover,.sidebarblock>.content>.title>a.link:hover,h4>a.link:hover,h5>a.link:hover,h6>a.link:hover{color:#a53221}\n.audioblock,.imageblock,.literalblock,.listingblock,.stemblock,.videoblock{margin-bottom:1.25em}\n.admonitionblock td.content>.title,.audioblock>.title,.exampleblock>.title,.imageblock>.title,.listingblock>.title,.literalblock>.title,.stemblock>.title,.openblock>.title,.paragraph>.title,.quoteblock>.title,table.tableblock>.title,.verseblock>.title,.videoblock>.title,.dlist>.title,.olist>.title,.ulist>.title,.qlist>.title,.hdlist>.title{text-rendering:optimizeLegibility;text-align:left;font-family:\"Noto Serif\",\"DejaVu Serif\",serif;font-size:1rem;font-style:italic}\ntable.tableblock.fit-content>caption.title{white-space:nowrap;width:0}\n.paragraph.lead>p,#preamble>.sectionbody>[class=\"paragraph\"]:first-of-type p{font-size:1.21875em;line-height:1.6;color:rgba(0,0,0,.85)}\ntable.tableblock #preamble>.sectionbody>[class=\"paragraph\"]:first-of-type p{font-size:inherit}\n.admonitionblock>table{border-collapse:separate;border:0;background:none;width:100%}\n.admonitionblock>table td.icon{text-align:center;width:80px}\n.admonitionblock>table td.icon img{max-width:none}\n.admonitionblock>table td.icon .title{font-weight:bold;font-family:\"Open Sans\",\"DejaVu Sans\",sans-serif;text-transform:uppercase}\n.admonitionblock>table td.content{padding-left:1.125em;padding-right:1.25em;border-left:1px solid #dddddf;color:rgba(0,0,0,.6)}\n.admonitionblock>table td.content>:last-child>:last-child{margin-bottom:0}\n.exampleblock>.content{border-style:solid;border-width:1px;border-color:#e6e6e6;margin-bottom:1.25em;padding:1.25em;background:#fff;-webkit-border-radius:4px;border-radius:4px}\n.exampleblock>.content>:first-child{margin-top:0}\n.exampleblock>.content>:last-child{margin-bottom:0}\n.sidebarblock{border-style:solid;border-width:1px;border-color:#e0e0dc;margin-bottom:1.25em;padding:1.25em;background:#f8f8f7;-webkit-border-radius:4px;border-radius:4px}\n.sidebarblock>:first-child{margin-top:0}\n.sidebarblock>:last-child{margin-bottom:0}\n.sidebarblock>.content>.title{color:#7a2518;margin-top:0;text-align:center}\n.exampleblock>.content>:last-child>:last-child,.exampleblock>.content .olist>ol>li:last-child>:last-child,.exampleblock>.content .ulist>ul>li:last-child>:last-child,.exampleblock>.content .qlist>ol>li:last-child>:last-child,.sidebarblock>.content>:last-child>:last-child,.sidebarblock>.content .olist>ol>li:last-child>:last-child,.sidebarblock>.content .ulist>ul>li:last-child>:last-child,.sidebarblock>.content .qlist>ol>li:last-child>:last-child{margin-bottom:0}\n.literalblock pre,.listingblock pre:not(.highlight),.listingblock pre[class=\"highlight\"],.listingblock pre[class^=\"highlight \"],.listingblock pre.CodeRay,.listingblock pre.prettyprint{background:#f7f7f8}\n.sidebarblock .literalblock pre,.sidebarblock .listingblock pre:not(.highlight),.sidebarblock .listingblock pre[class=\"highlight\"],.sidebarblock .listingblock pre[class^=\"highlight \"],.sidebarblock .listingblock pre.CodeRay,.sidebarblock .listingblock pre.prettyprint{background:#f2f1f1}\n.literalblock pre,.literalblock pre[class],.listingblock pre,.listingblock pre[class]{-webkit-border-radius:4px;border-radius:4px;word-wrap:break-word;overflow-x:auto;padding:1em;font-size:.8125em}\n@media screen and (min-width:768px){.literalblock pre,.literalblock pre[class],.listingblock pre,.listingblock pre[class]{font-size:.90625em}}\n@media screen and (min-width:1280px){.literalblock pre,.literalblock pre[class],.listingblock pre,.listingblock pre[class]{font-size:1em}}\n.literalblock pre.nowrap,.literalblock pre.nowrap pre,.listingblock pre.nowrap,.listingblock pre.nowrap pre{white-space:pre;word-wrap:normal}\n.literalblock.output pre{color:#f7f7f8;background-color:rgba(0,0,0,.9)}\n.listingblock pre.highlightjs{padding:0}\n.listingblock pre.highlightjs>code{padding:1em;-webkit-border-radius:4px;border-radius:4px}\n.listingblock pre.prettyprint{border-width:0}\n.listingblock>.content{position:relative}\n.listingblock code[data-lang]::before{display:none;content:attr(data-lang);position:absolute;font-size:.75em;top:.425rem;right:.5rem;line-height:1;text-transform:uppercase;color:#999}\n.listingblock:hover code[data-lang]::before{display:block}\n.listingblock.terminal pre .command::before{content:attr(data-prompt);padding-right:.5em;color:#999}\n.listingblock.terminal pre .command:not([data-prompt])::before{content:\"$\"}\ntable.pyhltable{border-collapse:separate;border:0;margin-bottom:0;background:none}\ntable.pyhltable td{vertical-align:top;padding-top:0;padding-bottom:0;line-height:1.45}\ntable.pyhltable td.code{padding-left:.75em;padding-right:0}\npre.pygments .lineno,table.pyhltable td:not(.code){color:#999;padding-left:0;padding-right:.5em;border-right:1px solid #dddddf}\npre.pygments .lineno{display:inline-block;margin-right:.25em}\ntable.pyhltable .linenodiv{background:none!important;padding-right:0!important}\n.quoteblock{margin:0 1em 1.25em 1.5em;display:table}\n.quoteblock>.title{margin-left:-1.5em;margin-bottom:.75em}\n.quoteblock blockquote,.quoteblock p{color:rgba(0,0,0,.85);font-size:1.15rem;line-height:1.75;word-spacing:.1em;letter-spacing:0;font-style:italic;text-align:justify}\n.quoteblock blockquote{margin:0;padding:0;border:0}\n.quoteblock blockquote::before{content:\"\\201c\";float:left;font-size:2.75em;font-weight:bold;line-height:.6em;margin-left:-.6em;color:#7a2518;text-shadow:0 1px 2px rgba(0,0,0,.1)}\n.quoteblock blockquote>.paragraph:last-child p{margin-bottom:0}\n.quoteblock .attribution{margin-top:.75em;margin-right:.5ex;text-align:right}\n.verseblock{margin:0 1em 1.25em}\n.verseblock pre{font-family:\"Open Sans\",\"DejaVu Sans\",sans;font-size:1.15rem;color:rgba(0,0,0,.85);font-weight:300;text-rendering:optimizeLegibility}\n.verseblock pre strong{font-weight:400}\n.verseblock .attribution{margin-top:1.25rem;margin-left:.5ex}\n.quoteblock .attribution,.verseblock .attribution{font-size:.9375em;line-height:1.45;font-style:italic}\n.quoteblock .attribution br,.verseblock .attribution br{display:none}\n.quoteblock .attribution cite,.verseblock .attribution cite{display:block;letter-spacing:-.025em;color:rgba(0,0,0,.6)}\n.quoteblock.abstract blockquote::before,.quoteblock.excerpt blockquote::before,.quoteblock .quoteblock blockquote::before{display:none}\n.quoteblock.abstract blockquote,.quoteblock.abstract p,.quoteblock.excerpt blockquote,.quoteblock.excerpt p,.quoteblock .quoteblock blockquote,.quoteblock .quoteblock p{line-height:1.6;word-spacing:0}\n.quoteblock.abstract{margin:0 1em 1.25em;display:block}\n.quoteblock.abstract>.title{margin:0 0 .375em;font-size:1.15em;text-align:center}\n.quoteblock.excerpt,.quoteblock .quoteblock{margin:0 0 1.25em;padding:0 0 .25em 1em;border-left:.25em solid #dddddf}\n.quoteblock.excerpt blockquote,.quoteblock.excerpt p,.quoteblock .quoteblock blockquote,.quoteblock .quoteblock p{color:inherit;font-size:1.0625rem}\n.quoteblock.excerpt .attribution,.quoteblock .quoteblock .attribution{color:inherit;text-align:left;margin-right:0}\ntable.tableblock{max-width:100%;border-collapse:separate}\np.tableblock:last-child{margin-bottom:0}\ntd.tableblock>.content{margin-bottom:-1.25em}\ntable.tableblock,th.tableblock,td.tableblock{border:0 solid #dedede}\ntable.grid-all>thead>tr>.tableblock,table.grid-all>tbody>tr>.tableblock{border-width:0 1px 1px 0}\ntable.grid-all>tfoot>tr>.tableblock{border-width:1px 1px 0 0}\ntable.grid-cols>*>tr>.tableblock{border-width:0 1px 0 0}\ntable.grid-rows>thead>tr>.tableblock,table.grid-rows>tbody>tr>.tableblock{border-width:0 0 1px}\ntable.grid-rows>tfoot>tr>.tableblock{border-width:1px 0 0}\ntable.grid-all>*>tr>.tableblock:last-child,table.grid-cols>*>tr>.tableblock:last-child{border-right-width:0}\ntable.grid-all>tbody>tr:last-child>.tableblock,table.grid-all>thead:last-child>tr>.tableblock,table.grid-rows>tbody>tr:last-child>.tableblock,table.grid-rows>thead:last-child>tr>.tableblock{border-bottom-width:0}\ntable.frame-all{border-width:1px}\ntable.frame-sides{border-width:0 1px}\ntable.frame-topbot,table.frame-ends{border-width:1px 0}\ntable.stripes-all tr,table.stripes-odd tr:nth-of-type(odd){background:#f8f8f7}\ntable.stripes-none tr,table.stripes-odd tr:nth-of-type(even){background:none}\nth.halign-left,td.halign-left{text-align:left}\nth.halign-right,td.halign-right{text-align:right}\nth.halign-center,td.halign-center{text-align:center}\nth.valign-top,td.valign-top{vertical-align:top}\nth.valign-bottom,td.valign-bottom{vertical-align:bottom}\nth.valign-middle,td.valign-middle{vertical-align:middle}\ntable thead th,table tfoot th{font-weight:bold}\ntbody tr th{display:table-cell;line-height:1.6;background:#f7f8f7}\ntbody tr th,tbody tr th p,tfoot tr th,tfoot tr th p{color:rgba(0,0,0,.8);font-weight:bold}\np.tableblock>code:only-child{background:none;padding:0}\np.tableblock{font-size:1em}\ntd>div.verse{white-space:pre}\nol{margin-left:1.75em}\nul li ol{margin-left:1.5em}\ndl dd{margin-left:1.125em}\ndl dd:last-child,dl dd:last-child>:last-child{margin-bottom:0}\nol>li p,ul>li p,ul dd,ol dd,.olist .olist,.ulist .ulist,.ulist .olist,.olist .ulist{margin-bottom:.625em}\nul.checklist,ul.none,ol.none,ul.no-bullet,ol.no-bullet,ol.unnumbered,ul.unstyled,ol.unstyled{list-style-type:none}\nul.no-bullet,ol.no-bullet,ol.unnumbered{margin-left:.625em}\nul.unstyled,ol.unstyled{margin-left:0}\nul.checklist{margin-left:.625em}\nul.checklist li>p:first-child>.fa-square-o:first-child,ul.checklist li>p:first-child>.fa-check-square-o:first-child{width:1.25em;font-size:.8em;position:relative;bottom:.125em}\nul.checklist li>p:first-child>input[type=\"checkbox\"]:first-child{margin-right:.25em}\nul.inline{display:-ms-flexbox;display:-webkit-box;display:flex;-ms-flex-flow:row wrap;-webkit-flex-flow:row wrap;flex-flow:row wrap;list-style:none;margin:0 0 .625em -1.25em}\nul.inline>li{margin-left:1.25em}\n.unstyled dl dt{font-weight:400;font-style:normal}\nol.arabic{list-style-type:decimal}\nol.decimal{list-style-type:decimal-leading-zero}\nol.loweralpha{list-style-type:lower-alpha}\nol.upperalpha{list-style-type:upper-alpha}\nol.lowerroman{list-style-type:lower-roman}\nol.upperroman{list-style-type:upper-roman}\nol.lowergreek{list-style-type:lower-greek}\n.hdlist>table,.colist>table{border:0;background:none}\n.hdlist>table>tbody>tr,.colist>table>tbody>tr{background:none}\ntd.hdlist1,td.hdlist2{vertical-align:top;padding:0 .625em}\ntd.hdlist1{font-weight:bold;padding-bottom:1.25em}\n.literalblock+.colist,.listingblock+.colist{margin-top:-.5em}\n.colist td:not([class]):first-child{padding:.4em .75em 0;line-height:1;vertical-align:top}\n.colist td:not([class]):first-child img{max-width:none}\n.colist td:not([class]):last-child{padding:.25em 0}\n.thumb,.th{line-height:0;display:inline-block;border:solid 4px #fff;-webkit-box-shadow:0 0 0 1px #ddd;box-shadow:0 0 0 1px #ddd}\n.imageblock.left{margin:.25em .625em 1.25em 0}\n.imageblock.right{margin:.25em 0 1.25em .625em}\n.imageblock>.title{margin-bottom:0}\n.imageblock.thumb,.imageblock.th{border-width:6px}\n.imageblock.thumb>.title,.imageblock.th>.title{padding:0 .125em}\n.image.left,.image.right{margin-top:.25em;margin-bottom:.25em;display:inline-block;line-height:0}\n.image.left{margin-right:.625em}\n.image.right{margin-left:.625em}\na.image{text-decoration:none;display:inline-block}\na.image object{pointer-events:none}\nsup.footnote,sup.footnoteref{font-size:.875em;position:static;vertical-align:super}\nsup.footnote a,sup.footnoteref a{text-decoration:none}\nsup.footnote a:active,sup.footnoteref a:active{text-decoration:underline}\n#footnotes{padding-top:.75em;padding-bottom:.75em;margin-bottom:.625em}\n#footnotes hr{width:20%;min-width:6.25em;margin:-.25em 0 .75em;border-width:1px 0 0}\n#footnotes .footnote{padding:0 .375em 0 .225em;line-height:1.3334;font-size:.875em;margin-left:1.2em;margin-bottom:.2em}\n#footnotes .footnote a:first-of-type{font-weight:bold;text-decoration:none;margin-left:-1.05em}\n#footnotes .footnote:last-of-type{margin-bottom:0}\n#content #footnotes{margin-top:-.625em;margin-bottom:0;padding:.75em 0}\n.gist .file-data>table{border:0;background:#fff;width:100%;margin-bottom:0}\n.gist .file-data>table td.line-data{width:99%}\ndiv.unbreakable{page-break-inside:avoid}\n.big{font-size:larger}\n.small{font-size:smaller}\n.underline{text-decoration:underline}\n.overline{text-decoration:overline}\n.line-through{text-decoration:line-through}\n.aqua{color:#00bfbf}\n.aqua-background{background-color:#00fafa}\n.black{color:#000}\n.black-background{background-color:#000}\n.blue{color:#0000bf}\n.blue-background{background-color:#0000fa}\n.fuchsia{color:#bf00bf}\n.fuchsia-background{background-color:#fa00fa}\n.gray{color:#606060}\n.gray-background{background-color:#7d7d7d}\n.green{color:#006000}\n.green-background{background-color:#007d00}\n.lime{color:#00bf00}\n.lime-background{background-color:#00fa00}\n.maroon{color:#600000}\n.maroon-background{background-color:#7d0000}\n.navy{color:#000060}\n.navy-background{background-color:#00007d}\n.olive{color:#606000}\n.olive-background{background-color:#7d7d00}\n.purple{color:#600060}\n.purple-background{background-color:#7d007d}\n.red{color:#bf0000}\n.red-background{background-color:#fa0000}\n.silver{color:#909090}\n.silver-background{background-color:#bcbcbc}\n.teal{color:#006060}\n.teal-background{background-color:#007d7d}\n.white{color:#bfbfbf}\n.white-background{background-color:#fafafa}\n.yellow{color:#bfbf00}\n.yellow-background{background-color:#fafa00}\nspan.icon>.fa{cursor:default}\na span.icon>.fa{cursor:inherit}\n.admonitionblock td.icon [class^=\"fa icon-\"]{font-size:2.5em;text-shadow:1px 1px 2px rgba(0,0,0,.5);cursor:default}\n.admonitionblock td.icon .icon-note::before{content:\"\\f05a\";color:#19407c}\n.admonitionblock td.icon .icon-tip::before{content:\"\\f0eb\";text-shadow:1px 1px 2px rgba(155,155,0,.8);color:#111}\n.admonitionblock td.icon .icon-warning::before{content:\"\\f071\";color:#bf6900}\n.admonitionblock td.icon .icon-caution::before{content:\"\\f06d\";color:#bf3400}\n.admonitionblock td.icon .icon-important::before{content:\"\\f06a\";color:#bf0000}\n.conum[data-value]{display:inline-block;color:#fff!important;background-color:rgba(0,0,0,.8);-webkit-border-radius:100px;border-radius:100px;text-align:center;font-size:.75em;width:1.67em;height:1.67em;line-height:1.67em;font-family:\"Open Sans\",\"DejaVu Sans\",sans-serif;font-style:normal;font-weight:bold}\n.conum[data-value] *{color:#fff!important}\n.conum[data-value]+b{display:none}\n.conum[data-value]::after{content:attr(data-value)}\npre .conum[data-value]{position:relative;top:-.125em}\nb.conum *{color:inherit!important}\n.conum:not([data-value]):empty{display:none}\ndt,th.tableblock,td.content,div.footnote{text-rendering:optimizeLegibility}\nh1,h2,p,td.content,span.alt{letter-spacing:-.01em}\np strong,td.content strong,div.footnote strong{letter-spacing:-.005em}\np,blockquote,dt,td.content,span.alt{font-size:1.0625rem}\np{margin-bottom:1.25rem}\n.sidebarblock p,.sidebarblock dt,.sidebarblock td.content,p.tableblock{font-size:1em}\n.exampleblock>.content{background-color:#fffef7;border-color:#e0e0dc;-webkit-box-shadow:0 1px 4px #e0e0dc;box-shadow:0 1px 4px #e0e0dc}\n.print-only{display:none!important}\n@page{margin:1.25cm .75cm}\n@media print{*{-webkit-box-shadow:none!important;box-shadow:none!important;text-shadow:none!important}\nhtml{font-size:80%}\na{color:inherit!important;text-decoration:underline!important}\na.bare,a[href^=\"#\"],a[href^=\"mailto:\"]{text-decoration:none!important}\na[href^=\"http:\"]:not(.bare)::after,a[href^=\"https:\"]:not(.bare)::after{content:\"(\" attr(href) \")\";display:inline-block;font-size:.875em;padding-left:.25em}\nabbr[title]::after{content:\" (\" attr(title) \")\"}\npre,blockquote,tr,img,object,svg{page-break-inside:avoid}\nthead{display:table-header-group}\nsvg{max-width:100%}\np,blockquote,dt,td.content{font-size:1em;orphans:3;widows:3}\nh2,h3,#toctitle,.sidebarblock>.content>.title{page-break-after:avoid}\n#toc,.sidebarblock,.exampleblock>.content{background:none!important}\n#toc{border-bottom:1px solid #dddddf!important;padding-bottom:0!important}\nbody.book #header{text-align:center}\nbody.book #header>h1:first-child{border:0!important;margin:2.5em 0 1em}\nbody.book #header .details{border:0!important;display:block;padding:0!important}\nbody.book #header .details span:first-child{margin-left:0!important}\nbody.book #header .details br{display:block}\nbody.book #header .details br+span::before{content:none!important}\nbody.book #toc{border:0!important;text-align:left!important;padding:0!important;margin:0!important}\nbody.book #toc,body.book #preamble,body.book h1.sect0,body.book .sect1>h2{page-break-before:always}\n.listingblock code[data-lang]::before{display:block}\n#footer{padding:0 .9375em}\n.hide-on-print{display:none!important}\n.print-only{display:block!important}\n.hide-for-print{display:none!important}\n.show-for-print{display:inherit!important}}\n@media print,amzn-kf8{#header>h1:first-child{margin-top:1.25rem}\n.sect1{padding:0!important}\n.sect1+.sect1{border:0}\n#footer{background:none}\n#footer-text{color:rgba(0,0,0,.6);font-size:.9em}}\n@media amzn-kf8{#header,#content,#footnotes,#footer{padding:0}}\n\n/* Zajo's customizations applied on top of the standard asciidoctor css above */\nh1{font-size:4em}\nh2{font-size:1.74em}\nh3,#toctitle,.sidebarblock>.content>.title{font-size:1.5em}\nh4{font-size:1.2em}\nh5{font-size:1em}\nh6{font-size:1em}\n#toc {text-align:left}\n#toc ul code{font-size:111%}\n#toc a:hover code {color:#00cc99}\na:focus{outline:0}\n.colist td{color:rgba(255,255,255,.67)}\nbody{text-align:left; background:#202020;color:rgba(255,255,255,.67);padding:0;margin:0;font-family:\"Istok Web\",\"DejaVu Serif\",serif;font-weight:400;font-style:normal;line-height:1;position:relative;cursor:auto;tab-size:4;-moz-osx-font-smoothing:grayscale;-webkit-font-smoothing:antialiased}\n.subheader,.admonitionblock td.content>.title,.audioblock>.title,.exampleblock>.title,.imageblock>.title,.listingblock>.title,.literalblock>.title,.stemblock>.title,.openblock>.title,.paragraph>.title,.quoteblock>.title,table.tableblock>.title,.verseblock>.title,.videoblock>.title,.dlist>.title,.olist>.title,.ulist>.title,.qlist>.title,.hdlist>.title{line-height:1.45;color:#a0a0a0;font-weight:400;margin-top:0;margin-bottom:.25em}\n.literalblock pre,.listingblock pre:not(.highlight),.listingblock pre[class=\"highlight\"],.listingblock pre[class^=\"highlight \"],.listingblock pre.CodeRay,.listingblock pre.prettyprint{background:#101010}\ntable{background:#202020;margin-bottom:1.25em;border:solid 1px #dedede}\ntable tr th,table tr td{padding:.5625em .625em;font-size:inherit;color:rgba(255,255,255,.67)}\ntable tr.even,table tr.alt,table tr:nth-of-type(even){background:#202020}\ntable thead tr th,table thead tr td,table tfoot tr th,table tfoot tr td{color:rgba(255,255,255,.67)}\nth{background-color:#404040}\na{color:#FFFFFF;text-decoration:underline;line-height:inherit}\na:hover{color:#00cc99}\na:focus{color:#FFFFFF}\nh1,h2,h3,#toctitle,.sidebarblock>.content>.title,h4,h5,h6{font-family:\"Quicksand\",\"DejaVu Sans\",sans-serif;font-weight:300;font-style:normal;color:#00cc99;text-rendering:optimizeLegibility;margin-top:1em;margin-bottom:.5em;line-height:1.4em}\ncode{font-family:\"Anonymous Pro\",\"DejaVu Sans Mono\",monospace;font-weight:400;color:black}\n*:not(pre)>code{font-size:1.08em;font-style:normal!important;letter-spacing:0;padding:0 0;word-spacing:-.15em;background-color:transparent;-webkit-border-radius:0;border-radius:0;line-height:1.45;text-rendering:optimizeLegibility;word-wrap:break-word;color:white}\npre,pre>code{line-height:1.45;color:rgba(255,255,255,.67);font-family:\"Anonymous Pro\",\"DejaVu Sans Mono\",monospace;font-weight:400;text-rendering:optimizeLegibility;font-size:1.05em;background-color:#101010}\na:not(pre)>code:hover {color:#00cc99}\nkbd{font-family:\"Anonymous Pro\",\"DejaVu Sans Mono\",monospace;display:inline-block;color:rgba(0,0,0,.8);font-size:.65em;line-height:1.45;background-color:#f7f7f7;border:1px solid #ccc;-webkit-border-radius:3px;border-radius:3px;-webkit-box-shadow:0 1px 0 rgba(0,0,0,.2),0 0 0 .1em white inset;box-shadow:0 1px 0 rgba(0,0,0,.2),0 0 0 .1em #fff inset;margin:0 .15em;padding:.2em .5em;vertical-align:middle;position:relative;top:-.1em;white-space:nowrap}\nh1 code{color:#00cc99; font-size:113%}\nh2 code{color:#00cc99; font-size:113%}\nh3 code{color:#00cc99; font-size:113%}\nh4 code{color:#00cc99; font-size:113%}\nh5 code{color:#00cc99; font-size:113%}\n#header>h1:first-child{font-family:\"Poiret One\";color:#00cc99;margin-top:2.25rem;margin-bottom:0;letter-spacing:-.07em}\n#author{color:#a366ff}\n#toc ul{font-family:\"Quicksand\",\"DejaVu Sans\",sans-serif;list-style-type:none}\n#toc a:hover{color:#00cc99}\n#toc.toc2{background-color:#404040}\n.admonitionblock td.icon .icon-note::before{content:\"\\f05a\";color:#00cc99}\n.admonitionblock td.icon .icon-tip::before{content:\"\\f0eb\";color:#00cc99;text-shadow:none}\n.admonitionblock td.icon .icon-warning::before{content:\"\\f071\";color:#a366ff}\n.admonitionblock td.icon .icon-caution::before{content:\"\\f06d\";color:#a366ff}\n.admonitionblock td.icon .icon-important::before{content:\"\\f06a\";color:#a366ff}\n.admonitionblock>table td.content{padding-left:1.125em;padding-right:1.25em;border-left:1px solid #dddddf;color:rgba(255,255,255,.67)}\n.conum[data-value]{display:inline-block;color:black!important;background-color:#d9d9d9;-webkit-border-radius:100px;border-radius:100px;text-align:center;font-size:.75em;width:1.67em;height:1.67em;line-height:1.67em;font-family:\"Open Sans\",\"DejaVu Sans\",sans-serif;font-style:normal;font-weight:bold}\n.exampleblock>.content{background-color:#404040;border-color:#e0e0dc;-webkit-box-shadow:0 1px 4px #e0e0dc;box-shadow:0 1px 4px #e0e0dc}\n.quoteblock {background-color:#404040}\n.quoteblock blockquote,.quoteblock p{color:rgba(255,255,255,.67);font-size:1.15rem;line-height:1.75;word-spacing:.1em;letter-spacing:0;font-style:italic;text-align:justify;background-color:#404040}\n.quoteblock blockquote::before{margin-left:-.8em;color:#00cc99}\n.quoteblock blockquote{font-family:\"Istok Web\",\"DejaVu Serif\"; font-size:1.0625rem; padding:0.5em}\n.quoteblock .attribution{padding-top:.75ex;margin-top:0;margin-right:0;padding-right:.5ex;text-align:right;background-color:#202020}\n.text-right{margin-top:-1em}\n" }, { "path": "doc/zajo-light.css", "content": "/* Asciidoctor default stylesheet | MIT License | http://asciidoctor.org */\n/* Uncomment @import statement below to use as custom stylesheet */\n/*@import \"https://fonts.googleapis.com/css?family=Open+Sans:300,300italic,400,400italic,600,600italic%7CNoto+Serif:400,400italic,700,700italic%7CDroid+Sans+Mono:400,700\";*/\n\n/* Zajo's custom font import. The rest of the customizations are at the bottom of this css file, which is otherwise kept unchanged */\n@import \"https://fonts.googleapis.com/css?family=Anonymous+Pro|Istok+Web|Quicksand|Poiret+One\";\n\narticle,aside,details,figcaption,figure,footer,header,hgroup,main,nav,section,summary{display:block}\naudio,canvas,video{display:inline-block}\naudio:not([controls]){display:none;height:0}\nscript{display:none!important}\nhtml{font-family:sans-serif;-ms-text-size-adjust:100%;-webkit-text-size-adjust:100%}\na{background:transparent}\na:focus{outline:thin dotted}\na:active,a:hover{outline:0}\nh1{font-size:2em;margin:.67em 0}\nabbr[title]{border-bottom:1px dotted}\nb,strong{font-weight:bold}\ndfn{font-style:italic}\nhr{-moz-box-sizing:content-box;box-sizing:content-box;height:0}\nmark{background:#ff0;color:#000}\ncode,kbd,pre,samp{font-family:monospace;font-size:1em}\npre{white-space:pre-wrap}\nq{quotes:\"\\201C\" \"\\201D\" \"\\2018\" \"\\2019\"}\nsmall{font-size:80%}\nsub,sup{font-size:75%;line-height:0;position:relative;vertical-align:baseline}\nsup{top:-.5em}\nsub{bottom:-.25em}\nimg{border:0}\nsvg:not(:root){overflow:hidden}\nfigure{margin:0}\nfieldset{border:1px solid silver;margin:0 2px;padding:.35em .625em .75em}\nlegend{border:0;padding:0}\nbutton,input,select,textarea{font-family:inherit;font-size:100%;margin:0}\nbutton,input{line-height:normal}\nbutton,select{text-transform:none}\nbutton,html input[type=\"button\"],input[type=\"reset\"],input[type=\"submit\"]{-webkit-appearance:button;cursor:pointer}\nbutton[disabled],html input[disabled]{cursor:default}\ninput[type=\"checkbox\"],input[type=\"radio\"]{box-sizing:border-box;padding:0}\nbutton::-moz-focus-inner,input::-moz-focus-inner{border:0;padding:0}\ntextarea{overflow:auto;vertical-align:top}\ntable{border-collapse:collapse;border-spacing:0}\n*,*::before,*::after{-moz-box-sizing:border-box;-webkit-box-sizing:border-box;box-sizing:border-box}\nhtml,body{font-size:100%}\nbody{background:#fff;color:rgba(0,0,0,.8);padding:0;margin:0;font-family:\"Noto Serif\",\"DejaVu Serif\",serif;font-weight:400;font-style:normal;line-height:1;position:relative;cursor:auto;tab-size:4;-moz-osx-font-smoothing:grayscale;-webkit-font-smoothing:antialiased}\na:hover{cursor:pointer}\nimg,object,embed{max-width:100%;height:auto}\nobject,embed{height:100%}\nimg{-ms-interpolation-mode:bicubic}\n.left{float:left!important}\n.right{float:right!important}\n.text-left{text-align:left!important}\n.text-right{text-align:right!important}\n.text-center{text-align:center!important}\n.text-justify{text-align:justify!important}\n.hide{display:none}\nimg,object,svg{display:inline-block;vertical-align:middle}\ntextarea{height:auto;min-height:50px}\nselect{width:100%}\n.center{margin-left:auto;margin-right:auto}\n.stretch{width:100%}\n.subheader,.admonitionblock td.content>.title,.audioblock>.title,.exampleblock>.title,.imageblock>.title,.listingblock>.title,.literalblock>.title,.stemblock>.title,.openblock>.title,.paragraph>.title,.quoteblock>.title,table.tableblock>.title,.verseblock>.title,.videoblock>.title,.dlist>.title,.olist>.title,.ulist>.title,.qlist>.title,.hdlist>.title{line-height:1.45;color:#7a2518;font-weight:400;margin-top:0;margin-bottom:.25em}\ndiv,dl,dt,dd,ul,ol,li,h1,h2,h3,#toctitle,.sidebarblock>.content>.title,h4,h5,h6,pre,form,p,blockquote,th,td{margin:0;padding:0;direction:ltr}\na{color:#2156a5;text-decoration:underline;line-height:inherit}\na:hover,a:focus{color:#1d4b8f}\na img{border:none}\np{font-family:inherit;font-weight:400;font-size:1em;line-height:1.6;margin-bottom:1.25em;text-rendering:optimizeLegibility}\np aside{font-size:.875em;line-height:1.35;font-style:italic}\nh1,h2,h3,#toctitle,.sidebarblock>.content>.title,h4,h5,h6{font-family:\"Open Sans\",\"DejaVu Sans\",sans-serif;font-weight:300;font-style:normal;color:#ba3925;text-rendering:optimizeLegibility;margin-top:1em;margin-bottom:.5em;line-height:1.0125em}\nh1 small,h2 small,h3 small,#toctitle small,.sidebarblock>.content>.title small,h4 small,h5 small,h6 small{font-size:60%;color:#e99b8f;line-height:0}\nh1{font-size:2.125em}\nh2{font-size:1.6875em}\nh3,#toctitle,.sidebarblock>.content>.title{font-size:1.375em}\nh4,h5{font-size:1.125em}\nh6{font-size:1em}\nhr{border:solid #dddddf;border-width:1px 0 0;clear:both;margin:1.25em 0 1.1875em;height:0}\nem,i{font-style:italic;line-height:inherit}\nstrong,b{font-weight:bold;line-height:inherit}\nsmall{font-size:60%;line-height:inherit}\ncode{font-family:\"Droid Sans Mono\",\"DejaVu Sans Mono\",monospace;font-weight:400;color:rgba(0,0,0,.9)}\nul,ol,dl{font-size:1em;line-height:1.6;margin-bottom:1.25em;list-style-position:outside;font-family:inherit}\nul,ol{margin-left:1.5em}\nul li ul,ul li ol{margin-left:1.25em;margin-bottom:0;font-size:1em}\nul.square li ul,ul.circle li ul,ul.disc li ul{list-style:inherit}\nul.square{list-style-type:square}\nul.circle{list-style-type:circle}\nul.disc{list-style-type:disc}\nol li ul,ol li ol{margin-left:1.25em;margin-bottom:0}\ndl dt{margin-bottom:.3125em;font-weight:bold}\ndl dd{margin-bottom:1.25em}\nabbr,acronym{text-transform:uppercase;font-size:90%;color:rgba(0,0,0,.8);border-bottom:1px dotted #ddd;cursor:help}\nabbr{text-transform:none}\nblockquote{margin:0 0 1.25em;padding:.5625em 1.25em 0 1.1875em;border-left:1px solid #ddd}\nblockquote cite{display:block;font-size:.9375em;color:rgba(0,0,0,.6)}\nblockquote cite::before{content:\"\\2014 \\0020\"}\nblockquote cite a,blockquote cite a:visited{color:rgba(0,0,0,.6)}\nblockquote,blockquote p{line-height:1.6;color:rgba(0,0,0,.85)}\n@media screen and (min-width:768px){h1,h2,h3,#toctitle,.sidebarblock>.content>.title,h4,h5,h6{line-height:1.2}\nh1{font-size:2.75em}\nh2{font-size:2.3125em}\nh3,#toctitle,.sidebarblock>.content>.title{font-size:1.6875em}\nh4{font-size:1.4375em}}\ntable{background:#fff;margin-bottom:1.25em;border:solid 1px #dedede}\ntable thead,table tfoot{background:#f7f8f7}\ntable thead tr th,table thead tr td,table tfoot tr th,table tfoot tr td{padding:.5em .625em .625em;font-size:inherit;color:rgba(0,0,0,.8);text-align:left}\ntable tr th,table tr td{padding:.5625em .625em;font-size:inherit;color:rgba(0,0,0,.8)}\ntable tr.even,table tr.alt,table tr:nth-of-type(even){background:#f8f8f7}\ntable thead tr th,table tfoot tr th,table tbody tr td,table tr td,table tfoot tr td{display:table-cell;line-height:1.6}\nh1,h2,h3,#toctitle,.sidebarblock>.content>.title,h4,h5,h6{line-height:1.2;word-spacing:-.05em}\nh1 strong,h2 strong,h3 strong,#toctitle strong,.sidebarblock>.content>.title strong,h4 strong,h5 strong,h6 strong{font-weight:400}\n.clearfix::before,.clearfix::after,.float-group::before,.float-group::after{content:\" \";display:table}\n.clearfix::after,.float-group::after{clear:both}\n*:not(pre)>code{font-size:.9375em;font-style:normal!important;letter-spacing:0;padding:.1em .5ex;word-spacing:-.15em;background-color:#f7f7f8;-webkit-border-radius:4px;border-radius:4px;line-height:1.45;text-rendering:optimizeSpeed;word-wrap:break-word}\n*:not(pre)>code.nobreak{word-wrap:normal}\n*:not(pre)>code.nowrap{white-space:nowrap}\npre,pre>code{line-height:1.45;color:rgba(0,0,0,.9);font-family:\"Droid Sans Mono\",\"DejaVu Sans Mono\",monospace;font-weight:400;text-rendering:optimizeSpeed}\nem em{font-style:normal}\nstrong strong{font-weight:400}\n.keyseq{color:rgba(51,51,51,.8)}\nkbd{font-family:\"Droid Sans Mono\",\"DejaVu Sans Mono\",monospace;display:inline-block;color:rgba(0,0,0,.8);font-size:.65em;line-height:1.45;background-color:#f7f7f7;border:1px solid #ccc;-webkit-border-radius:3px;border-radius:3px;-webkit-box-shadow:0 1px 0 rgba(0,0,0,.2),0 0 0 .1em white inset;box-shadow:0 1px 0 rgba(0,0,0,.2),0 0 0 .1em #fff inset;margin:0 .15em;padding:.2em .5em;vertical-align:middle;position:relative;top:-.1em;white-space:nowrap}\n.keyseq kbd:first-child{margin-left:0}\n.keyseq kbd:last-child{margin-right:0}\n.menuseq,.menuref{color:#000}\n.menuseq b:not(.caret),.menuref{font-weight:inherit}\n.menuseq{word-spacing:-.02em}\n.menuseq b.caret{font-size:1.25em;line-height:.8}\n.menuseq i.caret{font-weight:bold;text-align:center;width:.45em}\nb.button::before,b.button::after{position:relative;top:-1px;font-weight:400}\nb.button::before{content:\"[\";padding:0 3px 0 2px}\nb.button::after{content:\"]\";padding:0 2px 0 3px}\np a>code:hover{color:rgba(0,0,0,.9)}\n#header,#content,#footnotes,#footer{width:100%;margin-left:auto;margin-right:auto;margin-top:0;margin-bottom:0;max-width:62.5em;*zoom:1;position:relative;padding-left:.9375em;padding-right:.9375em}\n#header::before,#header::after,#content::before,#content::after,#footnotes::before,#footnotes::after,#footer::before,#footer::after{content:\" \";display:table}\n#header::after,#content::after,#footnotes::after,#footer::after{clear:both}\n#content{margin-top:1.25em}\n#content::before{content:none}\n#header>h1:first-child{color:rgba(0,0,0,.85);margin-top:2.25rem;margin-bottom:0}\n#header>h1:first-child+#toc{margin-top:8px;border-top:1px solid #dddddf}\n#header>h1:only-child,body.toc2 #header>h1:nth-last-child(2){border-bottom:1px solid #dddddf;padding-bottom:8px}\n#header .details{border-bottom:1px solid #dddddf;line-height:1.45;padding-top:.25em;padding-bottom:.25em;padding-left:.25em;color:rgba(0,0,0,.6);display:-ms-flexbox;display:-webkit-flex;display:flex;-ms-flex-flow:row wrap;-webkit-flex-flow:row wrap;flex-flow:row wrap}\n#header .details span:first-child{margin-left:-.125em}\n#header .details span.email a{color:rgba(0,0,0,.85)}\n#header .details br{display:none}\n#header .details br+span::before{content:\"\\00a0\\2013\\00a0\"}\n#header .details br+span.author::before{content:\"\\00a0\\22c5\\00a0\";color:rgba(0,0,0,.85)}\n#header .details br+span#revremark::before{content:\"\\00a0|\\00a0\"}\n#header #revnumber{text-transform:capitalize}\n#header #revnumber::after{content:\"\\00a0\"}\n#content>h1:first-child:not([class]){color:rgba(0,0,0,.85);border-bottom:1px solid #dddddf;padding-bottom:8px;margin-top:0;padding-top:1rem;margin-bottom:1.25rem}\n#toc{border-bottom:1px solid #e7e7e9;padding-bottom:.5em}\n#toc>ul{margin-left:.125em}\n#toc ul.sectlevel0>li>a{font-style:italic}\n#toc ul.sectlevel0 ul.sectlevel1{margin:.5em 0}\n#toc ul{font-family:\"Open Sans\",\"DejaVu Sans\",sans-serif;list-style-type:none}\n#toc li{line-height:1.3334;margin-top:.3334em}\n#toc a{text-decoration:none}\n#toc a:active{text-decoration:underline}\n#toctitle{color:#7a2518;font-size:1.2em}\n@media screen and (min-width:768px){#toctitle{font-size:1.375em}\nbody.toc2{padding-left:15em;padding-right:0}\n#toc.toc2{margin-top:0!important;background-color:#f8f8f7;position:fixed;width:15em;left:0;top:0;border-right:1px solid #e7e7e9;border-top-width:0!important;border-bottom-width:0!important;z-index:1000;padding:1.25em 1em;height:100%;overflow:auto}\n#toc.toc2 #toctitle{margin-top:0;margin-bottom:.8rem;font-size:1.2em}\n#toc.toc2>ul{font-size:.9em;margin-bottom:0}\n#toc.toc2 ul ul{margin-left:0;padding-left:1em}\n#toc.toc2 ul.sectlevel0 ul.sectlevel1{padding-left:0;margin-top:.5em;margin-bottom:.5em}\nbody.toc2.toc-right{padding-left:0;padding-right:15em}\nbody.toc2.toc-right #toc.toc2{border-right-width:0;border-left:1px solid #e7e7e9;left:auto;right:0}}\n@media screen and (min-width:1280px){body.toc2{padding-left:20em;padding-right:0}\n#toc.toc2{width:20em}\n#toc.toc2 #toctitle{font-size:1.375em}\n#toc.toc2>ul{font-size:.95em}\n#toc.toc2 ul ul{padding-left:1.25em}\nbody.toc2.toc-right{padding-left:0;padding-right:20em}}\n#content #toc{border-style:solid;border-width:1px;border-color:#e0e0dc;margin-bottom:1.25em;padding:1.25em;background:#f8f8f7;-webkit-border-radius:4px;border-radius:4px}\n#content #toc>:first-child{margin-top:0}\n#content #toc>:last-child{margin-bottom:0}\n#footer{max-width:100%;background-color:rgba(0,0,0,.8);padding:1.25em}\n#footer-text{color:rgba(255,255,255,.8);line-height:1.44}\n#content{margin-bottom:.625em}\n.sect1{padding-bottom:.625em}\n@media screen and (min-width:768px){#content{margin-bottom:1.25em}\n.sect1{padding-bottom:1.25em}}\n.sect1:last-child{padding-bottom:0}\n.sect1+.sect1{border-top:1px solid #e7e7e9}\n#content h1>a.anchor,h2>a.anchor,h3>a.anchor,#toctitle>a.anchor,.sidebarblock>.content>.title>a.anchor,h4>a.anchor,h5>a.anchor,h6>a.anchor{position:absolute;z-index:1001;width:1.5ex;margin-left:-1.5ex;display:block;text-decoration:none!important;visibility:hidden;text-align:center;font-weight:400}\n#content h1>a.anchor::before,h2>a.anchor::before,h3>a.anchor::before,#toctitle>a.anchor::before,.sidebarblock>.content>.title>a.anchor::before,h4>a.anchor::before,h5>a.anchor::before,h6>a.anchor::before{content:\"\\00A7\";font-size:.85em;display:block;padding-top:.1em}\n#content h1:hover>a.anchor,#content h1>a.anchor:hover,h2:hover>a.anchor,h2>a.anchor:hover,h3:hover>a.anchor,#toctitle:hover>a.anchor,.sidebarblock>.content>.title:hover>a.anchor,h3>a.anchor:hover,#toctitle>a.anchor:hover,.sidebarblock>.content>.title>a.anchor:hover,h4:hover>a.anchor,h4>a.anchor:hover,h5:hover>a.anchor,h5>a.anchor:hover,h6:hover>a.anchor,h6>a.anchor:hover{visibility:visible}\n#content h1>a.link,h2>a.link,h3>a.link,#toctitle>a.link,.sidebarblock>.content>.title>a.link,h4>a.link,h5>a.link,h6>a.link{color:#ba3925;text-decoration:none}\n#content h1>a.link:hover,h2>a.link:hover,h3>a.link:hover,#toctitle>a.link:hover,.sidebarblock>.content>.title>a.link:hover,h4>a.link:hover,h5>a.link:hover,h6>a.link:hover{color:#a53221}\n.audioblock,.imageblock,.literalblock,.listingblock,.stemblock,.videoblock{margin-bottom:1.25em}\n.admonitionblock td.content>.title,.audioblock>.title,.exampleblock>.title,.imageblock>.title,.listingblock>.title,.literalblock>.title,.stemblock>.title,.openblock>.title,.paragraph>.title,.quoteblock>.title,table.tableblock>.title,.verseblock>.title,.videoblock>.title,.dlist>.title,.olist>.title,.ulist>.title,.qlist>.title,.hdlist>.title{text-rendering:optimizeLegibility;text-align:left;font-family:\"Noto Serif\",\"DejaVu Serif\",serif;font-size:1rem;font-style:italic}\ntable.tableblock.fit-content>caption.title{white-space:nowrap;width:0}\n.paragraph.lead>p,#preamble>.sectionbody>[class=\"paragraph\"]:first-of-type p{font-size:1.21875em;line-height:1.6;color:rgba(0,0,0,.85)}\ntable.tableblock #preamble>.sectionbody>[class=\"paragraph\"]:first-of-type p{font-size:inherit}\n.admonitionblock>table{border-collapse:separate;border:0;background:none;width:100%}\n.admonitionblock>table td.icon{text-align:center;width:80px}\n.admonitionblock>table td.icon img{max-width:none}\n.admonitionblock>table td.icon .title{font-weight:bold;font-family:\"Open Sans\",\"DejaVu Sans\",sans-serif;text-transform:uppercase}\n.admonitionblock>table td.content{padding-left:1.125em;padding-right:1.25em;border-left:1px solid #dddddf;color:rgba(0,0,0,.6)}\n.admonitionblock>table td.content>:last-child>:last-child{margin-bottom:0}\n.exampleblock>.content{border-style:solid;border-width:1px;border-color:#e6e6e6;margin-bottom:1.25em;padding:1.25em;background:#fff;-webkit-border-radius:4px;border-radius:4px}\n.exampleblock>.content>:first-child{margin-top:0}\n.exampleblock>.content>:last-child{margin-bottom:0}\n.sidebarblock{border-style:solid;border-width:1px;border-color:#e0e0dc;margin-bottom:1.25em;padding:1.25em;background:#f8f8f7;-webkit-border-radius:4px;border-radius:4px}\n.sidebarblock>:first-child{margin-top:0}\n.sidebarblock>:last-child{margin-bottom:0}\n.sidebarblock>.content>.title{color:#7a2518;margin-top:0;text-align:center}\n.exampleblock>.content>:last-child>:last-child,.exampleblock>.content .olist>ol>li:last-child>:last-child,.exampleblock>.content .ulist>ul>li:last-child>:last-child,.exampleblock>.content .qlist>ol>li:last-child>:last-child,.sidebarblock>.content>:last-child>:last-child,.sidebarblock>.content .olist>ol>li:last-child>:last-child,.sidebarblock>.content .ulist>ul>li:last-child>:last-child,.sidebarblock>.content .qlist>ol>li:last-child>:last-child{margin-bottom:0}\n.literalblock pre,.listingblock pre:not(.highlight),.listingblock pre[class=\"highlight\"],.listingblock pre[class^=\"highlight \"],.listingblock pre.CodeRay,.listingblock pre.prettyprint{background:#f7f7f8}\n.sidebarblock .literalblock pre,.sidebarblock .listingblock pre:not(.highlight),.sidebarblock .listingblock pre[class=\"highlight\"],.sidebarblock .listingblock pre[class^=\"highlight \"],.sidebarblock .listingblock pre.CodeRay,.sidebarblock .listingblock pre.prettyprint{background:#f2f1f1}\n.literalblock pre,.literalblock pre[class],.listingblock pre,.listingblock pre[class]{-webkit-border-radius:4px;border-radius:4px;word-wrap:break-word;overflow-x:auto;padding:1em;font-size:.8125em}\n@media screen and (min-width:768px){.literalblock pre,.literalblock pre[class],.listingblock pre,.listingblock pre[class]{font-size:.90625em}}\n@media screen and (min-width:1280px){.literalblock pre,.literalblock pre[class],.listingblock pre,.listingblock pre[class]{font-size:1em}}\n.literalblock pre.nowrap,.literalblock pre.nowrap pre,.listingblock pre.nowrap,.listingblock pre.nowrap pre{white-space:pre;word-wrap:normal}\n.literalblock.output pre{color:#f7f7f8;background-color:rgba(0,0,0,.9)}\n.listingblock pre.highlightjs{padding:0}\n.listingblock pre.highlightjs>code{padding:1em;-webkit-border-radius:4px;border-radius:4px}\n.listingblock pre.prettyprint{border-width:0}\n.listingblock>.content{position:relative}\n.listingblock code[data-lang]::before{display:none;content:attr(data-lang);position:absolute;font-size:.75em;top:.425rem;right:.5rem;line-height:1;text-transform:uppercase;color:#999}\n.listingblock:hover code[data-lang]::before{display:block}\n.listingblock.terminal pre .command::before{content:attr(data-prompt);padding-right:.5em;color:#999}\n.listingblock.terminal pre .command:not([data-prompt])::before{content:\"$\"}\ntable.pyhltable{border-collapse:separate;border:0;margin-bottom:0;background:none}\ntable.pyhltable td{vertical-align:top;padding-top:0;padding-bottom:0;line-height:1.45}\ntable.pyhltable td.code{padding-left:.75em;padding-right:0}\npre.pygments .lineno,table.pyhltable td:not(.code){color:#999;padding-left:0;padding-right:.5em;border-right:1px solid #dddddf}\npre.pygments .lineno{display:inline-block;margin-right:.25em}\ntable.pyhltable .linenodiv{background:none!important;padding-right:0!important}\n.quoteblock{margin:0 1em 1.25em 1.5em;display:table}\n.quoteblock>.title{margin-left:-1.5em;margin-bottom:.75em}\n.quoteblock blockquote,.quoteblock p{color:rgba(0,0,0,.85);font-size:1.15rem;line-height:1.75;word-spacing:.1em;letter-spacing:0;font-style:italic;text-align:justify}\n.quoteblock blockquote{margin:0;padding:0;border:0}\n.quoteblock blockquote::before{content:\"\\201c\";float:left;font-size:2.75em;font-weight:bold;line-height:.6em;margin-left:-.6em;color:#7a2518;text-shadow:0 1px 2px rgba(0,0,0,.1)}\n.quoteblock blockquote>.paragraph:last-child p{margin-bottom:0}\n.quoteblock .attribution{margin-top:.75em;margin-right:.5ex;text-align:right}\n.verseblock{margin:0 1em 1.25em}\n.verseblock pre{font-family:\"Open Sans\",\"DejaVu Sans\",sans;font-size:1.15rem;color:rgba(0,0,0,.85);font-weight:300;text-rendering:optimizeLegibility}\n.verseblock pre strong{font-weight:400}\n.verseblock .attribution{margin-top:1.25rem;margin-left:.5ex}\n.quoteblock .attribution,.verseblock .attribution{font-size:.9375em;line-height:1.45;font-style:italic}\n.quoteblock .attribution br,.verseblock .attribution br{display:none}\n.quoteblock .attribution cite,.verseblock .attribution cite{display:block;letter-spacing:-.025em;color:rgba(0,0,0,.6)}\n.quoteblock.abstract blockquote::before,.quoteblock.excerpt blockquote::before,.quoteblock .quoteblock blockquote::before{display:none}\n.quoteblock.abstract blockquote,.quoteblock.abstract p,.quoteblock.excerpt blockquote,.quoteblock.excerpt p,.quoteblock .quoteblock blockquote,.quoteblock .quoteblock p{line-height:1.6;word-spacing:0}\n.quoteblock.abstract{margin:0 1em 1.25em;display:block}\n.quoteblock.abstract>.title{margin:0 0 .375em;font-size:1.15em;text-align:center}\n.quoteblock.excerpt,.quoteblock .quoteblock{margin:0 0 1.25em;padding:0 0 .25em 1em;border-left:.25em solid #dddddf}\n.quoteblock.excerpt blockquote,.quoteblock.excerpt p,.quoteblock .quoteblock blockquote,.quoteblock .quoteblock p{color:inherit;font-size:1.0625rem}\n.quoteblock.excerpt .attribution,.quoteblock .quoteblock .attribution{color:inherit;text-align:left;margin-right:0}\ntable.tableblock{max-width:100%;border-collapse:separate}\np.tableblock:last-child{margin-bottom:0}\ntd.tableblock>.content{margin-bottom:-1.25em}\ntable.tableblock,th.tableblock,td.tableblock{border:0 solid #dedede}\ntable.grid-all>thead>tr>.tableblock,table.grid-all>tbody>tr>.tableblock{border-width:0 1px 1px 0}\ntable.grid-all>tfoot>tr>.tableblock{border-width:1px 1px 0 0}\ntable.grid-cols>*>tr>.tableblock{border-width:0 1px 0 0}\ntable.grid-rows>thead>tr>.tableblock,table.grid-rows>tbody>tr>.tableblock{border-width:0 0 1px}\ntable.grid-rows>tfoot>tr>.tableblock{border-width:1px 0 0}\ntable.grid-all>*>tr>.tableblock:last-child,table.grid-cols>*>tr>.tableblock:last-child{border-right-width:0}\ntable.grid-all>tbody>tr:last-child>.tableblock,table.grid-all>thead:last-child>tr>.tableblock,table.grid-rows>tbody>tr:last-child>.tableblock,table.grid-rows>thead:last-child>tr>.tableblock{border-bottom-width:0}\ntable.frame-all{border-width:1px}\ntable.frame-sides{border-width:0 1px}\ntable.frame-topbot,table.frame-ends{border-width:1px 0}\ntable.stripes-all tr,table.stripes-odd tr:nth-of-type(odd){background:#f8f8f7}\ntable.stripes-none tr,table.stripes-odd tr:nth-of-type(even){background:none}\nth.halign-left,td.halign-left{text-align:left}\nth.halign-right,td.halign-right{text-align:right}\nth.halign-center,td.halign-center{text-align:center}\nth.valign-top,td.valign-top{vertical-align:top}\nth.valign-bottom,td.valign-bottom{vertical-align:bottom}\nth.valign-middle,td.valign-middle{vertical-align:middle}\ntable thead th,table tfoot th{font-weight:bold}\ntbody tr th{display:table-cell;line-height:1.6;background:#f7f8f7}\ntbody tr th,tbody tr th p,tfoot tr th,tfoot tr th p{color:rgba(0,0,0,.8);font-weight:bold}\np.tableblock>code:only-child{background:none;padding:0}\np.tableblock{font-size:1em}\ntd>div.verse{white-space:pre}\nol{margin-left:1.75em}\nul li ol{margin-left:1.5em}\ndl dd{margin-left:1.125em}\ndl dd:last-child,dl dd:last-child>:last-child{margin-bottom:0}\nol>li p,ul>li p,ul dd,ol dd,.olist .olist,.ulist .ulist,.ulist .olist,.olist .ulist{margin-bottom:.625em}\nul.checklist,ul.none,ol.none,ul.no-bullet,ol.no-bullet,ol.unnumbered,ul.unstyled,ol.unstyled{list-style-type:none}\nul.no-bullet,ol.no-bullet,ol.unnumbered{margin-left:.625em}\nul.unstyled,ol.unstyled{margin-left:0}\nul.checklist{margin-left:.625em}\nul.checklist li>p:first-child>.fa-square-o:first-child,ul.checklist li>p:first-child>.fa-check-square-o:first-child{width:1.25em;font-size:.8em;position:relative;bottom:.125em}\nul.checklist li>p:first-child>input[type=\"checkbox\"]:first-child{margin-right:.25em}\nul.inline{display:-ms-flexbox;display:-webkit-box;display:flex;-ms-flex-flow:row wrap;-webkit-flex-flow:row wrap;flex-flow:row wrap;list-style:none;margin:0 0 .625em -1.25em}\nul.inline>li{margin-left:1.25em}\n.unstyled dl dt{font-weight:400;font-style:normal}\nol.arabic{list-style-type:decimal}\nol.decimal{list-style-type:decimal-leading-zero}\nol.loweralpha{list-style-type:lower-alpha}\nol.upperalpha{list-style-type:upper-alpha}\nol.lowerroman{list-style-type:lower-roman}\nol.upperroman{list-style-type:upper-roman}\nol.lowergreek{list-style-type:lower-greek}\n.hdlist>table,.colist>table{border:0;background:none}\n.hdlist>table>tbody>tr,.colist>table>tbody>tr{background:none}\ntd.hdlist1,td.hdlist2{vertical-align:top;padding:0 .625em}\ntd.hdlist1{font-weight:bold;padding-bottom:1.25em}\n.literalblock+.colist,.listingblock+.colist{margin-top:-.5em}\n.colist td:not([class]):first-child{padding:.4em .75em 0;line-height:1;vertical-align:top}\n.colist td:not([class]):first-child img{max-width:none}\n.colist td:not([class]):last-child{padding:.25em 0}\n.thumb,.th{line-height:0;display:inline-block;border:solid 4px #fff;-webkit-box-shadow:0 0 0 1px #ddd;box-shadow:0 0 0 1px #ddd}\n.imageblock.left{margin:.25em .625em 1.25em 0}\n.imageblock.right{margin:.25em 0 1.25em .625em}\n.imageblock>.title{margin-bottom:0}\n.imageblock.thumb,.imageblock.th{border-width:6px}\n.imageblock.thumb>.title,.imageblock.th>.title{padding:0 .125em}\n.image.left,.image.right{margin-top:.25em;margin-bottom:.25em;display:inline-block;line-height:0}\n.image.left{margin-right:.625em}\n.image.right{margin-left:.625em}\na.image{text-decoration:none;display:inline-block}\na.image object{pointer-events:none}\nsup.footnote,sup.footnoteref{font-size:.875em;position:static;vertical-align:super}\nsup.footnote a,sup.footnoteref a{text-decoration:none}\nsup.footnote a:active,sup.footnoteref a:active{text-decoration:underline}\n#footnotes{padding-top:.75em;padding-bottom:.75em;margin-bottom:.625em}\n#footnotes hr{width:20%;min-width:6.25em;margin:-.25em 0 .75em;border-width:1px 0 0}\n#footnotes .footnote{padding:0 .375em 0 .225em;line-height:1.3334;font-size:.875em;margin-left:1.2em;margin-bottom:.2em}\n#footnotes .footnote a:first-of-type{font-weight:bold;text-decoration:none;margin-left:-1.05em}\n#footnotes .footnote:last-of-type{margin-bottom:0}\n#content #footnotes{margin-top:-.625em;margin-bottom:0;padding:.75em 0}\n.gist .file-data>table{border:0;background:#fff;width:100%;margin-bottom:0}\n.gist .file-data>table td.line-data{width:99%}\ndiv.unbreakable{page-break-inside:avoid}\n.big{font-size:larger}\n.small{font-size:smaller}\n.underline{text-decoration:underline}\n.overline{text-decoration:overline}\n.line-through{text-decoration:line-through}\n.aqua{color:#00bfbf}\n.aqua-background{background-color:#00fafa}\n.black{color:#000}\n.black-background{background-color:#000}\n.blue{color:#0000bf}\n.blue-background{background-color:#0000fa}\n.fuchsia{color:#bf00bf}\n.fuchsia-background{background-color:#fa00fa}\n.gray{color:#606060}\n.gray-background{background-color:#7d7d7d}\n.green{color:#006000}\n.green-background{background-color:#007d00}\n.lime{color:#00bf00}\n.lime-background{background-color:#00fa00}\n.maroon{color:#600000}\n.maroon-background{background-color:#7d0000}\n.navy{color:#000060}\n.navy-background{background-color:#00007d}\n.olive{color:#606000}\n.olive-background{background-color:#7d7d00}\n.purple{color:#600060}\n.purple-background{background-color:#7d007d}\n.red{color:#bf0000}\n.red-background{background-color:#fa0000}\n.silver{color:#909090}\n.silver-background{background-color:#bcbcbc}\n.teal{color:#006060}\n.teal-background{background-color:#007d7d}\n.white{color:#bfbfbf}\n.white-background{background-color:#fafafa}\n.yellow{color:#bfbf00}\n.yellow-background{background-color:#fafa00}\nspan.icon>.fa{cursor:default}\na span.icon>.fa{cursor:inherit}\n.admonitionblock td.icon [class^=\"fa icon-\"]{font-size:2.5em;text-shadow:1px 1px 2px rgba(0,0,0,.5);cursor:default}\n.admonitionblock td.icon .icon-note::before{content:\"\\f05a\";color:#19407c}\n.admonitionblock td.icon .icon-tip::before{content:\"\\f0eb\";text-shadow:1px 1px 2px rgba(155,155,0,.8);color:#111}\n.admonitionblock td.icon .icon-warning::before{content:\"\\f071\";color:#bf6900}\n.admonitionblock td.icon .icon-caution::before{content:\"\\f06d\";color:#bf3400}\n.admonitionblock td.icon .icon-important::before{content:\"\\f06a\";color:#bf0000}\n.conum[data-value]{display:inline-block;color:#fff!important;background-color:rgba(0,0,0,.8);-webkit-border-radius:100px;border-radius:100px;text-align:center;font-size:.75em;width:1.67em;height:1.67em;line-height:1.67em;font-family:\"Open Sans\",\"DejaVu Sans\",sans-serif;font-style:normal;font-weight:bold}\n.conum[data-value] *{color:#fff!important}\n.conum[data-value]+b{display:none}\n.conum[data-value]::after{content:attr(data-value)}\npre .conum[data-value]{position:relative;top:-.125em}\nb.conum *{color:inherit!important}\n.conum:not([data-value]):empty{display:none}\ndt,th.tableblock,td.content,div.footnote{text-rendering:optimizeLegibility}\nh1,h2,p,td.content,span.alt{letter-spacing:-.01em}\np strong,td.content strong,div.footnote strong{letter-spacing:-.005em}\np,blockquote,dt,td.content,span.alt{font-size:1.0625rem}\np{margin-bottom:1.25rem}\n.sidebarblock p,.sidebarblock dt,.sidebarblock td.content,p.tableblock{font-size:1em}\n.exampleblock>.content{background-color:#fffef7;border-color:#e0e0dc;-webkit-box-shadow:0 1px 4px #e0e0dc;box-shadow:0 1px 4px #e0e0dc}\n.print-only{display:none!important}\n@page{margin:1.25cm .75cm}\n@media print{*{-webkit-box-shadow:none!important;box-shadow:none!important;text-shadow:none!important}\nhtml{font-size:80%}\na{color:inherit!important;text-decoration:underline!important}\na.bare,a[href^=\"#\"],a[href^=\"mailto:\"]{text-decoration:none!important}\na[href^=\"http:\"]:not(.bare)::after,a[href^=\"https:\"]:not(.bare)::after{content:\"(\" attr(href) \")\";display:inline-block;font-size:.875em;padding-left:.25em}\nabbr[title]::after{content:\" (\" attr(title) \")\"}\npre,blockquote,tr,img,object,svg{page-break-inside:avoid}\nthead{display:table-header-group}\nsvg{max-width:100%}\np,blockquote,dt,td.content{font-size:1em;orphans:3;widows:3}\nh2,h3,#toctitle,.sidebarblock>.content>.title{page-break-after:avoid}\n#toc,.sidebarblock,.exampleblock>.content{background:none!important}\n#toc{border-bottom:1px solid #dddddf!important;padding-bottom:0!important}\nbody.book #header{text-align:center}\nbody.book #header>h1:first-child{border:0!important;margin:2.5em 0 1em}\nbody.book #header .details{border:0!important;display:block;padding:0!important}\nbody.book #header .details span:first-child{margin-left:0!important}\nbody.book #header .details br{display:block}\nbody.book #header .details br+span::before{content:none!important}\nbody.book #toc{border:0!important;text-align:left!important;padding:0!important;margin:0!important}\nbody.book #toc,body.book #preamble,body.book h1.sect0,body.book .sect1>h2{page-break-before:always}\n.listingblock code[data-lang]::before{display:block}\n#footer{padding:0 .9375em}\n.hide-on-print{display:none!important}\n.print-only{display:block!important}\n.hide-for-print{display:none!important}\n.show-for-print{display:inherit!important}}\n@media print,amzn-kf8{#header>h1:first-child{margin-top:1.25rem}\n.sect1{padding:0!important}\n.sect1+.sect1{border:0}\n#footer{background:none}\n#footer-text{color:rgba(0,0,0,.6);font-size:.9em}}\n@media amzn-kf8{#header,#content,#footnotes,#footer{padding:0}}\n\n/* Zajo's customizations applied on top of the standard asciidoctor css above */\nh1{font-size:4em}\nh2{font-size:1.74em}\nh3,#toctitle,.sidebarblock>.content>.title{font-size:1.5em}\nh4{font-size:1.2em}\nh5{font-size:1em}\nh6{font-size:1em}\n#toc {text-align:left}\n#toc ul code{font-size:111%}\n#toc a:hover code {color:#4101a7}\na:focus{outline:0}\n.colist td{color:rgba(0,0,0,.67)}\nbody{text-align:left; background:#fff;color:rgba(0,0,0,.67);padding:0;margin:0;font-family:\"Istok Web\",\"DejaVu Serif\",serif;font-weight:400;font-style:normal;line-height:1;position:relative;cursor:auto;tab-size:4;-moz-osx-font-smoothing:grayscale;-webkit-font-smoothing:antialiased}\n.subheader,.admonitionblock td.content>.title,.audioblock>.title,.exampleblock>.title,.imageblock>.title,.listingblock>.title,.literalblock>.title,.stemblock>.title,.openblock>.title,.paragraph>.title,.quoteblock>.title,table.tableblock>.title,.verseblock>.title,.videoblock>.title,.dlist>.title,.olist>.title,.ulist>.title,.qlist>.title,.hdlist>.title{line-height:1.45;color:#a0a0a0;font-weight:400;margin-top:0;margin-bottom:.25em}\na{color:#000000;text-decoration:underline;line-height:inherit}\na:hover{color:#4101a7}\na:focus{color:#000000}\nh1,h2,h3,#toctitle,.sidebarblock>.content>.title,h4,h5,h6{font-family:\"Quicksand\",\"DejaVu Sans\",sans-serif;font-weight:300;font-style:normal;color:#4101a7;text-rendering:optimizeLegibility;margin-top:1em;margin-bottom:.5em;line-height:1.4em}\ncode{font-family:\"Anonymous Pro\",\"DejaVu Sans Mono\",monospace;font-weight:400;color:black}\n*:not(pre)>code{font-size:1.08em;font-style:normal!important;letter-spacing:0;padding:0 0;word-spacing:-.15em;background-color:transparent;-webkit-border-radius:0;border-radius:0;line-height:1.45;text-rendering:optimizeLegibility;word-wrap:break-word}\npre,pre>code{line-height:1.45;color:rgba(0,0,0,.9);font-family:\"Anonymous Pro\",\"DejaVu Sans Mono\",monospace;font-weight:400;text-rendering:optimizeLegibility;font-size:1.05em;background-color:#f7f8f7}\na:not(pre)>code:hover {color:#4101a7}\nkbd{font-family:\"Anonymous Pro\",\"DejaVu Sans Mono\",monospace;display:inline-block;color:rgba(0,0,0,.8);font-size:.65em;line-height:1.45;background-color:#f7f7f7;border:1px solid #ccc;-webkit-border-radius:3px;border-radius:3px;-webkit-box-shadow:0 1px 0 rgba(0,0,0,.2),0 0 0 .1em white inset;box-shadow:0 1px 0 rgba(0,0,0,.2),0 0 0 .1em #fff inset;margin:0 .15em;padding:.2em .5em;vertical-align:middle;position:relative;top:-.1em;white-space:nowrap}\nh1 code{color:#4101a7; font-size:113%}\nh2 code{color:#4101a7; font-size:113%}\nh3 code{color:#4101a7; font-size:113%}\nh4 code{color:#4101a7; font-size:113%}\nh5 code{color:#4101a7; font-size:113%}\n#header>h1:first-child{font-family:\"Poiret One\";color:#ff5100;margin-top:2.25rem;margin-bottom:0;letter-spacing:-.07em}\n#author{color: #4101a7;}\n#toc ul{font-family:\"Quicksand\",\"DejaVu Sans\",sans-serif;list-style-type:none}\n#toc a:hover{color:#4101a7}\n#toc.toc2{background-color:#f7f8f7}\n.admonitionblock td.icon .icon-note::before{content:\"\\f05a\";color:#606060}\n.admonitionblock td.icon .icon-tip::before{content:\"\\f0eb\";color:#606060;text-shadow:none}\n.admonitionblock td.icon .icon-warning::before{content:\"\\f071\";color:#ff5100}\n.admonitionblock td.icon .icon-caution::before{content:\"\\f06d\";color:#ff5100}\n.admonitionblock td.icon .icon-important::before{content:\"\\f06a\";color:#ff5100}\n.conum[data-value]{display:inline-block;color:#fff!important;background-color:#606060;-webkit-border-radius:100px;border-radius:100px;text-align:center;font-size:.75em;width:1.67em;height:1.67em;line-height:1.67em;font-family:\"Open Sans\",\"DejaVu Sans\",sans-serif;font-style:normal;font-weight:bold}\n.exampleblock>.content{background-color:#ffffff;border-color:#e0e0dc;-webkit-box-shadow:0 1px 4px #e0e0dc;box-shadow:0 1px 4px #e0e0dc}\n.quoteblock blockquote::before{margin-left:-.8em;color:#4101a7}\n.quoteblock blockquote{font-family:\"Istok Web\",\"DejaVu Serif\"; font-size:1.0625rem; padding:0.5em}\n.text-right{margin-top:-1em}\n" }, { "path": "example/asio_beast_leaf_rpc.cpp", "content": "// Copyright (c) 2019 Sorin Fetche\n\n// Distributed under the Boost Software License, Version 1.0. (See accompanying\n// file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)\n\n// PLEASE NOTE: This example requires the Boost 1.70 version of Asio and Beast,\n// which at the time of this writing is in beta.\n\n// Example of a composed asynchronous operation which uses the LEAF library for\n// error handling and reporting.\n//\n// Examples of running:\n// - in one terminal (re)run: ./asio_beast_leaf_rpc_v3 0.0.0.0 8080\n// - in another run:\n// curl localhost:8080 -v -d \"sum 0 1 2 3\"\n// generating errors returned to the client:\n// curl localhost:8080 -v -X DELETE -d \"\"\n// curl localhost:8080 -v -d \"mul 1 2x3\"\n// curl localhost:8080 -v -d \"div 1 0\"\n// curl localhost:8080 -v -d \"mod 1\"\n//\n// Runs that showcase the error handling on the server side:\n// - error starting the server:\n// ./asio_beast_leaf_rpc_v3 0.0.0.0 80\n// - error while running the server logic:\n// ./asio_beast_leaf_rpc_v3 0.0.0.0 8080\n// curl localhost:8080 -v -d \"error-quit\"\n//\n#include \n#include \n#include \n#include \n#include \n#include \n#include \n#include \n#include \n#include \n#include \n#include \n#include \n#include \n#include \n\nnamespace beast = boost::beast;\nnamespace http = beast::http;\nnamespace leaf = boost::leaf;\nnamespace net = boost::asio;\n\nnamespace {\nusing error_code = boost::system::error_code;\n} // namespace\n\n// The operation being performed when an error occurs.\nstruct e_last_operation {\n std::string_view value;\n};\n\n// The HTTP request type.\nusing request_t = http::request;\n// The HTTP response type.\nusing response_t = http::response;\n\nresponse_t handle_request(request_t &&request);\n\n// A composed asynchronous operation that implements a basic remote calculator\n// over HTTP. It receives from the remote side commands such as:\n// sum 1 2 3\n// div 3 2\n// mod 1 0\n// in the body of POST requests and sends back the result.\n//\n// Besides the calculator related commands, it also offer a special command:\n// - `error_quit` that asks the server to simulate a server side error that\n// leads to the connection being dropped.\n//\n// From the error handling perspective there are three parts of the implementation:\n// - the handling of an HTTP request and creating the response to send back\n// (see handle_request)\n// - the parsing and execution of the remote command we received as the body of\n// an an HTTP POST request\n// (see execute_command())\n// - this composed asynchronous operation which calls them,\n//\n// This example operation is based on:\n// - https://github.com/boostorg/beast/blob/b02f59ff9126c5a17f816852efbbd0ed20305930/example/echo-op/echo_op.cpp\n// - part of\n// https://github.com/boostorg/beast/blob/b02f59ff9126c5a17f816852efbbd0ed20305930/example/advanced/server/advanced_server.cpp\n//\ntemplate \nauto async_demo_rpc(AsyncStream &stream, ErrorContext &error_context, CompletionToken &&token) ->\n typename net::async_result::type, void(leaf::result)>::return_type {\n\n static_assert(beast::is_async_stream::value, \"AsyncStream requirements not met\");\n\n using handler_type =\n typename net::async_completion)>::completion_handler_type;\n using base_type = beast::stable_async_base>;\n struct internal_op : base_type {\n // This object must have a stable address\n struct temporary_data {\n beast::flat_buffer buffer;\n std::optional> parser;\n std::optional response;\n };\n\n AsyncStream &m_stream;\n ErrorContext &m_error_context;\n temporary_data &m_data;\n bool m_write_and_quit;\n\n internal_op(AsyncStream &stream, ErrorContext &error_context, handler_type &&handler)\n : base_type{std::move(handler), stream.get_executor()}, m_stream{stream}, m_error_context{error_context},\n m_data{beast::allocate_stable(*this)}, m_write_and_quit{false} {\n start_read_request();\n }\n\n void operator()(error_code ec, std::size_t /*bytes_transferred*/ = 0) {\n leaf::result result_continue_execution;\n {\n auto active_context = activate_context(m_error_context);\n auto load = leaf::on_error(e_last_operation{m_data.response ? \"async_demo_rpc::continuation-write\"\n : \"async_demo_rpc::continuation-read\"});\n if (ec == http::error::end_of_stream) {\n // The remote side closed the connection.\n result_continue_execution = false;\n } else if (ec) {\n result_continue_execution = leaf::new_error(ec);\n } else {\n result_continue_execution = leaf::exception_to_result([&]() -> leaf::result {\n if (!m_data.response) {\n // Process the request we received.\n m_data.response = handle_request(std::move(m_data.parser->release()));\n m_write_and_quit = m_data.response->need_eof();\n http::async_write(m_stream, *m_data.response, std::move(*this));\n return true;\n }\n\n // If getting here, we completed a write operation.\n m_data.response.reset();\n // And start reading a new message if not quitting (i.e.\n // the message semantics of the last response we sent\n // required an end of file)\n if (!m_write_and_quit) {\n start_read_request();\n return true;\n }\n\n // We didn't initiate any new async operation above, so\n // we will not continue the execution.\n return false;\n });\n }\n // The activation object and load_last_operation need to be\n // reset before calling the completion handler This is because,\n // in general, the completion handler may be called directly or\n // posted and if posted, it could execute in another thread.\n // This means that regardless of how the handler gets to be\n // actually called we must ensure that it is not called with the\n // error context active. Note: An error context cannot be\n // activated twice\n }\n if (!result_continue_execution) {\n // We don't continue the execution due to an error, calling the\n // completion handler\n this->complete_now(result_continue_execution.error());\n } else if( !*result_continue_execution ) {\n // We don't continue the execution due to the flag not being\n // set, calling the completion handler\n this->complete_now(leaf::result{});\n }\n }\n\n void start_read_request() {\n m_data.parser.emplace();\n m_data.parser->body_limit(1024);\n http::async_read(m_stream, m_data.buffer, *m_data.parser, std::move(*this));\n }\n };\n\n auto initiation = [](auto &&completion_handler, AsyncStream *stream, ErrorContext *error_context) {\n internal_op op{*stream, *error_context, std::forward(completion_handler)};\n };\n\n // We are in the \"initiation\" part of the async operation.\n [[maybe_unused]] auto load = leaf::on_error(e_last_operation{\"async_demo_rpc::initiation\"});\n return net::async_initiate)>(initiation, token, &stream, &error_context);\n}\n\n// The location of a int64 parse error. It refers the range of characters from\n// which the parsing was done.\nstruct e_parse_int64_error {\n using location_base = std::pair;\n struct location : public location_base {\n using location_base::location_base;\n\n friend std::ostream &operator<<(std::ostream &os, location const &value) {\n auto const &sv = value.first;\n std::size_t pos = std::distance(sv.begin(), value.second);\n if (pos == 0) {\n os << \"->\\\"\" << sv << \"\\\"\";\n } else if (pos < sv.size()) {\n os << \"\\\"\" << sv.substr(0, pos) << \"\\\"->\\\"\" << sv.substr(pos) << \"\\\"\";\n } else {\n os << \"\\\"\" << sv << \"\\\"<-\";\n }\n return os;\n }\n };\n\n location value;\n};\n\n// Parses an integer from a string_view.\nleaf::result parse_int64(std::string_view word) {\n auto const begin = word.begin();\n auto const end = word.end();\n std::int64_t value = 0;\n auto i = begin;\n bool result = boost::spirit::qi::parse(i, end, boost::spirit::long_long, value);\n if (!result || i != end) {\n return leaf::new_error(e_parse_int64_error{std::make_pair(word, i)});\n }\n return value;\n}\n\n// The command being executed while we get an error. It refers the range of\n// characters from which the command was extracted.\nstruct e_command {\n std::string_view value;\n};\n\n// The details about an incorrect number of arguments error Some commands may\n// accept a variable number of arguments (e.g. greater than 1 would mean [2,\n// SIZE_MAX]).\nstruct e_unexpected_arg_count {\n struct arg_info {\n std::size_t count;\n std::size_t min;\n std::size_t max;\n\n friend std::ostream &operator<<(std::ostream &os, arg_info const &value) {\n os << value.count << \" (required: \";\n if (value.min == value.max) {\n os << value.min;\n } else if (value.max < SIZE_MAX) {\n os << \"[\" << value.min << \", \" << value.max << \"]\";\n } else {\n os << \"[\" << value.min << \", MAX]\";\n }\n os << \")\";\n return os;\n }\n };\n\n arg_info value;\n};\n\n// The HTTP status that should be returned in case we get into an error.\nstruct e_http_status {\n http::status value;\n};\n\n// Unexpected HTTP method.\nstruct e_unexpected_http_method {\n http::verb value;\n};\n\n// The E-type that describes the `error_quit` command as an error condition.\nstruct e_error_quit {\n struct none_t {};\n none_t value;\n};\n\n// Processes a remote command.\nleaf::result execute_command(std::string_view line) {\n // Split the command in words.\n std::list words; // or std::deque words;\n\n char const *const ws = \"\\t \\r\\n\";\n auto skip_ws = [&](std::string_view &line) {\n if (auto pos = line.find_first_not_of(ws); pos != std::string_view::npos) {\n line = line.substr(pos);\n } else {\n line = std::string_view{};\n }\n };\n\n skip_ws(line);\n while (!line.empty()) {\n std::string_view word;\n if (auto pos = line.find_first_of(ws); pos != std::string_view::npos) {\n word = line.substr(0, pos);\n line = line.substr(pos + 1);\n } else {\n word = line;\n line = std::string_view{};\n }\n\n if (!word.empty()) {\n words.push_back(word);\n }\n skip_ws(line);\n }\n\n static char const *const help = \"Help:\\n\"\n \" error-quit Simulated error to end the session\\n\"\n \" sum * Addition\\n\"\n \" sub + Substraction\\n\"\n \" mul * Multiplication\\n\"\n \" div + Division\\n\"\n \" mod Remainder\\n\"\n \" This message\";\n\n if (words.empty()) {\n return std::string(help);\n }\n\n auto command = words.front();\n words.pop_front();\n\n auto load_cmd = leaf::on_error(e_command{command}, e_http_status{http::status::bad_request});\n std::string response;\n\n if (command == \"error-quit\") {\n return leaf::new_error(e_error_quit{});\n } else if (command == \"sum\") {\n std::int64_t sum = 0;\n for (auto const &w : words) {\n BOOST_LEAF_AUTO(i, parse_int64(w));\n sum += i;\n }\n response = std::to_string(sum);\n } else if (command == \"sub\") {\n if (words.size() < 2) {\n return leaf::new_error(e_unexpected_arg_count{words.size(), 2, SIZE_MAX});\n }\n BOOST_LEAF_AUTO(sub, parse_int64(words.front()));\n words.pop_front();\n for (auto const &w : words) {\n BOOST_LEAF_AUTO(i, parse_int64(w));\n sub -= i;\n }\n response = std::to_string(sub);\n } else if (command == \"mul\") {\n std::int64_t mul = 1;\n for (auto const &w : words) {\n BOOST_LEAF_AUTO(i, parse_int64(w));\n mul *= i;\n }\n response = std::to_string(mul);\n } else if (command == \"div\") {\n if (words.size() < 2) {\n return leaf::new_error(e_unexpected_arg_count{words.size(), 2, SIZE_MAX});\n }\n BOOST_LEAF_AUTO(div, parse_int64(words.front()));\n words.pop_front();\n for (auto const &w : words) {\n BOOST_LEAF_AUTO(i, parse_int64(w));\n if (i == 0) {\n // In some cases this command execution function might throw,\n // not just return an error.\n throw std::runtime_error{\"division by zero\"};\n }\n div /= i;\n }\n response = std::to_string(div);\n } else if (command == \"mod\") {\n if (words.size() != 2) {\n return leaf::new_error(e_unexpected_arg_count{words.size(), 2, 2});\n }\n BOOST_LEAF_AUTO(i1, parse_int64(words.front()));\n words.pop_front();\n BOOST_LEAF_AUTO(i2, parse_int64(words.front()));\n words.pop_front();\n if (i2 == 0) {\n // In some cases this command execution function might throw, not\n // just return an error.\n leaf::throw_exception(std::runtime_error{\"division by zero\"});\n }\n response = std::to_string(i1 % i2);\n } else {\n response = help;\n }\n\n return response;\n}\n\nstd::string diagnostic_to_str(leaf::verbose_diagnostic_info const &diag) {\n auto str = boost::str(boost::format(\"%1%\") % diag);\n boost::algorithm::replace_all(str, \"\\n\", \"\\n \");\n return \"\\nDetailed error diagnostic:\\n----\\n\" + str + \"\\n----\";\n};\n\n// Handles an HTTP request and returns the response to send back.\nresponse_t handle_request(request_t &&request) {\n\n auto msg_prefix = [](e_command const *cmd) {\n if (cmd != nullptr) {\n return boost::str(boost::format(\"Error (%1%):\") % cmd->value);\n }\n return std::string(\"Error:\");\n };\n\n auto make_sr = [](e_http_status const *status, std::string &&response) {\n return std::make_pair(status != nullptr ? status->value : http::status::internal_server_error,\n std::move(response));\n };\n\n // In this variant of the RPC example we execute the remote command and\n // handle any errors coming from it in one place (using\n // `leaf::try_handle_all`).\n auto pair_status_response = leaf::try_handle_all(\n [&]() -> leaf::result> {\n if (request.method() != http::verb::post) {\n return leaf::new_error(e_unexpected_http_method{http::verb::post},\n e_http_status{http::status::bad_request});\n }\n BOOST_LEAF_AUTO(response, execute_command(request.body()));\n return std::make_pair(http::status::ok, std::move(response));\n },\n // For the `error_quit` command and associated error condition we have\n // the error handler itself fail (by throwing). This means that the\n // server will not send any response to the client, it will just\n // shutdown the connection. This implementation showcases two aspects:\n // - that the implementation of error handling can fail, too\n // - how the asynchronous operation calling this error handling function\n // reacts to this failure.\n [](e_error_quit const &) -> std::pair { throw std::runtime_error(\"error_quit\"); },\n // For the rest of error conditions we just build a message to be sent\n // to the remote client.\n [&](e_parse_int64_error const &e, e_http_status const *status, e_command const *cmd,\n leaf::verbose_diagnostic_info const &diag) {\n return make_sr(status, boost::str(boost::format(\"%1% int64 parse error: %2%\") % msg_prefix(cmd) % e.value) +\n diagnostic_to_str(diag));\n },\n [&](e_unexpected_arg_count const &e, e_http_status const *status, e_command const *cmd,\n leaf::verbose_diagnostic_info const &diag) {\n return make_sr(status,\n boost::str(boost::format(\"%1% wrong argument count: %2%\") % msg_prefix(cmd) % e.value) +\n diagnostic_to_str(diag));\n },\n [&](e_unexpected_http_method const &e, e_http_status const *status, e_command const *cmd,\n leaf::verbose_diagnostic_info const &diag) {\n return make_sr(status, boost::str(boost::format(\"%1% unexpected HTTP method. Expected: %2%\") %\n msg_prefix(cmd) % e.value) +\n diagnostic_to_str(diag));\n },\n [&](std::exception const & e, e_http_status const *status, e_command const *cmd,\n leaf::verbose_diagnostic_info const &diag) {\n return make_sr(status, boost::str(boost::format(\"%1% %2%\") % msg_prefix(cmd) % e.what()) +\n diagnostic_to_str(diag));\n },\n [&](e_http_status const *status, e_command const *cmd, leaf::verbose_diagnostic_info const &diag) {\n return make_sr(status, boost::str(boost::format(\"%1% unknown failure\") % msg_prefix(cmd)) +\n diagnostic_to_str(diag));\n });\n response_t response{pair_status_response.first, request.version()};\n response.set(http::field::server, \"Example-with-\" BOOST_BEAST_VERSION_STRING);\n response.set(http::field::content_type, \"text/plain\");\n response.keep_alive(request.keep_alive());\n pair_status_response.second += \"\\n\";\n response.body() = std::move(pair_status_response.second);\n response.prepare_payload();\n return response;\n}\n\nint main(int argc, char **argv) {\n auto msg_prefix = [](e_last_operation const *op) {\n if (op != nullptr) {\n return boost::str(boost::format(\"Error (%1%): \") % op->value);\n }\n return std::string(\"Error: \");\n };\n\n // Error handler for internal server internal errors (not communicated to\n // the remote client).\n auto error_handlers = std::make_tuple(\n [&](std::exception_ptr const &ep, e_last_operation const *op) {\n return leaf::try_handle_all(\n [&]() -> leaf::result { std::rethrow_exception(ep); },\n [&](std::exception const & e, leaf::verbose_diagnostic_info const &diag) {\n std::cerr << msg_prefix(op) << e.what() << \" (captured)\" << diagnostic_to_str(diag)\n << std::endl;\n return -11;\n },\n [&](leaf::verbose_diagnostic_info const &diag) {\n std::cerr << msg_prefix(op) << \"unknown (captured)\" << diagnostic_to_str(diag) << std::endl;\n return -12;\n });\n },\n [&](std::exception const & e, e_last_operation const *op, leaf::verbose_diagnostic_info const &diag) {\n std::cerr << msg_prefix(op) << e.what() << diagnostic_to_str(diag) << std::endl;\n return -21;\n },\n [&](error_code ec, leaf::verbose_diagnostic_info const &diag, e_last_operation const *op) {\n std::cerr << msg_prefix(op) << ec << \":\" << ec.message() << diagnostic_to_str(diag) << std::endl;\n return -22;\n },\n [&](leaf::verbose_diagnostic_info const &diag, e_last_operation const *op) {\n std::cerr << msg_prefix(op) << \"unknown\" << diagnostic_to_str(diag) << std::endl;\n return -23;\n });\n\n // Top level try block and error handler. It will handle errors from\n // starting the server for example failure to bind to a given port (e.g.\n // ports less than 1024 if not running as root)\n return leaf::try_handle_all(\n [&]() -> leaf::result {\n auto load = leaf::on_error(e_last_operation{\"main\"});\n if (argc != 3) {\n std::cerr << \"Usage: \" << argv[0] << \"

\" << std::endl;\n std::cerr << \"Example:\\n \" << argv[0] << \" 0.0.0.0 8080\" << std::endl;\n return -1;\n }\n\n auto const address{net::ip::make_address(argv[1])};\n auto const port{static_cast(std::atoi(argv[2]))};\n net::ip::tcp::endpoint const endpoint{address, port};\n\n net::io_context io_context;\n\n // Start the server acceptor and wait for a client.\n net::ip::tcp::acceptor acceptor{io_context, endpoint};\n\n auto local_endpoint = acceptor.local_endpoint();\n auto address_try_msg = acceptor.local_endpoint().address().to_string();\n if (address_try_msg == \"0.0.0.0\") {\n address_try_msg = \"localhost\";\n }\n std::cout << \"Server: Started on: \" << local_endpoint << std::endl;\n std::cout << \"Try in a different terminal:\\n\"\n << \" curl \" << address_try_msg << \":\" << local_endpoint.port() << \" -d \\\"\\\"\\nor\\n\"\n << \" curl \" << address_try_msg << \":\" << local_endpoint.port() << \" -d \\\"sum 1 2 3\\\"\"\n << std::endl;\n\n auto socket = acceptor.accept();\n std::cout << \"Server: Client connected: \" << socket.remote_endpoint() << std::endl;\n\n // The error context for the async operation.\n auto error_context = leaf::make_context(error_handlers);\n int rv = 0;\n async_demo_rpc(socket, error_context, [&](leaf::result result) {\n // Note: In case we wanted to add some additional information to\n // the error associated with the result we would need to\n // activate the error context\n auto active_context = activate_context(error_context);\n if (result) {\n std::cout << \"Server: Client work completed successfully\" << std::endl;\n rv = 0;\n } else {\n // Handle errors from running the server logic\n leaf::result result_int{result.error()};\n rv = error_context.handle_error(result_int.error(), error_handlers);\n }\n });\n io_context.run();\n\n // Let the remote side know we are shutting down.\n error_code ignored;\n socket.shutdown(net::ip::tcp::socket::shutdown_both, ignored);\n return rv;\n },\n error_handlers);\n}\n" }, { "path": "example/capture_in_exception.cpp", "content": "// Copyright 2018-2022 Emil Dotchevski and Reverge Studios, Inc.\n\n// Distributed under the Boost Software License, Version 1.0. (See accompanying\n// file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)\n\n// This is a simple program that demonstrates the use of LEAF to transport error\n// objects between threads, using exception handling. See capture_in_result.cpp\n// for the version that does not use exception handling.\n\n#include \n#include \n#include \n#include \n#include \n#include \n#include \n#include \n\nnamespace leaf = boost::leaf;\n\n// Define several error types.\nstruct e_thread_id { std::thread::id value; };\nstruct e_failure_info1 { std::string value; };\nstruct e_failure_info2 { int value; };\n\n// A type that represents a successfully returned result from a task.\nstruct task_result { };\n\n // This is our task function. It produces objects of type task_result, but it\n // may fail.\ntask_result task()\n{\n bool succeed = (rand()%4) != 0; //...at random.\n if( succeed )\n return { };\n else\n leaf::throw_exception(\n e_thread_id{std::this_thread::get_id()},\n e_failure_info1{\"info\"},\n e_failure_info2{42} );\n};\n\nint main()\n{\n int const task_count = 42;\n\n // The error_handlers are used in this thread (see leaf::try_catch below).\n // The arguments passed to individual lambdas are transported from the\n // worker thread to the main thread automatically.\n auto error_handlers = std::make_tuple(\n []( e_failure_info1 const & v1, e_failure_info2 const & v2, e_thread_id const & tid )\n {\n std::cerr << \"Error in thread \" << tid.value << \"! failure_info1: \" << v1.value << \", failure_info2: \" << v2.value << std::endl;\n },\n []( leaf::diagnostic_info const & unmatched )\n {\n std::cerr <<\n \"Unknown failure detected\" << std::endl <<\n \"Cryptic diagnostic information follows\" << std::endl <<\n unmatched;\n } );\n\n // Container to collect the generated std::future objects.\n std::vector> fut;\n\n // Launch the tasks, but rather than launching the task function directly,\n // we launch a wrapper function which calls leaf::capture, passing a context\n // object that will hold the error objects reported from the task in case it\n // throws. The error types the context is able to hold statically are\n // automatically deduced from the type of the error_handlers tuple.\n std::generate_n( std::back_inserter(fut), task_count,\n [&]\n {\n return std::async(\n std::launch::async,\n [&]\n {\n return leaf::capture(leaf::make_shared_context(error_handlers), &task);\n } );\n } );\n\n // Wait on the futures, get the task results, handle errors.\n for( auto & f : fut )\n {\n f.wait();\n\n leaf::try_catch(\n [&]\n {\n task_result r = f.get();\n\n // Success! Use r to access task_result.\n std::cout << \"Success!\" << std::endl;\n (void) r; // Presumably we'll somehow use the task_result.\n },\n error_handlers );\n }\n}\n" }, { "path": "example/capture_in_result.cpp", "content": "// Copyright 2018-2022 Emil Dotchevski and Reverge Studios, Inc.\n\n// Distributed under the Boost Software License, Version 1.0. (See accompanying\n// file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)\n\n// This is a simple program that demonstrates the use of LEAF to transport error\n// objects between threads, without using exception handling. See capture_eh.cpp\n// for the version that uses exception handling.\n\n#include \n#include \n#include \n#include \n#include \n#include \n#include \n#include \n\nnamespace leaf = boost::leaf;\n\n// Define several error types.\nstruct e_thread_id { std::thread::id value; };\nstruct e_failure_info1 { std::string value; };\nstruct e_failure_info2 { int value; };\n\n// A type that represents a successfully returned result from a task.\nstruct task_result { };\n\n // This is our task function. It produces objects of type task_result, but it\n // may fail.\nleaf::result task()\n{\n bool succeed = (rand()%4) != 0; //...at random.\n if( succeed )\n return { };\n else\n return leaf::new_error(\n e_thread_id{std::this_thread::get_id()},\n e_failure_info1{\"info\"},\n e_failure_info2{42} );\n};\n\nint main()\n{\n int const task_count = 42;\n\n // The error_handlers are used in this thread (see leaf::try_handle_all\n // below). The arguments passed to individual lambdas are transported from\n // the worker thread to the main thread automatically.\n auto error_handlers = std::make_tuple(\n []( e_failure_info1 const & v1, e_failure_info2 const & v2, e_thread_id const & tid )\n {\n std::cerr << \"Error in thread \" << tid.value << \"! failure_info1: \" << v1.value << \", failure_info2: \" << v2.value << std::endl;\n },\n []( leaf::diagnostic_info const & unmatched )\n {\n std::cerr <<\n \"Unknown failure detected\" << std::endl <<\n \"Cryptic diagnostic information follows\" << std::endl <<\n unmatched;\n } );\n\n // Container to collect the generated std::future objects.\n std::vector>> fut;\n\n // Launch the tasks, but rather than launching the task function directly,\n // we launch a wrapper function which calls leaf::capture, passing a context\n // object that will hold the error objects reported from the task in case of\n // an error. The error types the context is able to hold statically are\n // automatically deduced from the type of the error_handlers tuple.\n std::generate_n( std::back_inserter(fut), task_count,\n [&]\n {\n return std::async(\n std::launch::async,\n [&]\n {\n return leaf::capture(leaf::make_shared_context(error_handlers), &task);\n } );\n } );\n\n // Wait on the futures, get the task results, handle errors.\n for( auto & f : fut )\n {\n f.wait();\n\n leaf::try_handle_all(\n [&]() -> leaf::result\n {\n BOOST_LEAF_AUTO(r,f.get());\n\n // Success! Use r to access task_result.\n std::cout << \"Success!\" << std::endl;\n (void) r; // Presumably we'll somehow use the task_result.\n return { };\n },\n error_handlers );\n }\n}\n\n////////////////////////////////////////\n\n#ifdef BOOST_LEAF_NO_EXCEPTIONS\n\nnamespace boost\n{\n [[noreturn]] void throw_exception( std::exception const & e )\n {\n std::cerr << \"Terminating due to a C++ exception under BOOST_LEAF_NO_EXCEPTIONS: \" << e.what();\n std::terminate();\n }\n\n struct source_location;\n [[noreturn]] void throw_exception( std::exception const & e, boost::source_location const & )\n {\n throw_exception(e);\n }\n}\n\n#endif\n" }, { "path": "example/error_log.cpp", "content": "// Copyright 2018-2022 Emil Dotchevski and Reverge Studios, Inc.\n\n// Distributed under the Boost Software License, Version 1.0. (See accompanying\n// file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)\n\n// This program demonstrates the use of leaf::on_error to print the path an\n// error takes as it bubbles up the call stack. The printing code only runs if:\n// - An error occurs, and\n// - A handler that takes e_error_log argument is present. Otherwise none of the\n// error log machinery will be invoked by LEAF.\n\n// This example is similar to error_trace, except the path the error takes is\n// not captured, only printed.\n\n#include \n#include \n#include \n\n#define ENABLE_ERROR_LOG 1\n\nnamespace leaf = boost::leaf;\n\n// The error log is activated only if an error handling scope provides a handler\n// for e_error_log.\nstruct e_error_log\n{\n struct rec\n {\n char const * file;\n int line;\n friend std::ostream & operator<<( std::ostream & os, rec const & x )\n {\n return os << x.file << '(' << x.line << ')';\n }\n };\n\n e_error_log()\n {\n std::cerr << \"Error! Log:\" << std::endl;\n }\n\n // Our e_error_log instance is stateless, used only as a target to\n // operator<<.\n template \n friend std::ostream & operator<<( e_error_log const &, T const & x )\n {\n return std::cerr << x << std::endl;\n }\n};\n\n// The ERROR_LOG macro is designed for use in functions that detect or forward\n// errors up the call stack. If an error occurs, and if an error handling scope\n// provides a handler for e_error_log, the supplied lambda is executed as the\n// error bubbles up.\n#define ERROR_LOG auto _log = leaf::on_error( []( e_error_log & log ) { log << e_error_log::rec{__FILE__, __LINE__}; } )\n\n// Each function in the sequence below calls the previous function, and each\n// function has failure_percent chance of failing. If a failure occurs, the\n// ERROR_LOG macro will cause the path the error takes to be printed.\nint const failure_percent = 25;\n\nleaf::result f1()\n{\n ERROR_LOG;\n if( (std::rand()%100) > failure_percent )\n return { };\n else\n return leaf::new_error();\n}\n\nleaf::result f2()\n{\n ERROR_LOG;\n if( (std::rand()%100) > failure_percent )\n return f1();\n else\n return leaf::new_error();\n}\n\nleaf::result f3()\n{\n ERROR_LOG;\n if( (std::rand()%100) > failure_percent )\n return f2();\n else\n return leaf::new_error();\n}\n\nleaf::result f4()\n{\n ERROR_LOG;\n if( (std::rand()%100) > failure_percent )\n return f3();\n else\n return leaf::new_error();\n}\n\nleaf::result f5()\n{\n ERROR_LOG;\n if( (std::rand()%100) > failure_percent )\n return f4();\n else\n return leaf::new_error();\n}\n\nint main()\n{\n for( int i=0; i!=10; ++i )\n leaf::try_handle_all(\n [&]() -> leaf::result\n {\n std::cout << \"Run # \" << i << \": \";\n BOOST_LEAF_CHECK(f5());\n std::cout << \"Success!\" << std::endl;\n return { };\n },\n#if ENABLE_ERROR_LOG // This single #if enables or disables the printing of the error log.\n []( e_error_log const & )\n {\n },\n#endif\n []\n {\n std::cerr << \"Error!\" << std::endl;\n } );\n return 0;\n}\n\n////////////////////////////////////////\n\n#ifdef BOOST_LEAF_NO_EXCEPTIONS\n\nnamespace boost\n{\n [[noreturn]] void throw_exception( std::exception const & e )\n {\n std::cerr << \"Terminating due to a C++ exception under BOOST_LEAF_NO_EXCEPTIONS: \" << e.what();\n std::terminate();\n }\n\n struct source_location;\n [[noreturn]] void throw_exception( std::exception const & e, boost::source_location const & )\n {\n throw_exception(e);\n }\n}\n\n#endif\n" }, { "path": "example/error_trace.cpp", "content": "// Copyright 2018-2022 Emil Dotchevski and Reverge Studios, Inc.\n\n// Distributed under the Boost Software License, Version 1.0. (See accompanying\n// file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)\n\n// This program demonstrates the use of leaf::on_error to capture the path an\n// error takes as is bubbles up the call stack. The error path-capturing code\n// only runs if:\n// - An error occurs, and\n// - A handler that takes e_error_trace argument is present. Otherwise none of\n// the error trace machinery will be invoked by LEAF.\n\n// This example is similar to error_log, except the path the error takes is\n// recorded in a std::deque, rather than just printed in-place.\n\n#include \n#include \n#include \n#include \n\n#define ENABLE_ERROR_TRACE 1\n\nnamespace leaf = boost::leaf;\n\n// The error trace is activated only if an error handling scope provides a\n// handler for e_error_trace.\nstruct e_error_trace\n{\n struct rec\n {\n char const * file;\n int line;\n friend std::ostream & operator<<( std::ostream & os, rec const & x )\n {\n return os << x.file << '(' << x.line << ')' << std::endl;\n }\n };\n\n std::deque value;\n\n friend std::ostream & operator<<( std::ostream & os, e_error_trace const & tr )\n {\n for( auto & i : tr.value )\n os << i;\n return os;\n }\n};\n\n// The ERROR_TRACE macro is designed for use in functions that detect or forward\n// errors up the call stack. If an error occurs, and if an error handling scope\n// provides a handler for e_error_trace, the supplied lambda is executed as the\n// error bubbles up.\n#define ERROR_TRACE auto _trace = leaf::on_error( []( e_error_trace & tr ) { tr.value.emplace_front(e_error_trace::rec{__FILE__, __LINE__}); } )\n\n// Each function in the sequence below calls the previous function, and each\n// function has failure_percent chance of failing. If a failure occurs, the\n// ERROR_TRACE macro will cause the path the error takes to be captured in an\n// e_error_trace.\nint const failure_percent = 25;\n\nleaf::result f1()\n{\n ERROR_TRACE;\n if( (std::rand()%100) > failure_percent )\n return { };\n else\n return leaf::new_error();\n}\n\nleaf::result f2()\n{\n ERROR_TRACE;\n if( (std::rand()%100) > failure_percent )\n return f1();\n else\n return leaf::new_error();\n}\n\nleaf::result f3()\n{\n ERROR_TRACE;\n if( (std::rand()%100) > failure_percent )\n return f2();\n else\n return leaf::new_error();\n}\n\nleaf::result f4()\n{\n ERROR_TRACE;\n if( (std::rand()%100) > failure_percent )\n return f3();\n else\n return leaf::new_error();\n}\n\nleaf::result f5()\n{\n ERROR_TRACE;\n if( (std::rand()%100) > failure_percent )\n return f4();\n else\n return leaf::new_error();\n}\n\nint main()\n{\n for( int i=0; i!=10; ++i )\n leaf::try_handle_all(\n [&]() -> leaf::result\n {\n std::cout << \"Run # \" << i << \": \";\n BOOST_LEAF_CHECK(f5());\n std::cout << \"Success!\" << std::endl;\n return { };\n },\n#if ENABLE_ERROR_TRACE // This single #if enables or disables the capturing of the error trace.\n []( e_error_trace const & tr )\n {\n std::cerr << \"Error! Trace:\" << std::endl << tr;\n },\n#endif\n []\n {\n std::cerr << \"Error!\" << std::endl;\n } );\n return 0;\n}\n\n////////////////////////////////////////\n\n#ifdef BOOST_LEAF_NO_EXCEPTIONS\n\nnamespace boost\n{\n [[noreturn]] void throw_exception( std::exception const & e )\n {\n std::cerr << \"Terminating due to a C++ exception under BOOST_LEAF_NO_EXCEPTIONS: \" << e.what();\n std::terminate();\n }\n\n struct source_location;\n [[noreturn]] void throw_exception( std::exception const & e, boost::source_location const & )\n {\n throw_exception(e);\n }\n}\n\n#endif\n" }, { "path": "example/exception_to_result.cpp", "content": "// Copyright 2018-2022 Emil Dotchevski and Reverge Studios, Inc.\n\n// Distributed under the Boost Software License, Version 1.0. (See accompanying\n// file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)\n\n// This example demonstrates how to transport exceptions thrown by a low level\n// function through an intermediate scopes that are not exception-safe, to be\n// handled in a high level function which may or may not be exception-safe.\n\n#include \n#include \n\nnamespace leaf = boost::leaf;\n\nclass error_base: public virtual std::exception { };\nclass error_a: public virtual error_base { };\nclass error_b: public virtual error_base { };\nclass error_c: public virtual error_base { };\n\n\n// Lower-level library function which throws exceptions.\nint compute_answer_throws()\n{\n switch( rand()%4 )\n {\n default: return 42;\n case 1: throw error_a();\n case 2: throw error_b();\n case 3: throw error_c();\n }\n}\n\n\n// Call compute_answer_throws, switch to result for error handling.\nleaf::result compute_answer() noexcept\n{\n // Convert exceptions of types error_a and error_b to be communicated by\n // leaf::result. Any other exception will be communicated as a\n // std::exception_ptr.\n return leaf::exception_to_result(\n []\n {\n return compute_answer_throws();\n } );\n}\n\n\n// Print the answer if the call to compute_answer is successful.\nleaf::result print_answer() noexcept\n{\n BOOST_LEAF_AUTO( answer, compute_answer());\n std::cout << \"Answer: \" << answer << std::endl;\n return { };\n}\n\n\nint main()\n{\n // Exercise print_answer a few times and handle errors. Note that the\n // exception objects that compute_answer_throws throws are not handled as\n // exceptions, but as regular LEAF error error objects...\n for( int i=0; i!=42; ++i )\n {\n leaf::try_handle_all(\n []() -> leaf::result\n {\n BOOST_LEAF_CHECK(print_answer());\n return { };\n },\n\n []( error_a const & )\n {\n std::cerr << \"Error A!\" << std::endl;\n },\n\n []( error_b const & )\n {\n std::cerr << \"Error B!\" << std::endl;\n },\n\n // ...except for error_c errors, which (for demonstration) are\n // captured as exceptions into std::exception_ptr as \"unknown\"\n // exceptions. Presumably this should not happen, therefore at this\n // point we treat this situation as a logic error: we print\n // diagnostic information and bail out.\n []( std::exception_ptr const * ep )\n {\n std::cerr << \"Got unknown error!\" << std::endl;\n\n // Above, why do we take ep as a pointer? Because handle_all\n // requires that the last handler matches any error and, taken\n // as a pointer, if there isn't a std::exception_ptr associated\n // with the error, the handler will still be matched (with 0\n // passed for ep). Had we taken it by value or by const &, the\n // program would not have compiled.\n if( ep )\n leaf::try_catch(\n [&]\n {\n std::rethrow_exception(*ep);\n },\n []( leaf::error_info const & unmatched )\n {\n std::cerr << unmatched;\n } );\n } );\n }\n\n return 0;\n}\n" }, { "path": "example/lua_callback_eh.cpp", "content": "// Copyright 2018-2022 Emil Dotchevski and Reverge Studios, Inc.\n\n// Distributed under the Boost Software License, Version 1.0. (See accompanying\n// file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)\n\n// This is a simple program that shows how to report error objects out of a\n// C-callback (which may not throw exceptions).\n\nextern \"C\" {\n #include \"lua.h\"\n #include \"lauxlib.h\"\n}\n#include \n#include \n#include \n\nnamespace leaf = boost::leaf;\n\nenum do_work_error_code\n{\n ec1=1,\n ec2\n};\n\nstruct e_lua_pcall_error\n{\n int value;\n\n friend std::ostream & operator<<( std::ostream & os, e_lua_pcall_error const & x )\n {\n os << \"Lua error code = \" << x.value;\n switch( x.value )\n {\n case LUA_ERRRUN: return os << \" (LUA_ERRRUN)\";\n case LUA_ERRMEM: return os << \" (LUA_ERRMEM)\";\n case LUA_ERRERR: return os << \" (LUA_ERRERR)\";\n default: return os << \" (unknown)\";\n }\n }\n};\n\nstruct e_lua_error_message { std::string value; };\n\nstruct e_lua_exception { std::exception_ptr value; };\n\n// A noexcept wrapper for a lua_CFunction pointer. We capture the\n// std::current_exception and wrap it in a e_lua_exception object.\ntemplate \nint wrap_lua_CFunction( lua_State * L ) noexcept\n{\n return leaf::try_catch(\n [&]\n {\n return F(L);\n },\n [&]( leaf::error_info const & ei )\n {\n ei.error().load( e_lua_exception{std::current_exception()} );\n return luaL_error(L, \"C++ Exception\"); // luaL_error does not return (longjmp).\n } );\n}\n\n\n// This is a C callback with a specific signature, callable from programs\n// written in Lua. If it succeeds, it returns an int answer, by pushing it onto\n// the Lua stack. But \"sometimes\" it fails, in which case it throws an\n// exception, which will be processed by wrap_lua_CFunction (above).\nint do_work( lua_State * L )\n{\n bool success = rand() % 2; // \"Sometimes\" do_work fails.\n if( success )\n {\n lua_pushnumber(L, 42); // Success, push the result on the Lua stack, return to Lua.\n return 1;\n }\n else\n {\n leaf::throw_exception(ec1);\n }\n}\n\n\nstd::shared_ptr init_lua_state()\n{\n // Create a new lua_State, we'll use std::shared_ptr for automatic cleanup.\n std::shared_ptr L(lua_open(), &lua_close);\n\n // Register the do_work function (above) as a C callback, under the global\n // Lua name \"do_work\". With this, calls from Lua programs to do_work will\n // land in the do_work C function we've registered.\n lua_register( &*L, \"do_work\", &wrap_lua_CFunction<&do_work> );\n\n // Pass some Lua code as a C string literal to Lua. This creates a global\n // Lua function called \"call_do_work\", which we will later ask Lua to\n // execute.\n luaL_dostring( &*L, \"\\\n\\n function call_do_work()\\\n\\n return do_work()\\\n\\n end\" );\n\n return L;\n}\n\n\n// Here we will ask Lua to execute the function call_do_work, which is written\n// in Lua, and returns the value from do_work, which is written in C++ and\n// registered with the Lua interpreter as a C callback.\n\n// If do_work succeeds, we return the resulting int answer. If it fails, we'll\n// communicate that failure to our caller.\nint call_lua( lua_State * L )\n{\n return leaf::try_catch(\n [&]\n {\n leaf::error_monitor cur_err;\n\n // Ask the Lua interpreter to call the global Lua function call_do_work.\n lua_getfield( L, LUA_GLOBALSINDEX, \"call_do_work\" );\n if( int err = lua_pcall(L, 0, 1, 0) )\n {\n std::string msg = lua_tostring(L, 1);\n lua_pop(L,1);\n\n // We got a Lua error which may be the error we're reporting\n // from do_work, or some other error. If it is another error,\n // cur_err.assigned_error_id() will return a new leaf::error_id,\n // otherwise we'll be working with the original error reported\n // by a C++ exception out of do_work.\n leaf::throw_exception( cur_err.assigned_error_id().load( e_lua_pcall_error{err}, e_lua_error_message{std::move(msg)} ) );\n }\n else\n {\n // Success! Just return the int answer.\n int answer = lua_tonumber(L, -1);\n lua_pop(L, 1);\n return answer;\n }\n },\n\n []( e_lua_exception e ) -> int\n {\n // This is the exception communicated out of wrap_lua_CFunction.\n std::rethrow_exception( e.value );\n } );\n}\n\nint main()\n{\n std::shared_ptr L=init_lua_state();\n\n for( int i=0; i!=10; ++i )\n {\n leaf::try_catch(\n\n [&]\n {\n int answer = call_lua(&*L);\n std::cout << \"do_work succeeded, answer=\" << answer << '\\n';\n\n },\n\n []( do_work_error_code e, e_lua_error_message const & msg )\n {\n std::cout << \"Got do_work_error_code = \" << e << \", \" << msg.value << \"\\n\";\n },\n\n []( e_lua_pcall_error const & err, e_lua_error_message const & msg )\n {\n std::cout << \"Got e_lua_pcall_error, \" << err << \", \" << msg.value << \"\\n\";\n },\n\n []( leaf::error_info const & unmatched )\n {\n std::cerr <<\n \"Unknown failure detected\" << std::endl <<\n \"Cryptic diagnostic information follows\" << std::endl <<\n unmatched;\n } );\n }\n\n return 0;\n}\n" }, { "path": "example/lua_callback_result.cpp", "content": "// Copyright 2018-2022 Emil Dotchevski and Reverge Studios, Inc.\n\n// Distributed under the Boost Software License, Version 1.0. (See accompanying\n// file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)\n\n// This is a simple program that shows how to report error objects out of a\n// C-callback, converting them to leaf::result as soon as controlreaches C++.\n\nextern \"C\" {\n #include \"lua.h\"\n #include \"lauxlib.h\"\n}\n#include \n#include \n#include \n\nnamespace leaf = boost::leaf;\n\nenum do_work_error_code\n{\n ec1=1,\n ec2\n};\n\nstruct e_lua_pcall_error\n{\n int value;\n\n friend std::ostream & operator<<( std::ostream & os, e_lua_pcall_error const & x )\n {\n os << \"Lua error code = \" << x.value;\n switch( x.value )\n {\n case LUA_ERRRUN: return os << \" (LUA_ERRRUN)\";\n case LUA_ERRMEM: return os << \" (LUA_ERRMEM)\";\n case LUA_ERRERR: return os << \" (LUA_ERRERR)\";\n default: return os << \" (unknown)\";\n }\n }\n};\n\nstruct e_lua_error_message { std::string value; };\n\n\n// This is a C callback with a specific signature, callable from programs\n// written in Lua. If it succeeds, it returns an int answer, by pushing it onto\n// the Lua stack. But \"sometimes\" it fails, in which case it calls luaL_error.\n// This causes the Lua interpreter to abort and pop back into the C++ code which\n// called it (see call_lua below).\nint do_work( lua_State * L )\n{\n bool success = rand() % 2; // \"Sometimes\" do_work fails.\n if( success )\n {\n lua_pushnumber(L, 42); // Success, push the result on the Lua stack, return to Lua.\n return 1;\n }\n else\n {\n return leaf::new_error(ec1), luaL_error(L,\"do_work_error\"); // luaL_error does not return (longjmp).\n }\n}\n\n\nstd::shared_ptr init_lua_state()\n{\n // Create a new lua_State, we'll use std::shared_ptr for automatic cleanup.\n std::shared_ptr L(lua_open(), &lua_close);\n\n // Register the do_work function (above) as a C callback, under the global\n // Lua name \"do_work\". With this, calls from Lua programs to do_work will\n // land in the do_work C function we've registered.\n lua_register( &*L, \"do_work\", &do_work );\n\n // Pass some Lua code as a C string literal to Lua. This creates a global\n // Lua function called \"call_do_work\", which we will later ask Lua to\n // execute.\n luaL_dostring( &*L, \"\\\n\\n function call_do_work()\\\n\\n return do_work()\\\n\\n end\" );\n\n return L;\n}\n\n\n// Here we will ask Lua to execute the function call_do_work, which is written\n// in Lua, and returns the value from do_work, which is written in C++ and\n// registered with the Lua interpreter as a C callback.\n\n// If do_work succeeds, we return the resulting int answer. If it fails, we'll\n// communicate that failure to our caller.\nleaf::result call_lua( lua_State * L )\n{\n leaf::error_monitor cur_err;\n\n // Ask the Lua interpreter to call the global Lua function call_do_work.\n lua_getfield( L, LUA_GLOBALSINDEX, \"call_do_work\" );\n if( int err = lua_pcall(L, 0, 1, 0) ) // Ask Lua to call the global function call_do_work.\n {\n std::string msg = lua_tostring(L, 1);\n lua_pop(L, 1);\n\n // We got a Lua error which may be the error we're reporting from\n // do_work, or some other error. If it is another error,\n // cur_err.assigned_error_id() will return a new leaf::error_id,\n // otherwise we'll be working with the original value returned by\n // leaf::new_error in do_work.\n return cur_err.assigned_error_id().load( e_lua_pcall_error{err}, e_lua_error_message{std::move(msg)} );\n }\n else\n {\n // Success! Just return the int answer.\n int answer = lua_tonumber(L, -1);\n lua_pop(L, 1);\n return answer;\n }\n}\n\nint main()\n{\n std::shared_ptr L=init_lua_state();\n\n for( int i=0; i!=10; ++i )\n {\n leaf::try_handle_all(\n\n [&]() -> leaf::result\n {\n BOOST_LEAF_AUTO(answer, call_lua(&*L));\n std::cout << \"do_work succeeded, answer=\" << answer << '\\n';\n return { };\n },\n\n []( do_work_error_code e, e_lua_error_message const & msg )\n {\n std::cout << \"Got do_work_error_code = \" << e << \", \" << msg.value << \"\\n\";\n },\n\n []( e_lua_pcall_error const & err, e_lua_error_message const & msg )\n {\n std::cout << \"Got e_lua_pcall_error, \" << err << \", \" << msg.value << \"\\n\";\n },\n\n []( leaf::error_info const & unmatched )\n {\n std::cerr <<\n \"Unknown failure detected\" << std::endl <<\n \"Cryptic diagnostic information follows\" << std::endl <<\n unmatched;\n } );\n }\n\n return 0;\n}\n\n#ifdef BOOST_LEAF_NO_EXCEPTIONS\n\nnamespace boost\n{\n [[noreturn]] void throw_exception( std::exception const & e )\n {\n std::cerr << \"Terminating due to a C++ exception under BOOST_LEAF_NO_EXCEPTIONS: \" << e.what();\n std::terminate();\n }\n\n struct source_location;\n [[noreturn]] void throw_exception( std::exception const & e, boost::source_location const & )\n {\n throw_exception(e);\n }\n}\n\n#endif\n" }, { "path": "example/print_file/print_file_eh.cpp", "content": "// Copyright 2018-2022 Emil Dotchevski and Reverge Studios, Inc.\n\n// Distributed under the Boost Software License, Version 1.0. (See accompanying\n// file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)\n\n// This is the program presented in\n// https://boostorg.github.io/leaf/#introduction-eh.\n\n// It reads a text file in a buffer and prints it to std::cout, using LEAF to\n// handle errors. This version uses exception handling. The version that does\n// not use exception handling is in print_file_result.cpp.\n\n#include \n#include \n#include \n\nnamespace leaf = boost::leaf;\n\n\n// First, we need an enum to define our error codes:\nenum error_code\n{\n bad_command_line = 1,\n open_error,\n read_error,\n size_error,\n eof_error,\n output_error\n};\n\n\n// We will handle all failures in our main function, but first, here are the\n// declarations of the functions it calls, each communicating failures by\n// throwing exceptions\n\n// Parse the command line, return the file name.\nchar const * parse_command_line( int argc, char const * argv[] );\n\n// Open a file for reading.\nstd::shared_ptr file_open( char const * file_name );\n\n// Return the size of the file.\nstd::size_t file_size( FILE & f );\n\n// Read size bytes from f into buf.\nvoid file_read( FILE & f, void * buf, std::size_t size );\n\n\n// The main function, which handles all errors.\nint main( int argc, char const * argv[] )\n{\n return leaf::try_catch(\n\n [&]\n {\n char const * file_name = parse_command_line(argc,argv);\n\n auto load = leaf::on_error( leaf::e_file_name{file_name} );\n\n std::shared_ptr f = file_open(file_name);\n\n std::size_t s = file_size(*f);\n\n std::string buffer(1 + s, '\\0');\n file_read(*f, &buffer[0], buffer.size()-1);\n\n std::cout << buffer;\n std::cout.flush();\n if( std::cout.fail() )\n leaf::throw_exception(output_error, leaf::e_errno{errno});\n\n return 0;\n },\n\n // Each of the lambdas below is an error handler. LEAF will consider\n // them, in order, and call the first one that matches the available\n // error objects.\n\n // This handler will be called if the error includes:\n // - an object of type error_code equal to open_error, and\n // - an object of type leaf::e_errno that has .value equal to ENOENT,\n // and\n // - an object of type leaf::e_file_name.\n []( leaf::match, leaf::match_value, leaf::e_file_name const & fn )\n {\n std::cerr << \"File not found: \" << fn.value << std::endl;\n return 1;\n },\n\n // This handler will be called if the error includes:\n // - an object of type error_code equal to open_error, and\n // - an object of type leaf::e_errno (regardless of its .value), and\n // - an object of type leaf::e_file_name.\n []( leaf::match, leaf::e_errno const & errn, leaf::e_file_name const & fn )\n {\n std::cerr << \"Failed to open \" << fn.value << \", errno=\" << errn << std::endl;\n return 2;\n },\n\n // This handler will be called if the error includes:\n // - an object of type error_code equal to any of size_error,\n // read_error, eof_error, and\n // - an optional object of type leaf::e_errno (regardless of its\n // .value), and\n // - an object of type leaf::e_file_name.\n []( leaf::match, leaf::e_errno const * errn, leaf::e_file_name const & fn )\n {\n std::cerr << \"Failed to access \" << fn.value;\n if( errn )\n std::cerr << \", errno=\" << *errn;\n std::cerr << std::endl;\n return 3;\n },\n\n // This handler will be called if the error includes:\n // - an object of type error_code equal to output_error, and\n // - an object of type leaf::e_errno (regardless of its .value),\n []( leaf::match, leaf::e_errno const & errn )\n {\n std::cerr << \"Output error, errno=\" << errn << std::endl;\n return 4;\n },\n\n // This handler will be called if we've got a bad_command_line\n []( leaf::match )\n {\n std::cout << \"Bad command line argument\" << std::endl;\n return 5;\n },\n\n // This last handler matches any error: it prints diagnostic information\n // to help debug logic errors in the program, since it failed to match\n // an appropriate error handler to the error condition it encountered.\n // In this program this handler will never be called.\n []( leaf::error_info const & unmatched )\n {\n std::cerr <<\n \"Unknown failure detected\" << std::endl <<\n \"Cryptic diagnostic information follows\" << std::endl <<\n unmatched;\n return 6;\n } );\n}\n\n\n// Implementations of the functions called by main:\n\n\n// Parse the command line, return the file name.\nchar const * parse_command_line( int argc, char const * argv[] )\n{\n if( argc==2 )\n return argv[1];\n else\n leaf::throw_exception(bad_command_line);\n}\n\n\n// Open a file for reading.\nstd::shared_ptr file_open( char const * file_name )\n{\n if( FILE * f = fopen(file_name, \"rb\") )\n return std::shared_ptr(f, &fclose);\n else\n leaf::throw_exception(open_error, leaf::e_errno{errno});\n}\n\n\n// Return the size of the file.\nstd::size_t file_size( FILE & f )\n{\n auto load = leaf::on_error([] { return leaf::e_errno{errno}; });\n\n if( fseek(&f, 0, SEEK_END) )\n leaf::throw_exception(size_error);\n\n long s = ftell(&f);\n if( s==-1L )\n leaf::throw_exception(size_error);\n\n if( fseek(&f,0,SEEK_SET) )\n leaf::throw_exception(size_error);\n\n return std::size_t(s);\n}\n\n\n// Read size bytes from f into buf.\nvoid file_read( FILE & f, void * buf, std::size_t size )\n{\n std::size_t n = fread(buf, 1, size, &f);\n\n if( ferror(&f) )\n leaf::throw_exception(read_error, leaf::e_errno{errno});\n\n if( n!=size )\n leaf::throw_exception(eof_error);\n}\n" }, { "path": "example/print_file/print_file_outcome_result.cpp", "content": "// Copyright 2018-2022 Emil Dotchevski and Reverge Studios, Inc.\n\n// Distributed under the Boost Software License, Version 1.0. (See accompanying\n// file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)\n\n// This is the program presented in\n// https://boostorg.github.io/leaf/#introduction-result, converted to use\n// outcome::result instead of leaf::result.\n\n// It reads a text file in a buffer and prints it to std::cout, using LEAF to\n// handle errors. This version does not use exception handling.\n\n#include \n#include \n#include \n#include \n\nnamespace outcome = boost::outcome_v2;\nnamespace leaf = boost::leaf;\n\n\n// First, we need an enum to define our error codes:\nenum error_code\n{\n bad_command_line = 1,\n open_error,\n read_error,\n size_error,\n eof_error,\n output_error\n};\n\n\ntemplate \nusing result = outcome::std_result;\n\n// To enable LEAF to work with outcome::result, we need to specialize the\n// is_result_type template:\nnamespace boost { namespace leaf {\n template struct is_result_type>: std::true_type { };\n} }\n\n\n// We will handle all failures in our main function, but first, here are the\n// declarations of the functions it calls, each communicating failures using\n// result:\n\n// Parse the command line, return the file name.\nresult parse_command_line( int argc, char const * argv[] );\n\n// Open a file for reading.\nresult> file_open( char const * file_name );\n\n// Return the size of the file.\nresult file_size( FILE & f );\n\n// Read size bytes from f into buf.\nresult file_read( FILE & f, void * buf, std::size_t size );\n\n\n// The main function, which handles all errors.\nint main( int argc, char const * argv[] )\n{\n return leaf::try_handle_all(\n\n [&]() -> result\n {\n BOOST_LEAF_AUTO(file_name, parse_command_line(argc,argv));\n\n auto load = leaf::on_error( leaf::e_file_name{file_name} );\n\n BOOST_LEAF_AUTO(f, file_open(file_name));\n\n BOOST_LEAF_AUTO(s, file_size(*f));\n\n std::string buffer(1 + s, '\\0');\n BOOST_LEAF_CHECK(file_read(*f, &buffer[0], buffer.size()-1));\n\n std::cout << buffer;\n std::cout.flush();\n if( std::cout.fail() )\n return leaf::new_error(output_error, leaf::e_errno{errno}).to_error_code();\n\n return 0;\n },\n\n // Each of the lambdas below is an error handler. LEAF will consider\n // them, in order, and call the first one that matches the available\n // error objects.\n\n // This handler will be called if the error includes:\n // - an object of type error_code equal to open_error, and\n // - an object of type leaf::e_errno that has .value equal to ENOENT,\n // and\n // - an object of type leaf::e_file_name.\n []( leaf::match, leaf::match_value, leaf::e_file_name const & fn )\n {\n std::cerr << \"File not found: \" << fn.value << std::endl;\n return 1;\n },\n\n // This handler will be called if the error includes:\n // - an object of type error_code equal to open_error, and\n // - an object of type leaf::e_errno (regardless of its .value), and\n // - an object of type leaf::e_file_name.\n []( leaf::match, leaf::e_errno const & errn, leaf::e_file_name const & fn )\n {\n std::cerr << \"Failed to open \" << fn.value << \", errno=\" << errn << std::endl;\n return 2;\n },\n\n // This handler will be called if the error includes:\n // - an object of type error_code equal to any of size_error,\n // read_error, eof_error, and\n // - an optional object of type leaf::e_errno (regardless of its\n // .value), and\n // - an object of type leaf::e_file_name.\n []( leaf::match, leaf::e_errno const * errn, leaf::e_file_name const & fn )\n {\n std::cerr << \"Failed to access \" << fn.value;\n if( errn )\n std::cerr << \", errno=\" << *errn;\n std::cerr << std::endl;\n return 3;\n },\n\n // This handler will be called if the error includes:\n // - an object of type error_code equal to output_error, and\n // - an object of type leaf::e_errno (regardless of its .value),\n []( leaf::match, leaf::e_errno const & errn )\n {\n std::cerr << \"Output error, errno=\" << errn << std::endl;\n return 4;\n },\n\n // This handler will be called if we've got a bad_command_line\n []( leaf::match )\n {\n std::cout << \"Bad command line argument\" << std::endl;\n return 5;\n },\n\n // This last handler matches any error: it prints diagnostic information\n // to help debug logic errors in the program, since it failed to match\n // an appropriate error handler to the error condition it encountered.\n // In this program this handler will never be called.\n []( leaf::error_info const & unmatched )\n {\n std::cerr <<\n \"Unknown failure detected\" << std::endl <<\n \"Cryptic diagnostic information follows\" << std::endl <<\n unmatched;\n return 6;\n } );\n}\n\n\n// Implementations of the functions called by main:\n\n\n// Parse the command line, return the file name.\nresult parse_command_line( int argc, char const * argv[] )\n{\n if( argc==2 )\n return argv[1];\n else\n return leaf::new_error(bad_command_line).to_error_code();\n}\n\n\n// Open a file for reading.\nresult> file_open( char const * file_name )\n{\n if( FILE * f = fopen(file_name, \"rb\") )\n return std::shared_ptr(f, &fclose);\n else\n return leaf::new_error(open_error, leaf::e_errno{errno}).to_error_code();\n}\n\n\n// Return the size of the file.\nresult file_size( FILE & f )\n{\n auto load = leaf::on_error([] { return leaf::e_errno{errno}; });\n\n if( fseek(&f, 0, SEEK_END) )\n return leaf::new_error(size_error).to_error_code();\n\n long s = ftell(&f);\n if( s==-1L )\n return leaf::new_error(size_error).to_error_code();\n\n if( fseek(&f,0,SEEK_SET) )\n return leaf::new_error(size_error).to_error_code();\n\n return std::size_t(s);\n}\n\n\n// Read size bytes from f into buf.\nresult file_read( FILE & f, void * buf, std::size_t size )\n{\n std::size_t n = fread(buf, 1, size, &f);\n\n if( ferror(&f) )\n return leaf::new_error(read_error, leaf::e_errno{errno}).to_error_code();\n\n if( n!=size )\n return leaf::new_error(eof_error).to_error_code();\n\n return outcome::success();\n}\n\n////////////////////////////////////////\n\n#ifdef BOOST_LEAF_NO_EXCEPTIONS\n\nnamespace boost\n{\n [[noreturn]] void throw_exception( std::exception const & e )\n {\n std::cerr << \"Terminating due to a C++ exception under BOOST_LEAF_NO_EXCEPTIONS: \" << e.what();\n std::terminate();\n }\n\n struct source_location;\n [[noreturn]] void throw_exception( std::exception const & e, boost::source_location const & )\n {\n throw_exception(e);\n }\n}\n\n#endif\n" }, { "path": "example/print_file/print_file_result.cpp", "content": "// Copyright 2018-2022 Emil Dotchevski and Reverge Studios, Inc.\n\n// Distributed under the Boost Software License, Version 1.0. (See accompanying\n// file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)\n\n// This is the program presented in\n// https://boostorg.github.io/leaf/#introduction-result.\n\n// It reads a text file in a buffer and prints it to std::cout, using LEAF to\n// handle errors. This version does not use exception handling. The version that\n// does use exception handling is in print_file_eh.cpp.\n\n#include \n#include \n#include \n\nnamespace leaf = boost::leaf;\n\n\n// First, we need an enum to define our error codes:\nenum error_code\n{\n bad_command_line = 1,\n open_error,\n read_error,\n size_error,\n eof_error,\n output_error\n};\n\n\ntemplate \nusing result = leaf::result;\n\n\n// We will handle all failures in our main function, but first, here are the\n// declarations of the functions it calls, each communicating failures using\n// result:\n\n// Parse the command line, return the file name.\nresult parse_command_line( int argc, char const * argv[] );\n\n// Open a file for reading.\nresult> file_open( char const * file_name );\n\n// Return the size of the file.\nresult file_size( FILE & f );\n\n// Read size bytes from f into buf.\nresult file_read( FILE & f, void * buf, std::size_t size );\n\n\n// The main function, which handles all errors.\nint main( int argc, char const * argv[] )\n{\n return leaf::try_handle_all(\n\n [&]() -> result\n {\n BOOST_LEAF_AUTO(file_name, parse_command_line(argc,argv));\n\n auto load = leaf::on_error( leaf::e_file_name{file_name} );\n\n BOOST_LEAF_AUTO(f, file_open(file_name));\n\n BOOST_LEAF_AUTO(s, file_size(*f));\n\n std::string buffer(1 + s, '\\0');\n BOOST_LEAF_CHECK(file_read(*f, &buffer[0], buffer.size()-1));\n\n std::cout << buffer;\n std::cout.flush();\n if( std::cout.fail() )\n return leaf::new_error(output_error, leaf::e_errno{errno});\n\n return 0;\n },\n\n // Each of the lambdas below is an error handler. LEAF will consider\n // them, in order, and call the first one that matches the available\n // error objects.\n\n // This handler will be called if the error includes:\n // - an object of type error_code equal to open_error, and\n // - an object of type leaf::e_errno that has .value equal to ENOENT,\n // and\n // - an object of type leaf::e_file_name.\n []( leaf::match, leaf::match_value, leaf::e_file_name const & fn )\n {\n std::cerr << \"File not found: \" << fn.value << std::endl;\n return 1;\n },\n\n // This handler will be called if the error includes:\n // - an object of type error_code equal to open_error, and\n // - an object of type leaf::e_errno (regardless of its .value), and\n // - an object of type leaf::e_file_name.\n []( leaf::match, leaf::e_errno const & errn, leaf::e_file_name const & fn )\n {\n std::cerr << \"Failed to open \" << fn.value << \", errno=\" << errn << std::endl;\n return 2;\n },\n\n // This handler will be called if the error includes:\n // - an object of type error_code equal to any of size_error,\n // read_error, eof_error, and\n // - an optional object of type leaf::e_errno (regardless of its\n // .value), and\n // - an object of type leaf::e_file_name.\n []( leaf::match, leaf::e_errno const * errn, leaf::e_file_name const & fn )\n {\n std::cerr << \"Failed to access \" << fn.value;\n if( errn )\n std::cerr << \", errno=\" << *errn;\n std::cerr << std::endl;\n return 3;\n },\n\n // This handler will be called if the error includes:\n // - an object of type error_code equal to output_error, and\n // - an object of type leaf::e_errno (regardless of its .value),\n []( leaf::match, leaf::e_errno const & errn )\n {\n std::cerr << \"Output error, errno=\" << errn << std::endl;\n return 4;\n },\n\n // This handler will be called if we've got a bad_command_line\n []( leaf::match )\n {\n std::cout << \"Bad command line argument\" << std::endl;\n return 5;\n },\n\n // This last handler matches any error: it prints diagnostic information\n // to help debug logic errors in the program, since it failed to match\n // an appropriate error handler to the error condition it encountered.\n // In this program this handler will never be called.\n []( leaf::error_info const & unmatched )\n {\n std::cerr <<\n \"Unknown failure detected\" << std::endl <<\n \"Cryptic diagnostic information follows\" << std::endl <<\n unmatched;\n return 6;\n } );\n}\n\n\n// Implementations of the functions called by main:\n\n\n// Parse the command line, return the file name.\nresult parse_command_line( int argc, char const * argv[] )\n{\n if( argc==2 )\n return argv[1];\n else\n return leaf::new_error(bad_command_line);\n}\n\n\n// Open a file for reading.\nresult> file_open( char const * file_name )\n{\n if( FILE * f = fopen(file_name, \"rb\") )\n return std::shared_ptr(f, &fclose);\n else\n return leaf::new_error(open_error, leaf::e_errno{errno});\n}\n\n\n// Return the size of the file.\nresult file_size( FILE & f )\n{\n auto load = leaf::on_error([] { return leaf::e_errno{errno}; });\n\n if( fseek(&f, 0, SEEK_END) )\n return leaf::new_error(size_error);\n\n long s = ftell(&f);\n if( s==-1L )\n return leaf::new_error(size_error);\n\n if( fseek(&f,0,SEEK_SET) )\n return leaf::new_error(size_error);\n\n return std::size_t(s);\n}\n\n\n// Read size bytes from f into buf.\nresult file_read( FILE & f, void * buf, std::size_t size )\n{\n std::size_t n = fread(buf, 1, size, &f);\n\n if( ferror(&f) )\n return leaf::new_error(read_error, leaf::e_errno{errno});\n\n if( n!=size )\n return leaf::new_error(eof_error);\n\n return { };\n}\n\n////////////////////////////////////////\n\n#ifdef BOOST_LEAF_NO_EXCEPTIONS\n\nnamespace boost\n{\n [[noreturn]] void throw_exception( std::exception const & e )\n {\n std::cerr << \"Terminating due to a C++ exception under BOOST_LEAF_NO_EXCEPTIONS: \" << e.what();\n std::terminate();\n }\n\n struct source_location;\n [[noreturn]] void throw_exception( std::exception const & e, boost::source_location const & )\n {\n throw_exception(e);\n }\n}\n\n#endif\n" }, { "path": "example/print_file/readme.md", "content": "# Print File Example\n\nThis directory has three versions of the same simple program, which reads a\nfile, prints it to standard out and handles errors using LEAF, each using a\ndifferent variation on error handling:\n\n* [print_file_result.cpp](./print_file_result.cpp) reports errors with\n `leaf::result`, using an error code `enum` for classification of failures.\n\n* [print_file_outcome_result.cpp](./print_file_outcome_result.cpp) is the same\n as the above, but using `outcome::result`. This demonstrates the ability\n to transport arbitrary error objects through APIs that do not use\n `leaf::result`.\n\n* [print_file_eh.cpp](./print_file_eh.cpp) throws on error, using an error code\n `enum` for classification of failures.\n" }, { "path": "example/print_half.cpp", "content": "// Copyright 2018-2022 Emil Dotchevski and Reverge Studios, Inc.\n\n// Distributed under the Boost Software License, Version 1.0. (See accompanying\n// file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)\n\n// This program is an adaptation of the following Boost Outcome example:\n// https://github.com/ned14/outcome/blob/master/doc/src/snippets/using_result.cpp\n\n#include \n#include \n#include \n#include \n#include \n\nnamespace leaf = boost::leaf;\n\nenum class ConversionErrc\n{\n EmptyString = 1,\n IllegalChar,\n TooLong\n};\n\nleaf::result convert(const std::string& str) noexcept\n{\n if (str.empty())\n return leaf::new_error(ConversionErrc::EmptyString);\n\n if (!std::all_of(str.begin(), str.end(), ::isdigit))\n return leaf::new_error(ConversionErrc::IllegalChar);\n\n if (str.length() > 9)\n return leaf::new_error(ConversionErrc::TooLong);\n\n return atoi(str.c_str());\n}\n\n// Do not static_store BigInt to actually work -- it's a stub.\nstruct BigInt\n{\n static leaf::result fromString(const std::string& s) { return BigInt{s}; }\n explicit BigInt(const std::string&) { }\n BigInt half() const { return BigInt{\"\"}; }\n friend std::ostream& operator<<(std::ostream& o, const BigInt&) { return o << \"big int half\"; }\n};\n\n// This function handles ConversionErrc::TooLong errors, forwards any other\n// error to the caller.\nleaf::result print_half(const std::string& text)\n{\n return leaf::try_handle_some(\n [&]() -> leaf::result\n {\n BOOST_LEAF_AUTO(r,convert(text));\n std::cout << r / 2 << std::endl;\n return { };\n },\n [&]( leaf::match ) -> leaf::result\n {\n BOOST_LEAF_AUTO(i, BigInt::fromString(text));\n std::cout << i.half() << std::endl;\n return { };\n } );\n}\n\nint main( int argc, char const * argv[] )\n{\n return leaf::try_handle_all(\n [&]() -> leaf::result\n {\n BOOST_LEAF_CHECK( print_half(argc<2 ? \"\" : argv[1]) );\n std::cout << \"ok\" << std::endl;\n return 0;\n },\n\n []( leaf::match )\n {\n std::cerr << \"Empty string!\" << std::endl;\n return 1;\n },\n\n []( leaf::match )\n {\n std::cerr << \"Illegal char!\" << std::endl;\n return 2;\n },\n\n []( leaf::error_info const & unmatched )\n {\n // This will never execute in this program, but it would detect\n // logic errors where an unknown error reaches main. In this case,\n // we print diagnostic information.\n std::cerr <<\n \"Unknown failure detected\" << std::endl <<\n \"Cryptic diagnostic information follows\" << std::endl <<\n unmatched;\n return 3;\n } );\n}\n\n////////////////////////////////////////\n\n#ifdef BOOST_LEAF_NO_EXCEPTIONS\n\nnamespace boost\n{\n [[noreturn]] void throw_exception( std::exception const & e )\n {\n std::cerr << \"Terminating due to a C++ exception under BOOST_LEAF_NO_EXCEPTIONS: \" << e.what();\n std::terminate();\n }\n\n struct source_location;\n [[noreturn]] void throw_exception( std::exception const & e, boost::source_location const & )\n {\n throw_exception(e);\n }\n}\n\n#endif\n" }, { "path": "example/readme.md", "content": "# Example Programs Using LEAF to Handle Errors\n\n* [print_file](./print_file): The complete example from the [Five Minute Introduction](https://boostorg.github.io/leaf/#introduction). This directory contains several versions of the same program, each using a different error handling style.\n\n* [capture_in_result.cpp](https://github.com/boostorg/leaf/blob/master/example/capture_in_result.cpp?ts=4): Shows how to transport error objects between threads in a `leaf::result` object.\n* [capture_in_exception.cpp](https://github.com/boostorg/leaf/blob/master/example/capture_in_exception.cpp?ts=4): Shows how to transport error objects between threads in an exception object.\n* [lua_callback_result.cpp](https://github.com/boostorg/leaf/blob/master/example/lua_callback_result.cpp?ts=4): Transporting arbitrary error objects through an uncooperative C API.\n* [lua_callback_eh.cpp](https://github.com/boostorg/leaf/blob/master/example/lua_callback_eh.cpp?ts=4): Transporting arbitrary error objects through an uncooperative exception-safe API.\n* [exception_to_result.cpp](https://github.com/boostorg/leaf/blob/master/example/exception_to_result.cpp?ts=4): Demonstrates how to transport exceptions through a `noexcept` layer in the program.\n* [exception_error_log.cpp](https://github.com/boostorg/leaf/blob/master/example/error_log.cpp?ts=4): Using `accumulate` to produce an error log.\n* [exception_error_trace.cpp](https://github.com/boostorg/leaf/blob/master/example/error_trace.cpp?ts=4): Same as above, but the log is recorded in a `std::deque` rather than just printed.\n* [print_half.cpp](https://github.com/boostorg/leaf/blob/master/example/print_half.cpp?ts=4): This is a Boost Outcome example adapted to LEAF, demonstrating the use of `try_handle_some` to handle some errors, forwarding any other error to the caller.\n* [asio_beast_leaf_rpc.cpp](https://github.com/boostorg/leaf/blob/master/example/asio_beast_leaf_rpc.cpp?ts=4): A simple RPC calculator implemented with Beast+ASIO+LEAF.\n" }, { "path": "gen/generate_single_header.py", "content": "\"\"\"\n\n Copyright 2018-2022 Emil Dotchevski and Reverge Studios, Inc.\n Copyright (c) Sorin Fetche\n\n Distributed under the Boost Software License, Version 1.0. (See accompanying\n file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)\n\n This program generates a single header file from a file including multiple C/C++ headers.\n\n Usage:\n\n python3 generate_single_header.py --help\n\n e.g. python3 generate_single_header.py -i include/boost/leaf/detail/all.hpp -p include -o test/leaf.hpp boost/leaf\n\n\"\"\"\n\nimport argparse\nimport os\nimport re\nfrom datetime import date\nimport subprocess\n\nincluded = {}\ntotal_line_count = 11\n\ndef append(input_file_name, input_file, output_file, regex_includes, include_folder):\n global total_line_count\n line_count = 1\n for line in input_file:\n line_count += 1\n result = regex_includes.search(line)\n if result:\n next_input_file_name = result.group(\"include\")\n if next_input_file_name in included:\n output_file.write(\"// Expanded at line %d: %s\" % (included[next_input_file_name], line))\n total_line_count += 1\n else:\n included[next_input_file_name] = total_line_count\n print(\"%s (%d)\" % (next_input_file_name, total_line_count))\n with open(os.path.join(include_folder, next_input_file_name), \"r\") as next_input_file:\n output_file.write('// >>> %s#line 1 \"%s\"\\n' % (line, next_input_file_name))\n total_line_count += 2\n append(next_input_file_name, next_input_file, output_file, regex_includes, include_folder)\n if not ('include/boost/leaf/detail/all.hpp' in input_file_name):\n output_file.write('// <<< %s#line %d \"%s\"\\n' % (line, line_count, input_file_name))\n total_line_count += 2\n else:\n output_file.write(line)\n total_line_count += 1\n\ndef _main():\n parser = argparse.ArgumentParser(\n description=\"Generates a single include file from a file including multiple C/C++ headers\")\n parser.add_argument(\"-i\", \"--input\", action=\"store\", type=str, default=\"in.cpp\",\n help=\"Input file including the headers to be merged\")\n parser.add_argument(\"-o\", \"--output\", action=\"store\", type=str, default=\"out.cpp\",\n help=\"Output file. NOTE: It will be overwritten!\")\n parser.add_argument(\"-p\", \"--path\", action=\"store\", type=str, default=\".\",\n help=\"Include path\")\n parser.add_argument(\"--hash\", action=\"store\", type=str,\n help=\"The git hash to print in the output file, e.g. the output of \\\"git rev-parse HEAD\\\"\")\n parser.add_argument(\"prefix\", action=\"store\", type=str,\n help=\"Non-empty include file prefix (e.g. a/b)\")\n args = parser.parse_args()\n\n regex_includes = re.compile(r\"\"\"^\\s*#[\\t\\s]*include[\\t\\s]*(\"|\\<)(?P%s.*)(\"|\\>)\"\"\" % args.prefix)\n print(\"Rebuilding %s:\" % args.input)\n with open(args.output, 'w') as output_file, open(args.input, 'r') as input_file:\n output_file.write(\n '#ifndef BOOST_LEAF_HPP_INCLUDED\\n'\n '#define BOOST_LEAF_HPP_INCLUDED\\n'\n '\\n'\n '// LEAF single header distribution. Do not edit.\\n'\n '\\n'\n '// Generated on ' + date.today().strftime(\"%m/%d/%Y\"))\n if args.hash:\n output_file.write(\n ' from https://github.com/boostorg/leaf/tree/' + args.hash[0:7])\n output_file.write(\n '.\\n'\n '// Latest version of this file: https://raw.githubusercontent.com/boostorg/leaf/gh-pages/leaf.hpp.\\n'\n '\\n')\n append(args.input, input_file, output_file, regex_includes, args.path)\n output_file.write(\n '\\n'\n '#endif\\n' )\n# print(\"%d\" % total_line_count)\n\nif __name__ == \"__main__\":\n _main()\n" }, { "path": "include/boost/leaf/capture.hpp", "content": "#ifndef BOOST_LEAF_CAPTURE_HPP_INCLUDED\n#define BOOST_LEAF_CAPTURE_HPP_INCLUDED\n\n// Copyright 2018-2022 Emil Dotchevski and Reverge Studios, Inc.\n\n// Distributed under the Boost Software License, Version 1.0. (See accompanying\n// file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)\n\n#include \n#include \n#include \n\n#if BOOST_LEAF_CFG_CAPTURE\n\nnamespace boost { namespace leaf {\n\nnamespace leaf_detail\n{\n template ::value>\n struct is_result_tag;\n\n template \n struct is_result_tag\n {\n };\n\n template \n struct is_result_tag\n {\n };\n}\n\n#ifdef BOOST_LEAF_NO_EXCEPTIONS\n\nnamespace leaf_detail\n{\n template \n inline\n decltype(std::declval()(std::forward(std::declval())...))\n capture_impl(is_result_tag, context_ptr && ctx, F && f, A... a) noexcept\n {\n auto active_context = activate_context(*ctx);\n return std::forward(f)(std::forward(a)...);\n }\n\n template \n inline\n decltype(std::declval()(std::forward(std::declval())...))\n capture_impl(is_result_tag, context_ptr && ctx, F && f, A... a) noexcept\n {\n auto active_context = activate_context(*ctx);\n if( auto r = std::forward(f)(std::forward(a)...) )\n return r;\n else\n {\n ctx->captured_id_ = r.error();\n return std::move(ctx);\n }\n }\n\n template \n inline\n decltype(std::declval().get())\n future_get_impl(is_result_tag, Future & fut) noexcept\n {\n return fut.get();\n }\n\n template \n inline\n decltype(std::declval().get())\n future_get_impl(is_result_tag, Future & fut) noexcept\n {\n if( auto r = fut.get() )\n return r;\n else\n return error_id(r.error()); // unloads\n }\n}\n\n#else\n\nnamespace leaf_detail\n{\n class capturing_exception:\n public std::exception\n {\n std::exception_ptr ex_;\n context_ptr ctx_;\n\n public:\n\n capturing_exception(std::exception_ptr && ex, context_ptr && ctx) noexcept:\n ex_(std::move(ex)),\n ctx_(std::move(ctx))\n {\n BOOST_LEAF_ASSERT(ex_);\n BOOST_LEAF_ASSERT(ctx_);\n BOOST_LEAF_ASSERT(ctx_->captured_id_);\n }\n\n [[noreturn]] void unload_and_rethrow_original_exception() const\n {\n BOOST_LEAF_ASSERT(ctx_->captured_id_);\n tls::write_uint(unsigned(ctx_->captured_id_.value()));\n ctx_->propagate(ctx_->captured_id_);\n std::rethrow_exception(ex_);\n }\n\n template \n void print( std::basic_ostream & os ) const\n {\n ctx_->print(os);\n }\n };\n\n template \n inline\n decltype(std::declval()(std::forward(std::declval())...))\n capture_impl(is_result_tag, context_ptr && ctx, F && f, A... a)\n {\n auto active_context = activate_context(*ctx);\n error_monitor cur_err;\n try\n {\n return std::forward(f)(std::forward(a)...);\n }\n catch( capturing_exception const & )\n {\n throw;\n }\n catch( exception_base const & e )\n {\n ctx->captured_id_ = e.get_error_id();\n leaf_detail::throw_exception_impl( capturing_exception(std::current_exception(), std::move(ctx)) );\n }\n catch(...)\n {\n ctx->captured_id_ = cur_err.assigned_error_id();\n leaf_detail::throw_exception_impl( capturing_exception(std::current_exception(), std::move(ctx)) );\n }\n }\n\n template \n inline\n decltype(std::declval()(std::forward(std::declval())...))\n capture_impl(is_result_tag, context_ptr && ctx, F && f, A... a)\n {\n auto active_context = activate_context(*ctx);\n error_monitor cur_err;\n try\n {\n if( auto && r = std::forward(f)(std::forward(a)...) )\n return std::move(r);\n else\n {\n ctx->captured_id_ = r.error();\n return std::move(ctx);\n }\n }\n catch( capturing_exception const & )\n {\n throw;\n }\n catch( exception_base const & e )\n {\n ctx->captured_id_ = e.get_error_id();\n leaf_detail::throw_exception_impl( capturing_exception(std::current_exception(), std::move(ctx)) );\n }\n catch(...)\n {\n ctx->captured_id_ = cur_err.assigned_error_id();\n leaf_detail::throw_exception_impl( capturing_exception(std::current_exception(), std::move(ctx)) );\n }\n }\n\n template \n inline\n decltype(std::declval().get())\n future_get_impl(is_result_tag, Future & fut )\n {\n try\n {\n return fut.get();\n }\n catch( capturing_exception const & cap )\n {\n cap.unload_and_rethrow_original_exception();\n }\n }\n\n template \n inline\n decltype(std::declval().get())\n future_get_impl(is_result_tag, Future & fut )\n {\n try\n {\n if( auto r = fut.get() )\n return r;\n else\n return error_id(r.error()); // unloads\n }\n catch( capturing_exception const & cap )\n {\n cap.unload_and_rethrow_original_exception();\n }\n }\n}\n\n#endif\n\ntemplate \ninline\ndecltype(std::declval()(std::forward(std::declval())...))\ncapture(context_ptr && ctx, F && f, A... a)\n{\n using namespace leaf_detail;\n return capture_impl(is_result_tag()(std::forward(std::declval())...))>(), std::move(ctx), std::forward(f), std::forward(a)...);\n}\n\ntemplate \ninline\ndecltype(std::declval().get())\nfuture_get( Future & fut )\n{\n using namespace leaf_detail;\n return future_get_impl(is_result_tag().get())>(), fut);\n}\n\n} }\n\n#endif\n\n#endif\n" }, { "path": "include/boost/leaf/common.hpp", "content": "#ifndef BOOST_LEAF_COMMON_HPP_INCLUDED\n#define BOOST_LEAF_COMMON_HPP_INCLUDED\n\n// Copyright 2018-2022 Emil Dotchevski and Reverge Studios, Inc.\n\n// Distributed under the Boost Software License, Version 1.0. (See accompanying\n// file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)\n\n#include \n#include \n\n#include \n#if BOOST_LEAF_CFG_STD_STRING\n# include \n#endif\n#include \n#if BOOST_LEAF_CFG_WIN32\n# include \n# include \n# ifdef min\n# undef min\n# endif\n# ifdef max\n# undef max\n# endif\n#endif\n\nnamespace boost { namespace leaf {\n\nstruct BOOST_LEAF_SYMBOL_VISIBLE e_api_function { char const * value; };\n\n#if BOOST_LEAF_CFG_STD_STRING\n\nstruct BOOST_LEAF_SYMBOL_VISIBLE e_file_name\n{\n std::string value;\n};\n\n#else\n\nstruct BOOST_LEAF_SYMBOL_VISIBLE e_file_name\n{\n constexpr static char const * const value = \"\";\n BOOST_LEAF_CONSTEXPR explicit e_file_name( char const * ) { }\n};\n\n#endif\n\nstruct BOOST_LEAF_SYMBOL_VISIBLE e_errno\n{\n int value;\n\n explicit e_errno(int val=errno): value(val) { }\n\n template \n friend std::basic_ostream & operator<<(std::basic_ostream & os, e_errno const & err)\n {\n return os << type() << \": \" << err.value << \", \\\"\" << std::strerror(err.value) << '\"';\n }\n};\n\nstruct BOOST_LEAF_SYMBOL_VISIBLE e_type_info_name { char const * value; };\n\nstruct BOOST_LEAF_SYMBOL_VISIBLE e_at_line { int value; };\n\nnamespace windows\n{\n struct e_LastError\n {\n unsigned value;\n\n explicit e_LastError(unsigned val): value(val) { }\n\n#if BOOST_LEAF_CFG_WIN32\n e_LastError(): value(GetLastError()) { }\n\n template \n friend std::basic_ostream & operator<<(std::basic_ostream & os, e_LastError const & err)\n {\n struct msg_buf\n {\n LPVOID * p;\n msg_buf(): p(nullptr) { }\n ~msg_buf() noexcept { if(p) LocalFree(p); }\n };\n msg_buf mb;\n if( FormatMessageA(\n FORMAT_MESSAGE_ALLOCATE_BUFFER|FORMAT_MESSAGE_FROM_SYSTEM|FORMAT_MESSAGE_IGNORE_INSERTS,\n nullptr,\n err.value,\n MAKELANGID(LANG_NEUTRAL,SUBLANG_DEFAULT),\n (LPSTR)&mb.p,\n 0,\n nullptr) )\n {\n BOOST_LEAF_ASSERT(mb.p != nullptr);\n char * z = std::strchr((LPSTR)mb.p,0);\n if( z[-1] == '\\n' )\n *--z = 0;\n if( z[-1] == '\\r' )\n *--z = 0;\n return os << type() << \": \" << err.value << \", \\\"\" << (LPCSTR)mb.p << '\"';\n }\n return os;\n }\n#endif\n };\n}\n\n} }\n\n#endif\n" }, { "path": "include/boost/leaf/config/tls.hpp", "content": "#ifndef BOOST_LEAF_CONFIG_TLS_HPP_INCLUDED\n#define BOOST_LEAF_CONFIG_TLS_HPP_INCLUDED\n\n// Copyright 2018-2022 Emil Dotchevski and Reverge Studios, Inc.\n\n// Distributed under the Boost Software License, Version 1.0. (See accompanying\n// file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)\n\n#if defined(BOOST_LEAF_TLS_FREERTOS)\n# include \n#endif\n\n#ifndef BOOST_LEAF_USE_TLS_ARRAY\n#\tifdef BOOST_LEAF_CFG_TLS_INDEX_TYPE\n#\t\twarning \"BOOST_LEAF_CFG_TLS_INDEX_TYPE\" is ignored if BOOST_LEAF_USE_TLS_ARRAY is not defined.\n#\tendif\n#\tifdef BOOST_LEAF_CFG_TLS_ARRAY_SIZE\n#\t\twarning \"BOOST_LEAF_CFG_TLS_ARRAY_SIZE\" is ignored if BOOST_LEAF_USE_TLS_ARRAY is not defined.\n#\tendif\n#\tifdef BOOST_LEAF_CFG_TLS_ARRAY_START_INDEX\n#\t\twarning \"BOOST_LEAF_CFG_TLS_ARRAY_START_INDEX\" is ignored if BOOST_LEAF_USE_TLS_ARRAY is not defined.\n#\tendif\n#endif\n\n#if defined BOOST_LEAF_USE_TLS_ARRAY\n# include \n#elif defined(BOOST_LEAF_NO_THREADS)\n# include \n#else\n# include \n#endif\n\n#endif\n" }, { "path": "include/boost/leaf/config/tls_array.hpp", "content": "#ifndef BOOST_LEAF_CONFIG_TLS_ARRAY_HPP_INCLUDED\n#define BOOST_LEAF_CONFIG_TLS_ARRAY_HPP_INCLUDED\n\n// Copyright 2018-2022 Emil Dotchevski and Reverge Studios, Inc.\n// Copyright (c) 2022 Khalil Estell\n\n// Distributed under the Boost Software License, Version 1.0. (See accompanying\n// file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)\n\n// LEAF requires thread local storage support for pointers and for uin32_t values.\n\n// This header implements thread local storage for pointers and for unsigned int\n// values for platforms that support thread local pointers by index.\n\nnamespace boost { namespace leaf {\n\nnamespace tls\n{\n // The TLS support defined in this header requires the following two\n // functions to be defined elsewhere:\n void * read_void_ptr( int tls_index ) noexcept;\n void write_void_ptr( int tls_index, void * ) noexcept;\n}\n\n} }\n\n////////////////////////////////////////\n\n#include \n#include \n#include \n#include \n\n#ifndef BOOST_LEAF_CFG_TLS_INDEX_TYPE\n# define BOOST_LEAF_CFG_TLS_INDEX_TYPE unsigned char\n#endif\n\n#ifndef BOOST_LEAF_CFG_TLS_ARRAY_START_INDEX\n# define BOOST_LEAF_CFG_TLS_ARRAY_START_INDEX 0\n#endif\n\nstatic_assert((BOOST_LEAF_CFG_TLS_ARRAY_START_INDEX) >= 0,\n \"Bad BOOST_LEAF_CFG_TLS_ARRAY_START_INDEX\");\n\n#ifdef BOOST_LEAF_CFG_TLS_ARRAY_SIZE\n static_assert((BOOST_LEAF_CFG_TLS_ARRAY_SIZE) > (BOOST_LEAF_CFG_TLS_ARRAY_START_INDEX),\n \"Bad BOOST_LEAF_CFG_TLS_ARRAY_SIZE\");\n static_assert((BOOST_LEAF_CFG_TLS_ARRAY_SIZE) - 1 <= std::numeric_limits::max(),\n \"Bad BOOST_LEAF_CFG_TLS_ARRAY_SIZE\");\n#endif\n\n////////////////////////////////////////\n\nnamespace boost { namespace leaf {\n\nnamespace leaf_detail\n{\n using atomic_unsigned_int = std::atomic;\n}\n\nnamespace tls\n{\n template \n class BOOST_LEAF_SYMBOL_VISIBLE index_counter\n {\n static int c_;\n\n public:\n\n static BOOST_LEAF_CFG_TLS_INDEX_TYPE next()\n {\n int idx = ++c_;\n BOOST_LEAF_ASSERT(idx > (BOOST_LEAF_CFG_TLS_ARRAY_START_INDEX));\n BOOST_LEAF_ASSERT(idx < (BOOST_LEAF_CFG_TLS_ARRAY_SIZE));\n return idx;\n }\n };\n\n template \n struct BOOST_LEAF_SYMBOL_VISIBLE tls_index\n {\n static BOOST_LEAF_CFG_TLS_INDEX_TYPE idx;\n };\n\n template \n struct BOOST_LEAF_SYMBOL_VISIBLE alloc_tls_index\n {\n static BOOST_LEAF_CFG_TLS_INDEX_TYPE const idx;\n };\n\n template \n int index_counter::c_ = BOOST_LEAF_CFG_TLS_ARRAY_START_INDEX;\n\n template \n BOOST_LEAF_CFG_TLS_INDEX_TYPE tls_index::idx = BOOST_LEAF_CFG_TLS_ARRAY_START_INDEX;\n\n template \n BOOST_LEAF_CFG_TLS_INDEX_TYPE const alloc_tls_index::idx = tls_index::idx = index_counter<>::next();\n\n ////////////////////////////////////////\n\n template \n T * read_ptr() noexcept\n {\n int tls_idx = tls_index::idx;\n if( tls_idx == (BOOST_LEAF_CFG_TLS_ARRAY_START_INDEX) )\n return nullptr;\n --tls_idx;\n return reinterpret_cast(read_void_ptr(tls_idx));\n }\n\n template \n void write_ptr( T * p ) noexcept\n {\n int tls_idx = alloc_tls_index::idx;\n --tls_idx;\n write_void_ptr(tls_idx, p);\n BOOST_LEAF_ASSERT(read_void_ptr(tls_idx) == p);\n }\n\n ////////////////////////////////////////\n\n template \n unsigned read_uint() noexcept\n {\n static_assert(sizeof(std::intptr_t) >= sizeof(unsigned), \"Incompatible tls_array implementation\");\n return (unsigned) (std::intptr_t) (void *) read_ptr();\n }\n\n template \n void write_uint( unsigned x ) noexcept\n {\n static_assert(sizeof(std::intptr_t) >= sizeof(unsigned), \"Incompatible tls_array implementation\");\n write_ptr((Tag *) (void *) (std::intptr_t) x);\n }\n\n template \n void uint_increment() noexcept\n {\n write_uint(read_uint() + 1);\n }\n\n template \n void uint_decrement() noexcept\n {\n write_uint(read_uint() - 1);\n }\n}\n\n} }\n\n#endif\n" }, { "path": "include/boost/leaf/config/tls_cpp11.hpp", "content": "#ifndef BOOST_LEAF_CONFIG_TLS_CPP11_HPP_INCLUDED\n#define BOOST_LEAF_CONFIG_TLS_CPP11_HPP_INCLUDED\n\n// Copyright 2018-2022 Emil Dotchevski and Reverge Studios, Inc.\n\n// Distributed under the Boost Software License, Version 1.0. (See accompanying\n// file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)\n\n// LEAF requires thread local storage support for pointers and for uin32_t values.\n\n// This header implements thread local storage for pointers and for unsigned int\n// values using the C++11 built-in thread_local storage class specifier.\n\n#include \n#include \n\nnamespace boost { namespace leaf {\n\nnamespace leaf_detail\n{\n using atomic_unsigned_int = std::atomic;\n}\n\nnamespace tls\n{\n template \n struct BOOST_LEAF_SYMBOL_VISIBLE ptr\n {\n static thread_local T * p;\n };\n\n template \n thread_local T * ptr::p;\n\n template \n T * read_ptr() noexcept\n {\n return ptr::p;\n }\n\n template \n void write_ptr( T * p ) noexcept\n {\n ptr::p = p;\n }\n\n ////////////////////////////////////////\n\n template \n struct BOOST_LEAF_SYMBOL_VISIBLE tagged_uint\n {\n static thread_local unsigned x;\n };\n\n template \n thread_local unsigned tagged_uint::x;\n\n template \n unsigned read_uint() noexcept\n {\n return tagged_uint::x;\n }\n\n template \n void write_uint( unsigned x ) noexcept\n {\n tagged_uint::x = x;\n }\n\n template \n void uint_increment() noexcept\n {\n ++tagged_uint::x;\n }\n\n template \n void uint_decrement() noexcept\n {\n --tagged_uint::x;\n }\n}\n\n} }\n\n#endif\n" }, { "path": "include/boost/leaf/config/tls_freertos.hpp", "content": "#ifndef BOOST_LEAF_CONFIG_TLS_FREERTOS_HPP_INCLUDED\n#define BOOST_LEAF_CONFIG_TLS_FREERTOS_HPP_INCLUDED\n\n// Copyright 2018-2022 Emil Dotchevski and Reverge Studios, Inc.\n// Copyright (c) 2022 Khalil Estell\n\n// Distributed under the Boost Software License, Version 1.0. (See accompanying\n// file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)\n\n#include \n\n#ifndef BOOST_LEAF_USE_TLS_ARRAY\n# define BOOST_LEAF_USE_TLS_ARRAY\n#endif\n\n#ifndef BOOST_LEAF_CFG_TLS_ARRAY_SIZE\n# define BOOST_LEAF_CFG_TLS_ARRAY_SIZE configNUM_THREAD_LOCAL_STORAGE_POINTERS\n#endif\n\nstatic_assert((BOOST_LEAF_CFG_TLS_ARRAY_SIZE) <= configNUM_THREAD_LOCAL_STORAGE_POINTERS,\n \"Bad BOOST_LEAF_CFG_TLS_ARRAY_SIZE\");\n\nnamespace boost { namespace leaf {\n\nnamespace tls\n{\n // See https://www.freertos.org/thread-local-storage-pointers.html.\n\n inline void * read_void_ptr( int tls_index ) noexcept\n {\n return pvTaskGetThreadLocalStoragePointer(0, tls_index);\n }\n\n inline void write_void_ptr( int tls_index, void * p ) noexcept\n {\n vTaskSetThreadLocalStoragePointer(0, tls_index, p);\n }\n}\n\n} }\n\n#endif\n" }, { "path": "include/boost/leaf/config/tls_globals.hpp", "content": "#ifndef BOOST_LEAF_CONFIG_TLS_GLOBALS_HPP_INCLUDED\n#define BOOST_LEAF_CONFIG_TLS_GLOBALS_HPP_INCLUDED\n\n// Copyright 2018-2022 Emil Dotchevski and Reverge Studios, Inc.\n\n// Distributed under the Boost Software License, Version 1.0. (See accompanying\n// file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)\n\n// LEAF requires thread local storage support for pointers and for uin32_t values.\n\n// This header implements \"thread local\" storage for pointers and for unsigned int\n// values using globals, which is suitable for single thread environments.\n\n#include \n\nnamespace boost { namespace leaf {\n\nnamespace leaf_detail\n{\n using atomic_unsigned_int = unsigned int;\n}\n\nnamespace tls\n{\n template \n struct BOOST_LEAF_SYMBOL_VISIBLE ptr\n {\n static T * p;\n };\n\n template \n T * ptr::p;\n\n template \n T * read_ptr() noexcept\n {\n return ptr::p;\n }\n\n template \n void write_ptr( T * p ) noexcept\n {\n ptr::p = p;\n }\n\n ////////////////////////////////////////\n\n template \n struct BOOST_LEAF_SYMBOL_VISIBLE tagged_uint\n {\n static unsigned x;\n };\n\n template \n unsigned tagged_uint::x;\n\n template \n unsigned read_uint() noexcept\n {\n return tagged_uint::x;\n }\n\n template \n void write_uint( unsigned x ) noexcept\n {\n tagged_uint::x = x;\n }\n\n template \n void uint_increment() noexcept\n {\n ++tagged_uint::x;\n }\n\n template \n void uint_decrement() noexcept\n {\n --tagged_uint::x;\n }\n}\n\n} }\n\n#endif\n" }, { "path": "include/boost/leaf/config.hpp", "content": "#ifndef BOOST_LEAF_CONFIG_HPP_INCLUDED\n#define BOOST_LEAF_CONFIG_HPP_INCLUDED\n\n// Copyright 2018-2022 Emil Dotchevski and Reverge Studios, Inc.\n\n// Distributed under the Boost Software License, Version 1.0. (See accompanying\n// file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)\n\n// The following is based in part on Boost Config.\n\n// (C) Copyright John Maddock 2001 - 2003.\n// (C) Copyright Martin Wille 2003.\n// (C) Copyright Guillaume Melquiond 2003.\n\n#ifndef BOOST_LEAF_ASSERT\n# include \n# define BOOST_LEAF_ASSERT assert\n#endif\n\n////////////////////////////////////////\n\n#ifdef BOOST_LEAF_DIAGNOSTICS\n# warning BOOST_LEAF_DIAGNOSTICS has been renamed to BOOST_LEAF_CFG_DIAGNOSTICS.\n# define BOOST_LEAF_CFG_DIAGNOSTICS BOOST_LEAF_DIAGNOSTICS\n#endif\n\n////////////////////////////////////////\n\n#ifdef BOOST_LEAF_TLS_FREERTOS\n\n# ifndef BOOST_LEAF_EMBEDDED\n# define BOOST_LEAF_EMBEDDED\n# endif\n\n#endif\n\n////////////////////////////////////////\n\n#ifdef BOOST_LEAF_EMBEDDED\n\n# ifndef BOOST_LEAF_CFG_DIAGNOSTICS\n# define BOOST_LEAF_CFG_DIAGNOSTICS 0\n# endif\n\n# ifndef BOOST_LEAF_CFG_STD_SYSTEM_ERROR\n# define BOOST_LEAF_CFG_STD_SYSTEM_ERROR 0\n# endif\n\n# ifndef BOOST_LEAF_CFG_STD_STRING\n# define BOOST_LEAF_CFG_STD_STRING 0\n# endif\n\n# ifndef BOOST_LEAF_CFG_CAPTURE\n# define BOOST_LEAF_CFG_CAPTURE 0\n# endif\n\n#endif\n\n////////////////////////////////////////\n\n#ifndef BOOST_LEAF_CFG_DIAGNOSTICS\n# define BOOST_LEAF_CFG_DIAGNOSTICS 1\n#endif\n\n#ifndef BOOST_LEAF_CFG_STD_SYSTEM_ERROR\n# define BOOST_LEAF_CFG_STD_SYSTEM_ERROR 1\n#endif\n\n#ifndef BOOST_LEAF_CFG_STD_STRING\n# define BOOST_LEAF_CFG_STD_STRING 1\n#endif\n\n#ifndef BOOST_LEAF_CFG_CAPTURE\n# define BOOST_LEAF_CFG_CAPTURE 1\n#endif\n\n#ifndef BOOST_LEAF_CFG_WIN32\n# define BOOST_LEAF_CFG_WIN32 0\n#endif\n\n#ifndef BOOST_LEAF_CFG_GNUC_STMTEXPR\n# ifdef __GNUC__\n# \tdefine BOOST_LEAF_CFG_GNUC_STMTEXPR 1\n# else\n# \tdefine BOOST_LEAF_CFG_GNUC_STMTEXPR 0\n# endif\n#endif\n\n#if BOOST_LEAF_CFG_DIAGNOSTICS!=0 && BOOST_LEAF_CFG_DIAGNOSTICS!=1\n# error BOOST_LEAF_CFG_DIAGNOSTICS must be 0 or 1.\n#endif\n\n#if BOOST_LEAF_CFG_STD_SYSTEM_ERROR!=0 && BOOST_LEAF_CFG_STD_SYSTEM_ERROR!=1\n# error BOOST_LEAF_CFG_STD_SYSTEM_ERROR must be 0 or 1.\n#endif\n\n#if BOOST_LEAF_CFG_STD_STRING!=0 && BOOST_LEAF_CFG_STD_STRING!=1\n# error BOOST_LEAF_CFG_STD_STRING must be 0 or 1.\n#endif\n\n#if BOOST_LEAF_CFG_CAPTURE!=0 && BOOST_LEAF_CFG_CAPTURE!=1\n# error BOOST_LEAF_CFG_CAPTURE must be 0 or 1.\n#endif\n\n#if BOOST_LEAF_CFG_DIAGNOSTICS && !BOOST_LEAF_CFG_STD_STRING\n# error BOOST_LEAF_CFG_DIAGNOSTICS requires the use of std::string\n#endif\n\n#if BOOST_LEAF_CFG_WIN32!=0 && BOOST_LEAF_CFG_WIN32!=1\n# error BOOST_LEAF_CFG_WIN32 must be 0 or 1.\n#endif\n\n#if BOOST_LEAF_CFG_GNUC_STMTEXPR!=0 && BOOST_LEAF_CFG_GNUC_STMTEXPR!=1\n# error BOOST_LEAF_CFG_GNUC_STMTEXPR must be 0 or 1.\n#endif\n\n////////////////////////////////////////\n\n// Configure BOOST_LEAF_NO_EXCEPTIONS, unless already #defined\n#ifndef BOOST_LEAF_NO_EXCEPTIONS\n\n# if defined(__clang__) && !defined(__ibmxl__)\n// Clang C++ emulates GCC, so it has to appear early.\n\n# if !__has_feature(cxx_exceptions)\n# define BOOST_LEAF_NO_EXCEPTIONS\n# endif\n\n# elif defined(__DMC__)\n// Digital Mars C++\n\n# if !defined(_CPPUNWIND)\n# define BOOST_LEAF_NO_EXCEPTIONS\n# endif\n\n# elif defined(__GNUC__) && !defined(__ibmxl__)\n// GNU C++:\n\n# if !defined(__EXCEPTIONS)\n# define BOOST_LEAF_NO_EXCEPTIONS\n# endif\n\n# elif defined(__KCC)\n// Kai C++\n\n# if !defined(_EXCEPTIONS)\n# define BOOST_LEAF_NO_EXCEPTIONS\n# endif\n\n# elif defined(__CODEGEARC__)\n// CodeGear - must be checked for before Borland\n\n# if !defined(_CPPUNWIND) && !defined(__EXCEPTIONS)\n# define BOOST_LEAF_NO_EXCEPTIONS\n# endif\n\n# elif defined(__BORLANDC__)\n// Borland\n\n# if !defined(_CPPUNWIND) && !defined(__EXCEPTIONS)\n# define BOOST_LEAF_NO_EXCEPTIONS\n# endif\n\n# elif defined(__MWERKS__)\n// Metrowerks CodeWarrior\n\n# if !__option(exceptions)\n# define BOOST_LEAF_NO_EXCEPTIONS\n# endif\n\n# elif defined(__IBMCPP__) && defined(__COMPILER_VER__) && defined(__MVS__)\n// IBM z/OS XL C/C++\n\n# if !defined(_CPPUNWIND) && !defined(__EXCEPTIONS)\n# define BOOST_LEAF_NO_EXCEPTIONS\n# endif\n\n# elif defined(__ibmxl__)\n// IBM XL C/C++ for Linux (Little Endian)\n\n# if !__has_feature(cxx_exceptions)\n# define BOOST_LEAF_NO_EXCEPTIONS\n# endif\n\n# elif defined(_MSC_VER)\n// Microsoft Visual C++\n//\n// Must remain the last #elif since some other vendors (Metrowerks, for\n// example) also #define _MSC_VER\n\n# if !_CPPUNWIND\n# define BOOST_LEAF_NO_EXCEPTIONS\n# endif\n# endif\n\n#endif\n\n////////////////////////////////////////\n\n#ifdef _MSC_VER\n# define BOOST_LEAF_ALWAYS_INLINE __forceinline\n#else\n# define BOOST_LEAF_ALWAYS_INLINE __attribute__((always_inline)) inline\n#endif\n\n////////////////////////////////////////\n\n#ifndef BOOST_LEAF_NODISCARD\n# if __cplusplus >= 201703L\n# define BOOST_LEAF_NODISCARD [[nodiscard]]\n# else\n# define BOOST_LEAF_NODISCARD\n# endif\n#endif\n\n////////////////////////////////////////\n\n#ifndef BOOST_LEAF_CONSTEXPR\n# if __cplusplus > 201402L\n# define BOOST_LEAF_CONSTEXPR constexpr\n# else\n# define BOOST_LEAF_CONSTEXPR\n# endif\n#endif\n\n////////////////////////////////////////\n\n#ifndef BOOST_LEAF_NO_EXCEPTIONS\n# include \n# if (defined(__cpp_lib_uncaught_exceptions) && __cpp_lib_uncaught_exceptions >= 201411L) || (defined(_MSC_VER) && _MSC_VER >= 1900)\n# define BOOST_LEAF_STD_UNCAUGHT_EXCEPTIONS 1\n# else\n# define BOOST_LEAF_STD_UNCAUGHT_EXCEPTIONS 0\n# endif\n#endif\n\n////////////////////////////////////////\n\n#ifdef __GNUC__\n# define BOOST_LEAF_SYMBOL_VISIBLE __attribute__((__visibility__(\"default\")))\n#else\n# define BOOST_LEAF_SYMBOL_VISIBLE\n#endif\n\n////////////////////////////////////////\n\n#if defined(__GNUC__) && !(defined(__clang__) || defined(__INTEL_COMPILER) || defined(__ICL) || defined(__ICC) || defined(__ECC)) && (__GNUC__ * 100 + __GNUC_MINOR__) < 409\n# ifndef BOOST_LEAF_NO_CXX11_REF_QUALIFIERS\n# define BOOST_LEAF_NO_CXX11_REF_QUALIFIERS\n# endif\n#endif\n\n////////////////////////////////////////\n\n// Configure TLS access\n#include \n\n////////////////////////////////////////\n\n#endif\n" }, { "path": "include/boost/leaf/context.hpp", "content": "#ifndef BOOST_LEAF_CONTEXT_HPP_INCLUDED\n#define BOOST_LEAF_CONTEXT_HPP_INCLUDED\n\n// Copyright 2018-2022 Emil Dotchevski and Reverge Studios, Inc.\n\n// Distributed under the Boost Software License, Version 1.0. (See accompanying\n// file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)\n\n#include \n#include \n\n#if !defined(BOOST_LEAF_NO_THREADS) && !defined(NDEBUG)\n# include \n#endif\n\nnamespace boost { namespace leaf {\n\nclass error_info;\nclass diagnostic_info;\nclass verbose_diagnostic_info;\n\ntemplate \nstruct is_predicate: std::false_type\n{\n};\n\nnamespace leaf_detail\n{\n template \n struct is_exception: std::is_base_of::type>\n {\n };\n\n template \n struct handler_argument_traits;\n\n template ::value>\n struct handler_argument_traits_defaults;\n\n template \n struct handler_argument_traits_defaults\n {\n using error_type = typename std::decay::type;\n constexpr static bool always_available = false;\n\n template \n BOOST_LEAF_CONSTEXPR static error_type const * check( Tup const &, error_info const & ) noexcept;\n\n template \n BOOST_LEAF_CONSTEXPR static error_type * check( Tup &, error_info const & ) noexcept;\n\n template \n BOOST_LEAF_CONSTEXPR static E get( Tup & tup, error_info const & ei ) noexcept\n {\n return *check(tup, ei);\n }\n\n static_assert(!is_predicate::value, \"Handlers must take predicate arguments by value\");\n static_assert(!std::is_same::value, \"Handlers must take leaf::error_info arguments by const &\");\n static_assert(!std::is_same::value, \"Handlers must take leaf::diagnostic_info arguments by const &\");\n static_assert(!std::is_same::value, \"Handlers must take leaf::verbose_diagnostic_info arguments by const &\");\n };\n\n template \n struct handler_argument_traits_defaults: handler_argument_traits\n {\n using base = handler_argument_traits;\n static_assert(!base::always_available, \"Predicates can't use types that are always_available\");\n\n template \n BOOST_LEAF_CONSTEXPR static bool check( Tup const & tup, error_info const & ei ) noexcept\n {\n auto e = base::check(tup, ei);\n return e && Pred::evaluate(*e);\n }\n\n template \n BOOST_LEAF_CONSTEXPR static Pred get( Tup const & tup, error_info const & ei ) noexcept\n {\n return Pred{*base::check(tup, ei)};\n }\n };\n\n template \n struct handler_argument_always_available\n {\n using error_type = E;\n constexpr static bool always_available = true;\n\n template \n BOOST_LEAF_CONSTEXPR static bool check( Tup &, error_info const & ) noexcept\n {\n return true;\n }\n };\n\n template \n struct handler_argument_traits: handler_argument_traits_defaults\n {\n };\n\n template <>\n struct handler_argument_traits\n {\n using error_type = void;\n constexpr static bool always_available = false;\n\n template \n BOOST_LEAF_CONSTEXPR static std::exception const * check( Tup const &, error_info const & ) noexcept;\n };\n\n template \n struct handler_argument_traits\n {\n static_assert(sizeof(E) == 0, \"Error handlers may not take rvalue ref arguments\");\n };\n\n template \n struct handler_argument_traits: handler_argument_always_available::type>\n {\n template \n BOOST_LEAF_CONSTEXPR static E * get( Tup & tup, error_info const & ei) noexcept\n {\n return handler_argument_traits_defaults::check(tup, ei);\n }\n };\n\n template <>\n struct handler_argument_traits: handler_argument_always_available\n {\n template \n BOOST_LEAF_CONSTEXPR static error_info const & get( Tup const &, error_info const & ei ) noexcept\n {\n return ei;\n }\n };\n\n template \n struct handler_argument_traits_require_by_value\n {\n static_assert(sizeof(E) == 0, \"Error handlers must take this type by value\");\n };\n}\n\n////////////////////////////////////////\n\nnamespace leaf_detail\n{\n template \n struct tuple_for_each\n {\n BOOST_LEAF_CONSTEXPR static void activate( Tuple & tup ) noexcept\n {\n static_assert(!std::is_same(tup))>::type>::value, \"Bug in LEAF: context type deduction\");\n tuple_for_each::activate(tup);\n std::get(tup).activate();\n }\n\n BOOST_LEAF_CONSTEXPR static void deactivate( Tuple & tup ) noexcept\n {\n static_assert(!std::is_same(tup))>::type>::value, \"Bug in LEAF: context type deduction\");\n std::get(tup).deactivate();\n tuple_for_each::deactivate(tup);\n }\n\n BOOST_LEAF_CONSTEXPR static void propagate( Tuple & tup, int err_id ) noexcept\n {\n static_assert(!std::is_same(tup))>::type>::value, \"Bug in LEAF: context type deduction\");\n auto & sl = std::get(tup);\n sl.propagate(err_id);\n tuple_for_each::propagate(tup, err_id);\n }\n\n BOOST_LEAF_CONSTEXPR static void propagate_captured( Tuple & tup, int err_id ) noexcept\n {\n static_assert(!std::is_same(tup))>::type>::value, \"Bug in LEAF: context type deduction\");\n BOOST_LEAF_ASSERT(err_id != 0);\n auto & sl = std::get(tup);\n if( sl.has_value(err_id) )\n load_slot(err_id, std::move(sl).value(err_id));\n tuple_for_each::propagate_captured(tup, err_id);\n }\n\n template \n static void print( std::basic_ostream & os, void const * tup, int key_to_print )\n {\n BOOST_LEAF_ASSERT(tup != nullptr);\n tuple_for_each::print(os, tup, key_to_print);\n std::get(*static_cast(tup)).print(os, key_to_print);\n }\n };\n\n template \n struct tuple_for_each<0, Tuple>\n {\n BOOST_LEAF_CONSTEXPR static void activate( Tuple & ) noexcept { }\n BOOST_LEAF_CONSTEXPR static void deactivate( Tuple & ) noexcept { }\n BOOST_LEAF_CONSTEXPR static void propagate( Tuple &, int ) noexcept { }\n BOOST_LEAF_CONSTEXPR static void propagate_captured( Tuple &, int ) noexcept { }\n template \n BOOST_LEAF_CONSTEXPR static void print( std::basic_ostream &, void const *, int ) { }\n };\n}\n\n////////////////////////////////////////////\n\n#if BOOST_LEAF_CFG_DIAGNOSTICS\n\nnamespace leaf_detail\n{\n template struct requires_unexpected { constexpr static bool value = false; };\n template struct requires_unexpected { constexpr static bool value = requires_unexpected::value; };\n template struct requires_unexpected { constexpr static bool value = requires_unexpected::value; };\n template struct requires_unexpected { constexpr static bool value = requires_unexpected::value; };\n template <> struct requires_unexpected { constexpr static bool value = true; };\n template <> struct requires_unexpected { constexpr static bool value = true; };\n\n template \n struct unexpected_requested;\n\n template