diff options
| author | Niall Douglas (s [underscore] sourceforge {at} nedprod [dot] com) <spam@nowhere> | 2016-03-21 02:41:51 +0300 |
|---|---|---|
| committer | Niall Douglas (s [underscore] sourceforge {at} nedprod [dot] com) <spam@nowhere> | 2016-03-21 02:41:51 +0300 |
| commit | 758a934ab266ed660daa54b72e4606b78e374071 (patch) | |
| tree | 6f2fe1c5d2b8331f9319549bc6f0c3390168eb6b /attic/doc | |
AFIO v2: Relocate all the AFIO v2 files in fs_probe into the root hierarchy. AFIO v2 is now the master branch!
Diffstat (limited to 'attic/doc')
293 files changed, 17205 insertions, 0 deletions
diff --git a/attic/doc/Jamfile.v2 b/attic/doc/Jamfile.v2 new file mode 100644 index 00000000..c5f25789 --- /dev/null +++ b/attic/doc/Jamfile.v2 @@ -0,0 +1,74 @@ +# Boost.AFIO +# +# This documentation machinery is derived from Boost.Geometry + +# Use, modification and distribution is subject to the Boost Software License, +# Version 1.0. (See accompanying file LICENSE_1_0.txt or copy at +# http://www.boost.org/LICENSE_1_0.txt) + + +import os ; + +project afio/doc ; +using quickbook ; + +path-constant here : . ; + +make disqus_comments.html : ./disqus_comments.html : @copy_disqus_identifiers ; +if [ os.name ] = NT +{ + actions copy_disqus_identifiers + { + for %%a in ("$(>)") do set src_path=%%~dpa\disqus_identifiers + for %%a in ("$(<)") do set dest_path=%%~dpa\disqus_identifiers + robocopy /E %src_path% %dest_path% + copy /B $(>) $(<) + } +} +else +{ + actions copy_disqus_identifiers + { + cp -a `dirname $(>)`/disqus_identifiers `dirname $(<)`/disqus_identifiers + cp -a $(>) $(<) + } +} + +boostbook afio + : afio.qbk + : <dependency>Jamfile.v2 + <dependency>generated/class_dispatcher.qbk + <xsl:param>chunk.section.depth=4 +# <auto-index>off +# <auto-index-internal>on +# <auto-index-verbose>off +# <xsl:param>index.on.type=1 +# <format>html + <xsl:param>chunk.first.sections=1 + <xsl:param>toc.section.depth=4 + <xsl:param>toc.max.depth=4 + <xsl:param>generate.section.toc.level=4 + <xsl:param>boost.root=../.. + <format>onehtml:<xsl:param>img.src.path=../../../../libs/afio/doc/src/images/a/b/ + <format>html:<xsl:param>img.src.path=../../../../libs/afio/doc/src/images/a/b/ + <format>xhtml:<xsl:param>img.src.path=../../../../libs/afio/doc/src/images/a/b/ + <format>pdf:<xsl:param>img.src.path=../../../../../../libs/afio/doc/src/images/ + <xsl:param>root.filename=afio + <xsl:param>html.stylesheet=../../libs/afio/doc/html/myboostbook.css + <quickbook-define>enable_index + <include>$(here) + <format>pdf:<xsl:param>boost.url.prefix=https://ci.nedprod.com/ + <xsl:param>fop1.extensions=0 + #<format>pdf:<xsl:param>xep.extensions=1 + # TOC generation: this is needed for FOP 0.2, but must not be set to zero for FOP-0.9! + <format>pdf:<xsl:param>fop.extensions=0 + # No indent on body text: + <format>pdf:<xsl:param>body.start.indent=0pt + # Margin size: + <format>pdf:<xsl:param>page.margin.inner=0.5in + # Margin size: + <format>pdf:<xsl:param>page.margin.outer=0.5in +; + +install pdfinstall : afio/<format>pdf : <location>. <name>afio.pdf <install-type>PDF ; +explicit pdfinstall ; diff --git a/attic/doc/Readme.txt b/attic/doc/Readme.txt new file mode 100644 index 00000000..2a4c2ee1 --- /dev/null +++ b/attic/doc/Readme.txt @@ -0,0 +1,63 @@ +Instructions on how to build the AFIO docs +========================================== +Niall Douglas + +The Boost.AFIO docs are borrowed heavily from those of Boost.Geometry, so all +credit should go there. The following might look Windows specific, but I had +a terrible time matching up the right versions of binaries on POSIX from vendor +provided package repositories, so it's probably actually easier to configure +on Windows crazily enough. + +1. Install doxygen, java and python 2.7 such that it runs from PATH. + +2. Make a directory in a path containing no spaces somewhere to hold many tools. +Let's say C:\BoostBook or /home/ned/BoostBook. + +3. Follow these instructions from http://www.boost.org/doc/libs/1_55_0/doc/html/quickbook/install.html. + +WINDOWS ONLY: Get the xsltproc, libxml2, libxslt and the Docbook XSL mentioned +by the document above all into C:\BoostBook. The directory structure would look +like this: + +C:\BoostBook\bin\xsltproc.exe +... +C:\BoostBook\xml\docbook-xsl +... + +Note that the link on the above page to the Docbook XSL gives you the -ns version +which won't work. You need the -1 version from +http://sourceforge.net/projects/docbook/files/docbook-xsl/1.78.1/ + +4. OPTIONAL: Compile Boost QuickBook and copy the output binary into BoostBook\bin. + +5. If on Boost prior to v1.54, apply the doxygen_xml2qbk.patch in this directory +to Boost. This will add support for producing QuickBook documentation from public +member variables. Compile libs/geometry/doc/src/docutils/tools/doxygen_xml2qbk +using something like: + +./b2 libs/geometry/doc/src/docutils/tools/doxygen_xml2qbk + +... and copy the output binary into BoostBook\bin. + +6. I simply can't get any version past or present of Apache FOP to work with +the present DocBook XSLTs, so go to http://www.renderx.com/download/personal.html, +register for a personal edition of RenderX XEP, and follow the instructions from +http://www.boost.org/doc/libs/1_54_0/doc/html/boostbook/getting/started.html +to configure your user-config.jam with all the right paths but using XEP +instead of FOP. + +7. Open a command box and cd to this directory (libs/afio/doc). Do: + +set DOXYGEN_XML2QBK="C:\BoostBook\bin\doxygen_xml2qbk.exe" +python make_qbk.py + +8. Return to the boost top directory. Do: + +cd doc +../b2 ../libs/afio/doc + +HTML documentation is output alongside other Boost documentation. + +9. For PDF output do + +../b2 ../libs/afio/doc pdf diff --git a/attic/doc/acknowledgments.qbk b/attic/doc/acknowledgments.qbk new file mode 100644 index 00000000..0d57f1d3 --- /dev/null +++ b/attic/doc/acknowledgments.qbk @@ -0,0 +1,65 @@ +[/============================================================================ + Boost.AFIO + + Use, modification and distribution is subject to the Boost Software License, + Version 1.0. (See accompanying file LICENSE_1_0.txt or copy at + http://www.boost.org/LICENSE_1_0.txt) +=============================================================================/] + +[section Acknowledgments] + +We would like to thank all the people who contributed to the development of this library, many of whom +are not listed here but nevertheless are due our thanks. Our especial thanks goes (in chronological +order since 2012): + +* To my former team at BlackBerry (of whom Tony van Eerd is best known to the C++ community) for +the off the cuff discussions which led to me to conceptualise AFIO as an out-of-work side project. + +* To Google, for sponsoring Paul to work on AFIO as part of Google Summer of Code 2013. +Paul did the lion's share of the work of porting the preexisting pure C++ 11 code +base to Boost and to older compilers, both tasks which could never be called fun by anyone. + +* To the family and friends who had to put up with us during Google Summer of Code 2013 +adding 15-25 hours per week above +and beyond our normal work hours which meant time not spent with them. This part is +without doubt the hardest part of developing a new Boost library __dash__ what it requires +you to sacrifice in exchange for what little free time is already left over after +a work week. + +* To my former team and division at BlackBerry who successfully obtained the first ever +corporate permission for an employee to contribute to a non-business open source project. +The many months of wrangling to achieve that win was made moot when I was downsized +towards the end of GSoC just weeks after gaining the landmark approval from Legal, nevertheless my thanks are due to BlackBerry for trying to +change itself and letting me be a part of that. + +* To Christopher M. Kohlhoff for providing Boost.ASIO, which has been a high benchmark +to aspire towards. + +* To Beman Dawes for providing Boost.Filesystem and the Filesystem TS, without which filesystem +paths would be far more tricky to handle well in C++. + +* To Artur Laksberg for reviewing AFIO early on and making a number of valuable observations. + +* To Bjorn Reese for taking the time to be an early adopter of AFIO, and making many +observations of where AFIO could be obviously improved, almost all of which were our +delight to enact. + +* To Vicente J. Botet Escriba for very kindly adding a method to Boost.Thread's future's +for directly fetching their exception_ptr. This greatly improved AFIO's exception +propagation performance. + +* To Megan and Clara for putting up with the nightly 12am to 4am weekday after-work slots +during 2015 which were necessary to make any progress on AFIO and its sublibraries APIBind, +Spinlock and Monad. + +* To the many people on the boost-dev mailing list who contributed feedback on the design +of the sublibraries APIBind, Spinlock and Monad. + +* To Ahmed Charles for volunteering to review manage AFIO after two years of waiting in the +Boost peer review queue - thank you Ahmed! + +* And finally to all those who have submitted bugs and pull requests for AFIO, too many to +list here. + +[endsect] + diff --git a/attic/doc/advanced_topics.qbk b/attic/doc/advanced_topics.qbk new file mode 100644 index 00000000..002551dc --- /dev/null +++ b/attic/doc/advanced_topics.qbk @@ -0,0 +1,106 @@ +[/============================================================================ + Boost.AFIO + + Use, modification and distribution is subject to the Boost Software License, + Version 1.0. (See accompanying file LICENSE_1_0.txt or copy at + http://www.boost.org/LICENSE_1_0.txt) +=============================================================================/] + +[section:advanced_topics Advanced Topics] + +[section:custom_completion_handler How to write your own custom AFIO completion handler] + +If you want to extend __boost_afio__ with additional asynchronous functionality, +you're probably going to have to implement your own custom AFIO completion handler +which can be scheduled using __afio_completion__. +These are the second most lowest level, second most primitive completion handler AFIO has and while a +non-trivial amount of programmer effort to utilise, they do offer a maximum amount +of flexibility, functionality and of course, performance[footnote If you're willing to go even ['more] low level, AFIO's +`async_file_io_dispatcher_base` class exposes as protected member functions the variadic +templated function `chain_async_op()` and a suite of specialised `chain_async_ops()` helper +overloads. Therefore if you subclass `async_file_io_dispatcher_base`, you can enjoy the overhead of +just one `std::function<>` call.]. If you are NOT extending +AFIO with extra functionality, you almost certainly want __afio_call__ instead. + +Some advantages of custom completion handlers include: + +* Access to op id and any precondition op which was supplied at the point of scheduling. +* Ability to schedule immediate completions which are executed instantly after +their precondition instead of later when the thread source gets round to them. +This is particularly useful when your host OS has real async i/o support, because +you can use immediate completions to schedule non-blocking async i/o operations +as quickly as possible. Another use is taking advantage of Lx cache locality while +the cache lines are still paged in. +* Direct control of exception handling and error propagation, where arbitrary ops can be +completed at any time by any thread in any circumstance. +* Performance: completion handlers only have a single `std::function<>` invocation +overhead, rather than more as would be the case with `call()`. The reason why nesting +`std::function<>` invocations is bad is because each entails type erasure, which requires +the CPU to do an indirect jump (like a virtual function call) and while modern branch +predictors eliminate any penalty for executing just one of those, they most certainly +struggle when they have to execute a sequence of indirect jumps. For example, a single +indirect jump might cost just two CPU cycles, while a mispredicted indirect jump might +cost as much as 18-25 CPU cycles. + +Some disadvantages of custom completion handlers include: + +* Unlike __afio_call__, there is no custom return type machinery i.e. you'll have to +implement your own. This isn't hard __dash__ note how __afio_enumerate__'s internal completion +handler in afio.cpp takes a shared pointer as a parameter containing the promises of output for +the enumerations, thus allowing __afio_enumerate__ to set up a batch of futures +corresponding to those promises and return those to the user. +* Exception handling is rather more manual. That comes of course with flexibility as well as hassle. + +So, let's have a look at an example of a custom AFIO completion handler, this being +pretty much the simplest formulation possible: + +[completion_example1] + +Note how you have fair amount of flexibility of defining any input parameters you like so long as +the standard duo of id and precondition are there. This is enabled basically +through `std::bind<>` to prebind any custom parameters you may have to produce a `std::function<>` +instance with the aforementioned standard duo of parameters. As AFIO's completion +implementation natively works with `std::function<>`, you effectively get custom parameter +binds for free anyway. + +The above shows a simple custom completion handler __dash__ as mentioned earlier, one can also +do immediate completions, and this is an example of just that: + +[completion_example2] + +Note the new function for completing a deferred completion: `complete_async_op()`, which +can take a `std::exception_ptr` if you want AFIO to return an errored state. + +As of AFIO v1.2 all of the constraints which were imposed on immediate completions +are eliminated, and deferred completions were completely eliminated as now all completions +are always deferred. Therefore, as of v1.2, you can do anything you can do in a normally +scheduled op in an immediately scheduled op. Nevertheless, you should be aware of the +following when using any kind of completion handler: + +* As far as AFIO is concerned, the precondition is completed and all knowledge of it +deleted from AFIO's records by the time you see it in a completion handler (it is deleted +as soon as possible to save on RAM footprint). +* Therefore adding completions to the precondition of the completion being executed simply schedules +them immediately (or executes them immediately if they are immediate) which may not be what +you intended. +* If you want to read in the handle output by the precondition for your own use, be aware +that using the `async_io_op::get()` function will by default rethrow any exception stored +into the precondition op. This has a useful side effect if you always do the following at +the top of your completion handler implementation: + + `std::shared_ptr<async_io_handle> h(op.get());` + + ... by immediately rethrowing any precondition exception before you execute any more code. + You'll see this pattern very, very frequently throughout AFIO's source code and you are + encouraged to do the same. If you really don't want to propage exceptions immediately then do: + + `std::shared_ptr<async_io_handle> h(op.get(true)); // Ignore any error state until later` + + This will place a default constructed (i.e. empty) shared pointer into h if there is an + errored state, otherwise the correct handle. If you need to determine whether the precondition + is a null handle or an errored state, you can always use `get_exception_ptr()` on the + shared future referred to by the h member variable of the precondition op. + +[endsect] [/custom_completion_handler] + +[endsect] [/advanced_topics] diff --git a/attic/doc/afio.qbk b/attic/doc/afio.qbk new file mode 100644 index 00000000..bbadaf52 --- /dev/null +++ b/attic/doc/afio.qbk @@ -0,0 +1,238 @@ +[/============================================================================ + Boost.AFIO + + Use, modification and distribution is subject to the Boost Software License, + Version 1.0. (See accompanying file LICENSE_1_0.txt or copy at + http://www.boost.org/LICENSE_1_0.txt) +=============================================================================/] + +[library Boost.AFIO + [quickbook 1.7] + [version 1.40] + [id afio] + [category afio] + [authors [Douglas, Niall], [Kirth, Paul]] + [copyright 2013-2015 Niall Douglas and Paul Kirth] + [purpose A portable asynchronous file i/o and filesystem library extending Boost.ASIO] + [license + Distributed under the Boost Software License, Version 1.0. + (See accompanying file LICENSE_1_0.txt or copy at + [@http://www.boost.org/LICENSE_1_0.txt]) + ] + [source-mode c++] +] + +[def __boost__ Boost] +[def __boost_afio__ Boost.AFIO] +[def __boost_bindlib__ [@https://github.com/ned14/Boost.APIBind Boost.APIBind]] +[def __boost_outcome__ [@https://ned14.github.io/boost.outcome/group__future__promise.html Boost.Outcome]] +[def __triplegit__ TripleGit] +[def __fileurl__ file:///] +[def __dash__ \u2014] +[def __tick__ [role aligncenter [role green \u2714]]] +[def __itick__ [role aligncenter [role red \u2714]]] +[def __cross__ [role aligncenter [role red \u2718]]] +[def __icross__ [role aligncenter [role green \u2718]]] +[def __boost_asio__ [@http://www.boost.org/libs/asio/ Boost.ASIO]] +[def __boost_thread__ [@http://www.boost.org/libs/thread/ Boost.Thread]] +[def __boost_filesystem__ [@http://www.boost.org/libs/filesystem/ Boost.Filesystem]] +[def __boost_iostreams__ [@http://www.boost.org/libs/iostreams/ Boost.Iostreams]] +[def __boost_test__ [@http://www.boost.org/libs/iostreams/ Boost.Test]] +[def __catch__ [@https://github.com/philsquared/Catch]] + +[/ Commonly used links] +[def __afio_enumerate_req__ [link afio.reference.structs.enumerate_req `enumerate_req`]] +[def __afio_io_req__ [link afio.reference.structs.io_req `io_req`]] +[def __afio_path_req__ [link afio.reference.structs.path_req `path_req`]] +[def __afio_stat_t__ [link afio.reference.structs.stat_t `stat_t`]] +[def __afio_statfs_t__ [link afio.reference.structs.statfs_t `statfs_t`]] + +[def __afio_directory_entry__ [link afio.reference.classes.directory_entry `directory_entry`]] +[def __afio_dispatcher__ [link afio.reference.classes.dispatcher `dispatcher`]] +[def __afio_op__ [link afio.reference.classes.future `future<T>`]] +[def __afio_handle__ [link afio.reference.classes.handle `handle`]] +[def __afio_path__ [link afio.reference.classes.path `path`]] + +[def __afio_enumerate__ [link afio.reference.functions.enumerate `async_enumerate()`]] +[def __afio_extents__ [link afio.reference.functions.extents `async_extents()`]] +[def __afio_make_dispatcher__ [link afio.reference.functions.make_dispatcher `make_dispatcher()`]] +[def __afio_statfs__ [link afio.reference.functions.statfs `async_statfs()`]] +[def __afio_truncate__ [link afio.reference.functions.truncate `async_truncate()`]] +[def __afio_zero__ [link afio.reference.functions.zero `async_zero()`]] +[def __afio_when_all__ `when_all_p()`] + +[/ Templates] +[template raceguarantees[contents] +'''<informaltable frame="all"><tgroup cols="2"><thead><row><entry>Operating system</entry><entry>Race guarantees under a changing file system</entry></row></thead><tbody>'''[contents]'''</tbody></tgroup></informaltable>''' +] +[template raceguarantee[os descr]'''<row><entry>'''[os]'''</entry><entry>'''[descr]'''</entry></row>'''] + +[import ../example/workshop_naive.ipp] +[import ../example/workshop_naive_afio.ipp] +[import ../example/workshop_naive_async_afio.ipp] +[import ../example/workshop_atomic_updates_afio.ipp] +[import ../example/workshop_final_afio.ipp] + +[import ../example/adopt_example.cpp] +[import ../example/barrier_example.cpp] +[import ../example/benchmark_atomic_log.cpp] +[import ../example/call_example.cpp] +[import ../example/closure_execution_afio_io_example.cpp] +[import ../example/closure_execution_traditional_io_example.cpp] +[import ../example/completion_example1.cpp] +[import ../example/completion_example2.cpp] +[import ../example/enumerate_example.cpp] +[import ../example/filecopy_example.cpp] +[import ../example/filedir_example.cpp] +[import ../example/filter_example.cpp] +[import ../example/find_in_files_afio.cpp] +[import ../example/find_in_files_iostreams.cpp] +[import ../example/readallof_example.cpp] +[import ../example/readwrite_example.cpp] +[import ../example/readwrite_example_traditional.cpp] +[import ../example/statfs_example.cpp] +[import ../test/tests/atomic_log_append_test.cpp] +[import ../test/tests/race_protection_works.cpp] + +[section:introduction Introduction] + +'''<?dbhtml-include href="disqus_identifiers/introduction.html"?>''' + +__boost_afio__ is a C++ library which lets you schedule an ordered dependency graph of file and filesystem +input/output operations to be executed asynchronously to the maximum capacity of your hardware. If you want +to do portable asynchronous filesystem and file i/o in C++, especially if you need to easily order issues of reads and writes, +this is the correct library to be looking at. + +As a quick check list, if you have ever experienced any of these problems, then AFIO may be useful to you: + +# Your spinning magnetic rust hard drive goes bananas when some routine in your code + tries to do something to storage, and latency per op starts heading into the seconds range. + +# Your super fast SSD which is supposed to be delivering hundreds of thousands of ops/sec + is barely managing a tenth of its supposed ability with your code. After reading about the + importance of high queue depth to maximising performance from SSDs, you try opening many + handles to the same file and firing an army of thread pool workers at the problem to try + and increase queue depth, but your performance actually drops over the single threaded case. + +# Your code has to interact with a regularly changing filesystem and not get weird race errors e.g. you + try to create a new file in path /X/Y/Z, but some other program has just renamed directory /X/Y + to /A/B in the time between you deciding on /X/Y/Z and getting round to it. + +# Your code keeps file handles open a long time in a place where others might delete or rename + them, including any part of the directory hierarchy preceding the file. + +# Deleting directory trees randomly fails on Microsoft Windows for no obvious reason. + +# Your code needs to read and write files concurrently to other code without resorting to + shared memory region tricks e.g. if the files reside on a Samba or NFS network shared drive. + +# Your CPU needs to be doing more useful work instead of copying memory to and from disc i/o + buffers. As great as the STL iostream buffering is, unless disabled it doubles the LL cache + pressure on your CPU, evicting other more useful data. The STL iostreams design almost certainly won't + allow the kernel use VM tricks to directly busmaster DMA from its buffers to the hard drive, so + the kernel will have to copy those buffers a third time. That means that for every 1Kb you read + or write you are evicted, as a minimum, 3Kb from the LL caches in your CPU, all of which must be + refilled with more useful data later. + +# Your code wants to experience various filing system features identically across platforms which + also work on shared Samba and NFS network drives, such as: + * Deleting and renaming open files. + * Files having unique inode values. + * POSIX timestamping of last accessed, last modified, last status changed and created. + * File extent management and traversal. + * Explicitly documented filing system race guarantees. + * Interrogation of filing system characteristics, devices and mount points. + * Ten million item directories, or more. We have tested twenty five million item directories on NTFS + and ext4 and performance was actually tolerable with under a second pause. Ten million item directories is plenty fast, and + one million item directories you won't notice over a ten item directory. Note that your GUI file + explorer will very likely hang on ten million item directories, indeed so do most command line tools. + * Exclusive lock files (manually operated support already there, async support coming in v1.5). + * File change monitoring (coming in v1.5). + * File byte range advisory locking (coming in v1.5). + +[note Lest there be any disappointment in expectations, [*using AFIO alone will not magically improve your filesystem +performance], if anything there is a performance penalty in naive use of AFIO as a direct replacement for +naive synchronous file i/o. What AFIO gives you is a large amount of ['control] with easy to twiddle knobs +for benchmarking optimal filesystem strategies under various use cases. In other words, using AFIO lets you +more easily write and test code that ['never performs really badly] in corner cases.] + +__boost_afio__ is a __boost_bindlib__ based Boost library, and therefore is capable of any combination of +the following build configurations: + +* Uses either Boost OR the C++ 11 STL for atomic, thread, future, chrono etc. +* Uses either Boost OR the C++ 1y STL for Fileystem. At the time of writing, only VS2015 provides Filesystem +in its STL though libstdc++ 6.0 is expected to also do so. +* Uses either Boost OR standalone ASIO for the i/o engine. + +You may note that as a result AFIO can be used as a [@https://boostgsoc13.github.io/boost.afio/afio-stable.tar.bz2 completely standalone header-only library totally independent from +any dependencies on Boost] which can be dropped into any existing build system as [@https://boostgsoc13.github.io/boost.afio/afio-single-header.hpp.bz2 a simple single header include]. This, +incidentally, also extends to its unit test suite which can use either __boost_test__ OR __catch__ (actually my own thread +safe fork of CATCH). + +__boost_afio__ provides a pure portable POSIX file i/o backend and specialised file i/o backends +making use of host OS asynchronous file i/o facilities are provided for: + +* Windows NT IOCP (since v1.0) +* Linux KAIO (planned, would reduce thread pool blocking for read() and write() only) +* POSIX AIO, suitable for BSD only (planned, would reduce thread pool blocking for read() and write() only) +* WinRT (if there is demand, currently WinRT is not supported at all) + +__boost_afio__ is regularly compiled and per-commit unit tested on these platforms: + +* Android with ext4 (libc++ STL toolchain only). +* Apple Mac OS X 10.9 with HFS+ (should still work on 10.5). Note that OS X does not provide race free filesystem due to insufficient APIs provided. +* FreeBSD 10.1 with ZFS (should also work on 10.0). Note that the BSDs only provide race free filesystem for directories not files due to insufficient APIs provided. +* Linux kernels 2.6.32 to 3.13 with ext4. +* Microsoft Windows 8.1 with NTFS (should still work on XP). + +__boost_afio__ extends __boost_asio__ and is therefore dependent on ASIO (Boost or standalone). +With a good modern compiler [link afio.FAQ.closure_performance you can expect 50-90% of the +throughput of using raw Boost.ASIO] at a latency of [link afio.FAQ.closure_latency about 60,000 +/- 600 CPU cycles to get notified +of the completion of an operation]. This library was brought to __boost__ as part of Google +Summer of Code 2013. + +__boost_afio__ is a C++ 11 only library, and it requires, as an absolute minimum, a compiler with: + +* Rvalue reference support. +* Variadic templates. +* Template aliasing. +* Noexcept. +* Constexpr (C++ 11). + +Some popular compilers known to be minimally sufficient thanks to [@https://ci.nedprod.com/ our Jenkins CI bot] include: + +* Microsoft Visual Studio 2015, released in 2015. v1.0-v1.2 supported VS2010, v1.3 supported VS2013. +* GNU Compiler Collection v4.8, released in 2013. v1.0-v1.2 supported GCC 4.6, v1.3 supported GCC v4.7. +* clang v3.3, released in 2013. v1.0-v1.3 supported clang v3.2. clang v3.1 is known to produce segfaulting binaries. + +The Jenkins CI bot runs a full suite of static analysis tools (currently clang and MSVC static analysers and +clang-tidy, [@http://ispras.linuxbase.org/index.php/ABI_compliance_checker the ABI stability compliance checker] is planned), +runtime analysis tools (currently the clang undefined behaviour +and thread sanitisers plus valgrind memcheck) plus a full set of unit tests for all supported compilers +on all supported platforms for every single commit to master branch and every single pull request. Additionally, +the Travis CI bot runs a full set of code coverage for the unit tests which is pushed to coveralls.io. +[link unit_test_dashboard You can view the build and unit test CI dashboard for all compilers and platforms here]. + +[important Note that Boost.AFIO has not passed Boost peer review, and therefore is not a part of the Boost C++ libraries] + +As a very quick example of minimal usage: + +[filedir_example] + +'''<?dbhtml-include href="disqus_comments.html"?>''' + +[endsect] [/introduction] + +[include design_rationale.qbk] +[include compiling.qbk] +[include quickstart.qbk] +[include reference.qbk] +[/ [include advanced_topics.qbk]] +[include release_notes.qbk] +[include acknowledgments.qbk] + +[section:index Index] +''' +<index/> +''' +[endsect] [/index] diff --git a/attic/doc/benchmarks.xlsx b/attic/doc/benchmarks.xlsx Binary files differnew file mode 100644 index 00000000..e01e1a33 --- /dev/null +++ b/attic/doc/benchmarks.xlsx diff --git a/attic/doc/compiling.qbk b/attic/doc/compiling.qbk new file mode 100644 index 00000000..83e772f0 --- /dev/null +++ b/attic/doc/compiling.qbk @@ -0,0 +1,1196 @@ +[/============================================================================== + Use, modification and distribution is subject to the Boost Software License, + Version 1.0. (See accompanying file LICENSE_1_0.txt or copy at + http://www.boost.org/LICENSE_1_0.txt) +===============================================================================/] + + + +[section Compilation] + +[def __msvc__ MSVC] +[def __stlport__ [@http://sourceforge.net/projects/stlport STLport]] + +__boost_afio__ is by default a headers-only library, unless you define the macro +`BOOST_AFIO_HEADERS_ONLY` to zero before including afio.hpp. Users only need to include the +library headers in their programs in order to be able to access definitions +and algorithms provided by the __boost_afio__ library. No linking against +any binaries is required. + +As of v1.3 of the engine, __boost_afio__ is now capable of being used standalone +with no dependencies. You choose the dependencies by setting the following macros or +leaving them default: + +* `BOOST_AFIO_USE_BOOST_THREAD` (defaults to 0 except on Mingw32 only, Mingw-w64 has a working +std thread library): Use Boost instead of the C++ 11 STL for +atomic, chrono, future, mutex and thread. This is useful where your C++ 11 STL is deficient +or where Boost's facilities are more useful. + +* `BOOST_AFIO_USE_BOOST_FILESYSTEM` (defaults to 0 except on VS2015 and later): Use +__boost_filesystem__ instead of the C++ 1y Filesystem TS provided by your STL. As +currently only VS2015 provides Filesystem, it only defaults to 1 for that platform. + +* `ASIO_STANDALONE` (defaults to undefined): Use standalone ASIO instead of __boost_asio__. +You will need to provide a copy of standalone ASIO on your include path. + +If you wish to run unit tests, you may also adjust: + +* `BOOST_AFIO_USE_BOOST_UNIT_TEST` (defaults to 0): Use __boost_test__ instead +of __boost_bindlib__'s emulation based on __catch__. + +Thanks to __boost_bindlib__, if your compiler has inline namespace support, you can multiply use the above four build config +macros in [*any] combination you like, ['including] within the same translation unit +i.e. a Boost.Thread based AFIO coexists happily with a C++ 11 STL AFIO in the same compiland, +and any combination thereof. Simply undefine the old values of the macros, and define new values +including afio.hpp afterwards. + +If you do make use of __boost_filesystem__ in your AFIO build, note that +Boost.Filesystem is dependant on Boost.System which will also need to be linked in. +On some platforms (e.g. ARM) you may also need Boost.Atomic. + +After defining your build macros of choice, making latest AFIO available to your +code is as simple as: + + #include "boost.afio/include/boost/afio.hpp" // latest version + #include "boost.afio/include/boost/v1/afio.hpp" // specific version + +if being used standalone or if being used as part of Boost: + + #include "boost/afio.hpp" // latest version + #include "boost/afio/v1/afio.hpp" // specific version + +[heading:trunk_status Supported Compilers And Current Trunk Build And Unit Test State] +[#unit_test_dashboard] + +''' +<informaltable frame="all" border="1" color="black"> + <tgroup cols="6"> + <colspec colnum="1" colname="col1"/> + <colspec colnum="2" colname="col2"/> + <colspec colnum="3" colname="col3"/> + <colspec colnum="4" colname="col4"/> + <colspec colnum="5" colname="col5"/> + <colspec colnum="6" colname="col6"/> + <thead> + <row> + <entry>OS</entry> + <entry>Compiler</entry> + <entry>STL</entry> + <entry>CPU</entry> + <entry>Build</entry> + <entry>Unit tests</entry> + </row> + </thead> + <tbody> + <row> + <entry morerows="1">Static analysis</entry> + <entry>clang 3.7 tidy + static analyser + GCC 4.8</entry> + <entry/> + <entry/> + <entry> + <ulink url="https://ci.nedprod.com/job/Boost.AFIO%20Static%20Analysis%20clang/"> + <mediaobject> + <imageobject> + <imagedata fileref="https://ci.nedprod.com/buildStatus/icon?job=Boost.AFIO%20Static%20Analysis%20clang"/> + </imageobject> + </mediaobject> + </ulink> + </entry> + <entry/> + </row> + <row> + <entry>VS2013</entry> + <entry/> + <entry/> + <entry> + <ulink url="https://ci.nedprod.com/job/Boost.AFIO%20Static%20Analysis%20MSVC/"> + <mediaobject> + <imageobject> + <imagedata fileref="https://ci.nedprod.com/buildStatus/icon?job=Boost.AFIO%20Static%20Analysis%20MSVC"/> + </imageobject> + </mediaobject> + </ulink> + </entry> + <entry/> + </row> + <row> + <entry>Thread Sanitiser</entry> + <entry>clang 3.4</entry> + <entry>libstdc++ 4.9</entry> + <entry>x64</entry> + <entry/> + <entry> + <ulink url="https://ci.nedprod.com/job/Boost.AFIO%20Sanitise%20Linux%20clang%203.4/"> + <mediaobject> + <imageobject> + <imagedata fileref="https://ci.nedprod.com/buildStatus/icon?job=Boost.AFIO%20Sanitise%20Linux%20clang%203.4"/> + </imageobject> + </mediaobject> + </ulink> + </entry> + </row> + <row> + <entry>Valgrind</entry> + <entry>GCC 4.8</entry> + <entry>libstdc++ 4.8</entry> + <entry>x64</entry> + <entry/> + <entry> + <ulink url="https://ci.nedprod.com/job/Boost.AFIO%20Valgrind%20Linux%20GCC%204.8/"> + <mediaobject> + <imageobject> + <imagedata fileref="https://ci.nedprod.com/buildStatus/icon?job=Boost.AFIO%20Valgrind%20Linux%20GCC%204.8"/> + </imageobject> + </mediaobject> + </ulink> + </entry> + </row> + <row> + <entry>Apple Mac OS X 10.9</entry> + <entry>clang 3.5</entry> + <entry>libc++</entry> + <entry>x64</entry> + <entry> + <ulink url="https://travis-ci.org/BoostGSoC13/boost.afio"> + <mediaobject> + <imageobject> + <imagedata fileref="https://travis-ci.org/BoostGSoC13/boost.afio.png?branch=master"/> + </imageobject> + </mediaobject> + </ulink> + </entry> + <entry> + <ulink url="https://travis-ci.org/BoostGSoC13/boost.afio"> + <mediaobject> + <imageobject> + <imagedata fileref="https://travis-ci.org/BoostGSoC13/boost.afio.png?branch=master"/> + </imageobject> + </mediaobject> + </ulink> + </entry> + </row> + <row> + <entry morerows="1">Android 5.0</entry> + <entry>clang 3.5</entry> + <entry>libc++</entry> + <entry>x86</entry> + <entry> + <ulink url="https://ci.nedprod.com/job/Boost.AFIO%20Build/CPPSTD=c++11,CXX=g++-4.8,LINKTYPE=standalone,label=android-ndk/"> + <mediaobject> + <imageobject> + <imagedata fileref="https://ci.nedprod.com/job/Boost.AFIO%20Build/CPPSTD=c++11,CXX=g++-4.8,LINKTYPE=standalone,label=android-ndk/badge/icon"/> + </imageobject> + </mediaobject> + </ulink> + </entry> + <entry> + <ulink url="https://ci.nedprod.com/job/Boost.AFIO%20Test/CPPSTD=c++11,CXX=g++-4.8,LINKTYPE=standalone,label=android-ndk/"> + <mediaobject> + <imageobject> + <imagedata fileref="https://ci.nedprod.com/job/Boost.AFIO%20Test/CPPSTD=c++11,CXX=g++-4.8,LINKTYPE=standalone,label=android-ndk/badge/icon"/> + </imageobject> + </mediaobject> + </ulink> + </entry> + </row> + <row> + <entry>GCC 4.8</entry> + <entry>libc++</entry> + <entry>x86</entry> + <entry> + <ulink url="https://ci.nedprod.com/job/Boost.AFIO%20Build/CPPSTD=c++11,CXX=g++-4.8,LINKTYPE=standalone,label=android-ndk/"> + <mediaobject> + <imageobject> + <imagedata fileref="https://ci.nedprod.com/job/Boost.AFIO%20Build/CPPSTD=c++11,CXX=g++-4.8,LINKTYPE=standalone,label=android-ndk/badge/icon"/> + </imageobject> + </mediaobject> + </ulink> + </entry> + <entry> + <ulink url="https://ci.nedprod.com/job/Boost.AFIO%20Test/CPPSTD=c++11,CXX=g++-4.8,LINKTYPE=standalone,label=android-ndk/"> + <mediaobject> + <imageobject> + <imagedata fileref="https://ci.nedprod.com/job/Boost.AFIO%20Test/CPPSTD=c++11,CXX=g++-4.8,LINKTYPE=standalone,label=android-ndk/badge/icon"/> + </imageobject> + </mediaobject> + </ulink> + </entry> + </row> + <row> + <entry>FreeBSD 10.1 on ZFS</entry> + <entry>clang 3.4</entry> + <entry>libc++</entry> + <entry>x86</entry> + <entry> + <ulink url="https://ci.nedprod.com/job/Boost.AFIO%20Build/CPPSTD=c++11,CXX=clang++-3.3,LINKTYPE=static,label=freebsd10-clang3.3/"> + <mediaobject> + <imageobject> + <imagedata fileref="https://ci.nedprod.com/job/Boost.AFIO%20Build/CPPSTD=c++11,CXX=clang++-3.3,LINKTYPE=static,label=freebsd10-clang3.3/badge/icon"/> + </imageobject> + </mediaobject> + </ulink> + <ulink url="https://ci.nedprod.com/job/Boost.AFIO%20Build/CPPSTD=c++11,CXX=clang++-3.3,LINKTYPE=shared,label=freebsd10-clang3.3/"> + <mediaobject> + <imageobject> + <imagedata fileref="https://ci.nedprod.com/job/Boost.AFIO%20Build/CPPSTD=c++11,CXX=clang++-3.3,LINKTYPE=shared,label=freebsd10-clang3.3/badge/icon"/> + </imageobject> + </mediaobject> + </ulink> + <ulink url="https://ci.nedprod.com/job/Boost.AFIO%20Build/CPPSTD=c++11,CXX=clang++-3.3,LINKTYPE=standalone,label=freebsd10-clang3.3/"> + <mediaobject> + <imageobject> + <imagedata fileref="https://ci.nedprod.com/job/Boost.AFIO%20Build/CPPSTD=c++11,CXX=clang++-3.3,LINKTYPE=standalone,label=freebsd10-clang3.3/badge/icon"/> + </imageobject> + </mediaobject> + </ulink> + </entry> + <entry> + <ulink url="https://ci.nedprod.com/job/Boost.AFIO%20Test/CPPSTD=c++11,CXX=clang++-3.3,LINKTYPE=static,label=freebsd10-clang3.3/"> + <mediaobject> + <imageobject> + <imagedata fileref="https://ci.nedprod.com/job/Boost.AFIO%20Test/CPPSTD=c++11,CXX=clang++-3.3,LINKTYPE=static,label=freebsd10-clang3.3/badge/icon"/> + </imageobject> + </mediaobject> + </ulink> + <ulink url="https://ci.nedprod.com/job/Boost.AFIO%20Test/CPPSTD=c++11,CXX=clang++-3.3,LINKTYPE=shared,label=freebsd10-clang3.3/"> + <mediaobject> + <imageobject> + <imagedata fileref="https://ci.nedprod.com/job/Boost.AFIO%20Test/CPPSTD=c++11,CXX=clang++-3.3,LINKTYPE=shared,label=freebsd10-clang3.3/badge/icon"/> + </imageobject> + </mediaobject> + </ulink> + <ulink url="https://ci.nedprod.com/job/Boost.AFIO%20Test/CPPSTD=c++11,CXX=clang++-3.3,LINKTYPE=standalone,label=freebsd10-clang3.3/"> + <mediaobject> + <imageobject> + <imagedata fileref="https://ci.nedprod.com/job/Boost.AFIO%20Test/CPPSTD=c++11,CXX=clang++-3.3,LINKTYPE=standalone,label=freebsd10-clang3.3/badge/icon"/> + </imageobject> + </mediaobject> + </ulink> + </entry> + </row> + <row> + <entry morerows="1">Ubuntu Linux 12.04 LTS</entry> + <entry>clang 3.3</entry> + <entry>libstdc++ 4.8</entry> + <entry>x86</entry> + <entry> + <ulink url="https://ci.nedprod.com/job/Boost.AFIO%20Build/CPPSTD=c++11,CXX=clang++-3.3,LINKTYPE=static,label=linux-gcc-clang/"> + <mediaobject> + <imageobject> + <imagedata fileref="https://ci.nedprod.com/job/Boost.AFIO%20Build/CPPSTD=c++11,CXX=clang++-3.3,LINKTYPE=static,label=linux-gcc-clang/badge/icon"/> + </imageobject> + </mediaobject> + </ulink> + <ulink url="https://ci.nedprod.com/job/Boost.AFIO%20Build/CPPSTD=c++11,CXX=clang++-3.3,LINKTYPE=shared,label=linux-gcc-clang/"> + <mediaobject> + <imageobject> + <imagedata fileref="https://ci.nedprod.com/job/Boost.AFIO%20Build/CPPSTD=c++11,CXX=clang++-3.3,LINKTYPE=shared,label=linux-gcc-clang/badge/icon"/> + </imageobject> + </mediaobject> + </ulink> + <ulink url="https://ci.nedprod.com/job/Boost.AFIO%20Build/CPPSTD=c++11,CXX=clang++-3.3,LINKTYPE=standalone,label=linux-gcc-clang/"> + <mediaobject> + <imageobject> + <imagedata fileref="https://ci.nedprod.com/job/Boost.AFIO%20Build/CPPSTD=c++11,CXX=clang++-3.3,LINKTYPE=standalone,label=linux-gcc-clang/badge/icon"/> + </imageobject> + </mediaobject> + </ulink> + </entry> + <entry> + <ulink url="https://ci.nedprod.com/job/Boost.AFIO%20Test/CPPSTD=c++11,CXX=clang++-3.3,LINKTYPE=static,label=linux-gcc-clang/"> + <mediaobject> + <imageobject> + <imagedata fileref="https://ci.nedprod.com/job/Boost.AFIO%20Test/CPPSTD=c++11,CXX=clang++-3.3,LINKTYPE=static,label=linux-gcc-clang/badge/icon"/> + </imageobject> + </mediaobject> + </ulink> + <ulink url="https://ci.nedprod.com/job/Boost.AFIO%20Test/CPPSTD=c++11,CXX=clang++-3.3,LINKTYPE=shared,label=linux-gcc-clang/"> + <mediaobject> + <imageobject> + <imagedata fileref="https://ci.nedprod.com/job/Boost.AFIO%20Test/CPPSTD=c++11,CXX=clang++-3.3,LINKTYPE=shared,label=linux-gcc-clang/badge/icon"/> + </imageobject> + </mediaobject> + </ulink> + <ulink url="https://ci.nedprod.com/job/Boost.AFIO%20Test/CPPSTD=c++11,CXX=clang++-3.3,LINKTYPE=standalone,label=linux-gcc-clang/"> + <mediaobject> + <imageobject> + <imagedata fileref="https://ci.nedprod.com/job/Boost.AFIO%20Test/CPPSTD=c++11,CXX=clang++-3.3,LINKTYPE=standalone,label=linux-gcc-clang/badge/icon"/> + </imageobject> + </mediaobject> + </ulink> + </entry> + </row> + <row> + <entry>clang 3.4</entry> + <entry>libstdc++ 4.8</entry> + <entry>x86</entry> + <entry> + <ulink url="https://ci.nedprod.com/job/Boost.AFIO%20Build/CPPSTD=c++11,CXX=clang++-3.4,LINKTYPE=static,label=linux-gcc-clang/"> + <mediaobject> + <imageobject> + <imagedata fileref="https://ci.nedprod.com/job/Boost.AFIO%20Build/CPPSTD=c++11,CXX=clang++-3.4,LINKTYPE=static,label=linux-gcc-clang/badge/icon"/> + </imageobject> + </mediaobject> + </ulink> + <ulink url="https://ci.nedprod.com/job/Boost.AFIO%20Build/CPPSTD=c++11,CXX=clang++-3.4,LINKTYPE=shared,label=linux-gcc-clang/"> + <mediaobject> + <imageobject> + <imagedata fileref="https://ci.nedprod.com/job/Boost.AFIO%20Build/CPPSTD=c++11,CXX=clang++-3.4,LINKTYPE=shared,label=linux-gcc-clang/badge/icon"/> + </imageobject> + </mediaobject> + </ulink> + <ulink url="https://ci.nedprod.com/job/Boost.AFIO%20Build/CPPSTD=c++11,CXX=clang++-3.4,LINKTYPE=standalone,label=linux-gcc-clang/"> + <mediaobject> + <imageobject> + <imagedata fileref="https://ci.nedprod.com/job/Boost.AFIO%20Build/CPPSTD=c++11,CXX=clang++-3.4,LINKTYPE=standalone,label=linux-gcc-clang/badge/icon"/> + </imageobject> + </mediaobject> + </ulink> + </entry> + <entry> + <ulink url="https://ci.nedprod.com/job/Boost.AFIO%20Test/CPPSTD=c++11,CXX=clang++-3.4,LINKTYPE=static,label=linux-gcc-clang/"> + <mediaobject> + <imageobject> + <imagedata fileref="https://ci.nedprod.com/job/Boost.AFIO%20Test/CPPSTD=c++11,CXX=clang++-3.4,LINKTYPE=static,label=linux-gcc-clang/badge/icon"/> + </imageobject> + </mediaobject> + </ulink> + <ulink url="https://ci.nedprod.com/job/Boost.AFIO%20Test/CPPSTD=c++11,CXX=clang++-3.4,LINKTYPE=shared,label=linux-gcc-clang/"> + <mediaobject> + <imageobject> + <imagedata fileref="https://ci.nedprod.com/job/Boost.AFIO%20Test/CPPSTD=c++11,CXX=clang++-3.4,LINKTYPE=shared,label=linux-gcc-clang/badge/icon"/> + </imageobject> + </mediaobject> + </ulink> + <ulink url="https://ci.nedprod.com/job/Boost.AFIO%20Test/CPPSTD=c++11,CXX=clang++-3.4,LINKTYPE=standalone,label=linux-gcc-clang/"> + <mediaobject> + <imageobject> + <imagedata fileref="https://ci.nedprod.com/job/Boost.AFIO%20Test/CPPSTD=c++11,CXX=clang++-3.4,LINKTYPE=standalone,label=linux-gcc-clang/badge/icon"/> + </imageobject> + </mediaobject> + </ulink> + </entry> + </row> + <row> + <entry morerows="7">Ubuntu Linux 14.04 LTS</entry> + <entry>clang 3.5</entry> + <entry>libstdc++ 4.9</entry> + <entry>x64</entry> + <entry> + <ulink url="https://ci.nedprod.com/job/Boost.AFIO%20Build/CPPSTD=c++11,CXX=clang++-3.5,LINKTYPE=static,label=linux64-gcc-clang/"> + <mediaobject> + <imageobject> + <imagedata fileref="https://ci.nedprod.com/job/Boost.AFIO%20Build/CPPSTD=c++11,CXX=clang++-3.5,LINKTYPE=static,label=linux64-gcc-clang/badge/icon"/> + </imageobject> + </mediaobject> + </ulink> + <ulink url="https://ci.nedprod.com/job/Boost.AFIO%20Build/CPPSTD=c++11,CXX=clang++-3.5,LINKTYPE=shared,label=linux64-gcc-clang/"> + <mediaobject> + <imageobject> + <imagedata fileref="https://ci.nedprod.com/job/Boost.AFIO%20Build/CPPSTD=c++11,CXX=clang++-3.5,LINKTYPE=shared,label=linux64-gcc-clang/badge/icon"/> + </imageobject> + </mediaobject> + </ulink> + <ulink url="https://ci.nedprod.com/job/Boost.AFIO%20Build/CPPSTD=c++11,CXX=clang++-3.5,LINKTYPE=standalone,label=linux64-gcc-clang/"> + <mediaobject> + <imageobject> + <imagedata fileref="https://ci.nedprod.com/job/Boost.AFIO%20Build/CPPSTD=c++11,CXX=clang++-3.5,LINKTYPE=standalone,label=linux64-gcc-clang/badge/icon"/> + </imageobject> + </mediaobject> + </ulink> + </entry> + <entry> + <ulink url="https://ci.nedprod.com/job/Boost.AFIO%20Test/CPPSTD=c++11,CXX=clang++-3.5,LINKTYPE=static,label=linux64-gcc-clang/"> + <mediaobject> + <imageobject> + <imagedata fileref="https://ci.nedprod.com/job/Boost.AFIO%20Test/CPPSTD=c++11,CXX=clang++-3.5,LINKTYPE=static,label=linux64-gcc-clang/badge/icon"/> + </imageobject> + </mediaobject> + </ulink> + <ulink url="https://ci.nedprod.com/job/Boost.AFIO%20Test/CPPSTD=c++11,CXX=clang++-3.5,LINKTYPE=shared,label=linux64-gcc-clang/"> + <mediaobject> + <imageobject> + <imagedata fileref="https://ci.nedprod.com/job/Boost.AFIO%20Test/CPPSTD=c++11,CXX=clang++-3.5,LINKTYPE=shared,label=linux64-gcc-clang/badge/icon"/> + </imageobject> + </mediaobject> + </ulink> + <ulink url="https://ci.nedprod.com/job/Boost.AFIO%20Test/CPPSTD=c++11,CXX=clang++-3.5,LINKTYPE=standalone,label=linux64-gcc-clang/"> + <mediaobject> + <imageobject> + <imagedata fileref="https://ci.nedprod.com/job/Boost.AFIO%20Test/CPPSTD=c++11,CXX=clang++-3.5,LINKTYPE=standalone,label=linux64-gcc-clang/badge/icon"/> + </imageobject> + </mediaobject> + </ulink> + </entry> + </row> + <row> + <entry>clang 3.5</entry> + <entry>libstdc++ 4.9</entry> + <entry>ARMv7</entry> + <entry> + <ulink url="https://ci.nedprod.com/job/Boost.AFIO%20Build/CPPSTD=c++11,CXX=clang++-3.5,LINKTYPE=static,label=arm-gcc-clang/"> + <mediaobject> + <imageobject> + <imagedata fileref="https://ci.nedprod.com/job/Boost.AFIO%20Build/CPPSTD=c++11,CXX=clang++-3.5,LINKTYPE=static,label=arm-gcc-clang/badge/icon"/> + </imageobject> + </mediaobject> + </ulink> + <ulink url="https://ci.nedprod.com/job/Boost.AFIO%20Build/CPPSTD=c++11,CXX=clang++-3.5,LINKTYPE=shared,label=arm-gcc-clang/"> + <mediaobject> + <imageobject> + <imagedata fileref="https://ci.nedprod.com/job/Boost.AFIO%20Build/CPPSTD=c++11,CXX=clang++-3.5,LINKTYPE=shared,label=arm-gcc-clang/badge/icon"/> + </imageobject> + </mediaobject> + </ulink> + <ulink url="https://ci.nedprod.com/job/Boost.AFIO%20Build/CPPSTD=c++11,CXX=clang++-3.5,LINKTYPE=standalone,label=arm-gcc-clang/"> + <mediaobject> + <imageobject> + <imagedata fileref="https://ci.nedprod.com/job/Boost.AFIO%20Build/CPPSTD=c++11,CXX=clang++-3.5,LINKTYPE=standalone,label=arm-gcc-clang/badge/icon"/> + </imageobject> + </mediaobject> + </ulink> + </entry> + <entry> + <ulink url="https://ci.nedprod.com/job/Boost.AFIO%20Test/CPPSTD=c++11,CXX=clang++-3.5,LINKTYPE=static,label=arm-gcc-clang/"> + <mediaobject> + <imageobject> + <imagedata fileref="https://ci.nedprod.com/job/Boost.AFIO%20Test/CPPSTD=c++11,CXX=clang++-3.5,LINKTYPE=static,label=arm-gcc-clang/badge/icon"/> + </imageobject> + </mediaobject> + </ulink> + <ulink url="https://ci.nedprod.com/job/Boost.AFIO%20Test/CPPSTD=c++11,CXX=clang++-3.5,LINKTYPE=shared,label=arm-gcc-clang/"> + <mediaobject> + <imageobject> + <imagedata fileref="https://ci.nedprod.com/job/Boost.AFIO%20Test/CPPSTD=c++11,CXX=clang++-3.5,LINKTYPE=shared,label=arm-gcc-clang/badge/icon"/> + </imageobject> + </mediaobject> + </ulink> + <ulink url="https://ci.nedprod.com/job/Boost.AFIO%20Test/CPPSTD=c++11,CXX=clang++-3.5,LINKTYPE=standalone,label=arm-gcc-clang/"> + <mediaobject> + <imageobject> + <imagedata fileref="https://ci.nedprod.com/job/Boost.AFIO%20Test/CPPSTD=c++11,CXX=clang++-3.5,LINKTYPE=standalone,label=arm-gcc-clang/badge/icon"/> + </imageobject> + </mediaobject> + </ulink> + </entry> + </row> + <row> + <entry>clang 3.6</entry> + <entry>libstdc++ 4.9</entry> + <entry>x64</entry> + <entry> + <ulink url="https://ci.nedprod.com/job/Boost.AFIO%20Build/CPPSTD=c++11,CXX=clang++-3.6,LINKTYPE=static,label=linux64-gcc-clang/"> + <mediaobject> + <imageobject> + <imagedata fileref="https://ci.nedprod.com/job/Boost.AFIO%20Build/CPPSTD=c++11,CXX=clang++-3.6,LINKTYPE=static,label=linux64-gcc-clang/badge/icon"/> + </imageobject> + </mediaobject> + </ulink> + <ulink url="https://ci.nedprod.com/job/Boost.AFIO%20Build/CPPSTD=c++11,CXX=clang++-3.6,LINKTYPE=shared,label=linux64-gcc-clang/"> + <mediaobject> + <imageobject> + <imagedata fileref="https://ci.nedprod.com/job/Boost.AFIO%20Build/CPPSTD=c++11,CXX=clang++-3.6,LINKTYPE=shared,label=linux64-gcc-clang/badge/icon"/> + </imageobject> + </mediaobject> + </ulink> + <ulink url="https://ci.nedprod.com/job/Boost.AFIO%20Build/CPPSTD=c++11,CXX=clang++-3.6,LINKTYPE=standalone,label=linux64-gcc-clang/"> + <mediaobject> + <imageobject> + <imagedata fileref="https://ci.nedprod.com/job/Boost.AFIO%20Build/CPPSTD=c++11,CXX=clang++-3.6,LINKTYPE=standalone,label=linux64-gcc-clang/badge/icon"/> + </imageobject> + </mediaobject> + </ulink> + <ulink url="https://ci.nedprod.com/job/Boost.AFIO%20Build/CPPSTD=c++14,CXX=clang++-3.6,LINKTYPE=static,label=linux64-gcc-clang/"> + <mediaobject> + <imageobject> + <imagedata fileref="https://ci.nedprod.com/job/Boost.AFIO%20Build/CPPSTD=c++14,CXX=clang++-3.6,LINKTYPE=static,label=linux64-gcc-clang/badge/icon"/> + </imageobject> + </mediaobject> + </ulink> + <ulink url="https://ci.nedprod.com/job/Boost.AFIO%20Build/CPPSTD=c++14,CXX=clang++-3.6,LINKTYPE=shared,label=linux64-gcc-clang/"> + <mediaobject> + <imageobject> + <imagedata fileref="https://ci.nedprod.com/job/Boost.AFIO%20Build/CPPSTD=c++14,CXX=clang++-3.6,LINKTYPE=shared,label=linux64-gcc-clang/badge/icon"/> + </imageobject> + </mediaobject> + </ulink> + <ulink url="https://ci.nedprod.com/job/Boost.AFIO%20Build/CPPSTD=c++14,CXX=clang++-3.6,LINKTYPE=standalone,label=linux64-gcc-clang/"> + <mediaobject> + <imageobject> + <imagedata fileref="https://ci.nedprod.com/job/Boost.AFIO%20Build/CPPSTD=c++14,CXX=clang++-3.6,LINKTYPE=standalone,label=linux64-gcc-clang/badge/icon"/> + </imageobject> + </mediaobject> + </ulink> + </entry> + <entry> + <ulink url="https://ci.nedprod.com/job/Boost.AFIO%20Test/CPPSTD=c++11,CXX=clang++-3.6,LINKTYPE=static,label=linux64-gcc-clang/"> + <mediaobject> + <imageobject> + <imagedata fileref="https://ci.nedprod.com/job/Boost.AFIO%20Test/CPPSTD=c++11,CXX=clang++-3.6,LINKTYPE=static,label=linux64-gcc-clang/badge/icon"/> + </imageobject> + </mediaobject> + </ulink> + <ulink url="https://ci.nedprod.com/job/Boost.AFIO%20Test/CPPSTD=c++11,CXX=clang++-3.6,LINKTYPE=shared,label=linux64-gcc-clang/"> + <mediaobject> + <imageobject> + <imagedata fileref="https://ci.nedprod.com/job/Boost.AFIO%20Test/CPPSTD=c++11,CXX=clang++-3.6,LINKTYPE=shared,label=linux64-gcc-clang/badge/icon"/> + </imageobject> + </mediaobject> + </ulink> + <ulink url="https://ci.nedprod.com/job/Boost.AFIO%20Test/CPPSTD=c++11,CXX=clang++-3.6,LINKTYPE=standalone,label=linux64-gcc-clang/"> + <mediaobject> + <imageobject> + <imagedata fileref="https://ci.nedprod.com/job/Boost.AFIO%20Test/CPPSTD=c++11,CXX=clang++-3.6,LINKTYPE=standalone,label=linux64-gcc-clang/badge/icon"/> + </imageobject> + </mediaobject> + </ulink> + <ulink url="https://ci.nedprod.com/job/Boost.AFIO%20Test/CPPSTD=c++14,CXX=clang++-3.6,LINKTYPE=static,label=linux64-gcc-clang/"> + <mediaobject> + <imageobject> + <imagedata fileref="https://ci.nedprod.com/job/Boost.AFIO%20Test/CPPSTD=c++14,CXX=clang++-3.6,LINKTYPE=static,label=linux64-gcc-clang/badge/icon"/> + </imageobject> + </mediaobject> + </ulink> + <ulink url="https://ci.nedprod.com/job/Boost.AFIO%20Test/CPPSTD=c++14,CXX=clang++-3.6,LINKTYPE=shared,label=linux64-gcc-clang/"> + <mediaobject> + <imageobject> + <imagedata fileref="https://ci.nedprod.com/job/Boost.AFIO%20Test/CPPSTD=c++14,CXX=clang++-3.6,LINKTYPE=shared,label=linux64-gcc-clang/badge/icon"/> + </imageobject> + </mediaobject> + </ulink> + <ulink url="https://ci.nedprod.com/job/Boost.AFIO%20Test/CPPSTD=c++14,CXX=clang++-3.6,LINKTYPE=standalone,label=linux64-gcc-clang/"> + <mediaobject> + <imageobject> + <imagedata fileref="https://ci.nedprod.com/job/Boost.AFIO%20Test/CPPSTD=c++14,CXX=clang++-3.6,LINKTYPE=standalone,label=linux64-gcc-clang/badge/icon"/> + </imageobject> + </mediaobject> + </ulink> + </entry> + </row> + <row> + <entry>clang 3.7</entry> + <entry>libstdc++ 4.9</entry> + <entry>x64</entry> + <entry> + <ulink url="https://ci.nedprod.com/job/Boost.AFIO%20Build/CPPSTD=c++11,CXX=clang++-3.7,LINKTYPE=static,label=linux64-gcc-clang/"> + <mediaobject> + <imageobject> + <imagedata fileref="https://ci.nedprod.com/job/Boost.AFIO%20Build/CPPSTD=c++11,CXX=clang++-3.7,LINKTYPE=static,label=linux64-gcc-clang/badge/icon"/> + </imageobject> + </mediaobject> + </ulink> + <ulink url="https://ci.nedprod.com/job/Boost.AFIO%20Build/CPPSTD=c++11,CXX=clang++-3.7,LINKTYPE=shared,label=linux64-gcc-clang/"> + <mediaobject> + <imageobject> + <imagedata fileref="https://ci.nedprod.com/job/Boost.AFIO%20Build/CPPSTD=c++11,CXX=clang++-3.7,LINKTYPE=shared,label=linux64-gcc-clang/badge/icon"/> + </imageobject> + </mediaobject> + </ulink> + <ulink url="https://ci.nedprod.com/job/Boost.AFIO%20Build/CPPSTD=c++11,CXX=clang++-3.7,LINKTYPE=standalone,label=linux64-gcc-clang/"> + <mediaobject> + <imageobject> + <imagedata fileref="https://ci.nedprod.com/job/Boost.AFIO%20Build/CPPSTD=c++11,CXX=clang++-3.7,LINKTYPE=standalone,label=linux64-gcc-clang/badge/icon"/> + </imageobject> + </mediaobject> + </ulink> + <ulink url="https://ci.nedprod.com/job/Boost.AFIO%20Build/CPPSTD=c++14,CXX=clang++-3.7,LINKTYPE=static,label=linux64-gcc-clang/"> + <mediaobject> + <imageobject> + <imagedata fileref="https://ci.nedprod.com/job/Boost.AFIO%20Build/CPPSTD=c++14,CXX=clang++-3.7,LINKTYPE=static,label=linux64-gcc-clang/badge/icon"/> + </imageobject> + </mediaobject> + </ulink> + <ulink url="https://ci.nedprod.com/job/Boost.AFIO%20Build/CPPSTD=c++14,CXX=clang++-3.7,LINKTYPE=shared,label=linux64-gcc-clang/"> + <mediaobject> + <imageobject> + <imagedata fileref="https://ci.nedprod.com/job/Boost.AFIO%20Build/CPPSTD=c++14,CXX=clang++-3.7,LINKTYPE=shared,label=linux64-gcc-clang/badge/icon"/> + </imageobject> + </mediaobject> + </ulink> + <ulink url="https://ci.nedprod.com/job/Boost.AFIO%20Build/CPPSTD=c++14,CXX=clang++-3.7,LINKTYPE=standalone,label=linux64-gcc-clang/"> + <mediaobject> + <imageobject> + <imagedata fileref="https://ci.nedprod.com/job/Boost.AFIO%20Build/CPPSTD=c++14,CXX=clang++-3.7,LINKTYPE=standalone,label=linux64-gcc-clang/badge/icon"/> + </imageobject> + </mediaobject> + </ulink> + </entry> + <entry> + <ulink url="https://ci.nedprod.com/job/Boost.AFIO%20Test/CPPSTD=c++11,CXX=clang++-3.7,LINKTYPE=static,label=linux64-gcc-clang/"> + <mediaobject> + <imageobject> + <imagedata fileref="https://ci.nedprod.com/job/Boost.AFIO%20Test/CPPSTD=c++11,CXX=clang++-3.7,LINKTYPE=static,label=linux64-gcc-clang/badge/icon"/> + </imageobject> + </mediaobject> + </ulink> + <ulink url="https://ci.nedprod.com/job/Boost.AFIO%20Test/CPPSTD=c++11,CXX=clang++-3.7,LINKTYPE=shared,label=linux64-gcc-clang/"> + <mediaobject> + <imageobject> + <imagedata fileref="https://ci.nedprod.com/job/Boost.AFIO%20Test/CPPSTD=c++11,CXX=clang++-3.7,LINKTYPE=shared,label=linux64-gcc-clang/badge/icon"/> + </imageobject> + </mediaobject> + </ulink> + <ulink url="https://ci.nedprod.com/job/Boost.AFIO%20Test/CPPSTD=c++11,CXX=clang++-3.7,LINKTYPE=standalone,label=linux64-gcc-clang/"> + <mediaobject> + <imageobject> + <imagedata fileref="https://ci.nedprod.com/job/Boost.AFIO%20Test/CPPSTD=c++11,CXX=clang++-3.7,LINKTYPE=standalone,label=linux64-gcc-clang/badge/icon"/> + </imageobject> + </mediaobject> + </ulink> + <ulink url="https://ci.nedprod.com/job/Boost.AFIO%20Test/CPPSTD=c++14,CXX=clang++-3.7,LINKTYPE=static,label=linux64-gcc-clang/"> + <mediaobject> + <imageobject> + <imagedata fileref="https://ci.nedprod.com/job/Boost.AFIO%20Test/CPPSTD=c++14,CXX=clang++-3.7,LINKTYPE=static,label=linux64-gcc-clang/badge/icon"/> + </imageobject> + </mediaobject> + </ulink> + <ulink url="https://ci.nedprod.com/job/Boost.AFIO%20Test/CPPSTD=c++14,CXX=clang++-3.7,LINKTYPE=shared,label=linux64-gcc-clang/"> + <mediaobject> + <imageobject> + <imagedata fileref="https://ci.nedprod.com/job/Boost.AFIO%20Test/CPPSTD=c++14,CXX=clang++-3.7,LINKTYPE=shared,label=linux64-gcc-clang/badge/icon"/> + </imageobject> + </mediaobject> + </ulink> + <ulink url="https://ci.nedprod.com/job/Boost.AFIO%20Test/CPPSTD=c++14,CXX=clang++-3.7,LINKTYPE=standalone,label=linux64-gcc-clang/"> + <mediaobject> + <imageobject> + <imagedata fileref="https://ci.nedprod.com/job/Boost.AFIO%20Test/CPPSTD=c++14,CXX=clang++-3.7,LINKTYPE=standalone,label=linux64-gcc-clang/badge/icon"/> + </imageobject> + </mediaobject> + </ulink> + </entry> + </row> + <row> + <entry>GCC 4.8</entry> + <entry>libstdc++ 4.8</entry> + <entry>x64</entry> + <entry> + <ulink url="https://ci.nedprod.com/job/Boost.AFIO%20Build/CPPSTD=c++11,CXX=g++-4.8,LINKTYPE=static,label=linux64-gcc-clang/"> + <mediaobject> + <imageobject> + <imagedata fileref="https://ci.nedprod.com/job/Boost.AFIO%20Build/CPPSTD=c++11,CXX=g++-4.8,LINKTYPE=static,label=linux64-gcc-clang/badge/icon"/> + </imageobject> + </mediaobject> + </ulink> + <ulink url="https://ci.nedprod.com/job/Boost.AFIO%20Build/CPPSTD=c++11,CXX=g++-4.8,LINKTYPE=shared,label=linux64-gcc-clang/"> + <mediaobject> + <imageobject> + <imagedata fileref="https://ci.nedprod.com/job/Boost.AFIO%20Build/CPPSTD=c++11,CXX=g++-4.8,LINKTYPE=shared,label=linux64-gcc-clang/badge/icon"/> + </imageobject> + </mediaobject> + </ulink> + <ulink url="https://ci.nedprod.com/job/Boost.AFIO%20Build/CPPSTD=c++11,CXX=g++-4.8,LINKTYPE=standalone,label=linux64-gcc-clang/"> + <mediaobject> + <imageobject> + <imagedata fileref="https://ci.nedprod.com/job/Boost.AFIO%20Build/CPPSTD=c++11,CXX=g++-4.8,LINKTYPE=standalone,label=linux64-gcc-clang/badge/icon"/> + </imageobject> + </mediaobject> + </ulink> + </entry> + <entry> + <ulink url="https://ci.nedprod.com/job/Boost.AFIO%20Test/CPPSTD=c++11,CXX=g++-4.8,LINKTYPE=static,label=linux64-gcc-clang/"> + <mediaobject> + <imageobject> + <imagedata fileref="https://ci.nedprod.com/job/Boost.AFIO%20Test/CPPSTD=c++11,CXX=g++-4.8,LINKTYPE=static,label=linux64-gcc-clang/badge/icon"/> + </imageobject> + </mediaobject> + </ulink> + <ulink url="https://ci.nedprod.com/job/Boost.AFIO%20Test/CPPSTD=c++11,CXX=g++-4.8,LINKTYPE=shared,label=linux64-gcc-clang/"> + <mediaobject> + <imageobject> + <imagedata fileref="https://ci.nedprod.com/job/Boost.AFIO%20Test/CPPSTD=c++11,CXX=g++-4.8,LINKTYPE=shared,label=linux64-gcc-clang/badge/icon"/> + </imageobject> + </mediaobject> + </ulink> + <ulink url="https://ci.nedprod.com/job/Boost.AFIO%20Test/CPPSTD=c++11,CXX=g++-4.8,LINKTYPE=standalone,label=linux64-gcc-clang/"> + <mediaobject> + <imageobject> + <imagedata fileref="https://ci.nedprod.com/job/Boost.AFIO%20Test/CPPSTD=c++11,CXX=g++-4.8,LINKTYPE=standalone,label=linux64-gcc-clang/badge/icon"/> + </imageobject> + </mediaobject> + </ulink> + </entry> + </row> + <row> + <entry>GCC 4.9</entry> + <entry>libstdc++ 4.9</entry> + <entry>x64</entry> + <entry> + <ulink url="https://ci.nedprod.com/job/Boost.AFIO%20Build/CPPSTD=c++11,CXX=g++-4.9,LINKTYPE=static,label=linux64-gcc-clang/"> + <mediaobject> + <imageobject> + <imagedata fileref="https://ci.nedprod.com/job/Boost.AFIO%20Build/CPPSTD=c++11,CXX=g++-4.9,LINKTYPE=static,label=linux64-gcc-clang/badge/icon"/> + </imageobject> + </mediaobject> + </ulink> + <ulink url="https://ci.nedprod.com/job/Boost.AFIO%20Build/CPPSTD=c++11,CXX=g++-4.9,LINKTYPE=shared,label=linux64-gcc-clang/"> + <mediaobject> + <imageobject> + <imagedata fileref="https://ci.nedprod.com/job/Boost.AFIO%20Build/CPPSTD=c++11,CXX=g++-4.9,LINKTYPE=shared,label=linux64-gcc-clang/badge/icon"/> + </imageobject> + </mediaobject> + </ulink> + <ulink url="https://ci.nedprod.com/job/Boost.AFIO%20Build/CPPSTD=c++11,CXX=g++-4.9,LINKTYPE=standalone,label=linux64-gcc-clang/"> + <mediaobject> + <imageobject> + <imagedata fileref="https://ci.nedprod.com/job/Boost.AFIO%20Build/CPPSTD=c++11,CXX=g++-4.9,LINKTYPE=standalone,label=linux64-gcc-clang/badge/icon"/> + </imageobject> + </mediaobject> + </ulink> + <ulink url="https://ci.nedprod.com/job/Boost.AFIO%20Build/CPPSTD=c++14,CXX=g++-4.9,LINKTYPE=static,label=linux64-gcc-clang/"> + <mediaobject> + <imageobject> + <imagedata fileref="https://ci.nedprod.com/job/Boost.AFIO%20Build/CPPSTD=c++14,CXX=g++-4.9,LINKTYPE=static,label=linux64-gcc-clang/badge/icon"/> + </imageobject> + </mediaobject> + </ulink> + <ulink url="https://ci.nedprod.com/job/Boost.AFIO%20Build/CPPSTD=c++14,CXX=g++-4.9,LINKTYPE=shared,label=linux64-gcc-clang/"> + <mediaobject> + <imageobject> + <imagedata fileref="https://ci.nedprod.com/job/Boost.AFIO%20Build/CPPSTD=c++14,CXX=g++-4.9,LINKTYPE=shared,label=linux64-gcc-clang/badge/icon"/> + </imageobject> + </mediaobject> + </ulink> + <ulink url="https://ci.nedprod.com/job/Boost.AFIO%20Build/CPPSTD=c++14,CXX=g++-4.9,LINKTYPE=standalone,label=linux64-gcc-clang/"> + <mediaobject> + <imageobject> + <imagedata fileref="https://ci.nedprod.com/job/Boost.AFIO%20Build/CPPSTD=c++14,CXX=g++-4.9,LINKTYPE=standalone,label=linux64-gcc-clang/badge/icon"/> + </imageobject> + </mediaobject> + </ulink> + </entry> + <entry> + <ulink url="https://ci.nedprod.com/job/Boost.AFIO%20Test/CPPSTD=c++11,CXX=g++-4.9,LINKTYPE=static,label=linux64-gcc-clang/"> + <mediaobject> + <imageobject> + <imagedata fileref="https://ci.nedprod.com/job/Boost.AFIO%20Test/CPPSTD=c++11,CXX=g++-4.9,LINKTYPE=static,label=linux64-gcc-clang/badge/icon"/> + </imageobject> + </mediaobject> + </ulink> + <ulink url="https://ci.nedprod.com/job/Boost.AFIO%20Test/CPPSTD=c++11,CXX=g++-4.9,LINKTYPE=shared,label=linux64-gcc-clang/"> + <mediaobject> + <imageobject> + <imagedata fileref="https://ci.nedprod.com/job/Boost.AFIO%20Test/CPPSTD=c++11,CXX=g++-4.9,LINKTYPE=shared,label=linux64-gcc-clang/badge/icon"/> + </imageobject> + </mediaobject> + </ulink> + <ulink url="https://ci.nedprod.com/job/Boost.AFIO%20Test/CPPSTD=c++11,CXX=g++-4.9,LINKTYPE=standalone,label=linux64-gcc-clang/"> + <mediaobject> + <imageobject> + <imagedata fileref="https://ci.nedprod.com/job/Boost.AFIO%20Test/CPPSTD=c++11,CXX=g++-4.9,LINKTYPE=standalone,label=linux64-gcc-clang/badge/icon"/> + </imageobject> + </mediaobject> + </ulink> + <ulink url="https://ci.nedprod.com/job/Boost.AFIO%20Test/CPPSTD=c++14,CXX=g++-4.9,LINKTYPE=static,label=linux64-gcc-clang/"> + <mediaobject> + <imageobject> + <imagedata fileref="https://ci.nedprod.com/job/Boost.AFIO%20Test/CPPSTD=c++14,CXX=g++-4.9,LINKTYPE=static,label=linux64-gcc-clang/badge/icon"/> + </imageobject> + </mediaobject> + </ulink> + <ulink url="https://ci.nedprod.com/job/Boost.AFIO%20Test/CPPSTD=c++14,CXX=g++-4.9,LINKTYPE=shared,label=linux64-gcc-clang/"> + <mediaobject> + <imageobject> + <imagedata fileref="https://ci.nedprod.com/job/Boost.AFIO%20Test/CPPSTD=c++14,CXX=g++-4.9,LINKTYPE=shared,label=linux64-gcc-clang/badge/icon"/> + </imageobject> + </mediaobject> + </ulink> + <ulink url="https://ci.nedprod.com/job/Boost.AFIO%20Test/CPPSTD=c++14,CXX=g++-4.9,LINKTYPE=standalone,label=linux64-gcc-clang/"> + <mediaobject> + <imageobject> + <imagedata fileref="https://ci.nedprod.com/job/Boost.AFIO%20Test/CPPSTD=c++14,CXX=g++-4.9,LINKTYPE=standalone,label=linux64-gcc-clang/badge/icon"/> + </imageobject> + </mediaobject> + </ulink> + </entry> + </row> + <row> + <entry>GCC 4.9</entry> + <entry>libstdc++ 4.9</entry> + <entry>ARMv7</entry> + <entry> + <ulink url="https://ci.nedprod.com/job/Boost.AFIO%20Build/CPPSTD=c++11,CXX=g++-4.9,LINKTYPE=static,label=arm-gcc-clang/"> + <mediaobject> + <imageobject> + <imagedata fileref="https://ci.nedprod.com/job/Boost.AFIO%20Build/CPPSTD=c++11,CXX=g++-4.9,LINKTYPE=static,label=arm-gcc-clang/badge/icon"/> + </imageobject> + </mediaobject> + </ulink> + <ulink url="https://ci.nedprod.com/job/Boost.AFIO%20Build/CPPSTD=c++11,CXX=g++-4.9,LINKTYPE=shared,label=arm-gcc-clang/"> + <mediaobject> + <imageobject> + <imagedata fileref="https://ci.nedprod.com/job/Boost.AFIO%20Build/CPPSTD=c++11,CXX=g++-4.9,LINKTYPE=shared,label=arm-gcc-clang/badge/icon"/> + </imageobject> + </mediaobject> + </ulink> + <ulink url="https://ci.nedprod.com/job/Boost.AFIO%20Build/CPPSTD=c++11,CXX=g++-4.9,LINKTYPE=standalone,label=arm-gcc-clang/"> + <mediaobject> + <imageobject> + <imagedata fileref="https://ci.nedprod.com/job/Boost.AFIO%20Build/CPPSTD=c++11,CXX=g++-4.9,LINKTYPE=standalone,label=arm-gcc-clang/badge/icon"/> + </imageobject> + </mediaobject> + </ulink> + <ulink url="https://ci.nedprod.com/job/Boost.AFIO%20Build/CPPSTD=c++14,CXX=g++-4.9,LINKTYPE=static,label=arm-gcc-clang/"> + <mediaobject> + <imageobject> + <imagedata fileref="https://ci.nedprod.com/job/Boost.AFIO%20Build/CPPSTD=c++14,CXX=g++-4.9,LINKTYPE=static,label=arm-gcc-clang/badge/icon"/> + </imageobject> + </mediaobject> + </ulink> + <ulink url="https://ci.nedprod.com/job/Boost.AFIO%20Build/CPPSTD=c++14,CXX=g++-4.9,LINKTYPE=shared,label=arm-gcc-clang/"> + <mediaobject> + <imageobject> + <imagedata fileref="https://ci.nedprod.com/job/Boost.AFIO%20Build/CPPSTD=c++14,CXX=g++-4.9,LINKTYPE=shared,label=arm-gcc-clang/badge/icon"/> + </imageobject> + </mediaobject> + </ulink> + <ulink url="https://ci.nedprod.com/job/Boost.AFIO%20Build/CPPSTD=c++14,CXX=g++-4.9,LINKTYPE=standalone,label=arm-gcc-clang/"> + <mediaobject> + <imageobject> + <imagedata fileref="https://ci.nedprod.com/job/Boost.AFIO%20Build/CPPSTD=c++14,CXX=g++-4.9,LINKTYPE=standalone,label=arm-gcc-clang/badge/icon"/> + </imageobject> + </mediaobject> + </ulink> + </entry> + <entry> + <ulink url="https://ci.nedprod.com/job/Boost.AFIO%20Test/CPPSTD=c++11,CXX=g++-4.9,LINKTYPE=static,label=arm-gcc-clang/"> + <mediaobject> + <imageobject> + <imagedata fileref="https://ci.nedprod.com/job/Boost.AFIO%20Test/CPPSTD=c++11,CXX=g++-4.9,LINKTYPE=static,label=arm-gcc-clang/badge/icon"/> + </imageobject> + </mediaobject> + </ulink> + <ulink url="https://ci.nedprod.com/job/Boost.AFIO%20Test/CPPSTD=c++11,CXX=g++-4.9,LINKTYPE=shared,label=arm-gcc-clang/"> + <mediaobject> + <imageobject> + <imagedata fileref="https://ci.nedprod.com/job/Boost.AFIO%20Test/CPPSTD=c++11,CXX=g++-4.9,LINKTYPE=shared,label=arm-gcc-clang/badge/icon"/> + </imageobject> + </mediaobject> + </ulink> + <ulink url="https://ci.nedprod.com/job/Boost.AFIO%20Test/CPPSTD=c++11,CXX=g++-4.9,LINKTYPE=standalone,label=arm-gcc-clang/"> + <mediaobject> + <imageobject> + <imagedata fileref="https://ci.nedprod.com/job/Boost.AFIO%20Test/CPPSTD=c++11,CXX=g++-4.9,LINKTYPE=standalone,label=arm-gcc-clang/badge/icon"/> + </imageobject> + </mediaobject> + </ulink> + <ulink url="https://ci.nedprod.com/job/Boost.AFIO%20Test/CPPSTD=c++14,CXX=g++-4.9,LINKTYPE=static,label=arm-gcc-clang/"> + <mediaobject> + <imageobject> + <imagedata fileref="https://ci.nedprod.com/job/Boost.AFIO%20Test/CPPSTD=c++14,CXX=g++-4.9,LINKTYPE=static,label=arm-gcc-clang/badge/icon"/> + </imageobject> + </mediaobject> + </ulink> + <ulink url="https://ci.nedprod.com/job/Boost.AFIO%20Test/CPPSTD=c++14,CXX=g++-4.9,LINKTYPE=shared,label=arm-gcc-clang/"> + <mediaobject> + <imageobject> + <imagedata fileref="https://ci.nedprod.com/job/Boost.AFIO%20Test/CPPSTD=c++14,CXX=g++-4.9,LINKTYPE=shared,label=arm-gcc-clang/badge/icon"/> + </imageobject> + </mediaobject> + </ulink> + <ulink url="https://ci.nedprod.com/job/Boost.AFIO%20Test/CPPSTD=c++14,CXX=g++-4.9,LINKTYPE=standalone,label=arm-gcc-clang/"> + <mediaobject> + <imageobject> + <imagedata fileref="https://ci.nedprod.com/job/Boost.AFIO%20Test/CPPSTD=c++14,CXX=g++-4.9,LINKTYPE=standalone,label=arm-gcc-clang/badge/icon"/> + </imageobject> + </mediaobject> + </ulink> + </entry> + </row> + <row> + <entry>GCC 5.1</entry> + <entry>libstdc++ 5.1</entry> + <entry>x64</entry> + <entry> + <ulink url="https://ci.nedprod.com/job/Boost.AFIO%20Build/CPPSTD=c++11,CXX=g++-5,LINKTYPE=static,label=linux64-gcc-clang/"> + <mediaobject> + <imageobject> + <imagedata fileref="https://ci.nedprod.com/job/Boost.AFIO%20Build/CPPSTD=c++11,CXX=g++-5,LINKTYPE=static,label=linux64-gcc-clang/badge/icon"/> + </imageobject> + </mediaobject> + </ulink> + <ulink url="https://ci.nedprod.com/job/Boost.AFIO%20Build/CPPSTD=c++11,CXX=g++-5,LINKTYPE=shared,label=linux64-gcc-clang/"> + <mediaobject> + <imageobject> + <imagedata fileref="https://ci.nedprod.com/job/Boost.AFIO%20Build/CPPSTD=c++11,CXX=g++-5,LINKTYPE=shared,label=linux64-gcc-clang/badge/icon"/> + </imageobject> + </mediaobject> + </ulink> + <ulink url="https://ci.nedprod.com/job/Boost.AFIO%20Build/CPPSTD=c++11,CXX=g++-5,LINKTYPE=standalone,label=linux64-gcc-clang/"> + <mediaobject> + <imageobject> + <imagedata fileref="https://ci.nedprod.com/job/Boost.AFIO%20Build/CPPSTD=c++11,CXX=g++-5,LINKTYPE=standalone,label=linux64-gcc-clang/badge/icon"/> + </imageobject> + </mediaobject> + </ulink> + <ulink url="https://ci.nedprod.com/job/Boost.AFIO%20Build/CPPSTD=c++14,CXX=g++-5,LINKTYPE=static,label=linux64-gcc-clang/"> + <mediaobject> + <imageobject> + <imagedata fileref="https://ci.nedprod.com/job/Boost.AFIO%20Build/CPPSTD=c++14,CXX=g++-5,LINKTYPE=static,label=linux64-gcc-clang/badge/icon"/> + </imageobject> + </mediaobject> + </ulink> + <ulink url="https://ci.nedprod.com/job/Boost.AFIO%20Build/CPPSTD=c++14,CXX=g++-5,LINKTYPE=shared,label=linux64-gcc-clang/"> + <mediaobject> + <imageobject> + <imagedata fileref="https://ci.nedprod.com/job/Boost.AFIO%20Build/CPPSTD=c++14,CXX=g++-5,LINKTYPE=shared,label=linux64-gcc-clang/badge/icon"/> + </imageobject> + </mediaobject> + </ulink> + <ulink url="https://ci.nedprod.com/job/Boost.AFIO%20Build/CPPSTD=c++14,CXX=g++-5,LINKTYPE=standalone,label=linux64-gcc-clang/"> + <mediaobject> + <imageobject> + <imagedata fileref="https://ci.nedprod.com/job/Boost.AFIO%20Build/CPPSTD=c++14,CXX=g++-5,LINKTYPE=standalone,label=linux64-gcc-clang/badge/icon"/> + </imageobject> + </mediaobject> + </ulink> + </entry> + <entry> + <ulink url="https://ci.nedprod.com/job/Boost.AFIO%20Test/CPPSTD=c++11,CXX=g++-5,LINKTYPE=static,label=linux64-gcc-clang/"> + <mediaobject> + <imageobject> + <imagedata fileref="https://ci.nedprod.com/job/Boost.AFIO%20Test/CPPSTD=c++11,CXX=g++-5,LINKTYPE=static,label=linux64-gcc-clang/badge/icon"/> + </imageobject> + </mediaobject> + </ulink> + <ulink url="https://ci.nedprod.com/job/Boost.AFIO%20Test/CPPSTD=c++11,CXX=g++-5,LINKTYPE=shared,label=linux64-gcc-clang/"> + <mediaobject> + <imageobject> + <imagedata fileref="https://ci.nedprod.com/job/Boost.AFIO%20Test/CPPSTD=c++11,CXX=g++-5,LINKTYPE=shared,label=linux64-gcc-clang/badge/icon"/> + </imageobject> + </mediaobject> + </ulink> + <ulink url="https://ci.nedprod.com/job/Boost.AFIO%20Test/CPPSTD=c++11,CXX=g++-5,LINKTYPE=standalone,label=linux64-gcc-clang/"> + <mediaobject> + <imageobject> + <imagedata fileref="https://ci.nedprod.com/job/Boost.AFIO%20Test/CPPSTD=c++11,CXX=g++-5,LINKTYPE=standalone,label=linux64-gcc-clang/badge/icon"/> + </imageobject> + </mediaobject> + </ulink> + <ulink url="https://ci.nedprod.com/job/Boost.AFIO%20Test/CPPSTD=c++14,CXX=g++-5,LINKTYPE=static,label=linux64-gcc-clang/"> + <mediaobject> + <imageobject> + <imagedata fileref="https://ci.nedprod.com/job/Boost.AFIO%20Test/CPPSTD=c++14,CXX=g++-5,LINKTYPE=static,label=linux64-gcc-clang/badge/icon"/> + </imageobject> + </mediaobject> + </ulink> + <ulink url="https://ci.nedprod.com/job/Boost.AFIO%20Test/CPPSTD=c++14,CXX=g++-5,LINKTYPE=shared,label=linux64-gcc-clang/"> + <mediaobject> + <imageobject> + <imagedata fileref="https://ci.nedprod.com/job/Boost.AFIO%20Test/CPPSTD=c++14,CXX=g++-5,LINKTYPE=shared,label=linux64-gcc-clang/badge/icon"/> + </imageobject> + </mediaobject> + </ulink> + <ulink url="https://ci.nedprod.com/job/Boost.AFIO%20Test/CPPSTD=c++14,CXX=g++-5,LINKTYPE=standalone,label=linux64-gcc-clang/"> + <mediaobject> + <imageobject> + <imagedata fileref="https://ci.nedprod.com/job/Boost.AFIO%20Test/CPPSTD=c++14,CXX=g++-5,LINKTYPE=standalone,label=linux64-gcc-clang/badge/icon"/> + </imageobject> + </mediaobject> + </ulink> + </entry> + </row> + <row> + <entry morerows="2">Microsoft Windows 8.1</entry> + <entry>Mingw-w64 GCC 4.8</entry> + <entry>libstdc++ 4.8</entry> + <entry>x64</entry> + <entry> + <ulink url="https://ci.nedprod.com/job/Boost.AFIO%20Build/CPPSTD=c++11,CXX=mingw64,LINKTYPE=static,label=win8-msvc-mingw/"> + <mediaobject> + <imageobject> + <imagedata fileref="https://ci.nedprod.com/job/Boost.AFIO%20Build/CPPSTD=c++11,CXX=mingw64,LINKTYPE=static,label=win8-msvc-mingw/badge/icon"/> + </imageobject> + </mediaobject> + </ulink> + <ulink url="https://ci.nedprod.com/job/Boost.AFIO%20Build/CPPSTD=c++11,CXX=mingw64,LINKTYPE=shared,label=win8-msvc-mingw/"> + <mediaobject> + <imageobject> + <imagedata fileref="https://ci.nedprod.com/job/Boost.AFIO%20Build/CPPSTD=c++11,CXX=mingw64,LINKTYPE=shared,label=win8-msvc-mingw/badge/icon"/> + </imageobject> + </mediaobject> + </ulink> + </entry> + <entry> + <ulink url="https://ci.nedprod.com/job/Boost.AFIO%20Test/CPPSTD=c++11,CXX=mingw64,LINKTYPE=static,label=win8-msvc-mingw/"> + <mediaobject> + <imageobject> + <imagedata fileref="https://ci.nedprod.com/job/Boost.AFIO%20Test/CPPSTD=c++11,CXX=mingw64,LINKTYPE=static,label=win8-msvc-mingw/badge/icon"/> + </imageobject> + </mediaobject> + </ulink> + <ulink url="https://ci.nedprod.com/job/Boost.AFIO%20Test/CPPSTD=c++11,CXX=mingw64,LINKTYPE=shared,label=win8-msvc-mingw/"> + <mediaobject> + <imageobject> + <imagedata fileref="https://ci.nedprod.com/job/Boost.AFIO%20Test/CPPSTD=c++11,CXX=mingw64,LINKTYPE=shared,label=win8-msvc-mingw/badge/icon"/> + </imageobject> + </mediaobject> + </ulink> + </entry> + </row> + <row> + <entry>Visual Studio 2015</entry> + <entry>Dinkumware</entry> + <entry>x64</entry> + <entry> + <ulink url="https://ci.nedprod.com/job/Boost.AFIO%20Build/CPPSTD=c++14,CXX=msvc-14.0,LINKTYPE=static,label=win8-msvc-mingw/"> + <mediaobject> + <imageobject> + <imagedata fileref="https://ci.nedprod.com/job/Boost.AFIO%20Build/CPPSTD=c++14,CXX=msvc-14.0,LINKTYPE=static,label=win8-msvc-mingw/badge/icon"/> + </imageobject> + </mediaobject> + </ulink> + <ulink url="https://ci.nedprod.com/job/Boost.AFIO%20Build/CPPSTD=c++14,CXX=msvc-14.0,LINKTYPE=shared,label=win8-msvc-mingw/"> + <mediaobject> + <imageobject> + <imagedata fileref="https://ci.nedprod.com/job/Boost.AFIO%20Build/CPPSTD=c++14,CXX=msvc-14.0,LINKTYPE=shared,label=win8-msvc-mingw/badge/icon"/> + </imageobject> + </mediaobject> + </ulink> + <ulink url="https://ci.nedprod.com/job/Boost.AFIO%20Build/CPPSTD=c++14,CXX=msvc-14.0,LINKTYPE=standalone,label=win8-msvc-mingw/"> + <mediaobject> + <imageobject> + <imagedata fileref="https://ci.nedprod.com/job/Boost.AFIO%20Build/CPPSTD=c++14,CXX=msvc-14.0,LINKTYPE=standalone,label=win8-msvc-mingw/badge/icon"/> + </imageobject> + </mediaobject> + </ulink> + </entry> + <entry> + <ulink url="https://ci.nedprod.com/job/Boost.AFIO%20Test/CPPSTD=c++14,CXX=msvc-14.0,LINKTYPE=static,label=win8-msvc-mingw/"> + <mediaobject> + <imageobject> + <imagedata fileref="https://ci.nedprod.com/job/Boost.AFIO%20Test/CPPSTD=c++14,CXX=msvc-14.0,LINKTYPE=static,label=win8-msvc-mingw/badge/icon"/> + </imageobject> + </mediaobject> + </ulink> + <ulink url="https://ci.nedprod.com/job/Boost.AFIO%20Test/CPPSTD=c++14,CXX=msvc-14.0,LINKTYPE=shared,label=win8-msvc-mingw/"> + <mediaobject> + <imageobject> + <imagedata fileref="https://ci.nedprod.com/job/Boost.AFIO%20Test/CPPSTD=c++14,CXX=msvc-14.0,LINKTYPE=shared,label=win8-msvc-mingw/badge/icon"/> + </imageobject> + </mediaobject> + </ulink> + <ulink url="https://ci.nedprod.com/job/Boost.AFIO%20Test/CPPSTD=c++14,CXX=msvc-14.0,LINKTYPE=standalone,label=win8-msvc-mingw/"> + <mediaobject> + <imageobject> + <imagedata fileref="https://ci.nedprod.com/job/Boost.AFIO%20Test/CPPSTD=c++14,CXX=msvc-14.0,LINKTYPE=standalone,label=win8-msvc-mingw/badge/icon"/> + </imageobject> + </mediaobject> + </ulink> + </entry> + </row> + </tbody> + </tgroup> + </informaltable> +''' + + +[heading Boost AFIO Installation into Boost] + +As of v1.3 of the engine, you can simply download [@https://boostgsoc13.github.io/boost.afio/afio-stable.tar.bz2 the afio stable +tarball] (same as git clone __boost_afio__ followed by a git submodules recursive update and init) and get to work. If however you +wish to use AFIO as part of the Boost libraries, AFIO is also a Boost module: + +# Download the latest version of the Boost Libraries from boost.org. + At the time of writing the current version is Boost 1.59. + Installing AFIO as a Boost module is not compatible with versions of Boost earlier than 1.56 as this was + the first Boost version to become source code modularised. + + +# Download the latest Boost AFIO stable tarball from [@https://boostgsoc13.github.io/boost.afio/afio-stable.tar.bz2 https://boostgsoc13.github.io/boost.afio/afio-stable.tar.bz2]. + We do however recommend using the git repository, as it will allow for future updates. If you are unfamiliar + with git, check the github website for instructions on how to use git. This is a good place to + start: [@https://help.github.com/articles/set-up-git]. Don't forget that after cloning you need to + do a `git submodule update --init --recursive` to have git fill in the submodules. + + +# Assuming that your copy of Boost lives at /home/ned/boost do: + + `` + cd /home/ned/boost/libs + tar jxf afio-stable.tar.bz2 afio + cd .. + ./b2 headers + ./b2 libs/afio/build cxxflags=-std=c++11 + `` + + On Microsoft Windows it's almost the same, just don't specify the `-std=c++11` if you are using VS2015. +Note if you forget the `-std` currently you need to wipe the `bin.v2` directory to reset it as the result is cached +by Boost.Build. + +# If you'd also like to execute the unit test suite, do: + `` + ./b2 libs/afio/test cxxflags=-std=c++11 + `` + +# Similar if you'd like to build documentation, do: + `` + cd doc + ../b2 ../libs/afio/doc + ../b2 ../libs/afio/doc pdf + `` + + I may be missing something, but the pdf appears inside bin.v2, not in pdf for some reason. + Note that the PDF has some significant formatting problems. + +# Thanks to modular Boost, AFIO is now exactly the same as any other Boost library and can +be used in exactly the same way as if AFIO were already part of Boost. + + +[heading Running the Unit Tests] + +To run the unit tests as a standalone build, something like this will probably work for POSIX (it will default to clang on FreeBSD): + +`` + ./standalone_alltests_gcc.sh + ./test_all +`` + +Note this has a dependency on __boost_filesystem__ as libstdc++ 4.9 (the last I tested) has insufficient Filesystem support. For VS2015: + +`` + standalone_alltests_msvc.bat + test_all.exe +`` + +VS2015 ships with Filesystem, so this is totally standalone. + + +To run the unit tests under Boost with [*bjam], run from the boost top directory: +`` + ./b2 libs/afio/test cxxflags=-std=c++11 +`` +This will run the entire suite of unit tests. Some useful command line arguments for Boost.Build: + +* [*--link-test]: will only compile and link the test files. This option can be combined with + the [*--test=] option to only compile and link a specific subset of unit tests. + Note that [*--link-test] supersedes [*--test-all] and [*--test-each] options, + and cannot be combined with the other tests. + +* [*--running-on-ci]: will compile, link and execute only those tests which don't use `fsync()`. + +* [*--lto]: perform link-time code assembly. On POSIX with clang, you NEED the gold linker installed for LTO + to work - otherwise it appears to work, but in fact is doing a normal link. + +* [*--test-all]: will run a comprehensive unit tests that combines all the other unit tests into a single + continuous test. This is useful to detect errors that will only show up at longer running + times. Note that [*--test-each] is not compatible with this option. + +* [*--test-each]: will run a series of individually compiled unit tests in succession. + This option forgoes the lengthy monolithic test-suite in favor of a + series of small tests. This option can be combined with the [*--test=] + option to only run a specific subset of unit tests. Note that [*--test-all] + is not compatible with this option. + +* [*--test=]: will use only the test files designated by the string following this flag. + +For example: + + `` + b2 link=static toolset=gcc-5 cxxflags=-std=c++1z --test="first_test.cpp second_test.cpp" + `` + +will only compile and run only the tests in `first_test.cpp` and `second_test.cpp`. All other unit tests will +be ignored, and all other command-line options still apply. + +[endsect] [/ end of Compilation] diff --git a/attic/doc/copyright_block.qbk b/attic/doc/copyright_block.qbk new file mode 100644 index 00000000..5b447d56 --- /dev/null +++ b/attic/doc/copyright_block.qbk @@ -0,0 +1,7 @@ +[/============================================================================ + Boost.AFIO + + Use, modification and distribution is subject to the Boost Software License, + Version 1.0. (See accompanying file LICENSE_1_0.txt or copy at + http://www.boost.org/LICENSE_1_0.txt) +=============================================================================/] diff --git a/attic/doc/design_rationale.qbk b/attic/doc/design_rationale.qbk new file mode 100644 index 00000000..617e29ff --- /dev/null +++ b/attic/doc/design_rationale.qbk @@ -0,0 +1,462 @@ +[/============================================================================== + Use, modification and distribution is subject to the Boost Software License, + Version 1.0. (See accompanying file LICENSE_1_0.txt or copy at + http://www.boost.org/LICENSE_1_0.txt) +===============================================================================/] + +[section:overview AFIO single page cheat sheet for the very impatient] + +'''<?dbhtml-include href="disqus_identifiers/overview.html"?>''' + +* AFIO models file descriptors/handles as a reference counted `std::shared_ptr<__afio_handle__>` (aliased as `afio::handle_ptr`) where `handle` is an +opaque abstract base class. `handle` may, or may not, refer to a currently open file descriptor/handle +i.e. it is possible to close it before the reference count reaches zero. You can create your own custom +implementations of `handle`. + +* AFIO models a filesystem as a reference counted `std::shared_ptr<__afio_dispatcher__>` (aliased as `afio::dispatcher_ptr`) where `dispatcher` is also +an opaque abstract base class. When constructed using __afio_make_dispatcher__ you specify a URI such as [*`__fileurl__`] which specifies what +namespace the dispatcher will dispatch onto. You can create your own custom `dispatcher` implementations for some URI regex pattern too. + +* AFIO provides its own custom future type `afio::__afio_op__<T = void>` which [*always] represents a future `handle_ptr` plus an optional `T` +which is usually `void` (hence defaulting `T` to `void`). This custom future type is implemented using __boost_outcome__'s lightweight +monadic future factory toolkit, and therefore provides all the C++ 1z Concurrency TS and __boost_thread__ extensions including +continuations and wait composure. Note that lightweight futures can carry an `error_code` as well as an `exception_ptr`, and therefore +much of the need for non-throwing `error_code` taking API overloads is not needed (though any function not returning a future still +uses that idiom). + +* AFIO provides its own custom filesystem path type `afio::__afio_path__` which is a thin wrap of your STL/Boost +Filesystem path. This is done because on Microsoft Windows, AFIO [*always] uses NT kernel paths, +never Win32 paths. By skipping the Win32 translation layer one achieves significantly better +performance and much closer to POSIX semantics including case sensitivity, plus there are no issues +with path length limits. On Windows `afio::path` (NT kernel paths) will usually auto convert to and from `filesystem::path` +(Win32 paths), however do note there is not always a one to one mapping from a NT kernel path to +a Win32 path in which case the Win32 paths to send in will never be the Win32 paths you get out. +See the documentation for __afio_path__. + + [caution Until [@https://github.com/BoostGSoC13/boost.afio/issues/79 issue #79] is resolved, don't +do directory enumerations from an x86 binary on a x64 Windows system. This is due to a bug in +Microsoft's WOW64 syscall translation layer which Microsoft have decided is wontfix.] + +* Error reporting [*always] follows the ["earliest possible reporting] rule. As absolutely +everything is asynchronous in AFIO, that also means that error and exception handling also occurs +asynchronously. So if you try to use a future as an input and that future is +errored at the point of use, the errored state is immediately rethrown. As futures may +become errored asynchronously, that means you must always write code which assumes any +API which consumes a future can throw (unless you know for a fact the future is ready and +not errored). + + [note Gathering error states from many futures at once is made easier using the `when_all_p()` +(when all propagating) extended wait composure function from __boost_outcome__ __dash__ this +propagates any error in any of the entry futures into the composed output future, thus saving +you having to check the futures for errors by hand.] + +* Handles to directories may ignore requests to close them i.e. `handle_ptr->close()` +is a no-op. This is due to a performance feature called ["directory handle caching] which shares +read-only directory handles amongst all users unless specifically requested not to do so. You +can test for this using the `available_to_directory_cache()` member function of `handle`. + +* As a general rule, AFIO spots when you try to delete a currently open file handle where +that is illegal on your platform (Microsoft Windows) and will instead rename the file to a +cryptographically strong random name of the form `<32 chars of random hex>.afiod` and ask the operating system to delete +it later when the last handle is closed. Any enumerations of directories containing these +randomised named files will omit those entries by default. This emulates POSIX semantics, albeit imperfectly. +One caveat is it cannot always do this with directories, +though it tries hard to try again later where it can. A future version of AFIO will add `tmpfs` +support which will let us relocate troublesome directories into the temp directory where they can +be deleted much later, thus more closely matching POSIX semantics still further. + +__boost_afio__ version 1.4 provides the following operations: + +[table:supported_operations +[[Operation][Asynchronous batch `__afio_dispatcher__` functions][Synchronous `__afio_handle__` functions][Asynchronous free functions][Synchronous free functions][Related types]] +[[[link afio.reference.functions.dir Open/create a directory: `dir()`]] [1] [] [2] [4] [__afio_path_req__]] +[[[link afio.reference.functions.rmdir Delete a directory: `rmdir()`]] [1] [] [2] [4] [__afio_path_req__]] +[[[link afio.reference.functions.file Open/create a file: `file()`]] [1] [] [2] [4] [__afio_path_req__]] +[[[link afio.reference.functions.rmfile Delete a file: `rmfile()`]] [1] [] [2] [4] [__afio_path_req__]] +[[[link afio.reference.functions.symlink Open/create a symlink: `symlink()`]] [1] [] [2] [4] [__afio_path_req__]] +[[[link afio.reference.functions.rmsymlink Delete a symlink: `rmsymlink()`]] [1] [] [2] [4] [__afio_path_req__]] +[[[link afio.reference.functions.sync Synchronise changes to physical storage: `sync()`]] [1] [] [1] [2] []] +[[[link afio.reference.functions.zero Deallocate/zero physical storage: `zero()`]] [1] [] [1] [2] []] +[[[link afio.reference.functions.close Close a fd/handle: `close()`]] [1] [] [1] [2] []] +[[[link afio.reference.functions.read Scatter read file contents: `read()`]] [1] [] [2] [4] [__afio_io_req__]] +[[[link afio.reference.functions.write Gather write file contents: `write()`]] [1] [] [2] [4] [__afio_io_req__]] +[[[link afio.reference.functions.truncate Set maximum file extent: `truncate()`]] [1] [] [1] [2] []] +[[[link afio.reference.functions.enumerate Enumerate directory contents/ +fetch file metadata: `enumerate()`]] [1] [] [3] [6] [__afio_enumerate_req__, __afio_directory_entry__, __afio_stat_t__]] +[[[link afio.reference.functions.extents Enumerate file physical storage extents: `extents()`]] [1] [] [1] [2] []] +[[[link afio.reference.functions.statfs Examine mounted storage volume: `statfs()`]] [1] [] [1] [2] [__afio_statfs_t__]] + +[[[link afio.reference.classes.handle.path Get current path of an open fd/handle +even if other processes are renaming it +(Linux, Windows; FreeBSD directories only; +not OS X): `path()`]] [] [2] [] [] [__afio_path__]] +[[[link afio.reference.classes.handle.direntry Get open fd/handle metadata: `direntry()`, `lstat()`]][] [2] [] [] [__afio_directory_entry__, __afio_stat_t__]] +[[[link afio.reference.classes.handle.target Get target path of a symlink: `target()`]] [] [1] [] [] []] +[[[link afio.reference.classes.handle Map a read-only file into memory: `try_mapfile()`]] [] [1] [] [] []] +[[[link afio.reference.classes.handle.link Hard link an open fd/handle to a new path: `link()`]][] [1] [] [] [__afio_path_req__]] +[[[link afio.reference.classes.handle.unlink Unlink an open fd/handle from its existing +path (caution!): `unlink()`]] [] [1] [] [] [__afio_path_req__]] +[[[link afio.reference.classes.handle.atomic_relink ['Strong guaranteed atomically] relink an open +fd/handle from its existing path to a different path: `atomic_relink()`]] [] [1] [] [] [__afio_path_req__]] +] + +Planned new operations coming next version of AFIO so you know what's coming next: + +* Mutual exclusion and locking which works across NFS and Samba: + * The ability to tag many `handle`'s with what locking to do per operation. + * Asynchronous exclusive lock files. + * Asynchronous multi-file byte range locking. + * Individual file change monitoring (needed to implement locking). +* [*`tmp://`] URI backend for a temporary file filesystem. +* Optional inline hashing of file reads and writes with SpookyHash/Blake2b/SHA256. +* Maybe Boost.Fiber support to gain coroutines on all compilers. + +'''<?dbhtml-include href="disqus_comments.html"?>''' + +[endsect] [/overview] + + +[section:design Design Introduction and Rationale] + +'''<?dbhtml-include href="disqus_identifiers/design_rationale.html"?>''' + +__boost_afio__ came about out of the need for a scalable, high performance, portable asynchronous +file i/o and filesystem implementation library for a forthcoming filing system based graph store ACID compliant transactional +persistence layer called __triplegit__ __dash__ call it a ["SQLite3 but for graphstores][footnote The +[@http://unqlite.org/ UnQLite embedded NoSQL database engine] is exactly one of those of course. +Unfortunately I intend TripleGit for implementing portable Component Objects for +C++ extending C++ Modules, which means I need a database engine suitable for incorporation into +a dynamic linker, which unfortunately is not quite UnQLite.]. The fact that a portable +asynchronous file i/o and filesystem library for C++ was needed at all came as a bit of a surprise: one +thinks of these things as done and dusted decades ago, but it turns out that the fully featured +[@http://nikhilm.github.io/uvbook/filesystem.html libuv], a C library, is good enough for most +people needing portable asynchronous file i/o. However as great as libuv is, it isn't very C++-ish, and +hooking it in with __boost_asio__ (parts of which are expected to enter the ISO C++ language +standard) isn't particularly clean. I therefore resolved to write a native Boost asynchronous +file i/o and filesystem implementation, and keep it as simple as possible. + +[heading A quick version history] + +AFIO started life as a C++ 0x library written for an early Visual Studio 2013 Community Preview back +in 2012 as a outside-of-work side project when I was working at BlackBerry. It was ported to Boost +during Google Summer of Code 2013 with the help of student Paul Kirth, and VS2012 and VS2010 support +was added. For v1.0, AFIO used a simple dispatch engine which kept the extant ops in a hash table, +and the entire dispatch engine was protected by a single giant and recursive mutex. Performance +never exceeded about 150k ops/sec maximum on a four core Intel Ivy Bridge CPU. + +That performance was embarrassing, so for v1.1 the entire engine was rewritten using atomic shared +pointers to be completely lock free, and very nearly wait free if it weren't for +the thin spin locks around the central ops hash table. Now performance +can reach 1.5m ops/sec on a four core Intel Ivy Bridge CPU, or more than half of Boost.ASIO's +maximum dispatch rate. + +For the v1.2 engine, another large refactor was done, this time to substantially simplify the +engine by removing the use of `std::packaged_task<>` completely, replacing it with a +new intrusive-capable `enqueued_task<>` which permits the engine to early out in many cases, +plus allowing the consolidation of all spinlocked points down to just two: one in dispatch, +and one other in completion, which is now optimal. Performance of the v1.2 engine rose +by about 20% over the v1.1 engine, plus AFIO is now fully clean on all race detecting tools. + +For the v1.3 engine, yet another large refactor was done, though not for performance but rather +to make it much easier to maintain AFIO in the future, especially after acceptance into Boost +whereupon one cannot arbitrarily break API anymore, and one must maintain backwards compatibility. +To this end the dependencies between AFIO and Boost were completely abstracted into a substitutable +symbol aliasing layer such that any combination of Boost and C++ 11 STL threading/chrono, filesystem +and networking can be selected externally using macros. Indeed, any of the eight build combinations +can coexist in the same translation unit too, I have unit test runs which prove it! With the v1.3 +engine AFIO optionally no longer needs Boost at all, not even for its unit testing. However the +cost was dropping support for all Visual Studios before 2013 and all GCCs before 4.7 as they +don't have the template aliasing support needed to implement the STL abstraction layer. A very large +amount of legacy cruft code e.g. support for non-variadic templates was cleaned out for the v1.3 release. + +[heading This version 1.4 of AFIO] +During ACCU and C++ Now 2015 I spoke with a number of ISO WG21 committee members about the structural +design problems in iostreams and the Filesystem TS (lack of filesystem race freedom, lack of context +dependant filesystem), and what design the committee would prefer to see to fix those problems. As it +happens, we were all close to the same page, so from the v1.4 engine onwards I resolved to refactor the AFIO API thusly: + +# Since v1.0 AFIO implemented the Concurrency TS continuations atop standard futures using a central hash table +to keep the continuations information per future. This had the big advantage that standard STL and Boost +futures could be used, but it came with many other problems, mainly performance and code complexity related. +An additional problem was that the Concurrency TS had moved on considerably since 2012, and AFIO's emulation +was now significantly out of date. +For v1.4 a new lightweight future-promise factory toolkit library called __boost_outcome__ was written between the +end of C++ Now (May) and the beginning of the AFIO peer review (July) which makes +easy the writing of arbitrarily customisable future-promises for C++ which: + + * Implements an almost complete Concurrency TS ([@http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2015/n4399.html N4399]) +future-promise specification with almost all the Boost.Thread future-promise extensions. + * Are very considerably more performant (2x-3x) and much more reliably low latency (no memory allocation). + * Permit arbitrary wait composure of any kind of custom future-promise with one another. + * Are part of a general purpose lightweight C++ monadic programming implementation, so futures are merely +asynchronous monads. + * Natively support C++ 1z coroutines ([@http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2015/n4499.pdf N4499]) +which are currently only supported by Visual Studio 2015. + + The use of this future factory toolkit makes the AFIO continuations infrastructure redundant, and it will +therefore be removed shortly. The monadic programming library also makes quite a bit of internal AFIO +implementation code much more simplified as thanks to the monads, one can use noexcept design throughout and therefore +skip dealing directly with exception safety as the monads take away the potential of control flow being reversed +by an exception throw. + + [note This version of AFIO being presented for Boost review does not yet make use of lightweight future-promises, +and instead mocks up the eventual API using the existing highly mature and very well tested engine. The API presented +is expected to be final, except for the very few items specified as deprecated (see below for a list). This has been +done in order to test that the engine rewrite based on lightweight future-promise exactly matches the behaviour of +the current engine using an identical unit test suite. + +I should emphasise that I expect any programs written to match the presented API to continue to work after the engine +rewrite __dash__ after all the internal unit test suite will do so.] + +# For race free filesystem programming, you really need to base all path related operations on an open file +descriptor or handle, so something like: + + `` + afio::handle_ptr &h; // Some open file handle + + // Create a sibling file to h->path() race free + afio::handle_ptr newfileh=afio::file(h, "../newfile", afio::file_flags::create); + + // Asynchronously create a sibling file to h->path() race free + // afio::future has type void because afio::future *always* carries a shared pointer to a handle + // (it only gets a type when the operation returns more than a file handle) + afio::future<void> newfilefh2=afio::async_file(h, "../newfile", afio::file_flags::create); + + // Wait for the asynchronous file creation to complete, rethrowing any error or exception + afio::handle_ptr newfileh2=newfilefh2.get_handle(); + `` + + I'll admit this design isn't quite what the members of WG21 had in mind, especially the notion that `afio::future<void>` +with type void always carries a shared pointer to a handle and that implicit type slicing from `afio::future<T>` +to `afio::future<void>` is not just allowed but absolutely essential. However apart from that, the +above API is probably quite close to what members of WG21 were thinking. + +# One oft-observed design limitation in the Filesystem TS is that it cannot support filesystems in filesystems, +with the most classic example being a ZIP archive on a filesystem where it might be nice to allow generic C++ +filesystem code to not need to be aware that the filesystem it sees is inside a ZIP archive. The solution could be one or both of these options: + + # Make the Filesystem TS operations hang as virtual member functions off some `filesystem` abstract base class. + # Have a thread local variable set the current `filesystem` instance to be used by the global Filesystem TS +functions on that thread. + + AFIO v1.4 and probably v1.5 won't implement this as this is really a thing for Boost.Filesystem to do. However, +AFIO's __afio_make_dispatcher__ already takes a URI and there is a RAII facility for setting the current +thread local dispatcher, so AFIO is ready for a Filesystem TS implementation matching the above design to be written on top of it in that +a `dispatcher` instance has a suite of virtual member functions +which define what some filesystem is or does. AFIO v1.4 only provides POSIX and NT kernel filesystem backends +currently, however it is expected that v1.5 will add a new temporary filesystem backend which lets programs +portably work inside `tmpfs` in whichever form that takes across Linux, FreeBSD, Apple OS X and Microsoft Windows. +Additional backends implementing say a ZIP archive filesystem are similarly easy to add on. + +As mentioned above, note that due to the above refactoring some parts of this v1.4 release of AFIO are deprecated and are expected +to be removed shortly. You can find a list of these shortly to be removed APIs and parts [link afio.release_notes here]. +The list is not long, and the removals are obvious. + +'''<?dbhtml-include href="disqus_comments.html"?>''' + +[section:acid_write_ordering Write ordering constraints, and how these can +be used to achieve some of the Durability in ACID without needing `fsync()`] + +'''<?dbhtml-include href="disqus_identifiers/design_rationale.html"?>''' + +[*ACID] stands for Atomic Consistent Isolated Durable, and it is a key requirement for +database implementations which manage data you don't want to lose, which tends to be +a common use case in databases. Whilst achieving all four is non-trivial, achieving Durability is +simultaneously both the easiest and the hardest of the four. This is because the easy +way of ensuring durability is to always wait for each write to reach non-volatile storage, +yet such a naive solution is typically exceptionally slow. Achieving performant +data durability is without doubt a wicked hard problem in computer science. + +Because a majority of users of __boost_afio__ are going to be people needing +some form of data persistence guarantees, this section is a short essay on the current +state of data persistence on various popular platforms. Any errors or omissions, both +of which are probable, are entirely the fault of this author Niall Douglas. Note also that +the forthcoming information was probably correct around the winter of 2014, and it highly +likely to become less correct over time as filing system implementations evolve. + +'''<?dbhtml-include href="disqus_comments.html"?>''' + +[section:background Background on how filing systems work] + +'''<?dbhtml-include href="disqus_identifiers/design_rationale.html"?>''' + +Filing system implementations traditionally offer three methods of ensuring that writes +have reached non-volatile storage: + +# The family of `fsync()` or its equivalent functions, which flush any cached written +data not yet stored onto non-volatile storage. These are usually synchronous operations, +in that they do not return until they have finished. A big caveat with these functions +is that some filing systems e.g. ext3 flush ['every] bit of pending write data for +the filing system instead of just the pending writes for the file handle specified i.e. they +are equivalent to a synchronous `sync()` as described below. + +# The family of `O_SYNC` or its equivalent per file handle flags, which simply +disable any form of write back caching. These usually make all data write functions +not return until written data has reached non-volatile storage. This flag, for all intents +and purposes, effectively asks for ["old fashioned] filing system behaviour from before +when filing systems tried to be clever by not actually writing changes when a program +writes changes. + +# The whole filing system cached written data flush, often performed by a function +like `sync()`. Unlike the previous two, this is usually an asynchronous operation +and there is usually no portable way of knowing when it has completed. Nevertheless, +it is important because on traditional Unix implementations data persistence is simply +`sync()` on a regular period cronjob, and while modern Unix implementations usually +no longer do this, the end implementation has not fundamentally changed much[footnote +The main change is that individual writes get an individual lifetime before they must +be written to storage rather flushing everything according to some external wall clock.]. + +There is also the matter of the difference between data and ['meta]data: metadata +is the stuff a filing system stores such that it knows about your data. For each +of the first two of the above three families of functions, most systems provide +three variants: flush metadata, flush data, and flush both metadata and data, so +for clarity: + +[table:data_persistence_types Mechanisms for enforcing data persistence onto physical storage + [[][Flush file metadata][Flush file data][Flush both metadata and data]] + [[Once off][`fsync(parentdir_fd)`][`fdatasync(fd)`][`fsync(fd)`]] + [[Always][Varies[footnote Many filing systems (NTFS, HFS+, ext3/4 with `data=ordered`) keep back a metadata flush until when a file handle close causes data to finish reaching physical storage. This ensures that file entries don't appear in directories with zero sizes.]][`fcntl(fd, F_SETFL, O_DSYNC)`][`fcntl(fd, F_SETFL, O_SYNC)`]] +] + +In addition to manually flushing data to physical storage, every filing system also +implements some form of timer based flush whereby a piece of written data will always +be sent to physical storage within some predefined period of time after the write. +Most filing systems implement different timeouts for metadata and data, but typically +on almost all production filing systems __dash__ unless they are in a power-saving laptop mode -- +any data write is guaranteed to be sent to non-volatile storage within one minute. +Let me be clear here for later argument's sake: ['the filing system is allowed to +reorder writes by up to one minute in time from the order in which they were issued]. +Or put another way, most filing systems have a one minute temporal constraint on +write order. + +Most people think of `fsync()`, `O_SYNC` and `sync()` in terms of flushing caches. +An alternative way of thinking about them is that they ['impose an order on +writes] to non-volatile storage which acts above and beyond the timeout based write order. There +is no doubt that they are a very crude and highly inefficient way of doing so because +they are all or nothing, but they do open the option of ['emulating] +native filing system support for write ordering constraints when nothing else better +is available. So why is the ability to constrain write ordering important? + +'''<?dbhtml-include href="disqus_comments.html"?>''' + +[endsect] [/background] + +[section:write_ordering_data Write ordering data and durability: why does it matter?] + +'''<?dbhtml-include href="disqus_identifiers/design_rationale.html"?>''' + +[note You may find the paper presented at C++ Now 2014 [@http://arxiv.org/abs/1405.3323 ["Large Code Base Change Ripple Management in C++: My thoughts on how a new Boost C++ Library could help]] of interest here.] + +Implementing performant Durability essentially reduces down to answering two questions: (i) how long does it take to restore +a consistent state after an unexpected power loss, and (ii) how much of your most recent data are +you willing to lose? AFIO has been designed and written as the asynchronous file i/o +portability layer for the forthcoming direct +filing system graphstore database __triplegit__ which, like as with ZFS, implements late Durability i.e. +you are guaranteed that your writes from some wall clock distance from now can never +be lost. As discussing how TripleGit will use AFIO is probably useful to many others, +that is what the remainder of this section does. + +__triplegit__ will achieve the Consistent and Isolated parts of being a reliable database by placing +abortable, garbage collectable concurrent writes of new data into separate files, and pushing +the atomicity enforcement into a very small piece of ordering logic in order to reduce +transaction contention by multiple writers as much as possible. +If you wish to never lose most recent data, to implement a transaction +one (i) writes one's data to the filing +system, (ii) ensure it has reached non-volatile storage, (iii) appends the knowledge it +definitely is on non-volatile storage to the intent log, and then (iv) ensure one's +append also has reached non-volatile storage. This is presently the only way to ensure +that valuable data definitely is never lost on any filing system that I know of. The obvious +problem is that this method involves writing all your data with `O_SYNC` and using `fsync()` +on the intent log. This might perform okay with a single writer, but with multiple +writers performance is usually awful, especially on storage incapable of high +queue depths and potentially many hundreds of milliseconds of latency (e.g. SD Cards). +Despite the performance issues, there are many valid use cases for especially precious +data, and TripleGit of course will offer such a facility, at both the per-graph and per-update +levels. + +__triplegit__'s normal persistence strategy is a bit more clever: write all your data, but keep a hash like a SHA of its contents +as you write it[footnote TripleGit actually uses a different, much faster 256 bit 3 cycles/byte cryptographic hash +called [@https://blake2.net/ Blake2] by default, but one can force use of SHA256/512 on a per-graph basis, +or indeed if your CPU has SHA hardware offload instructions these may be used by default.]. When you write your intent log, +atomically append all the SHAs of the items +you just wrote and skip `O_DATA` and `fsync()` completely. If power gets removed +before all the data is written to non-volatile storage, you can figure out that +the database is dirty easily enough, and you simply parse from the end of the intent +log backwards, checking each item's contents to ensure their SHAs match up, throwing +away any transaction where any file is missing or any file's contents don't match. +On a filing system such as ext4 where data is guaranteed to be sent to non-volatile +storage after one minute[footnote This is the default, and it may be changed by a +system e.g. I have seen thirty minutes set for laptops. Note that the Linux-specific +call `syncfs()` lets one artifically schedule whole filing system flushes.], and of +course so long as you don't mind losing up to one +minute's worth of data, this solution can have much better performance than the +previous solution with lots of simultaneous writers. + +The problem though is that while better, performance is still far less than optimal. +Firstly, you have to calculate a whole load of hashes all the time, and that isn't trivial +especially on lower end platforms like a mobile phone where 25-30 cycles per byte +SHA256 performance might be typical. Secondly, dirty database reconstruction is +rather like how ext2 had to call `fsck` on boot: a whole load of time and i/o +must be expended to fix up damage in the store, and while it's running one generally +must wait. + +What would be really, really useful is if the filing system exposed its internal +write ordering constraint implementation to user mode code, so one could say ["schedule writing A, B, +C and D in any order whenever you get round to it, but you ['must] write all +of those before you write any of E, F and G]. Such an ability gives maximum +scope to the filing system to reorder and coalesce writes as it sees fit, +but still allows database implementations to ensure that a transaction's intent +log entry can never appear without all the data it refers to. Such an ability +would eliminate the need for expensive dirty database checking and reconstruction, +or the need for any journalling infrastructure used to skip the manual integrity checking. + +Unfortunately I know of no filing system which makes publicly available such +a facility. The closest that I know of is ZFS which internally uses a concept of transaction +groups which are, for all intents and purposes, partial whole filing system snapshots issued once every +five seconds. Data writes may be reordered into any order within +a transaction group, but transaction group commits are strongly tied to the wall +clock and are [*always] committed sequentially. Since the +addition of the ZFS Write Throttle, the default settings are to accept new writes +as fast as RAM can handle, buffering up to +thirty wall clock seconds of writes before pacing the acceptance of new write data to match +the speed of the non-volatile storage (which may be a ZFS Intent Log (ZIL) device if you're doing +synchronous writes). This implies up to +thirty seconds of buffered data could be lost, but note that ZFS still guarantees +transaction group sequential write order. Therefore, what ZFS is in fact guaranteeing +is this: ["we may reorder your write by up to five seconds away from the sequence +in which you wrote it and other writes surrounding it. Other than that, we guarantee +the order in which you write is the order in which that data reaches physical storage.] +[footnote Source: [@http://www.c0t0d0s0.org/archives/5343-Insights-into-ZFS-today-The-nature-of-writing-things.html]] + +What this means is this: on ZFS, TripleGit can turn off all write synchronisation and +replace it with a five second delay between writing new data and updating the intent log, +and in so doing guaranteeing that the intent log's contents will [*always] refer to data +definitely on storage (or rather, close enough that one need not perform a lot of repair +work on first use after power loss). One can additionally skip SHA hashing on reads because ZFS guarantees file and metadata will always match and as TripleGit always +copy on writes data, either a copy's length matches the intent log's or it doesn't (i.e. +the file's length as reported by the filing system really is how much true data it contains), plus the file +modified timestamp always reflects the actual last modifed timestamp of the data. + +Note that ext3 and ext4 can also guarantee that file and metadata will always match using +the (IOPS expensive) mount option `data=journal`, which can be detected from `/proc/mounts`. +If combined with the proprietary Linux call `syncfs()`, one can reasonably emulate ZFS's +behaviour, albeit rather inefficiently. Another option is to have an idle thread issue fsync for writes +in the order they were issued after some timeout period, thus making sure that writes definitely will reach physical storage within +some given timeout and in their order of issue __dash__ this can be used to emulate the ZFS wall clock based write order +consistency guarantees. + +[note You may find the tutorial of interest which implements an ACID transactional key-value store +using the theory in this section.] + +Sadly, most use of __triplegit__ and __boost_afio__ will be without the luxury of ZFS, so here +is a quick table of power loss data safety. Once again, I reiterate that errors and omissions are my fault alone. + +[include power_loss_safety_table.qbk] + +'''<?dbhtml-include href="disqus_comments.html"?>''' + +[endsect] [/write_ordering_data] + +[endsect] [/acid_write_ordering] + +[endsect] [/ end of section Design Rationale] diff --git a/attic/doc/disqus_comments.html b/attic/doc/disqus_comments.html new file mode 100644 index 00000000..9f13aae6 --- /dev/null +++ b/attic/doc/disqus_comments.html @@ -0,0 +1,42 @@ +<div><a name="comments" /><div id="disqus_thread"></div> +<script type="text/javascript"> +<![CDATA[ +// Get the hX element with class "title" +var titles = document.getElementsByClassName("title"); +for (var n = 0; n < titles.length; n++) { + var title = titles[n]; + if(title.lastElementChild.nodeName!="a") + { + var a_elem = document.createElement("a"); + a_elem.setAttribute("href", "#comments"); + var span_elem = document.createElement("span"); + span_elem.setAttribute("class", "disqus-comment-count"); + span_elem.setAttribute("data-disqus-identifier", disqus_identifier); + var text_node = document.createTextNode("Comments"); + span_elem.appendChild(text_node); + a_elem.appendChild(span_elem); + title.parentElement.appendChild(a_elem); + title.setAttribute("style", "clear: both; display: inline-block;") + } +} + /* * * CONFIGURATION VARIABLES * * */ + var disqus_shortname = 'boostafio'; + + /* * * DON'T EDIT BELOW THIS LINE * * */ + (function () { + var s = document.createElement('script'); s.async = true; + s.type = 'text/javascript'; + s.src = 'https://' + disqus_shortname + '.disqus.com/count.js'; + (document.getElementsByTagName('HEAD')[0] || document.getElementsByTagName('BODY')[0]).appendChild(s); + }()); + + /* * * DON'T EDIT BELOW THIS LINE * * */ + (function() { + var dsq = document.createElement('script'); dsq.type = 'text/javascript'; dsq.async = true; + dsq.src = 'https://' + disqus_shortname + '.disqus.com/embed.js'; + (document.getElementsByTagName('head')[0] || document.getElementsByTagName('body')[0]).appendChild(dsq); + })(); +]]> +</script> +<noscript>Please enable JavaScript to view the <a href="https://disqus.com/?ref_noscript" rel="nofollow">comments powered by Disqus.</a></noscript> +</div>
\ No newline at end of file diff --git a/attic/doc/disqus_identifiers/async_close.html b/attic/doc/disqus_identifiers/async_close.html new file mode 100644 index 00000000..b2c93318 --- /dev/null +++ b/attic/doc/disqus_identifiers/async_close.html @@ -0,0 +1,4 @@ +<script type="text/javascript"> +var disqus_identifier = 'async_close'; +var disqus_title = 'Boost.AFIO async_close'; +</script> diff --git a/attic/doc/disqus_identifiers/async_dir_2_absolute.html b/attic/doc/disqus_identifiers/async_dir_2_absolute.html new file mode 100644 index 00000000..642d49e5 --- /dev/null +++ b/attic/doc/disqus_identifiers/async_dir_2_absolute.html @@ -0,0 +1,4 @@ +<script type="text/javascript"> +var disqus_identifier = 'async_dir_2_absolute'; +var disqus_title = 'Boost.AFIO async_dir (absolute)'; +</script> diff --git a/attic/doc/disqus_identifiers/async_dir_3_relative.html b/attic/doc/disqus_identifiers/async_dir_3_relative.html new file mode 100644 index 00000000..c920b147 --- /dev/null +++ b/attic/doc/disqus_identifiers/async_dir_3_relative.html @@ -0,0 +1,4 @@ +<script type="text/javascript"> +var disqus_identifier = 'async_dir_3_relative'; +var disqus_title = 'Boost.AFIO async_dir (relative)'; +</script> diff --git a/attic/doc/disqus_identifiers/async_enumerate_6_glob_first.html b/attic/doc/disqus_identifiers/async_enumerate_6_glob_first.html new file mode 100644 index 00000000..cb5b6928 --- /dev/null +++ b/attic/doc/disqus_identifiers/async_enumerate_6_glob_first.html @@ -0,0 +1,4 @@ +<script type="text/javascript"> +var disqus_identifier = 'async_enumerate_6_glob_first'; +var disqus_title = 'Boost.AFIO async_enumerate (glob first)'; +</script> diff --git a/attic/doc/disqus_identifiers/async_enumerate_6_maxitems_first.html b/attic/doc/disqus_identifiers/async_enumerate_6_maxitems_first.html new file mode 100644 index 00000000..1780f687 --- /dev/null +++ b/attic/doc/disqus_identifiers/async_enumerate_6_maxitems_first.html @@ -0,0 +1,4 @@ +<script type="text/javascript"> +var disqus_identifier = 'async_enumerate_6_maxitems_first'; +var disqus_title = 'Boost.AFIO async_enumerate (maxitems first)'; +</script> diff --git a/attic/doc/disqus_identifiers/async_enumerate_6_metadata_first.html b/attic/doc/disqus_identifiers/async_enumerate_6_metadata_first.html new file mode 100644 index 00000000..25389f03 --- /dev/null +++ b/attic/doc/disqus_identifiers/async_enumerate_6_metadata_first.html @@ -0,0 +1,4 @@ +<script type="text/javascript"> +var disqus_identifier = 'async_enumerate_6_metadata_first'; +var disqus_title = 'Boost.AFIO async_enumerate (metadata first)'; +</script> diff --git a/attic/doc/disqus_identifiers/async_extents.html b/attic/doc/disqus_identifiers/async_extents.html new file mode 100644 index 00000000..58948b24 --- /dev/null +++ b/attic/doc/disqus_identifiers/async_extents.html @@ -0,0 +1,4 @@ +<script type="text/javascript"> +var disqus_identifier = 'async_extents'; +var disqus_title = 'Boost.AFIO async_extents'; +</script> diff --git a/attic/doc/disqus_identifiers/async_file_2_absolute.html b/attic/doc/disqus_identifiers/async_file_2_absolute.html new file mode 100644 index 00000000..fc7fa7b5 --- /dev/null +++ b/attic/doc/disqus_identifiers/async_file_2_absolute.html @@ -0,0 +1,4 @@ +<script type="text/javascript"> +var disqus_identifier = 'async_file_2_absolute'; +var disqus_title = 'Boost.AFIO async_file (absolute)'; +</script> diff --git a/attic/doc/disqus_identifiers/async_file_3_relative.html b/attic/doc/disqus_identifiers/async_file_3_relative.html new file mode 100644 index 00000000..022b80e4 --- /dev/null +++ b/attic/doc/disqus_identifiers/async_file_3_relative.html @@ -0,0 +1,4 @@ +<script type="text/javascript"> +var disqus_identifier = 'async_file_3_relative'; +var disqus_title = 'Boost.AFIO async_file (relative)'; +</script> diff --git a/attic/doc/disqus_identifiers/async_op_flags.html b/attic/doc/disqus_identifiers/async_op_flags.html new file mode 100644 index 00000000..87162f3f --- /dev/null +++ b/attic/doc/disqus_identifiers/async_op_flags.html @@ -0,0 +1,4 @@ +<script type="text/javascript"> +var disqus_identifier = 'async_op_flags'; +var disqus_title = 'Boost.AFIO async_op_flags'; +</script> diff --git a/attic/doc/disqus_identifiers/async_read_3_length_deducing.html b/attic/doc/disqus_identifiers/async_read_3_length_deducing.html new file mode 100644 index 00000000..6e212146 --- /dev/null +++ b/attic/doc/disqus_identifiers/async_read_3_length_deducing.html @@ -0,0 +1,4 @@ +<script type="text/javascript"> +var disqus_identifier = 'async_read_3_length_deducing'; +var disqus_title = 'Boost.AFIO async_read (length deducing)'; +</script> diff --git a/attic/doc/disqus_identifiers/async_read_4_length_specifying.html b/attic/doc/disqus_identifiers/async_read_4_length_specifying.html new file mode 100644 index 00000000..b928bda4 --- /dev/null +++ b/attic/doc/disqus_identifiers/async_read_4_length_specifying.html @@ -0,0 +1,4 @@ +<script type="text/javascript"> +var disqus_identifier = 'async_read_4_length_specifying'; +var disqus_title = 'Boost.AFIO async_read (length specifying)'; +</script> diff --git a/attic/doc/disqus_identifiers/async_rmdir_2_absolute.html b/attic/doc/disqus_identifiers/async_rmdir_2_absolute.html new file mode 100644 index 00000000..fef4b17c --- /dev/null +++ b/attic/doc/disqus_identifiers/async_rmdir_2_absolute.html @@ -0,0 +1,4 @@ +<script type="text/javascript"> +var disqus_identifier = 'async_rmdir_2_absolute'; +var disqus_title = 'Boost.AFIO async_rmdir (absolute)'; +</script> diff --git a/attic/doc/disqus_identifiers/async_rmdir_3_relative.html b/attic/doc/disqus_identifiers/async_rmdir_3_relative.html new file mode 100644 index 00000000..fa4a2fe3 --- /dev/null +++ b/attic/doc/disqus_identifiers/async_rmdir_3_relative.html @@ -0,0 +1,4 @@ +<script type="text/javascript"> +var disqus_identifier = 'async_rmdir_3_relative'; +var disqus_title = 'Boost.AFIO async_rmdir (relative)'; +</script> diff --git a/attic/doc/disqus_identifiers/async_rmfile_2_absolute.html b/attic/doc/disqus_identifiers/async_rmfile_2_absolute.html new file mode 100644 index 00000000..28813118 --- /dev/null +++ b/attic/doc/disqus_identifiers/async_rmfile_2_absolute.html @@ -0,0 +1,4 @@ +<script type="text/javascript"> +var disqus_identifier = 'async_rmfile_2_absolute'; +var disqus_title = 'Boost.AFIO async_rmfile (absolute)'; +</script> diff --git a/attic/doc/disqus_identifiers/async_rmfile_3_relative.html b/attic/doc/disqus_identifiers/async_rmfile_3_relative.html new file mode 100644 index 00000000..6f59d726 --- /dev/null +++ b/attic/doc/disqus_identifiers/async_rmfile_3_relative.html @@ -0,0 +1,4 @@ +<script type="text/javascript"> +var disqus_identifier = 'async_rmfile_3_relative'; +var disqus_title = 'Boost.AFIO async_rmfile (relative)'; +</script> diff --git a/attic/doc/disqus_identifiers/async_rmsymlink_2_absolute.html b/attic/doc/disqus_identifiers/async_rmsymlink_2_absolute.html new file mode 100644 index 00000000..360c2e10 --- /dev/null +++ b/attic/doc/disqus_identifiers/async_rmsymlink_2_absolute.html @@ -0,0 +1,4 @@ +<script type="text/javascript"> +var disqus_identifier = 'async_rmsymlink_2_absolute'; +var disqus_title = 'Boost.AFIO async_rmsymlink (absolute)'; +</script> diff --git a/attic/doc/disqus_identifiers/async_rmsymlink_3_relative.html b/attic/doc/disqus_identifiers/async_rmsymlink_3_relative.html new file mode 100644 index 00000000..9c61dc3b --- /dev/null +++ b/attic/doc/disqus_identifiers/async_rmsymlink_3_relative.html @@ -0,0 +1,4 @@ +<script type="text/javascript"> +var disqus_identifier = 'async_rmsymlink_3_relative'; +var disqus_title = 'Boost.AFIO async_rmsymlink (relative)'; +</script> diff --git a/attic/doc/disqus_identifiers/async_statfs.html b/attic/doc/disqus_identifiers/async_statfs.html new file mode 100644 index 00000000..1f2216ba --- /dev/null +++ b/attic/doc/disqus_identifiers/async_statfs.html @@ -0,0 +1,4 @@ +<script type="text/javascript"> +var disqus_identifier = 'async_statfs'; +var disqus_title = 'Boost.AFIO async_statfs'; +</script> diff --git a/attic/doc/disqus_identifiers/async_symlink_3_absolute.html b/attic/doc/disqus_identifiers/async_symlink_3_absolute.html new file mode 100644 index 00000000..71a1616e --- /dev/null +++ b/attic/doc/disqus_identifiers/async_symlink_3_absolute.html @@ -0,0 +1,4 @@ +<script type="text/javascript"> +var disqus_identifier = 'async_symlink_3_absolute'; +var disqus_title = 'Boost.AFIO async_symlink (absolute)'; +</script> diff --git a/attic/doc/disqus_identifiers/async_symlink_4_relative.html b/attic/doc/disqus_identifiers/async_symlink_4_relative.html new file mode 100644 index 00000000..0aa157a0 --- /dev/null +++ b/attic/doc/disqus_identifiers/async_symlink_4_relative.html @@ -0,0 +1,4 @@ +<script type="text/javascript"> +var disqus_identifier = 'async_symlink_4_relative'; +var disqus_title = 'Boost.AFIO async_symlink (relative)'; +</script> diff --git a/attic/doc/disqus_identifiers/async_sync.html b/attic/doc/disqus_identifiers/async_sync.html new file mode 100644 index 00000000..c8b864bf --- /dev/null +++ b/attic/doc/disqus_identifiers/async_sync.html @@ -0,0 +1,4 @@ +<script type="text/javascript"> +var disqus_identifier = 'async_sync'; +var disqus_title = 'Boost.AFIO async_sync'; +</script> diff --git a/attic/doc/disqus_identifiers/async_truncate.html b/attic/doc/disqus_identifiers/async_truncate.html new file mode 100644 index 00000000..f6d3e379 --- /dev/null +++ b/attic/doc/disqus_identifiers/async_truncate.html @@ -0,0 +1,4 @@ +<script type="text/javascript"> +var disqus_identifier = 'async_truncate'; +var disqus_title = 'Boost.AFIO async_truncate'; +</script> diff --git a/attic/doc/disqus_identifiers/async_write_3_length_deducing.html b/attic/doc/disqus_identifiers/async_write_3_length_deducing.html new file mode 100644 index 00000000..c746931d --- /dev/null +++ b/attic/doc/disqus_identifiers/async_write_3_length_deducing.html @@ -0,0 +1,4 @@ +<script type="text/javascript"> +var disqus_identifier = 'async_write_3_length_deducing'; +var disqus_title = 'Boost.AFIO async_write (length deducing)'; +</script> diff --git a/attic/doc/disqus_identifiers/async_write_4_length_specifying.html b/attic/doc/disqus_identifiers/async_write_4_length_specifying.html new file mode 100644 index 00000000..aaf1dfe3 --- /dev/null +++ b/attic/doc/disqus_identifiers/async_write_4_length_specifying.html @@ -0,0 +1,4 @@ +<script type="text/javascript"> +var disqus_identifier = 'async_write_4_length_specifying'; +var disqus_title = 'Boost.AFIO async_write (length specifying)'; +</script> diff --git a/attic/doc/disqus_identifiers/async_zero.html b/attic/doc/disqus_identifiers/async_zero.html new file mode 100644 index 00000000..ac2fdbf3 --- /dev/null +++ b/attic/doc/disqus_identifiers/async_zero.html @@ -0,0 +1,4 @@ +<script type="text/javascript"> +var disqus_identifier = 'async_zero'; +var disqus_title = 'Boost.AFIO async_zero'; +</script> diff --git a/attic/doc/disqus_identifiers/atomic_logging.html b/attic/doc/disqus_identifiers/atomic_logging.html new file mode 100644 index 00000000..fabd3186 --- /dev/null +++ b/attic/doc/disqus_identifiers/atomic_logging.html @@ -0,0 +1,4 @@ +<script type="text/javascript"> +var disqus_identifier = 'atomic_logging'; +var disqus_title = 'Boost.AFIO Achieving atomicity on the filing system'; +</script> diff --git a/attic/doc/disqus_identifiers/atomic_relink.html b/attic/doc/disqus_identifiers/atomic_relink.html new file mode 100644 index 00000000..baff8655 --- /dev/null +++ b/attic/doc/disqus_identifiers/atomic_relink.html @@ -0,0 +1,4 @@ +<script type="text/javascript"> +var disqus_identifier = 'atomic_relink'; +var disqus_title = 'Boost.AFIO atomic_relink'; +</script> diff --git a/attic/doc/disqus_identifiers/boost_afio_validate_inputs.html b/attic/doc/disqus_identifiers/boost_afio_validate_inputs.html new file mode 100644 index 00000000..04b38e87 --- /dev/null +++ b/attic/doc/disqus_identifiers/boost_afio_validate_inputs.html @@ -0,0 +1,4 @@ +<script type="text/javascript"> +var disqus_identifier = 'boost_afio_validate_inputs'; +var disqus_title = 'Boost.AFIO BOOST_AFIO_VALIDATE_INPUTS'; +</script> diff --git a/attic/doc/disqus_identifiers/close_1_batch.html b/attic/doc/disqus_identifiers/close_1_batch.html new file mode 100644 index 00000000..16966b7d --- /dev/null +++ b/attic/doc/disqus_identifiers/close_1_batch.html @@ -0,0 +1,4 @@ +<script type="text/javascript"> +var disqus_identifier = 'close_1_batch'; +var disqus_title = 'Boost.AFIO close (batch)'; +</script> diff --git a/attic/doc/disqus_identifiers/close_1_throwing.html b/attic/doc/disqus_identifiers/close_1_throwing.html new file mode 100644 index 00000000..3b5805c3 --- /dev/null +++ b/attic/doc/disqus_identifiers/close_1_throwing.html @@ -0,0 +1,4 @@ +<script type="text/javascript"> +var disqus_identifier = 'close_1_throwing'; +var disqus_title = 'Boost.AFIO close (throwing)'; +</script> diff --git a/attic/doc/disqus_identifiers/close_2_non_throwing.html b/attic/doc/disqus_identifiers/close_2_non_throwing.html new file mode 100644 index 00000000..f54a7f4f --- /dev/null +++ b/attic/doc/disqus_identifiers/close_2_non_throwing.html @@ -0,0 +1,4 @@ +<script type="text/javascript"> +var disqus_identifier = 'close_2_non_throwing'; +var disqus_title = 'Boost.AFIO close (non throwing)'; +</script> diff --git a/attic/doc/disqus_identifiers/compilation.html b/attic/doc/disqus_identifiers/compilation.html new file mode 100644 index 00000000..ba4f9c05 --- /dev/null +++ b/attic/doc/disqus_identifiers/compilation.html @@ -0,0 +1,4 @@ +<script type="text/javascript"> +var disqus_identifier = 'compilation'; +var disqus_title = 'Boost.AFIO Compilation'; +</script> diff --git a/attic/doc/disqus_identifiers/complete_async_op_2_errored.html b/attic/doc/disqus_identifiers/complete_async_op_2_errored.html new file mode 100644 index 00000000..62eb6a5f --- /dev/null +++ b/attic/doc/disqus_identifiers/complete_async_op_2_errored.html @@ -0,0 +1,4 @@ +<script type="text/javascript"> +var disqus_identifier = 'complete_async_op_2_errored'; +var disqus_title = 'Boost.AFIO complete_async_op (errored)'; +</script> diff --git a/attic/doc/disqus_identifiers/complete_async_op_3_normal.html b/attic/doc/disqus_identifiers/complete_async_op_3_normal.html new file mode 100644 index 00000000..3105f198 --- /dev/null +++ b/attic/doc/disqus_identifiers/complete_async_op_3_normal.html @@ -0,0 +1,4 @@ +<script type="text/javascript"> +var disqus_identifier = 'complete_async_op_3_normal'; +var disqus_title = 'Boost.AFIO complete_async_op (normal)'; +</script> diff --git a/attic/doc/disqus_identifiers/current_dispatcher.html b/attic/doc/disqus_identifiers/current_dispatcher.html new file mode 100644 index 00000000..db0db905 --- /dev/null +++ b/attic/doc/disqus_identifiers/current_dispatcher.html @@ -0,0 +1,4 @@ +<script type="text/javascript"> +var disqus_identifier = 'current_dispatcher'; +var disqus_title = 'Boost.AFIO current_dispatcher'; +</script> diff --git a/attic/doc/disqus_identifiers/current_dispatcher_guard.html b/attic/doc/disqus_identifiers/current_dispatcher_guard.html new file mode 100644 index 00000000..616ba439 --- /dev/null +++ b/attic/doc/disqus_identifiers/current_dispatcher_guard.html @@ -0,0 +1,4 @@ +<script type="text/javascript"> +var disqus_identifier = 'current_dispatcher_guard'; +var disqus_title = 'Boost.AFIO current_dispatcher_guard'; +</script> diff --git a/attic/doc/disqus_identifiers/depends.html b/attic/doc/disqus_identifiers/depends.html new file mode 100644 index 00000000..38cde85b --- /dev/null +++ b/attic/doc/disqus_identifiers/depends.html @@ -0,0 +1,4 @@ +<script type="text/javascript"> +var disqus_identifier = 'depends'; +var disqus_title = 'Boost.AFIO depends'; +</script> diff --git a/attic/doc/disqus_identifiers/design_rationale.html b/attic/doc/disqus_identifiers/design_rationale.html new file mode 100644 index 00000000..86a3c735 --- /dev/null +++ b/attic/doc/disqus_identifiers/design_rationale.html @@ -0,0 +1,4 @@ +<script type="text/javascript"> +var disqus_identifier = 'design_rationale'; +var disqus_title = 'Boost.AFIO Design Introduction and Rationale'; +</script> diff --git a/attic/doc/disqus_identifiers/dir_1_batch.html b/attic/doc/disqus_identifiers/dir_1_batch.html new file mode 100644 index 00000000..a3233b3a --- /dev/null +++ b/attic/doc/disqus_identifiers/dir_1_batch.html @@ -0,0 +1,4 @@ +<script type="text/javascript"> +var disqus_identifier = 'dir_1_batch'; +var disqus_title = 'Boost.AFIO dir (batch)'; +</script> diff --git a/attic/doc/disqus_identifiers/dir_2_absolute_throwing.html b/attic/doc/disqus_identifiers/dir_2_absolute_throwing.html new file mode 100644 index 00000000..f47d4d8f --- /dev/null +++ b/attic/doc/disqus_identifiers/dir_2_absolute_throwing.html @@ -0,0 +1,4 @@ +<script type="text/javascript"> +var disqus_identifier = 'dir_2_absolute_throwing'; +var disqus_title = 'Boost.AFIO dir (absolute throwing)'; +</script> diff --git a/attic/doc/disqus_identifiers/dir_3_absolute_non_throwing.html b/attic/doc/disqus_identifiers/dir_3_absolute_non_throwing.html new file mode 100644 index 00000000..a6412efd --- /dev/null +++ b/attic/doc/disqus_identifiers/dir_3_absolute_non_throwing.html @@ -0,0 +1,4 @@ +<script type="text/javascript"> +var disqus_identifier = 'dir_3_absolute_non_throwing'; +var disqus_title = 'Boost.AFIO dir (absolute non throwing)'; +</script> diff --git a/attic/doc/disqus_identifiers/dir_3_relative_throwing.html b/attic/doc/disqus_identifiers/dir_3_relative_throwing.html new file mode 100644 index 00000000..c1b7ebfd --- /dev/null +++ b/attic/doc/disqus_identifiers/dir_3_relative_throwing.html @@ -0,0 +1,4 @@ +<script type="text/javascript"> +var disqus_identifier = 'dir_3_relative_throwing'; +var disqus_title = 'Boost.AFIO dir (relative throwing)'; +</script> diff --git a/attic/doc/disqus_identifiers/dir_4_relative_non_throwing.html b/attic/doc/disqus_identifiers/dir_4_relative_non_throwing.html new file mode 100644 index 00000000..d344ce32 --- /dev/null +++ b/attic/doc/disqus_identifiers/dir_4_relative_non_throwing.html @@ -0,0 +1,4 @@ +<script type="text/javascript"> +var disqus_identifier = 'dir_4_relative_non_throwing'; +var disqus_title = 'Boost.AFIO dir (relative non throwing)'; +</script> diff --git a/attic/doc/disqus_identifiers/directory_entry.html b/attic/doc/disqus_identifiers/directory_entry.html new file mode 100644 index 00000000..3296f02b --- /dev/null +++ b/attic/doc/disqus_identifiers/directory_entry.html @@ -0,0 +1,4 @@ +<script type="text/javascript"> +var disqus_identifier = 'directory_entry'; +var disqus_title = 'Boost.AFIO directory_entry'; +</script> diff --git a/attic/doc/disqus_identifiers/directory_entry_hash.html b/attic/doc/disqus_identifiers/directory_entry_hash.html new file mode 100644 index 00000000..3648f329 --- /dev/null +++ b/attic/doc/disqus_identifiers/directory_entry_hash.html @@ -0,0 +1,4 @@ +<script type="text/javascript"> +var disqus_identifier = 'directory_entry_hash'; +var disqus_title = 'Boost.AFIO directory_entry_hash'; +</script> diff --git a/attic/doc/disqus_identifiers/direntry.html b/attic/doc/disqus_identifiers/direntry.html new file mode 100644 index 00000000..2de1ad6e --- /dev/null +++ b/attic/doc/disqus_identifiers/direntry.html @@ -0,0 +1,4 @@ +<script type="text/javascript"> +var disqus_identifier = 'direntry'; +var disqus_title = 'Boost.AFIO direntry'; +</script> diff --git a/attic/doc/disqus_identifiers/dispatcher.html b/attic/doc/disqus_identifiers/dispatcher.html new file mode 100644 index 00000000..857985c1 --- /dev/null +++ b/attic/doc/disqus_identifiers/dispatcher.html @@ -0,0 +1,4 @@ +<script type="text/javascript"> +var disqus_identifier = 'dispatcher'; +var disqus_title = 'Boost.AFIO dispatcher'; +</script> diff --git a/attic/doc/disqus_identifiers/enqueued_task.html b/attic/doc/disqus_identifiers/enqueued_task.html new file mode 100644 index 00000000..137233d7 --- /dev/null +++ b/attic/doc/disqus_identifiers/enqueued_task.html @@ -0,0 +1,4 @@ +<script type="text/javascript"> +var disqus_identifier = 'enqueued_task'; +var disqus_title = 'Boost.AFIO enqueued_task'; +</script> diff --git a/attic/doc/disqus_identifiers/enqueued_task_r___.html b/attic/doc/disqus_identifiers/enqueued_task_r___.html new file mode 100644 index 00000000..40a724a8 --- /dev/null +++ b/attic/doc/disqus_identifiers/enqueued_task_r___.html @@ -0,0 +1,4 @@ +<script type="text/javascript"> +var disqus_identifier = 'enqueued_task_r___'; +var disqus_title = 'Boost.AFIO enqueued_task< R()>'; +</script> diff --git a/attic/doc/disqus_identifiers/enqueued_task_void___.html b/attic/doc/disqus_identifiers/enqueued_task_void___.html new file mode 100644 index 00000000..97a496c0 --- /dev/null +++ b/attic/doc/disqus_identifiers/enqueued_task_void___.html @@ -0,0 +1,4 @@ +<script type="text/javascript"> +var disqus_identifier = 'enqueued_task_void___'; +var disqus_title = 'Boost.AFIO enqueued_task< void()>'; +</script> diff --git a/attic/doc/disqus_identifiers/enumerate_1_batch.html b/attic/doc/disqus_identifiers/enumerate_1_batch.html new file mode 100644 index 00000000..aa429d0c --- /dev/null +++ b/attic/doc/disqus_identifiers/enumerate_1_batch.html @@ -0,0 +1,4 @@ +<script type="text/javascript"> +var disqus_identifier = 'enumerate_1_batch'; +var disqus_title = 'Boost.AFIO enumerate (batch)'; +</script> diff --git a/attic/doc/disqus_identifiers/enumerate_6_glob_first_throwing.html b/attic/doc/disqus_identifiers/enumerate_6_glob_first_throwing.html new file mode 100644 index 00000000..eb6f9df9 --- /dev/null +++ b/attic/doc/disqus_identifiers/enumerate_6_glob_first_throwing.html @@ -0,0 +1,4 @@ +<script type="text/javascript"> +var disqus_identifier = 'enumerate_6_glob_first_throwing'; +var disqus_title = 'Boost.AFIO enumerate (glob first throwing)'; +</script> diff --git a/attic/doc/disqus_identifiers/enumerate_6_max_items_first_throwing.html b/attic/doc/disqus_identifiers/enumerate_6_max_items_first_throwing.html new file mode 100644 index 00000000..f0a922bf --- /dev/null +++ b/attic/doc/disqus_identifiers/enumerate_6_max_items_first_throwing.html @@ -0,0 +1,4 @@ +<script type="text/javascript"> +var disqus_identifier = 'enumerate_6_max_items_first_throwing'; +var disqus_title = 'Boost.AFIO enumerate (max items first throwing)'; +</script> diff --git a/attic/doc/disqus_identifiers/enumerate_6_metadata_first_throwing.html b/attic/doc/disqus_identifiers/enumerate_6_metadata_first_throwing.html new file mode 100644 index 00000000..e46c7492 --- /dev/null +++ b/attic/doc/disqus_identifiers/enumerate_6_metadata_first_throwing.html @@ -0,0 +1,4 @@ +<script type="text/javascript"> +var disqus_identifier = 'enumerate_6_metadata_first_throwing'; +var disqus_title = 'Boost.AFIO enumerate (metadata first throwing)'; +</script> diff --git a/attic/doc/disqus_identifiers/enumerate_7_glob_first_non_throwing.html b/attic/doc/disqus_identifiers/enumerate_7_glob_first_non_throwing.html new file mode 100644 index 00000000..d91c7de6 --- /dev/null +++ b/attic/doc/disqus_identifiers/enumerate_7_glob_first_non_throwing.html @@ -0,0 +1,4 @@ +<script type="text/javascript"> +var disqus_identifier = 'enumerate_7_glob_first_non_throwing'; +var disqus_title = 'Boost.AFIO enumerate (glob first non throwing)'; +</script> diff --git a/attic/doc/disqus_identifiers/enumerate_7_max_items_first_non_throwing.html b/attic/doc/disqus_identifiers/enumerate_7_max_items_first_non_throwing.html new file mode 100644 index 00000000..e3ac326f --- /dev/null +++ b/attic/doc/disqus_identifiers/enumerate_7_max_items_first_non_throwing.html @@ -0,0 +1,4 @@ +<script type="text/javascript"> +var disqus_identifier = 'enumerate_7_max_items_first_non_throwing'; +var disqus_title = 'Boost.AFIO enumerate (max items first non throwing)'; +</script> diff --git a/attic/doc/disqus_identifiers/enumerate_7_metadata_first_non_throwing.html b/attic/doc/disqus_identifiers/enumerate_7_metadata_first_non_throwing.html new file mode 100644 index 00000000..b29b2662 --- /dev/null +++ b/attic/doc/disqus_identifiers/enumerate_7_metadata_first_non_throwing.html @@ -0,0 +1,4 @@ +<script type="text/javascript"> +var disqus_identifier = 'enumerate_7_metadata_first_non_throwing'; +var disqus_title = 'Boost.AFIO enumerate (metadata first non throwing)'; +</script> diff --git a/attic/doc/disqus_identifiers/enumerate_req.html b/attic/doc/disqus_identifiers/enumerate_req.html new file mode 100644 index 00000000..83ba5797 --- /dev/null +++ b/attic/doc/disqus_identifiers/enumerate_req.html @@ -0,0 +1,4 @@ +<script type="text/javascript"> +var disqus_identifier = 'enumerate_req'; +var disqus_title = 'Boost.AFIO enumerate_req'; +</script> diff --git a/attic/doc/disqus_identifiers/extents_1_batch.html b/attic/doc/disqus_identifiers/extents_1_batch.html new file mode 100644 index 00000000..7b65be4f --- /dev/null +++ b/attic/doc/disqus_identifiers/extents_1_batch.html @@ -0,0 +1,4 @@ +<script type="text/javascript"> +var disqus_identifier = 'extents_1_batch'; +var disqus_title = 'Boost.AFIO extents (batch)'; +</script> diff --git a/attic/doc/disqus_identifiers/extents_1_throwing.html b/attic/doc/disqus_identifiers/extents_1_throwing.html new file mode 100644 index 00000000..5cc507b1 --- /dev/null +++ b/attic/doc/disqus_identifiers/extents_1_throwing.html @@ -0,0 +1,4 @@ +<script type="text/javascript"> +var disqus_identifier = 'extents_1_throwing'; +var disqus_title = 'Boost.AFIO extents (throwing)'; +</script> diff --git a/attic/doc/disqus_identifiers/extents_2_non_throwing.html b/attic/doc/disqus_identifiers/extents_2_non_throwing.html new file mode 100644 index 00000000..d9ef8a1e --- /dev/null +++ b/attic/doc/disqus_identifiers/extents_2_non_throwing.html @@ -0,0 +1,4 @@ +<script type="text/javascript"> +var disqus_identifier = 'extents_2_non_throwing'; +var disqus_title = 'Boost.AFIO extents (non throwing)'; +</script> diff --git a/attic/doc/disqus_identifiers/file_1_batch.html b/attic/doc/disqus_identifiers/file_1_batch.html new file mode 100644 index 00000000..16138891 --- /dev/null +++ b/attic/doc/disqus_identifiers/file_1_batch.html @@ -0,0 +1,4 @@ +<script type="text/javascript"> +var disqus_identifier = 'file_1_batch'; +var disqus_title = 'Boost.AFIO file (batch)'; +</script> diff --git a/attic/doc/disqus_identifiers/file_2_absolute_throwing.html b/attic/doc/disqus_identifiers/file_2_absolute_throwing.html new file mode 100644 index 00000000..aa29f2a7 --- /dev/null +++ b/attic/doc/disqus_identifiers/file_2_absolute_throwing.html @@ -0,0 +1,4 @@ +<script type="text/javascript"> +var disqus_identifier = 'file_2_absolute_throwing'; +var disqus_title = 'Boost.AFIO file (absolute throwing)'; +</script> diff --git a/attic/doc/disqus_identifiers/file_3_absolute_non_throwing.html b/attic/doc/disqus_identifiers/file_3_absolute_non_throwing.html new file mode 100644 index 00000000..8e2823ef --- /dev/null +++ b/attic/doc/disqus_identifiers/file_3_absolute_non_throwing.html @@ -0,0 +1,4 @@ +<script type="text/javascript"> +var disqus_identifier = 'file_3_absolute_non_throwing'; +var disqus_title = 'Boost.AFIO file (absolute non throwing)'; +</script> diff --git a/attic/doc/disqus_identifiers/file_3_relative_throwing.html b/attic/doc/disqus_identifiers/file_3_relative_throwing.html new file mode 100644 index 00000000..d33f7ba5 --- /dev/null +++ b/attic/doc/disqus_identifiers/file_3_relative_throwing.html @@ -0,0 +1,4 @@ +<script type="text/javascript"> +var disqus_identifier = 'file_3_relative_throwing'; +var disqus_title = 'Boost.AFIO file (relative throwing)'; +</script> diff --git a/attic/doc/disqus_identifiers/file_4_relative_non_throwing.html b/attic/doc/disqus_identifiers/file_4_relative_non_throwing.html new file mode 100644 index 00000000..87da22c6 --- /dev/null +++ b/attic/doc/disqus_identifiers/file_4_relative_non_throwing.html @@ -0,0 +1,4 @@ +<script type="text/javascript"> +var disqus_identifier = 'file_4_relative_non_throwing'; +var disqus_title = 'Boost.AFIO file (relative non throwing)'; +</script> diff --git a/attic/doc/disqus_identifiers/file_buffer_default_size.html b/attic/doc/disqus_identifiers/file_buffer_default_size.html new file mode 100644 index 00000000..5b01320d --- /dev/null +++ b/attic/doc/disqus_identifiers/file_buffer_default_size.html @@ -0,0 +1,4 @@ +<script type="text/javascript"> +var disqus_identifier = 'file_buffer_default_size'; +var disqus_title = 'Boost.AFIO file_buffer_default_size'; +</script> diff --git a/attic/doc/disqus_identifiers/file_concat.html b/attic/doc/disqus_identifiers/file_concat.html new file mode 100644 index 00000000..2734ee7a --- /dev/null +++ b/attic/doc/disqus_identifiers/file_concat.html @@ -0,0 +1,4 @@ +<script type="text/javascript"> +var disqus_identifier = 'file_concat'; +var disqus_title = 'Boost.AFIO Concatenating files'; +</script> diff --git a/attic/doc/disqus_identifiers/file_flags.html b/attic/doc/disqus_identifiers/file_flags.html new file mode 100644 index 00000000..30ab0cf1 --- /dev/null +++ b/attic/doc/disqus_identifiers/file_flags.html @@ -0,0 +1,4 @@ +<script type="text/javascript"> +var disqus_identifier = 'file_flags'; +var disqus_title = 'Boost.AFIO file_flags'; +</script> diff --git a/attic/doc/disqus_identifiers/filesystem_races.html b/attic/doc/disqus_identifiers/filesystem_races.html new file mode 100644 index 00000000..983c7068 --- /dev/null +++ b/attic/doc/disqus_identifiers/filesystem_races.html @@ -0,0 +1,4 @@ +<script type="text/javascript"> +var disqus_identifier = 'filesystem_races'; +var disqus_title = 'Boost.AFIO Handling races on the filing system'; +</script> diff --git a/attic/doc/disqus_identifiers/filter.html b/attic/doc/disqus_identifiers/filter.html new file mode 100644 index 00000000..a5ee0da8 --- /dev/null +++ b/attic/doc/disqus_identifiers/filter.html @@ -0,0 +1,4 @@ +<script type="text/javascript"> +var disqus_identifier = 'filter'; +var disqus_title = 'Boost.AFIO filter'; +</script> diff --git a/attic/doc/disqus_identifiers/from_hex_string.html b/attic/doc/disqus_identifiers/from_hex_string.html new file mode 100644 index 00000000..62ff2557 --- /dev/null +++ b/attic/doc/disqus_identifiers/from_hex_string.html @@ -0,0 +1,4 @@ +<script type="text/javascript"> +var disqus_identifier = 'from_hex_string'; +var disqus_title = 'Boost.AFIO from_hex_string'; +</script> diff --git a/attic/doc/disqus_identifiers/fs_metadata_flags.html b/attic/doc/disqus_identifiers/fs_metadata_flags.html new file mode 100644 index 00000000..385aeb5b --- /dev/null +++ b/attic/doc/disqus_identifiers/fs_metadata_flags.html @@ -0,0 +1,4 @@ +<script type="text/javascript"> +var disqus_identifier = 'fs_metadata_flags'; +var disqus_title = 'Boost.AFIO fs_metadata_flags'; +</script> diff --git a/attic/doc/disqus_identifiers/future.html b/attic/doc/disqus_identifiers/future.html new file mode 100644 index 00000000..ff4ec506 --- /dev/null +++ b/attic/doc/disqus_identifiers/future.html @@ -0,0 +1,4 @@ +<script type="text/javascript"> +var disqus_identifier = 'future'; +var disqus_title = 'Boost.AFIO future'; +</script> diff --git a/attic/doc/disqus_identifiers/future_void_.html b/attic/doc/disqus_identifiers/future_void_.html new file mode 100644 index 00000000..9c66b728 --- /dev/null +++ b/attic/doc/disqus_identifiers/future_void_.html @@ -0,0 +1,4 @@ +<script type="text/javascript"> +var disqus_identifier = 'future_void_'; +var disqus_title = 'Boost.AFIO future< void >'; +</script> diff --git a/attic/doc/disqus_identifiers/handle.html b/attic/doc/disqus_identifiers/handle.html new file mode 100644 index 00000000..5b2716de --- /dev/null +++ b/attic/doc/disqus_identifiers/handle.html @@ -0,0 +1,4 @@ +<script type="text/javascript"> +var disqus_identifier = 'handle'; +var disqus_title = 'Boost.AFIO handle'; +</script> diff --git a/attic/doc/disqus_identifiers/handle_mapped_file.html b/attic/doc/disqus_identifiers/handle_mapped_file.html new file mode 100644 index 00000000..5d15abaa --- /dev/null +++ b/attic/doc/disqus_identifiers/handle_mapped_file.html @@ -0,0 +1,4 @@ +<script type="text/javascript"> +var disqus_identifier = 'handle_mapped_file'; +var disqus_title = 'Boost.AFIO handle::mapped_file'; +</script> diff --git a/attic/doc/disqus_identifiers/hello_world.html b/attic/doc/disqus_identifiers/hello_world.html new file mode 100644 index 00000000..a1440b38 --- /dev/null +++ b/attic/doc/disqus_identifiers/hello_world.html @@ -0,0 +1,4 @@ +<script type="text/javascript"> +var disqus_identifier = 'hello_world'; +var disqus_title = 'Boost.AFIO Hello World, asynchronously!'; +</script> diff --git a/attic/doc/disqus_identifiers/introduction.html b/attic/doc/disqus_identifiers/introduction.html new file mode 100644 index 00000000..cc7a7d42 --- /dev/null +++ b/attic/doc/disqus_identifiers/introduction.html @@ -0,0 +1,4 @@ +<script type="text/javascript"> +var disqus_identifier = 'introduction'; +var disqus_title = 'Boost.AFIO Introduction'; +</script> diff --git a/attic/doc/disqus_identifiers/io_req.html b/attic/doc/disqus_identifiers/io_req.html new file mode 100644 index 00000000..7e15efc9 --- /dev/null +++ b/attic/doc/disqus_identifiers/io_req.html @@ -0,0 +1,4 @@ +<script type="text/javascript"> +var disqus_identifier = 'io_req'; +var disqus_title = 'Boost.AFIO io_req'; +</script> diff --git a/attic/doc/disqus_identifiers/io_req_constt_.html b/attic/doc/disqus_identifiers/io_req_constt_.html new file mode 100644 index 00000000..fe03917d --- /dev/null +++ b/attic/doc/disqus_identifiers/io_req_constt_.html @@ -0,0 +1,4 @@ +<script type="text/javascript"> +var disqus_identifier = 'io_req_constt_'; +var disqus_title = 'Boost.AFIO io_req< const T >'; +</script> diff --git a/attic/doc/disqus_identifiers/io_req_constvoid_.html b/attic/doc/disqus_identifiers/io_req_constvoid_.html new file mode 100644 index 00000000..47407ae9 --- /dev/null +++ b/attic/doc/disqus_identifiers/io_req_constvoid_.html @@ -0,0 +1,4 @@ +<script type="text/javascript"> +var disqus_identifier = 'io_req_constvoid_'; +var disqus_title = 'Boost.AFIO io_req< const void >'; +</script> diff --git a/attic/doc/disqus_identifiers/io_req_void_.html b/attic/doc/disqus_identifiers/io_req_void_.html new file mode 100644 index 00000000..00f200d3 --- /dev/null +++ b/attic/doc/disqus_identifiers/io_req_void_.html @@ -0,0 +1,4 @@ +<script type="text/javascript"> +var disqus_identifier = 'io_req_void_'; +var disqus_title = 'Boost.AFIO io_req< void >'; +</script> diff --git a/attic/doc/disqus_identifiers/is_future.html b/attic/doc/disqus_identifiers/is_future.html new file mode 100644 index 00000000..480024da --- /dev/null +++ b/attic/doc/disqus_identifiers/is_future.html @@ -0,0 +1,4 @@ +<script type="text/javascript"> +var disqus_identifier = 'is_future'; +var disqus_title = 'Boost.AFIO is_future'; +</script> diff --git a/attic/doc/disqus_identifiers/is_future_-future_-t-_.html b/attic/doc/disqus_identifiers/is_future_-future_-t-_.html new file mode 100644 index 00000000..3653e1c8 --- /dev/null +++ b/attic/doc/disqus_identifiers/is_future_-future_-t-_.html @@ -0,0 +1,4 @@ +<script type="text/javascript"> +var disqus_identifier = 'is_future_-future_-t-_'; +var disqus_title = 'Boost.AFIO > is_future< future< T > >'; +</script> diff --git a/attic/doc/disqus_identifiers/link.html b/attic/doc/disqus_identifiers/link.html new file mode 100644 index 00000000..c1c169f1 --- /dev/null +++ b/attic/doc/disqus_identifiers/link.html @@ -0,0 +1,4 @@ +<script type="text/javascript"> +var disqus_identifier = 'link'; +var disqus_title = 'Boost.AFIO link'; +</script> diff --git a/attic/doc/disqus_identifiers/lock_req.html b/attic/doc/disqus_identifiers/lock_req.html new file mode 100644 index 00000000..cb97f9db --- /dev/null +++ b/attic/doc/disqus_identifiers/lock_req.html @@ -0,0 +1,4 @@ +<script type="text/javascript"> +var disqus_identifier = 'lock_req'; +var disqus_title = 'Boost.AFIO lock_req'; +</script> diff --git a/attic/doc/disqus_identifiers/make_dispatcher.html b/attic/doc/disqus_identifiers/make_dispatcher.html new file mode 100644 index 00000000..62ddcb44 --- /dev/null +++ b/attic/doc/disqus_identifiers/make_dispatcher.html @@ -0,0 +1,4 @@ +<script type="text/javascript"> +var disqus_identifier = 'make_dispatcher'; +var disqus_title = 'Boost.AFIO make_dispatcher'; +</script> diff --git a/attic/doc/disqus_identifiers/make_io_req_3_length_deducing.html b/attic/doc/disqus_identifiers/make_io_req_3_length_deducing.html new file mode 100644 index 00000000..b00e3326 --- /dev/null +++ b/attic/doc/disqus_identifiers/make_io_req_3_length_deducing.html @@ -0,0 +1,4 @@ +<script type="text/javascript"> +var disqus_identifier = 'make_io_req_3_length_deducing'; +var disqus_title = 'Boost.AFIO make_io_req (length deducing)'; +</script> diff --git a/attic/doc/disqus_identifiers/make_io_req_4_length_specifying.html b/attic/doc/disqus_identifiers/make_io_req_4_length_specifying.html new file mode 100644 index 00000000..ad6b8e79 --- /dev/null +++ b/attic/doc/disqus_identifiers/make_io_req_4_length_specifying.html @@ -0,0 +1,4 @@ +<script type="text/javascript"> +var disqus_identifier = 'make_io_req_4_length_specifying'; +var disqus_title = 'Boost.AFIO make_io_req (length specifying)'; +</script> diff --git a/attic/doc/disqus_identifiers/metadata_flags.html b/attic/doc/disqus_identifiers/metadata_flags.html new file mode 100644 index 00000000..dafb37b9 --- /dev/null +++ b/attic/doc/disqus_identifiers/metadata_flags.html @@ -0,0 +1,4 @@ +<script type="text/javascript"> +var disqus_identifier = 'metadata_flags'; +var disqus_title = 'Boost.AFIO metadata_flags'; +</script> diff --git a/attic/doc/disqus_identifiers/normalise_path.html b/attic/doc/disqus_identifiers/normalise_path.html new file mode 100644 index 00000000..baaefbda --- /dev/null +++ b/attic/doc/disqus_identifiers/normalise_path.html @@ -0,0 +1,4 @@ +<script type="text/javascript"> +var disqus_identifier = 'normalise_path'; +var disqus_title = 'Boost.AFIO normalise_path'; +</script> diff --git a/attic/doc/disqus_identifiers/open_states.html b/attic/doc/disqus_identifiers/open_states.html new file mode 100644 index 00000000..f841a7f2 --- /dev/null +++ b/attic/doc/disqus_identifiers/open_states.html @@ -0,0 +1,4 @@ +<script type="text/javascript"> +var disqus_identifier = 'open_states'; +var disqus_title = 'Boost.AFIO open_states'; +</script> diff --git a/attic/doc/disqus_identifiers/overview.html b/attic/doc/disqus_identifiers/overview.html new file mode 100644 index 00000000..b9d818d8 --- /dev/null +++ b/attic/doc/disqus_identifiers/overview.html @@ -0,0 +1,4 @@ +<script type="text/javascript"> +var disqus_identifier = 'overview'; +var disqus_title = 'Boost.AFIO Single page cheat sheet'; +</script> diff --git a/attic/doc/disqus_identifiers/page_sizes.html b/attic/doc/disqus_identifiers/page_sizes.html new file mode 100644 index 00000000..5844ce0a --- /dev/null +++ b/attic/doc/disqus_identifiers/page_sizes.html @@ -0,0 +1,4 @@ +<script type="text/javascript"> +var disqus_identifier = 'page_sizes'; +var disqus_title = 'Boost.AFIO page_sizes'; +</script> diff --git a/attic/doc/disqus_identifiers/path.html b/attic/doc/disqus_identifiers/path.html new file mode 100644 index 00000000..45103272 --- /dev/null +++ b/attic/doc/disqus_identifiers/path.html @@ -0,0 +1,4 @@ +<script type="text/javascript"> +var disqus_identifier = 'path'; +var disqus_title = 'Boost.AFIO path'; +</script> diff --git a/attic/doc/disqus_identifiers/path_direct.html b/attic/doc/disqus_identifiers/path_direct.html new file mode 100644 index 00000000..ff27a444 --- /dev/null +++ b/attic/doc/disqus_identifiers/path_direct.html @@ -0,0 +1,4 @@ +<script type="text/javascript"> +var disqus_identifier = 'path_direct'; +var disqus_title = 'Boost.AFIO path::direct'; +</script> diff --git a/attic/doc/disqus_identifiers/path_hash.html b/attic/doc/disqus_identifiers/path_hash.html new file mode 100644 index 00000000..e8b57dbb --- /dev/null +++ b/attic/doc/disqus_identifiers/path_hash.html @@ -0,0 +1,4 @@ +<script type="text/javascript"> +var disqus_identifier = 'path_hash'; +var disqus_title = 'Boost.AFIO path_hash'; +</script> diff --git a/attic/doc/disqus_identifiers/path_make_absolute.html b/attic/doc/disqus_identifiers/path_make_absolute.html new file mode 100644 index 00000000..5dbed920 --- /dev/null +++ b/attic/doc/disqus_identifiers/path_make_absolute.html @@ -0,0 +1,4 @@ +<script type="text/javascript"> +var disqus_identifier = 'path_make_absolute'; +var disqus_title = 'Boost.AFIO path::make_absolute'; +</script> diff --git a/attic/doc/disqus_identifiers/path_req.html b/attic/doc/disqus_identifiers/path_req.html new file mode 100644 index 00000000..eba6159d --- /dev/null +++ b/attic/doc/disqus_identifiers/path_req.html @@ -0,0 +1,4 @@ +<script type="text/javascript"> +var disqus_identifier = 'path_req'; +var disqus_title = 'Boost.AFIO path_req'; +</script> diff --git a/attic/doc/disqus_identifiers/path_req_absolute.html b/attic/doc/disqus_identifiers/path_req_absolute.html new file mode 100644 index 00000000..6874d4f2 --- /dev/null +++ b/attic/doc/disqus_identifiers/path_req_absolute.html @@ -0,0 +1,4 @@ +<script type="text/javascript"> +var disqus_identifier = 'path_req_absolute'; +var disqus_title = 'Boost.AFIO path_req::absolute'; +</script> diff --git a/attic/doc/disqus_identifiers/path_req_relative.html b/attic/doc/disqus_identifiers/path_req_relative.html new file mode 100644 index 00000000..3bab0433 --- /dev/null +++ b/attic/doc/disqus_identifiers/path_req_relative.html @@ -0,0 +1,4 @@ +<script type="text/javascript"> +var disqus_identifier = 'path_req_relative'; +var disqus_title = 'Boost.AFIO path_req::relative'; +</script> diff --git a/attic/doc/disqus_identifiers/process_threadpool.html b/attic/doc/disqus_identifiers/process_threadpool.html new file mode 100644 index 00000000..0a47d8cb --- /dev/null +++ b/attic/doc/disqus_identifiers/process_threadpool.html @@ -0,0 +1,4 @@ +<script type="text/javascript"> +var disqus_identifier = 'process_threadpool'; +var disqus_title = 'Boost.AFIO process_threadpool'; +</script> diff --git a/attic/doc/disqus_identifiers/random_fill.html b/attic/doc/disqus_identifiers/random_fill.html new file mode 100644 index 00000000..cb222f67 --- /dev/null +++ b/attic/doc/disqus_identifiers/random_fill.html @@ -0,0 +1,4 @@ +<script type="text/javascript"> +var disqus_identifier = 'random_fill'; +var disqus_title = 'Boost.AFIO random_fill'; +</script> diff --git a/attic/doc/disqus_identifiers/random_string.html b/attic/doc/disqus_identifiers/random_string.html new file mode 100644 index 00000000..5ec46573 --- /dev/null +++ b/attic/doc/disqus_identifiers/random_string.html @@ -0,0 +1,4 @@ +<script type="text/javascript"> +var disqus_identifier = 'random_string'; +var disqus_title = 'Boost.AFIO random_string'; +</script> diff --git a/attic/doc/disqus_identifiers/read_1_batch.html b/attic/doc/disqus_identifiers/read_1_batch.html new file mode 100644 index 00000000..513ad269 --- /dev/null +++ b/attic/doc/disqus_identifiers/read_1_batch.html @@ -0,0 +1,4 @@ +<script type="text/javascript"> +var disqus_identifier = 'read_1_batch'; +var disqus_title = 'Boost.AFIO read (batch)'; +</script> diff --git a/attic/doc/disqus_identifiers/read_3_length_deducing_throwing.html b/attic/doc/disqus_identifiers/read_3_length_deducing_throwing.html new file mode 100644 index 00000000..ed90b51d --- /dev/null +++ b/attic/doc/disqus_identifiers/read_3_length_deducing_throwing.html @@ -0,0 +1,4 @@ +<script type="text/javascript"> +var disqus_identifier = 'read_3_length_deducing_throwing'; +var disqus_title = 'Boost.AFIO read (length deducing throwing)'; +</script> diff --git a/attic/doc/disqus_identifiers/read_4_length_deducing_non_throwing.html b/attic/doc/disqus_identifiers/read_4_length_deducing_non_throwing.html new file mode 100644 index 00000000..95d394a2 --- /dev/null +++ b/attic/doc/disqus_identifiers/read_4_length_deducing_non_throwing.html @@ -0,0 +1,4 @@ +<script type="text/javascript"> +var disqus_identifier = 'read_4_length_deducing_non_throwing'; +var disqus_title = 'Boost.AFIO read (length deducing non throwing)'; +</script> diff --git a/attic/doc/disqus_identifiers/read_4_length_specifying_throwing.html b/attic/doc/disqus_identifiers/read_4_length_specifying_throwing.html new file mode 100644 index 00000000..58acd552 --- /dev/null +++ b/attic/doc/disqus_identifiers/read_4_length_specifying_throwing.html @@ -0,0 +1,4 @@ +<script type="text/javascript"> +var disqus_identifier = 'read_4_length_specifying_throwing'; +var disqus_title = 'Boost.AFIO read (length specifying throwing)'; +</script> diff --git a/attic/doc/disqus_identifiers/read_5_length_specifying_non_throwing.html b/attic/doc/disqus_identifiers/read_5_length_specifying_non_throwing.html new file mode 100644 index 00000000..ae41f5ba --- /dev/null +++ b/attic/doc/disqus_identifiers/read_5_length_specifying_non_throwing.html @@ -0,0 +1,4 @@ +<script type="text/javascript"> +var disqus_identifier = 'read_5_length_specifying_non_throwing'; +var disqus_title = 'Boost.AFIO read (length specifying non throwing)'; +</script> diff --git a/attic/doc/disqus_identifiers/rmdir_1_batch.html b/attic/doc/disqus_identifiers/rmdir_1_batch.html new file mode 100644 index 00000000..7358e4a6 --- /dev/null +++ b/attic/doc/disqus_identifiers/rmdir_1_batch.html @@ -0,0 +1,4 @@ +<script type="text/javascript"> +var disqus_identifier = 'rmdir_1_batch'; +var disqus_title = 'Boost.AFIO rmdir (batch)'; +</script> diff --git a/attic/doc/disqus_identifiers/rmdir_2_absolute_throwing.html b/attic/doc/disqus_identifiers/rmdir_2_absolute_throwing.html new file mode 100644 index 00000000..2851d094 --- /dev/null +++ b/attic/doc/disqus_identifiers/rmdir_2_absolute_throwing.html @@ -0,0 +1,4 @@ +<script type="text/javascript"> +var disqus_identifier = 'rmdir_2_absolute_throwing'; +var disqus_title = 'Boost.AFIO rmdir (absolute throwing)'; +</script> diff --git a/attic/doc/disqus_identifiers/rmdir_3_absolute_non_throwing.html b/attic/doc/disqus_identifiers/rmdir_3_absolute_non_throwing.html new file mode 100644 index 00000000..2733111d --- /dev/null +++ b/attic/doc/disqus_identifiers/rmdir_3_absolute_non_throwing.html @@ -0,0 +1,4 @@ +<script type="text/javascript"> +var disqus_identifier = 'rmdir_3_absolute_non_throwing'; +var disqus_title = 'Boost.AFIO rmdir (absolute non throwing)'; +</script> diff --git a/attic/doc/disqus_identifiers/rmdir_3_relative_throwing.html b/attic/doc/disqus_identifiers/rmdir_3_relative_throwing.html new file mode 100644 index 00000000..9d4f8ca7 --- /dev/null +++ b/attic/doc/disqus_identifiers/rmdir_3_relative_throwing.html @@ -0,0 +1,4 @@ +<script type="text/javascript"> +var disqus_identifier = 'rmdir_3_relative_throwing'; +var disqus_title = 'Boost.AFIO rmdir (relative throwing)'; +</script> diff --git a/attic/doc/disqus_identifiers/rmdir_4_relative_non_throwing.html b/attic/doc/disqus_identifiers/rmdir_4_relative_non_throwing.html new file mode 100644 index 00000000..2df7bdf9 --- /dev/null +++ b/attic/doc/disqus_identifiers/rmdir_4_relative_non_throwing.html @@ -0,0 +1,4 @@ +<script type="text/javascript"> +var disqus_identifier = 'rmdir_4_relative_non_throwing'; +var disqus_title = 'Boost.AFIO rmdir (relative non throwing)'; +</script> diff --git a/attic/doc/disqus_identifiers/rmfile_1_batch.html b/attic/doc/disqus_identifiers/rmfile_1_batch.html new file mode 100644 index 00000000..9b7fa611 --- /dev/null +++ b/attic/doc/disqus_identifiers/rmfile_1_batch.html @@ -0,0 +1,4 @@ +<script type="text/javascript"> +var disqus_identifier = 'rmfile_1_batch'; +var disqus_title = 'Boost.AFIO rmfile (batch)'; +</script> diff --git a/attic/doc/disqus_identifiers/rmfile_2_absolute_throwing.html b/attic/doc/disqus_identifiers/rmfile_2_absolute_throwing.html new file mode 100644 index 00000000..adc16a28 --- /dev/null +++ b/attic/doc/disqus_identifiers/rmfile_2_absolute_throwing.html @@ -0,0 +1,4 @@ +<script type="text/javascript"> +var disqus_identifier = 'rmfile_2_absolute_throwing'; +var disqus_title = 'Boost.AFIO rmfile (absolute throwing)'; +</script> diff --git a/attic/doc/disqus_identifiers/rmfile_3_absolute_non_throwing.html b/attic/doc/disqus_identifiers/rmfile_3_absolute_non_throwing.html new file mode 100644 index 00000000..1d3b9e8a --- /dev/null +++ b/attic/doc/disqus_identifiers/rmfile_3_absolute_non_throwing.html @@ -0,0 +1,4 @@ +<script type="text/javascript"> +var disqus_identifier = 'rmfile_3_absolute_non_throwing'; +var disqus_title = 'Boost.AFIO rmfile (absolute non throwing)'; +</script> diff --git a/attic/doc/disqus_identifiers/rmfile_3_relative_throwing.html b/attic/doc/disqus_identifiers/rmfile_3_relative_throwing.html new file mode 100644 index 00000000..6ca0d375 --- /dev/null +++ b/attic/doc/disqus_identifiers/rmfile_3_relative_throwing.html @@ -0,0 +1,4 @@ +<script type="text/javascript"> +var disqus_identifier = 'rmfile_3_relative_throwing'; +var disqus_title = 'Boost.AFIO rmfile (relative throwing)'; +</script> diff --git a/attic/doc/disqus_identifiers/rmfile_4_relative_non_throwing.html b/attic/doc/disqus_identifiers/rmfile_4_relative_non_throwing.html new file mode 100644 index 00000000..00b54653 --- /dev/null +++ b/attic/doc/disqus_identifiers/rmfile_4_relative_non_throwing.html @@ -0,0 +1,4 @@ +<script type="text/javascript"> +var disqus_identifier = 'rmfile_4_relative_non_throwing'; +var disqus_title = 'Boost.AFIO rmfile (relative non throwing)'; +</script> diff --git a/attic/doc/disqus_identifiers/rmsymlink_1_batch.html b/attic/doc/disqus_identifiers/rmsymlink_1_batch.html new file mode 100644 index 00000000..538bf72d --- /dev/null +++ b/attic/doc/disqus_identifiers/rmsymlink_1_batch.html @@ -0,0 +1,4 @@ +<script type="text/javascript"> +var disqus_identifier = 'rmsymlink_1_batch'; +var disqus_title = 'Boost.AFIO rmsymlink (batch)'; +</script> diff --git a/attic/doc/disqus_identifiers/rmsymlink_2_absolute_throwing.html b/attic/doc/disqus_identifiers/rmsymlink_2_absolute_throwing.html new file mode 100644 index 00000000..e1ca2a8b --- /dev/null +++ b/attic/doc/disqus_identifiers/rmsymlink_2_absolute_throwing.html @@ -0,0 +1,4 @@ +<script type="text/javascript"> +var disqus_identifier = 'rmsymlink_2_absolute_throwing'; +var disqus_title = 'Boost.AFIO rmsymlink (absolute throwing)'; +</script> diff --git a/attic/doc/disqus_identifiers/rmsymlink_3_absolute_non_throwing.html b/attic/doc/disqus_identifiers/rmsymlink_3_absolute_non_throwing.html new file mode 100644 index 00000000..6af15ff3 --- /dev/null +++ b/attic/doc/disqus_identifiers/rmsymlink_3_absolute_non_throwing.html @@ -0,0 +1,4 @@ +<script type="text/javascript"> +var disqus_identifier = 'rmsymlink_3_absolute_non_throwing'; +var disqus_title = 'Boost.AFIO rmsymlink (absolute non throwing)'; +</script> diff --git a/attic/doc/disqus_identifiers/rmsymlink_3_relative_throwing.html b/attic/doc/disqus_identifiers/rmsymlink_3_relative_throwing.html new file mode 100644 index 00000000..1bcd46b5 --- /dev/null +++ b/attic/doc/disqus_identifiers/rmsymlink_3_relative_throwing.html @@ -0,0 +1,4 @@ +<script type="text/javascript"> +var disqus_identifier = 'rmsymlink_3_relative_throwing'; +var disqus_title = 'Boost.AFIO rmsymlink (relative throwing)'; +</script> diff --git a/attic/doc/disqus_identifiers/rmsymlink_4_relative_non_throwing.html b/attic/doc/disqus_identifiers/rmsymlink_4_relative_non_throwing.html new file mode 100644 index 00000000..f9b138a4 --- /dev/null +++ b/attic/doc/disqus_identifiers/rmsymlink_4_relative_non_throwing.html @@ -0,0 +1,4 @@ +<script type="text/javascript"> +var disqus_identifier = 'rmsymlink_4_relative_non_throwing'; +var disqus_title = 'Boost.AFIO rmsymlink (relative non throwing)'; +</script> diff --git a/attic/doc/disqus_identifiers/so_what.html b/attic/doc/disqus_identifiers/so_what.html new file mode 100644 index 00000000..e21d7d43 --- /dev/null +++ b/attic/doc/disqus_identifiers/so_what.html @@ -0,0 +1,4 @@ +<script type="text/javascript"> +var disqus_identifier = 'so_what'; +var disqus_title = 'Boost.AFIO What benefit does asynchronous file i/o bring me? A demonstration of AFIO's power'; +</script> diff --git a/attic/doc/disqus_identifiers/stat_t.html b/attic/doc/disqus_identifiers/stat_t.html new file mode 100644 index 00000000..df51c7df --- /dev/null +++ b/attic/doc/disqus_identifiers/stat_t.html @@ -0,0 +1,4 @@ +<script type="text/javascript"> +var disqus_identifier = 'stat_t'; +var disqus_title = 'Boost.AFIO stat_t'; +</script> diff --git a/attic/doc/disqus_identifiers/statfs_2_batch.html b/attic/doc/disqus_identifiers/statfs_2_batch.html new file mode 100644 index 00000000..01ece709 --- /dev/null +++ b/attic/doc/disqus_identifiers/statfs_2_batch.html @@ -0,0 +1,4 @@ +<script type="text/javascript"> +var disqus_identifier = 'statfs_2_batch'; +var disqus_title = 'Boost.AFIO statfs (batch)'; +</script> diff --git a/attic/doc/disqus_identifiers/statfs_2_throwing.html b/attic/doc/disqus_identifiers/statfs_2_throwing.html new file mode 100644 index 00000000..2fabc77d --- /dev/null +++ b/attic/doc/disqus_identifiers/statfs_2_throwing.html @@ -0,0 +1,4 @@ +<script type="text/javascript"> +var disqus_identifier = 'statfs_2_throwing'; +var disqus_title = 'Boost.AFIO statfs (throwing)'; +</script> diff --git a/attic/doc/disqus_identifiers/statfs_3_nonthrowing.html b/attic/doc/disqus_identifiers/statfs_3_nonthrowing.html new file mode 100644 index 00000000..1f28a9e1 --- /dev/null +++ b/attic/doc/disqus_identifiers/statfs_3_nonthrowing.html @@ -0,0 +1,4 @@ +<script type="text/javascript"> +var disqus_identifier = 'statfs_3_nonthrowing'; +var disqus_title = 'Boost.AFIO statfs (nonthrowing)'; +</script> diff --git a/attic/doc/disqus_identifiers/statfs_t.html b/attic/doc/disqus_identifiers/statfs_t.html new file mode 100644 index 00000000..1f3b4903 --- /dev/null +++ b/attic/doc/disqus_identifiers/statfs_t.html @@ -0,0 +1,4 @@ +<script type="text/javascript"> +var disqus_identifier = 'statfs_t'; +var disqus_title = 'Boost.AFIO statfs_t'; +</script> diff --git a/attic/doc/disqus_identifiers/statfs_t_f_flags_t.html b/attic/doc/disqus_identifiers/statfs_t_f_flags_t.html new file mode 100644 index 00000000..62d73567 --- /dev/null +++ b/attic/doc/disqus_identifiers/statfs_t_f_flags_t.html @@ -0,0 +1,4 @@ +<script type="text/javascript"> +var disqus_identifier = 'statfs_t_f_flags_t'; +var disqus_title = 'Boost.AFIO statfs_t::f_flags_t'; +</script> diff --git a/attic/doc/disqus_identifiers/std_thread_pool.html b/attic/doc/disqus_identifiers/std_thread_pool.html new file mode 100644 index 00000000..0dd3883e --- /dev/null +++ b/attic/doc/disqus_identifiers/std_thread_pool.html @@ -0,0 +1,4 @@ +<script type="text/javascript"> +var disqus_identifier = 'std_thread_pool'; +var disqus_title = 'Boost.AFIO std_thread_pool'; +</script> diff --git a/attic/doc/disqus_identifiers/std_thread_pool_worker.html b/attic/doc/disqus_identifiers/std_thread_pool_worker.html new file mode 100644 index 00000000..c57c71cc --- /dev/null +++ b/attic/doc/disqus_identifiers/std_thread_pool_worker.html @@ -0,0 +1,4 @@ +<script type="text/javascript"> +var disqus_identifier = 'std_thread_pool_worker'; +var disqus_title = 'Boost.AFIO std_thread_pool::worker'; +</script> diff --git a/attic/doc/disqus_identifiers/symlink_2_batch.html b/attic/doc/disqus_identifiers/symlink_2_batch.html new file mode 100644 index 00000000..b2ead36a --- /dev/null +++ b/attic/doc/disqus_identifiers/symlink_2_batch.html @@ -0,0 +1,4 @@ +<script type="text/javascript"> +var disqus_identifier = 'symlink_2_batch'; +var disqus_title = 'Boost.AFIO symlink (batch)'; +</script> diff --git a/attic/doc/disqus_identifiers/symlink_3_absolute_throwing.html b/attic/doc/disqus_identifiers/symlink_3_absolute_throwing.html new file mode 100644 index 00000000..1bb7d36c --- /dev/null +++ b/attic/doc/disqus_identifiers/symlink_3_absolute_throwing.html @@ -0,0 +1,4 @@ +<script type="text/javascript"> +var disqus_identifier = 'symlink_3_absolute_throwing'; +var disqus_title = 'Boost.AFIO symlink (absolute throwing)'; +</script> diff --git a/attic/doc/disqus_identifiers/symlink_4_absolute_non_throwing.html b/attic/doc/disqus_identifiers/symlink_4_absolute_non_throwing.html new file mode 100644 index 00000000..849bf2e7 --- /dev/null +++ b/attic/doc/disqus_identifiers/symlink_4_absolute_non_throwing.html @@ -0,0 +1,4 @@ +<script type="text/javascript"> +var disqus_identifier = 'symlink_4_absolute_non_throwing'; +var disqus_title = 'Boost.AFIO symlink (absolute non throwing)'; +</script> diff --git a/attic/doc/disqus_identifiers/symlink_4_relative_throwing.html b/attic/doc/disqus_identifiers/symlink_4_relative_throwing.html new file mode 100644 index 00000000..3808178e --- /dev/null +++ b/attic/doc/disqus_identifiers/symlink_4_relative_throwing.html @@ -0,0 +1,4 @@ +<script type="text/javascript"> +var disqus_identifier = 'symlink_4_relative_throwing'; +var disqus_title = 'Boost.AFIO symlink (relative throwing)'; +</script> diff --git a/attic/doc/disqus_identifiers/symlink_5_relative_non_throwing.html b/attic/doc/disqus_identifiers/symlink_5_relative_non_throwing.html new file mode 100644 index 00000000..01226a6c --- /dev/null +++ b/attic/doc/disqus_identifiers/symlink_5_relative_non_throwing.html @@ -0,0 +1,4 @@ +<script type="text/javascript"> +var disqus_identifier = 'symlink_5_relative_non_throwing'; +var disqus_title = 'Boost.AFIO symlink (relative non throwing)'; +</script> diff --git a/attic/doc/disqus_identifiers/sync_1_batch.html b/attic/doc/disqus_identifiers/sync_1_batch.html new file mode 100644 index 00000000..aab33809 --- /dev/null +++ b/attic/doc/disqus_identifiers/sync_1_batch.html @@ -0,0 +1,4 @@ +<script type="text/javascript"> +var disqus_identifier = 'sync_1_batch'; +var disqus_title = 'Boost.AFIO sync (batch)'; +</script> diff --git a/attic/doc/disqus_identifiers/sync_1_throwing.html b/attic/doc/disqus_identifiers/sync_1_throwing.html new file mode 100644 index 00000000..d1859b97 --- /dev/null +++ b/attic/doc/disqus_identifiers/sync_1_throwing.html @@ -0,0 +1,4 @@ +<script type="text/javascript"> +var disqus_identifier = 'sync_1_throwing'; +var disqus_title = 'Boost.AFIO sync (throwing)'; +</script> diff --git a/attic/doc/disqus_identifiers/sync_2_non_throwing.html b/attic/doc/disqus_identifiers/sync_2_non_throwing.html new file mode 100644 index 00000000..77b73b5a --- /dev/null +++ b/attic/doc/disqus_identifiers/sync_2_non_throwing.html @@ -0,0 +1,4 @@ +<script type="text/javascript"> +var disqus_identifier = 'sync_2_non_throwing'; +var disqus_title = 'Boost.AFIO sync (non throwing)'; +</script> diff --git a/attic/doc/disqus_identifiers/target.html b/attic/doc/disqus_identifiers/target.html new file mode 100644 index 00000000..366ddba2 --- /dev/null +++ b/attic/doc/disqus_identifiers/target.html @@ -0,0 +1,4 @@ +<script type="text/javascript"> +var disqus_identifier = 'target'; +var disqus_title = 'Boost.AFIO target'; +</script> diff --git a/attic/doc/disqus_identifiers/thread_source.html b/attic/doc/disqus_identifiers/thread_source.html new file mode 100644 index 00000000..b0a765c7 --- /dev/null +++ b/attic/doc/disqus_identifiers/thread_source.html @@ -0,0 +1,4 @@ +<script type="text/javascript"> +var disqus_identifier = 'thread_source'; +var disqus_title = 'Boost.AFIO thread_source'; +</script> diff --git a/attic/doc/disqus_identifiers/to_asio_buffers_1_asio_const_buffer.html b/attic/doc/disqus_identifiers/to_asio_buffers_1_asio_const_buffer.html new file mode 100644 index 00000000..6d429eab --- /dev/null +++ b/attic/doc/disqus_identifiers/to_asio_buffers_1_asio_const_buffer.html @@ -0,0 +1,4 @@ +<script type="text/javascript"> +var disqus_identifier = 'to_asio_buffers_1_asio_const_buffer'; +var disqus_title = 'Boost.AFIO to_asio_buffers (asio const_buffer)'; +</script> diff --git a/attic/doc/disqus_identifiers/to_asio_buffers_1_asio_mutable_buffer.html b/attic/doc/disqus_identifiers/to_asio_buffers_1_asio_mutable_buffer.html new file mode 100644 index 00000000..4ce97d77 --- /dev/null +++ b/attic/doc/disqus_identifiers/to_asio_buffers_1_asio_mutable_buffer.html @@ -0,0 +1,4 @@ +<script type="text/javascript"> +var disqus_identifier = 'to_asio_buffers_1_asio_mutable_buffer'; +var disqus_title = 'Boost.AFIO to_asio_buffers (asio mutable_buffer)'; +</script> diff --git a/attic/doc/disqus_identifiers/to_asio_buffers_1_c_arrays.html b/attic/doc/disqus_identifiers/to_asio_buffers_1_c_arrays.html new file mode 100644 index 00000000..35618177 --- /dev/null +++ b/attic/doc/disqus_identifiers/to_asio_buffers_1_c_arrays.html @@ -0,0 +1,4 @@ +<script type="text/javascript"> +var disqus_identifier = 'to_asio_buffers_1_c_arrays'; +var disqus_title = 'Boost.AFIO to_asio_buffers (C arrays)'; +</script> diff --git a/attic/doc/disqus_identifiers/to_asio_buffers_1_const_c_arrays.html b/attic/doc/disqus_identifiers/to_asio_buffers_1_const_c_arrays.html new file mode 100644 index 00000000..44513b8e --- /dev/null +++ b/attic/doc/disqus_identifiers/to_asio_buffers_1_const_c_arrays.html @@ -0,0 +1,4 @@ +<script type="text/javascript"> +var disqus_identifier = 'to_asio_buffers_1_const_c_arrays'; +var disqus_title = 'Boost.AFIO to_asio_buffers (const C arrays)'; +</script> diff --git a/attic/doc/disqus_identifiers/to_asio_buffers_1_const_trivial_and_container_types.html b/attic/doc/disqus_identifiers/to_asio_buffers_1_const_trivial_and_container_types.html new file mode 100644 index 00000000..dab9b115 --- /dev/null +++ b/attic/doc/disqus_identifiers/to_asio_buffers_1_const_trivial_and_container_types.html @@ -0,0 +1,4 @@ +<script type="text/javascript"> +var disqus_identifier = 'to_asio_buffers_1_const_trivial_and_container_types'; +var disqus_title = 'Boost.AFIO to_asio_buffers (const trivial and container types)'; +</script> diff --git a/attic/doc/disqus_identifiers/to_asio_buffers_1_trivial_and_container_types.html b/attic/doc/disqus_identifiers/to_asio_buffers_1_trivial_and_container_types.html new file mode 100644 index 00000000..c94e64fa --- /dev/null +++ b/attic/doc/disqus_identifiers/to_asio_buffers_1_trivial_and_container_types.html @@ -0,0 +1,4 @@ +<script type="text/javascript"> +var disqus_identifier = 'to_asio_buffers_1_trivial_and_container_types'; +var disqus_title = 'Boost.AFIO to_asio_buffers (trivial and container types)'; +</script> diff --git a/attic/doc/disqus_identifiers/to_asio_buffers_2_buffer.html b/attic/doc/disqus_identifiers/to_asio_buffers_2_buffer.html new file mode 100644 index 00000000..605880a9 --- /dev/null +++ b/attic/doc/disqus_identifiers/to_asio_buffers_2_buffer.html @@ -0,0 +1,4 @@ +<script type="text/javascript"> +var disqus_identifier = 'to_asio_buffers_2_buffer'; +var disqus_title = 'Boost.AFIO to_asio_buffers (buffer)'; +</script> diff --git a/attic/doc/disqus_identifiers/to_asio_buffers_2_buffer_of_t.html b/attic/doc/disqus_identifiers/to_asio_buffers_2_buffer_of_t.html new file mode 100644 index 00000000..98e7ea16 --- /dev/null +++ b/attic/doc/disqus_identifiers/to_asio_buffers_2_buffer_of_t.html @@ -0,0 +1,4 @@ +<script type="text/javascript"> +var disqus_identifier = 'to_asio_buffers_2_buffer_of_t'; +var disqus_title = 'Boost.AFIO to_asio_buffers (buffer of T)'; +</script> diff --git a/attic/doc/disqus_identifiers/to_asio_buffers_2_const_buffer_of_t.html b/attic/doc/disqus_identifiers/to_asio_buffers_2_const_buffer_of_t.html new file mode 100644 index 00000000..15c1c7a5 --- /dev/null +++ b/attic/doc/disqus_identifiers/to_asio_buffers_2_const_buffer_of_t.html @@ -0,0 +1,4 @@ +<script type="text/javascript"> +var disqus_identifier = 'to_asio_buffers_2_const_buffer_of_t'; +var disqus_title = 'Boost.AFIO to_asio_buffers (const buffer of T)'; +</script> diff --git a/attic/doc/disqus_identifiers/to_hex_string.html b/attic/doc/disqus_identifiers/to_hex_string.html new file mode 100644 index 00000000..fb9a740a --- /dev/null +++ b/attic/doc/disqus_identifiers/to_hex_string.html @@ -0,0 +1,4 @@ +<script type="text/javascript"> +var disqus_identifier = 'to_hex_string'; +var disqus_title = 'Boost.AFIO to_hex_string'; +</script> diff --git a/attic/doc/disqus_identifiers/truncate_2_batch.html b/attic/doc/disqus_identifiers/truncate_2_batch.html new file mode 100644 index 00000000..511723ad --- /dev/null +++ b/attic/doc/disqus_identifiers/truncate_2_batch.html @@ -0,0 +1,4 @@ +<script type="text/javascript"> +var disqus_identifier = 'truncate_2_batch'; +var disqus_title = 'Boost.AFIO truncate (batch)'; +</script> diff --git a/attic/doc/disqus_identifiers/truncate_2_throwing.html b/attic/doc/disqus_identifiers/truncate_2_throwing.html new file mode 100644 index 00000000..ef6129d7 --- /dev/null +++ b/attic/doc/disqus_identifiers/truncate_2_throwing.html @@ -0,0 +1,4 @@ +<script type="text/javascript"> +var disqus_identifier = 'truncate_2_throwing'; +var disqus_title = 'Boost.AFIO truncate (throwing)'; +</script> diff --git a/attic/doc/disqus_identifiers/truncate_3_non_throwing.html b/attic/doc/disqus_identifiers/truncate_3_non_throwing.html new file mode 100644 index 00000000..e95d0d40 --- /dev/null +++ b/attic/doc/disqus_identifiers/truncate_3_non_throwing.html @@ -0,0 +1,4 @@ +<script type="text/javascript"> +var disqus_identifier = 'truncate_3_non_throwing'; +var disqus_title = 'Boost.AFIO truncate (non throwing)'; +</script> diff --git a/attic/doc/disqus_identifiers/type.html b/attic/doc/disqus_identifiers/type.html new file mode 100644 index 00000000..d85d8474 --- /dev/null +++ b/attic/doc/disqus_identifiers/type.html @@ -0,0 +1,4 @@ +<script type="text/javascript"> +var disqus_identifier = 'type'; +var disqus_title = 'Boost.AFIO Type'; +</script> diff --git a/attic/doc/disqus_identifiers/unlink.html b/attic/doc/disqus_identifiers/unlink.html new file mode 100644 index 00000000..a4ddfbf7 --- /dev/null +++ b/attic/doc/disqus_identifiers/unlink.html @@ -0,0 +1,4 @@ +<script type="text/javascript"> +var disqus_identifier = 'unlink'; +var disqus_title = 'Boost.AFIO unlink'; +</script> diff --git a/attic/doc/disqus_identifiers/utils_page_allocator.html b/attic/doc/disqus_identifiers/utils_page_allocator.html new file mode 100644 index 00000000..18455b3d --- /dev/null +++ b/attic/doc/disqus_identifiers/utils_page_allocator.html @@ -0,0 +1,4 @@ +<script type="text/javascript"> +var disqus_identifier = 'utils_page_allocator'; +var disqus_title = 'Boost.AFIO utils::page_allocator'; +</script> diff --git a/attic/doc/disqus_identifiers/utils_page_allocator_-void-_.html b/attic/doc/disqus_identifiers/utils_page_allocator_-void-_.html new file mode 100644 index 00000000..df8e7d4d --- /dev/null +++ b/attic/doc/disqus_identifiers/utils_page_allocator_-void-_.html @@ -0,0 +1,4 @@ +<script type="text/javascript"> +var disqus_identifier = 'utils_page_allocator_-void-_'; +var disqus_title = 'Boost.AFIO rebind utils::page_allocator< void >::rebind'; +</script> diff --git a/attic/doc/disqus_identifiers/utils_page_allocator_rebind.html b/attic/doc/disqus_identifiers/utils_page_allocator_rebind.html new file mode 100644 index 00000000..8a4cbfdd --- /dev/null +++ b/attic/doc/disqus_identifiers/utils_page_allocator_rebind.html @@ -0,0 +1,4 @@ +<script type="text/javascript"> +var disqus_identifier = 'utils_page_allocator_rebind'; +var disqus_title = 'Boost.AFIO utils::page_allocator::rebind'; +</script> diff --git a/attic/doc/disqus_identifiers/utils_secded_ecc.html b/attic/doc/disqus_identifiers/utils_secded_ecc.html new file mode 100644 index 00000000..b612cff9 --- /dev/null +++ b/attic/doc/disqus_identifiers/utils_secded_ecc.html @@ -0,0 +1,4 @@ +<script type="text/javascript"> +var disqus_identifier = 'utils_secded_ecc'; +var disqus_title = 'Boost.AFIO utils::secded_ecc'; +</script> diff --git a/attic/doc/disqus_identifiers/verify_status.html b/attic/doc/disqus_identifiers/verify_status.html new file mode 100644 index 00000000..6efb84c6 --- /dev/null +++ b/attic/doc/disqus_identifiers/verify_status.html @@ -0,0 +1,4 @@ +<script type="text/javascript"> +var disqus_identifier = 'verify_status'; +var disqus_title = 'Boost.AFIO verify_status'; +</script> diff --git a/attic/doc/disqus_identifiers/write_1_batch.html b/attic/doc/disqus_identifiers/write_1_batch.html new file mode 100644 index 00000000..278a7a65 --- /dev/null +++ b/attic/doc/disqus_identifiers/write_1_batch.html @@ -0,0 +1,4 @@ +<script type="text/javascript"> +var disqus_identifier = 'write_1_batch'; +var disqus_title = 'Boost.AFIO write (batch)'; +</script> diff --git a/attic/doc/disqus_identifiers/write_3_length_deducing_throwing.html b/attic/doc/disqus_identifiers/write_3_length_deducing_throwing.html new file mode 100644 index 00000000..e8fc3912 --- /dev/null +++ b/attic/doc/disqus_identifiers/write_3_length_deducing_throwing.html @@ -0,0 +1,4 @@ +<script type="text/javascript"> +var disqus_identifier = 'write_3_length_deducing_throwing'; +var disqus_title = 'Boost.AFIO write (length deducing throwing)'; +</script> diff --git a/attic/doc/disqus_identifiers/write_4_length_deducing_non_throwing.html b/attic/doc/disqus_identifiers/write_4_length_deducing_non_throwing.html new file mode 100644 index 00000000..7fdfec58 --- /dev/null +++ b/attic/doc/disqus_identifiers/write_4_length_deducing_non_throwing.html @@ -0,0 +1,4 @@ +<script type="text/javascript"> +var disqus_identifier = 'write_4_length_deducing_non_throwing'; +var disqus_title = 'Boost.AFIO write (length deducing non throwing)'; +</script> diff --git a/attic/doc/disqus_identifiers/write_4_length_specifying_throwing.html b/attic/doc/disqus_identifiers/write_4_length_specifying_throwing.html new file mode 100644 index 00000000..448aa312 --- /dev/null +++ b/attic/doc/disqus_identifiers/write_4_length_specifying_throwing.html @@ -0,0 +1,4 @@ +<script type="text/javascript"> +var disqus_identifier = 'write_4_length_specifying_throwing'; +var disqus_title = 'Boost.AFIO write (length specifying throwing)'; +</script> diff --git a/attic/doc/disqus_identifiers/write_5_length_specifying_non_throwing.html b/attic/doc/disqus_identifiers/write_5_length_specifying_non_throwing.html new file mode 100644 index 00000000..a88e7e11 --- /dev/null +++ b/attic/doc/disqus_identifiers/write_5_length_specifying_non_throwing.html @@ -0,0 +1,4 @@ +<script type="text/javascript"> +var disqus_identifier = 'write_5_length_specifying_non_throwing'; +var disqus_title = 'Boost.AFIO write (length specifying non throwing)'; +</script> diff --git a/attic/doc/disqus_identifiers/zero_2_batch.html b/attic/doc/disqus_identifiers/zero_2_batch.html new file mode 100644 index 00000000..90e2ee14 --- /dev/null +++ b/attic/doc/disqus_identifiers/zero_2_batch.html @@ -0,0 +1,4 @@ +<script type="text/javascript"> +var disqus_identifier = 'zero_2_batch'; +var disqus_title = 'Boost.AFIO zero (batch)'; +</script> diff --git a/attic/doc/disqus_identifiers/zero_2_throwing.html b/attic/doc/disqus_identifiers/zero_2_throwing.html new file mode 100644 index 00000000..61b6d700 --- /dev/null +++ b/attic/doc/disqus_identifiers/zero_2_throwing.html @@ -0,0 +1,4 @@ +<script type="text/javascript"> +var disqus_identifier = 'zero_2_throwing'; +var disqus_title = 'Boost.AFIO zero (throwing)'; +</script> diff --git a/attic/doc/disqus_identifiers/zero_3_non_throwing.html b/attic/doc/disqus_identifiers/zero_3_non_throwing.html new file mode 100644 index 00000000..faa6d6ae --- /dev/null +++ b/attic/doc/disqus_identifiers/zero_3_non_throwing.html @@ -0,0 +1,4 @@ +<script type="text/javascript"> +var disqus_identifier = 'zero_3_non_throwing'; +var disqus_title = 'Boost.AFIO zero (non throwing)'; +</script> diff --git a/attic/doc/doxy/Doxyfile b/attic/doc/doxy/Doxyfile new file mode 100644 index 00000000..5a9ce944 --- /dev/null +++ b/attic/doc/doxy/Doxyfile @@ -0,0 +1,248 @@ +# Doxyfile 1.5.5 + +#--------------------------------------------------------------------------- +# Project related configuration options +#--------------------------------------------------------------------------- +DOXYFILE_ENCODING = UTF-8 +PROJECT_NAME = "Boost.AFIO" +PROJECT_NUMBER = +OUTPUT_DIRECTORY = ./doxygen_output +CREATE_SUBDIRS = NO +OUTPUT_LANGUAGE = English +BRIEF_MEMBER_DESC = YES +REPEAT_BRIEF = YES +ABBREVIATE_BRIEF = +ALWAYS_DETAILED_SEC = YES +INLINE_INHERITED_MEMB = YES +FULL_PATH_NAMES = YES +STRIP_FROM_PATH = +STRIP_FROM_INC_PATH = +SHORT_NAMES = NO +JAVADOC_AUTOBRIEF = NO +QT_AUTOBRIEF = NO +MULTILINE_CPP_IS_BRIEF = NO +INHERIT_DOCS = YES +SEPARATE_MEMBER_PAGES = NO +TAB_SIZE = 8 + +# The aliases are shortcuts for Doxygen documentation. +# Within Boost.Geometry they are used in the top section, so for both +# Doxygen documentation and QuickBook documentation. +# They avoid repetitions and make the documentation more structured. +# There are also qbk expressions, which might qbk defines and templates. + +# There are sections for +# \brief* for various brief descriptions +# \tparam* for various template parameters +# \param* for various parameters +# \return* for various return cases +ALIASES = qbk{1}="\xmlonly <qbk>\1</qbk> \endxmlonly" \ + qbk{2}="\xmlonly <qbk.\1>\2</qbk.\1> \endxmlonly" \ + raceguarantees{1}="\xmlonly <qbk>[heading Race Guarantees][raceguarantees \1 ]</qbk> \endxmlonly" \ + complexity{1}="\xmlonly <qbk>[heading Complexity]\1</qbk> \endxmlonly" \ + exceptionmodel{1}="\xmlonly <qbk>[heading Exception Model]\1</qbk> \endxmlonly" \ + exceptionmodelstd="\xmlonly <qbk>[heading Exception Model]Propagates exceptions of any input preconditions with an errored state at the point of dispatch, and throws a `std::invalid_argument` if any inputs have values which could not possibly be correct. Once a batch of input ops has been verified at the point of entry as not errored, you are guaranteed that the batch is atomically scheduled as a whole, unless a failure to allocate memory occurs.</qbk> \endxmlonly" \ + exceptionmodelfree="\xmlonly <qbk>[heading Exception Model]Propagates the exception of any input precondition with an errored state at the point of dispatch, and throws a `std::invalid_argument` if any inputs have values which could not possibly be correct. Note that error code returning functions may still throw exceptions e.g. failure to allocate memory.</qbk> \endxmlonly" \ + direct_io_note="Note that on Windows this call issues a separate async file operation for each buffer supplied, thus making scatter/gather i/o no more efficient than making separate calls. The big exception to this is when doing unbuffered page aligned i/o for which Windows provides special scatter/gather i/o functions. You should therefore assume that only each buffer is atomically read or written rather than the full sequence of buffers at once (this also applies to POSIX systems without the preadv()/pwritev() operations)." \ + ntkernelnamespacenote="Be aware that on Windows AFIO operates exclusively in the NT kernel namespace, NOT the Win32 namespace, and therefore paths you supply are converted by `afio::path` in NT kernel namespace paths. `normalise_path()` can convert an afio path back to a Filesystem TS path for you, but note that this may not be the path that was supplied originally. NT kernel namespace paths have a 32,767 character limit and an almost POSIX like lack of restrictions on naming or historical behaviour quirks, but as a result AFIO does not support DOS short names or any of the other historical Win32 filing system baggage." \ + deprecate{1}="\xmlonly <qbk>[caution \1]</qbk> \endxmlonly" \ + constr="Default constructor." \ + cconstr="Copy constructor." \ + mconstr="Move constructor." \ + cassign="Copy assignment." \ + massign="Move assignment." \ + io_req1="\brief Constructs an instance. \ + \param _precondition An optional precondition for this operation \ + \param v A pointer to memory or reference to object into which to read or write \ + \param _where The offset at which to transfer" \ + io_req2="\brief Constructs an instance. \ + \param _precondition An optional precondition for this operation \ + \param _buffers A sequence of mutable/const Boost.ASIO buffers to read into/write from \ + \param _where The offset at which to transfer" \ + io_req3="\brief Constructs an instance. \ + \param _precondition An optional precondition for this operation \ + \param _buffer A mutable/const Boost.ASIO buffer to read into/write from \ + \param _where The offset at which to transfer" \ + qexample{1}="\xmlonly <qbk>[heading Example][\1]</qbk> \endxmlonly" + +OPTIMIZE_OUTPUT_FOR_C = NO +OPTIMIZE_OUTPUT_JAVA = NO +OPTIMIZE_FOR_FORTRAN = NO +OPTIMIZE_OUTPUT_VHDL = NO +BUILTIN_STL_SUPPORT = YES +CPP_CLI_SUPPORT = NO +SIP_SUPPORT = NO +DISTRIBUTE_GROUP_DOC = NO +SUBGROUPING = YES +TYPEDEF_HIDES_STRUCT = NO +#--------------------------------------------------------------------------- +# Build related configuration options +#--------------------------------------------------------------------------- +EXTRACT_ALL = NO +EXTRACT_PRIVATE = NO +EXTRACT_STATIC = YES +EXTRACT_LOCAL_CLASSES = NO +EXTRACT_LOCAL_METHODS = NO +EXTRACT_ANON_NSPACES = NO +HIDE_UNDOC_MEMBERS = NO +HIDE_UNDOC_CLASSES = NO +HIDE_FRIEND_COMPOUNDS = NO +HIDE_IN_BODY_DOCS = NO +INTERNAL_DOCS = NO +CASE_SENSE_NAMES = NO +HIDE_SCOPE_NAMES = NO +SHOW_INCLUDE_FILES = NO +INLINE_INFO = NO +SORT_MEMBER_DOCS = NO +SORT_BRIEF_DOCS = NO +SORT_GROUP_NAMES = YES +SORT_BY_SCOPE_NAME = YES +GENERATE_TODOLIST = NO +GENERATE_TESTLIST = YES +GENERATE_BUGLIST = YES +GENERATE_DEPRECATEDLIST= YES +ENABLED_SECTIONS = +MAX_INITIALIZER_LINES = 30 +SHOW_USED_FILES = NO +FILE_VERSION_FILTER = +#--------------------------------------------------------------------------- +# configuration options related to warning and progress messages +#--------------------------------------------------------------------------- +QUIET = YES +WARNINGS = YES +WARN_IF_UNDOCUMENTED = NO +WARN_IF_DOC_ERROR = YES +WARN_NO_PARAMDOC = NO +WARN_FORMAT = "$file:$line: $text" +WARN_LOGFILE = +#--------------------------------------------------------------------------- +# configuration options related to the input files +#--------------------------------------------------------------------------- +INPUT = ../../include/boost/afio/v2/afio.hpp \ + ./doxygen_input/pages \ + ./doxygen_input/groups +INPUT_ENCODING = UTF-8 +FILE_PATTERNS = *.hpp +RECURSIVE = NO +EXCLUDE = ./doxygen_extension_examples.hpp +EXCLUDE_SYMLINKS = NO +EXCLUDE_PATTERNS = +EXCLUDE_SYMBOLS = +EXAMPLE_PATH = ../../example +EXAMPLE_PATTERNS = *.cpp +EXAMPLE_RECURSIVE = NO +IMAGE_PATH = doxygen_input/images +INPUT_FILTER = +FILTER_PATTERNS = +FILTER_SOURCE_FILES = NO +#--------------------------------------------------------------------------- +# configuration options related to source browsing +#--------------------------------------------------------------------------- +SOURCE_BROWSER = YES +INLINE_SOURCES = NO +STRIP_CODE_COMMENTS = YES +REFERENCED_BY_RELATION = NO +REFERENCES_RELATION = NO +REFERENCES_LINK_SOURCE = NO +USE_HTAGS = NO +VERBATIM_HEADERS = NO +#--------------------------------------------------------------------------- +# configuration options related to the alphabetical class index +#--------------------------------------------------------------------------- +COLS_IN_ALPHA_INDEX = 3 +IGNORE_PREFIX = +#--------------------------------------------------------------------------- +# configuration options related to the HTML output +#--------------------------------------------------------------------------- +GENERATE_HTML = YES +HTML_OUTPUT = html +HTML_FILE_EXTENSION = .html +HTML_HEADER = doxygen_input/doxygen_header.html +HTML_FOOTER = doxygen_input/doxygen_footer.html +HTML_STYLESHEET = +GENERATE_HTMLHELP = NO +GENERATE_DOCSET = NO +DOCSET_FEEDNAME = "Generated documentation, by Doxygen" +DOCSET_BUNDLE_ID = org.doxygen.Project +HTML_DYNAMIC_SECTIONS = NO +CHM_FILE = +HHC_LOCATION = +GENERATE_CHI = NO +BINARY_TOC = NO +TOC_EXPAND = NO +DISABLE_INDEX = NO +ENUM_VALUES_PER_LINE = 4 +GENERATE_TREEVIEW = NO +TREEVIEW_WIDTH = 250 + +#--------------------------------------------------------------------------- +# configuration options related to the XML output +#--------------------------------------------------------------------------- +GENERATE_XML = YES +XML_OUTPUT = xml +XML_SCHEMA = +XML_DTD = +XML_PROGRAMLISTING = NO + +#--------------------------------------------------------------------------- +# Configuration options turned off +#--------------------------------------------------------------------------- +GENERATE_LATEX = NO +GENERATE_MAN = NO +GENERATE_RTF = NO +GENERATE_AUTOGEN_DEF = NO +GENERATE_PERLMOD = NO + + +#--------------------------------------------------------------------------- +# Configuration options related to the preprocessor +#--------------------------------------------------------------------------- +ENABLE_PREPROCESSING = YES +MACRO_EXPANSION = YES +EXPAND_ONLY_PREDEF = YES +SEARCH_INCLUDES = YES +INCLUDE_PATH = +INCLUDE_FILE_PATTERNS = +PREDEFINED = \ + BOOST_CONCEPT_REQUIRES(x)= \ + BOOST_CONCEPT_ASSERT(x)= \ + BOOST_STATIC_ASSERT(x)= \ + BOOST_AFIO_DECL= \ + DOXYGEN_SHOULD_SKIP_THIS \ + DOXYGEN_NO_CLASS_ENUMS \ + BOOST_NOEXCEPT_OR_NOTHROW=noexcept \ + BOOST_CONSTEXPR_OR_CONST=constexpr \ + BOOST_CONSTEXPR=constexpr \ + BOOST_CXX14_CONSTEXPR=constexpr +EXPAND_AS_DEFINED = BOOST_AFIO_DIRECTORY_ENTRY_ACCESS_METHOD \ + BOOST_AFIO_HEADERS_ONLY_FUNC_SPEC \ + BOOST_AFIO_HEADERS_ONLY_MEMFUNC_SPEC \ + BOOST_AFIO_HEADERS_ONLY_VIRTUAL_SPEC \ + BOOST_AFIO_HEADERS_ONLY_VIRTUAL_UNDEFINED_SPEC \ + BOOST_AFIO_V2_NAMESPACE \ + BOOST_AFIO_V2_NAMESPACE_BEGIN \ + BOOST_AFIO_V2_NAMESPACE_END +SKIP_FUNCTION_MACROS = YES + + +#--------------------------------------------------------------------------- +# Configuration::additions related to the search engine +#--------------------------------------------------------------------------- +SEARCHENGINE = NO + +ALIASES += docs_adopt="This function enables you to adopt third party custom `__afio_handle__` derivatives as ops into the scheduler. Think of it as if you were calling file(), except the op returns the supplied handle and otherwise does nothing." +ALIASES += docs_dir="Note that if there is already a handle open to the directory requested, that will be returned instead of a new handle unless file_flags::unique_directory_handle is specified. For such handles where available_to_directory_cache() is true, they cannot be explicitly closed either, you must let the reference count reach zero for that to happen.\n\nRelated types: `__afio_path_req__`" +ALIASES += docs_rmdir="Make sure you read the docs for `__afio_handle__::unlink()` for important caveats.\n\nNote that on operating systems with an unstable `__afio_handle__::path(true)` you need to be cautious of deleting files by handle as any hard link to that file may be deleted instead of the one you intended. To work around this, portable code should delete by directory handle as the precondition and known leafname.\n\nRelated types: `__afio_path_req__`" +ALIASES += docs_file="Be aware that any files created are by default sparse if supported on the local filing system. On Windows opening any file for writing converts it to sparse. Use file_flags::no_sparse to prevent this on those filing systems which permit it.\n\nRelated types: `__afio_path_req__`" +ALIASES += docs_rmfile="Note that you can delete files before they are closed on Windows just as with POSIX if and only if all open handles to that file were opened with permission for the file to be deleted (AFIO always sets this). The actual file data will be deleted when the last handle is closed on the system.\n\nMake sure you read the docs for `__afio_handle__::unlink()` for important caveats.\n\nNote that on operating systems with an unstable `__afio_handle__::path(true)` you need to be cautious of deleting files by handle as any hard link to that file may be deleted instead of the one you intended. To work around this, portable code should delete by directory handle as the precondition and known leafname.\n\nRelated types: `__afio_path_req__`" +ALIASES += docs_symlink="Note that if creating and you don't specify a target, the target for the symlink is the precondition. On Windows directories are symlinked using a reparse point instead of a symlink due to the default lack of the <tt>SeCreateSymbolicLinkPrivilege</tt> for non-Administrative users. On Windows you can open symlinks as a file and so a valid handle is output, whereas on POSIX except for Linux you cannot do this and an invalid handle is output.\n\nRelated types: `__afio_path_req__`" +ALIASES += docs_rmsymlink="Make sure you read the docs for `__afio_handle__::unlink()` for important caveats.\n\nNote that on operating systems with an unstable `__afio_handle__::path(true)` you need to be cautious of deleting files by handle as any hard link to that file may be deleted instead of the one you intended. To work around this, portable code should delete by directory handle as the precondition and known leafname.\n\nRelated types: `__afio_path_req__`" +ALIASES += docs_sync="It goes without saying that this call can take very significant amounts of time to complete!" +ALIASES += docs_zero="Most extent based filing systems provide an optimised way of zeroing parts of a file by deallocating the storage backing those regions, and marking those regions as unwritten instead of actually writing zero bytes to storage. They appear as zeroes to anything reading those ranges, and have the big advantage of not consuming any actual physical storage. On Windows, extent deallocation writes zeros for ordinary files and only actually deallocates physical storage if the file is sparse or compressed (note that AFIO by default creates sparse files where possible, and converts any file opened for writing to a sparse file). For your information, deallocation on NTFS is on a 64Kb granularity, but the zeros are written at a byte granularity. On Linux, an attempt is made to use FALLOC_FL_PUNCH_HOLE which if it fails then a write of zeros corresponding to the same ranges is made instead. On FreeBSD, long runs of zeros are automatically detected and eliminated on physical storage, and so zeros are simply written. On OS X, there is no formal hole punching API that we are aware of, and so zeros are simply written." +ALIASES += docs_close="Note this is ignored for handles where available_to_directory_cache() is true as those cannot be explicitly closed. Note that failure to explicitly schedule closing a file handle using this call means it will be [*synchronously] closed on last reference count by `__afio_handle__`. This can consume considerable time, especially if SyncOnClose is enabled." +ALIASES += docs_read="Related types: `__afio_io_req__`" +ALIASES += docs_write="Related types: `__afio_io_req__`" +ALIASES += docs_truncate="" +ALIASES += docs_enumerate="By default dir() returns shared handles i.e. dir("foo") and dir("foo") will return the exact same handle, and therefore enumerating not all of the entries at once is a race condition. The solution is to either set maxitems to a value large enough to guarantee a directory will be enumerated in a single shot, or to open a separate directory handle using the file_flags::unique_directory_handle flag.\n\nNote that setting maxitems=1 will often cause a buffer space exhaustion, causing a second syscall with an enlarged buffer. This is because AFIO cannot know if the allocated buffer can hold all of the filename being retrieved, so it may have to retry. Put another way, setting maxitems=1 will give you the worst performance possible, whereas maxitems=2 will probably only return one item most of the time.\n\nRelated types: `__afio_enumerate_req__`, `__afio_directory_entry__`, `__afio_stat_t__`" +ALIASES += docs_extents="In a sparsely allocated file, it can be useful to know which extents contain non-zero data. Note that this call is racy (i.e. the extents are enumerated one by one on some platforms, this means they may be out of date with respect to one another) when other threads or processes are concurrently calling zero() or write() - this is a host OS API limitation." +ALIASES += docs_statfs="Related types: `__afio_statfs_t__`" diff --git a/attic/doc/doxy/doxygen_enhance.py b/attic/doc/doxy/doxygen_enhance.py new file mode 100644 index 00000000..af892be9 --- /dev/null +++ b/attic/doc/doxy/doxygen_enhance.py @@ -0,0 +1,33 @@ +#! /usr/bin/env python +# -*- coding: utf-8 -*- +# =========================================================================== +# Copyright (c) 2010 Barend Gehrels, Amsterdam, the Netherlands. +# +# Use, modification and distribution is subject to the Boost Software License, +# Version 1.0. (See accompanying file LICENSE_1_0.txt or copy at +# http://www.boost.org/LICENSE_1_0.txt)9 +# ============================================================================ + +import sys + +args = sys.argv[1:] +if len(args) != 1: + raise SystemExit("Usage: doxygen_enhance <html filename>") + + +# 1) set variable for doxygen_contents to be posted +file_in = open(args[0], 'r') +doxygen_contents = file_in.read() + +doxygen_contents = doxygen_contents.replace('<span>Modules</span>', '<span>Function overview</span>') +doxygen_contents = doxygen_contents.replace('<span>Related Pages</span>', '<span>Main pages</span>') +doxygen_contents = doxygen_contents.replace('<span>Main Page</span>', '<span>Introduction</span>') +doxygen_contents = doxygen_contents.replace('<li><a href="namespaces.html"><span>Namespaces</span></a></li>', '') + +doxygen_contents = doxygen_contents.replace('<h1>Modules</h1>Here is a list of all modules:<ul>', '<h1>Function overview</h1>Here is a list of all functions:<ul>') +doxygen_contents = doxygen_contents.replace('<h1>Related Pages</h1>Here is a list of all related documentation pages:<ul>', '<h1>Main pages</h1>The following pages give backgrounds on Boost.Geometry:<ul>') + + +file_out = file (args[0], 'w') +file_out.write(doxygen_contents) +file_out.close() diff --git a/attic/doc/doxy/doxygen_input/doxygen_footer.html b/attic/doc/doxy/doxygen_input/doxygen_footer.html new file mode 100644 index 00000000..049eed89 --- /dev/null +++ b/attic/doc/doxy/doxygen_input/doxygen_footer.html @@ -0,0 +1,22 @@ +<hr size="1"> +<table width="100%"> +<tbody> +<tr> +<td align="left"><small> +<p>January, 2014</p> +</small></td> +<td align="right"> +<small> +Copyright © 2013-2014 Niall Douglas, Cork, Ireland<br> +Copyright © 2013 Paul Kirth, California<br> +</small> +</td> +</tr> +</tbody> +</table> + +<address style="text-align: right;"><small> +Documentation is generated by <a href="http://www.doxygen.org/index.html">Doxygen</a> +</small></address> +</body> +</html>
\ No newline at end of file diff --git a/attic/doc/doxy/doxygen_input/doxygen_header.html b/attic/doc/doxy/doxygen_input/doxygen_header.html new file mode 100644 index 00000000..eb6e908c --- /dev/null +++ b/attic/doc/doxy/doxygen_input/doxygen_header.html @@ -0,0 +1,24 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> +<html> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"> +<title>Boost.AFIO</title> +<link href="doxygen.css" rel="stylesheet" type="text/css"> +<link href="tabs.css" rel="stylesheet" type="text/css"> +</head> + +<table cellpadding="2" width="100%"> +<tbody> +<tr> +<td valign="top"> +<img alt="Boost.AFIO" src="images/ggl-logo-big.png" height="80" width="200"> + +</td> +<td valign="top" align="right"> +<a href="http://www.boost.org"> +<img alt="Boost C++ Libraries" src="images/accepted_by_boost.png" height="80" width="230" border="0"> +</a> +</td> +</tr> +</tbody> +</table> diff --git a/attic/doc/doxy/doxygen_input/groups/groups.hpp b/attic/doc/doxy/doxygen_input/groups/groups.hpp new file mode 100644 index 00000000..12f5ed1e --- /dev/null +++ b/attic/doc/doxy/doxygen_input/groups/groups.hpp @@ -0,0 +1,48 @@ +// Boost.AFIO + +// Use, modification and distribution is subject to the Boost Software License, +// Version 1.0. (See accompanying file LICENSE_1_0.txt or copy at +// http://www.boost.org/LICENSE_1_0.txt) +// File defining groups for Doxygen. +// Note that group descriptions are (currently) not used. + +/*! +\defgroup macros Macros +\defgroup process_threadpool Process Thread pool +\defgroup normalise_path Normalise path +\defgroup when_all_futures when_all_p() +\defgroup file_flags file_flags +\defgroup metadata_flags metadata_flags +\defgroup async_op_flags async_op_flags +\defgroup fs_metadata_flags fs_metadata +\defgroup dispatcher__filter x +\defgroup dispatcher__completion x +\defgroup dispatcher__call x +\defgroup dispatcher__filedirops x +\defgroup dispatcher__barrier x +\defgroup dispatcher__enumerate x +\defgroup dispatcher__extents x +\defgroup dispatcher__statfs x +\defgroup dispatcher__misc x +\defgroup dispatcher__depends x +\defgroup async_file_io_dispatcher dispatcher +\defgroup io_req io_req +\defgroup make_io_req make_io_req +\defgroup utils Utilities +\defgroup async_io_handle__ops Handle Ops +\defgroup dir Opening/Creating Directories +\defgroup rmdir Deleting Directories +\defgroup file Opening/Creating Files +\defgroup rmfile Deleting Files +\defgroup symlink Opening/Creating Symlinks +\defgroup rmsymlink Deleting Symlinks +\defgroup sync Fsync +\defgroup zero Zeroing and Deallocation +\defgroup close Closing files +\defgroup read Reading data +\defgroup write Writing data +\defgroup truncate Resizing files +\defgroup enumerate Enumerating directory contents +\defgroup extents Enumerating file extents +\defgroup statfs Fetch metadata of storage volume +*/ diff --git a/attic/doc/doxy/doxygen_input/pages/doxygen_mainpage.hpp b/attic/doc/doxy/doxygen_input/pages/doxygen_mainpage.hpp new file mode 100644 index 00000000..e406719a --- /dev/null +++ b/attic/doc/doxy/doxygen_input/pages/doxygen_mainpage.hpp @@ -0,0 +1,26 @@ +// Boost.AFIO +// +// Use, modification and distribution is subject to the Boost Software License, +// Version 1.0. (See accompanying file LICENSE_1_0.txt or copy at +// http://www.boost.org/LICENSE_1_0.txt) + +#ifndef _DOXYGEN_MAINPAGE_HPP +#define _DOXYGEN_MAINPAGE_HPP + + +// -> introduction.qbk +// -> quickstart.qbk + +/*! +\mainpage Boost.AFIO + +Welcome to the Boost.AFIO documentation. You may find the more formal documentation at +http://boostgsoc13.github.io/boost.afio/ of use. It also includes a full reference manual. + +*/ + + + + + +#endif // _DOXYGEN_MAINPAGE_HPP diff --git a/attic/doc/doxy/make_documentation.bat b/attic/doc/doxy/make_documentation.bat new file mode 100644 index 00000000..bdb6d8fe --- /dev/null +++ b/attic/doc/doxy/make_documentation.bat @@ -0,0 +1,17 @@ +:: =========================================================================== +:: Copyright (c) 2010 Barend Gehrels, Amsterdam, the Netherlands. +:: +:: Use, modification and distribution is subject to the Boost Software License, +:: Version 1.0. (See accompanying file LICENSE_1_0.txt or copy at +:: http://www.boost.org/LICENSE_1_0.txt)9 +:: ============================================================================ + +@echo off + +doxygen + +cd doxygen_output\html + +for %%f in (*.html) do ..\..\doxygen_enhance.py %%f + +cd ..\.. diff --git a/attic/doc/doxygen_xml2qbk.patch b/attic/doc/doxygen_xml2qbk.patch new file mode 100644 index 00000000..2f983604 --- /dev/null +++ b/attic/doc/doxygen_xml2qbk.patch @@ -0,0 +1,113 @@ + .../tools/doxygen_xml2qbk/doxygen_elements.hpp | 2 +- + .../tools/doxygen_xml2qbk/doxygen_xml_parser.hpp | 43 +++++++++++++++++++--- + .../tools/doxygen_xml2qbk/quickbook_output.hpp | 29 +++++++++++++-- + 3 files changed, 64 insertions(+), 10 deletions(-) + +diff --git a/libs/geometry/doc/src/docutils/tools/doxygen_xml2qbk/doxygen_elements.hpp b/libs/geometry/doc/src/docutils/tools/doxygen_xml2qbk/doxygen_elements.hpp +index 04d50dc..43fc98b 100644 +--- a/libs/geometry/doc/src/docutils/tools/doxygen_xml2qbk/doxygen_elements.hpp ++++ b/libs/geometry/doc/src/docutils/tools/doxygen_xml2qbk/doxygen_elements.hpp +@@ -164,7 +164,7 @@ struct class_or_struct : public element + std::vector<function> functions; + + std::vector<base_element> typedefs; +- std::vector<base_element> variables; ++ std::vector<parameter> variables; + + std::vector<base_class> base_classes; + }; +diff --git a/libs/geometry/doc/src/docutils/tools/doxygen_xml2qbk/doxygen_xml_parser.hpp b/libs/geometry/doc/src/docutils/tools/doxygen_xml2qbk/doxygen_xml_parser.hpp +index 0a98f42..119a573 100644 +--- a/libs/geometry/doc/src/docutils/tools/doxygen_xml2qbk/doxygen_xml_parser.hpp ++++ b/libs/geometry/doc/src/docutils/tools/doxygen_xml2qbk/doxygen_xml_parser.hpp +@@ -691,13 +691,44 @@ static void parse(rapidxml::xml_node<>* node, configuration const& config, docum + } + else if (kind == "variable") + { +- if (boost::equals(get_attribute(node, "static"), "yes") +- && boost::equals(get_attribute(node, "mutable"), "no") +- && boost::equals(get_attribute(node, "prot"), "public")) ++ if (boost::equals(get_attribute(node, "prot"), "public")) + { +- std::string name = parse_named_node(node->first_node(), "name"); +- doc.cos.variables.push_back(base_element(name)); +- doc.cos.variables.back().id = id; ++ parameter p; ++ p.id = id; ++ for(rapidxml::xml_node<>* var_node = node->first_node(); var_node; var_node=var_node->next_sibling()) ++ { ++ if(boost::equals(var_node->name(), "name")) ++ { ++ p.name = var_node->value(); ++ } ++ else if(boost::equals(var_node->name(), "type")) ++ { ++ get_contents(var_node->first_node(), p.fulltype); ++ p.type = p.fulltype; ++ //boost::replace_all(p.type, " const", ""); ++ //boost::trim(p.type); ++ //boost::replace_all(p.type, "&", ""); ++ //boost::replace_all(p.type, "*", ""); ++ boost::trim(p.type); ++ ++ // If alt output is used retrieve type with QBK links ++ if ( configuration::alt == config.output_style ) ++ { ++ p.fulltype_without_links = p.fulltype; ++ p.fulltype.clear(); ++ parse_para(var_node->first_node(), config, p.fulltype, p.skip); ++ } ++ } ++ else if(boost::equals(var_node->name(), "briefdescription")) ++ { ++ parse_para(var_node->first_node(), config, p.brief_description, p.skip); ++ } ++ else if(p.brief_description.empty() && boost::equals(var_node->name(), "detaileddescription")) ++ { ++ parse_para(var_node->first_node(), config, p.brief_description, p.skip); ++ } ++ } ++ doc.cos.variables.push_back(p); + } + } + +diff --git a/libs/geometry/doc/src/docutils/tools/doxygen_xml2qbk/quickbook_output.hpp b/libs/geometry/doc/src/docutils/tools/doxygen_xml2qbk/quickbook_output.hpp +index 34295b7..0cb6f24 100644 +--- a/libs/geometry/doc/src/docutils/tools/doxygen_xml2qbk/quickbook_output.hpp ++++ b/libs/geometry/doc/src/docutils/tools/doxygen_xml2qbk/quickbook_output.hpp +@@ -544,9 +544,32 @@ void quickbook_output(class_or_struct const& cos, configuration const& config, s + out << std::endl; + } + +- out << "{" << std::endl +- << " // ..." << std::endl +- << "};" << std::endl ++ out << "{" << std::endl; ++ if (! cos.variables.empty()) ++ { ++ size_t maxlength = 0; ++ BOOST_FOREACH(parameter const& p, cos.variables) ++ { ++ if (! p.skip) ++ { ++ size_t length = 6 + p.fulltype.size() + p.name.size(); ++ if (length > maxlength) maxlength = length; ++ } ++ } ++ BOOST_FOREACH(parameter const& p, cos.variables) ++ { ++ if (! p.skip) ++ { ++ size_t length = 4 + p.fulltype.size() + p.name.size(); ++ out << " " << p.fulltype << " " << p.name << ";"; ++ while(length++ < maxlength) out << " "; ++ out << "// " << p.brief_description << std::endl; ++ } ++ } ++ } ++ else ++ out << " // ..." << std::endl; ++ out << "};" << std::endl + << "``" << std::endl << std::endl; + quickbook_markup(cos.qbk_markup, markup_after, markup_synopsis, out); + diff --git a/attic/doc/generated/class_current_dispatcher_guard.qbk b/attic/doc/generated/class_current_dispatcher_guard.qbk new file mode 100644 index 00000000..64556646 --- /dev/null +++ b/attic/doc/generated/class_current_dispatcher_guard.qbk @@ -0,0 +1,81 @@ +[/============================================================================ + Boost.AFIO + + Use, modification and distribution is subject to the Boost Software License, + Version 1.0. (See accompanying file LICENSE_1_0.txt or copy at + http://www.boost.org/LICENSE_1_0.txt) +=============================================================================/] + + +[/ Generated by doxygen_xml2qbk 1.1.1, don't change, will be overwritten automatically] +[/ Generated from doxy/doxygen_output/xml\classboost_1_1afio_1_1current__dispatcher__guard.xml] +[section:current_dispatcher_guard current_dispatcher_guard] +'''<?dbhtml-include href="disqus_identifiers/current_dispatcher_guard.html"?>''' + +'''<indexterm><primary>current_dispatcher_guard</primary></indexterm>''' + + +[heading Description] +RAII holder for the current async file i/o dispatcher. + +[heading Synopsis] +``class current_dispatcher_guard +{ + // ... +}; +`` + +[heading Constructor(s)] +[table +[[Function] [Description] [Parameters] ] +[[``current_dispatcher_guard(dispatcher_ptr _new)`` + +] [] [[* dispatcher_ptr]: ['_new]: + + + +]] +[[``~current_dispatcher_guard()`` + +] [] [ + +]] +] + +[heading Member Function(s)] +[table +[[Function] [Description] [Parameters] [Returns]] +[[``void release()`` + +] [Restore the former async file i/o dispatcher now. ] [ + +][ + +] +] +[[``void dismiss()`` + +] [Don't restore the former async file i/o dispatcher. ] [ + +][ + +] +] +[[``void reset(dispatcher_ptr p)`` + +] [Set a different former async file i/o dispatcher on destruction. ] [[* dispatcher_ptr]: ['p]: + + + +][ + +] +] +] + +[heading Header] +`#include <boost/afio/v2/afio.hpp>` + +'''<?dbhtml-include href="disqus_comments.html"?>''' +[endsect] + diff --git a/attic/doc/generated/class_directory_entry.qbk b/attic/doc/generated/class_directory_entry.qbk new file mode 100644 index 00000000..d6eb5a80 --- /dev/null +++ b/attic/doc/generated/class_directory_entry.qbk @@ -0,0 +1,405 @@ +[/============================================================================ + Boost.AFIO + + Use, modification and distribution is subject to the Boost Software License, + Version 1.0. (See accompanying file LICENSE_1_0.txt or copy at + http://www.boost.org/LICENSE_1_0.txt) +=============================================================================/] + + +[/ Generated by doxygen_xml2qbk 1.1.1, don't change, will be overwritten automatically] +[/ Generated from doxy/doxygen_output/xml\classboost_1_1afio_1_1directory__entry.xml] +[section:directory_entry directory_entry] +'''<?dbhtml-include href="disqus_identifiers/directory_entry.html"?>''' + +'''<indexterm><primary>directory_entry</primary></indexterm>''' +The abstract base class for an entry in a directory with lazily filled metadata. + +[heading Description] +Note that [^`directory_entry_hash`] will hash one of these for you, and a [^`std::hash<``directory_entry``>`] specialisation is defined for you so you ought to be able to use directory\u005fentry directly in an [^`unordered_map<>`]. + +See [^`__afio_stat_t__`] for explanations of the fields. + +[heading Synopsis] +``class directory_entry +{ + // ... +}; +`` + +[heading Constructor(s)] +[table +[[Function] [Description] [Parameters] ] +[[``directory_entry()`` + +] [Default constructor. ] [ + +]] +[[``directory_entry(path::string_type _leafname, stat_t __stat, metadata_flags _have_metadata)`` + +] [Default constructor. ] [[* path::string_type]: ['_leafname]: + +[* stat_t]: ['__stat]: + +[* metadata_flags]: ['_have_metadata]: + + + +]] +[[``directory_entry(const directory_entry & )`` + +] [] [[* const directory_entry &]: [']: + + + +]] +[[``directory_entry(directory_entry && o)`` + +] [] [[* directory_entry &&]: ['o]: + + + +]] +] + +[heading Member Function(s)] +[table +[[Function] [Description] [Parameters] [Returns]] +[[``directory_entry & operator=(const directory_entry & )`` + +] [] [[* const directory_entry &]: [']: + + + +][ + +] +] +[[``directory_entry & operator=(directory_entry && o)`` + +] [] [[* directory_entry &&]: ['o]: + + + +][ + +] +] +[[``bool operator==(const directory_entry & rhs)`` + +] [] [[* const directory_entry &]: ['rhs]: + + + +][ + +] +] +[[``bool operator!=(const directory_entry & rhs)`` + +] [] [[* const directory_entry &]: ['rhs]: + + + +][ + +] +] +[[``bool operator<(const directory_entry & rhs)`` + +] [] [[* const directory_entry &]: ['rhs]: + + + +][ + +] +] +[[``bool operator<=(const directory_entry & rhs)`` + +] [] [[* const directory_entry &]: ['rhs]: + + + +][ + +] +] +[[``bool operator>(const directory_entry & rhs)`` + +] [] [[* const directory_entry &]: ['rhs]: + + + +][ + +] +] +[[``bool operator>=(const directory_entry & rhs)`` + +] [] [[* const directory_entry &]: ['rhs]: + + + +][ + +] +] +[[``path::string_type name()`` + +] [] [ + +][ +The name of the directory entry. May be empty if the file is deleted. + +] +] +[[``metadata_flags metadata_ready()`` + +] [] [ + +][ +A bitfield of what metadata is ready right now + +] +] +[[``metadata_flags fetch_metadata(handle_ptr dirh, metadata_flags wanted)`` + +] [Fetches the specified metadata, returning that newly available. This is a blocking call if wanted metadata is not yet ready. Note that if the call blocks and the leafname no longer exists or the directory handle is null, an exception is thrown. ] [[* handle_ptr]: ['dirh]: An open handle to the entry's containing directory. You can get this from an op ref using dirop.get_handle(). + +[* metadata_flags]: ['wanted]: A bitfield of the metadata to fetch. This does not replace existing metadata. + + + +][ +The metadata now available in this directory entry. + +] +] +[[``stat_t fetch_lstat(handle_ptr dirh, metadata_flags wanted = directory_entry::metadata_fastpath())`` + +] [Returns a copy of the internal [^`stat_t`] structure. This is a blocking call if wanted metadata is not yet ready. Note that if the call blocks and the leafname no longer exists or the directory handle is null, an exception is thrown. ] [[* handle_ptr]: ['dirh]: An open handle to the entry's containing directory. You can get this from an op ref using dirop.get_handle(). + +[* metadata_flags]: ['wanted]: A bitfield of the metadata to fetch. This does not replace existing metadata. + + + +][ +A copy of the internal [^`stat_t`] structure. + +] +] +[[``fieldtype st_dev(handle_ptr dirh = handle_ptr())`` + +] [Returns st_dev. ] [[* handle_ptr]: ['dirh]: An optional open handle to the entry's containing directory if fetching missing metadata is desired (an exception is thrown otherwise). You can get this from an op ref using dirop.get_handle(). + + + +][ + +] +] +[[``fieldtype st_ino(handle_ptr dirh = handle_ptr())`` + +] [Returns st_ino. ] [[* handle_ptr]: ['dirh]: An optional open handle to the entry's containing directory if fetching missing metadata is desired (an exception is thrown otherwise). You can get this from an op ref using dirop.get_handle(). + + + +][ + +] +] +[[``fieldtype st_type(handle_ptr dirh = handle_ptr())`` + +] [Returns st_type. ] [[* handle_ptr]: ['dirh]: An optional open handle to the entry's containing directory if fetching missing metadata is desired (an exception is thrown otherwise). You can get this from an op ref using dirop.get_handle(). + + + +][ + +] +] +[[``fieldtype st_perms(handle_ptr dirh = handle_ptr())`` + +] [Returns st_perms. ] [[* handle_ptr]: ['dirh]: An optional open handle to the entry's containing directory if fetching missing metadata is desired (an exception is thrown otherwise). You can get this from an op ref using dirop.get_handle(). + + + +][ + +] +] +[[``fieldtype st_nlink(handle_ptr dirh = handle_ptr())`` + +] [Returns st_nlink. ] [[* handle_ptr]: ['dirh]: An optional open handle to the entry's containing directory if fetching missing metadata is desired (an exception is thrown otherwise). You can get this from an op ref using dirop.get_handle(). + + + +][ + +] +] +[[``fieldtype st_uid(handle_ptr dirh = handle_ptr())`` + +] [Returns st_uid. ] [[* handle_ptr]: ['dirh]: An optional open handle to the entry's containing directory if fetching missing metadata is desired (an exception is thrown otherwise). You can get this from an op ref using dirop.get_handle(). + + + +][ + +] +] +[[``fieldtype st_gid(handle_ptr dirh = handle_ptr())`` + +] [Returns st_gid. ] [[* handle_ptr]: ['dirh]: An optional open handle to the entry's containing directory if fetching missing metadata is desired (an exception is thrown otherwise). You can get this from an op ref using dirop.get_handle(). + + + +][ + +] +] +[[``fieldtype st_rdev(handle_ptr dirh = handle_ptr())`` + +] [Returns st_rdev. ] [[* handle_ptr]: ['dirh]: An optional open handle to the entry's containing directory if fetching missing metadata is desired (an exception is thrown otherwise). You can get this from an op ref using dirop.get_handle(). + + + +][ + +] +] +[[``fieldtype st_atim(handle_ptr dirh = handle_ptr())`` + +] [Returns st_atim. ] [[* handle_ptr]: ['dirh]: An optional open handle to the entry's containing directory if fetching missing metadata is desired (an exception is thrown otherwise). You can get this from an op ref using dirop.get_handle(). + + + +][ + +] +] +[[``fieldtype st_mtim(handle_ptr dirh = handle_ptr())`` + +] [Returns st_mtim. ] [[* handle_ptr]: ['dirh]: An optional open handle to the entry's containing directory if fetching missing metadata is desired (an exception is thrown otherwise). You can get this from an op ref using dirop.get_handle(). + + + +][ + +] +] +[[``fieldtype st_ctim(handle_ptr dirh = handle_ptr())`` + +] [Returns st_ctim. ] [[* handle_ptr]: ['dirh]: An optional open handle to the entry's containing directory if fetching missing metadata is desired (an exception is thrown otherwise). You can get this from an op ref using dirop.get_handle(). + + + +][ + +] +] +[[``fieldtype st_size(handle_ptr dirh = handle_ptr())`` + +] [Returns st_size. ] [[* handle_ptr]: ['dirh]: An optional open handle to the entry's containing directory if fetching missing metadata is desired (an exception is thrown otherwise). You can get this from an op ref using dirop.get_handle(). + + + +][ + +] +] +[[``fieldtype st_allocated(handle_ptr dirh = handle_ptr())`` + +] [Returns st_allocated. ] [[* handle_ptr]: ['dirh]: An optional open handle to the entry's containing directory if fetching missing metadata is desired (an exception is thrown otherwise). You can get this from an op ref using dirop.get_handle(). + + + +][ + +] +] +[[``fieldtype st_blocks(handle_ptr dirh = handle_ptr())`` + +] [Returns st_blocks. ] [[* handle_ptr]: ['dirh]: An optional open handle to the entry's containing directory if fetching missing metadata is desired (an exception is thrown otherwise). You can get this from an op ref using dirop.get_handle(). + + + +][ + +] +] +[[``fieldtype st_blksize(handle_ptr dirh = handle_ptr())`` + +] [Returns st_blksize. ] [[* handle_ptr]: ['dirh]: An optional open handle to the entry's containing directory if fetching missing metadata is desired (an exception is thrown otherwise). You can get this from an op ref using dirop.get_handle(). + + + +][ + +] +] +[[``fieldtype st_flags(handle_ptr dirh = handle_ptr())`` + +] [Returns st_flags. ] [[* handle_ptr]: ['dirh]: An optional open handle to the entry's containing directory if fetching missing metadata is desired (an exception is thrown otherwise). You can get this from an op ref using dirop.get_handle(). + + + +][ + +] +] +[[``fieldtype st_gen(handle_ptr dirh = handle_ptr())`` + +] [Returns st_gen. ] [[* handle_ptr]: ['dirh]: An optional open handle to the entry's containing directory if fetching missing metadata is desired (an exception is thrown otherwise). You can get this from an op ref using dirop.get_handle(). + + + +][ + +] +] +[[``fieldtype st_birthtim(handle_ptr dirh = handle_ptr())`` + +] [Returns st_birthtim. ] [[* handle_ptr]: ['dirh]: An optional open handle to the entry's containing directory if fetching missing metadata is desired (an exception is thrown otherwise). You can get this from an op ref using dirop.get_handle(). + + + +][ + +] +] +[[``metadata_flags metadata_supported()`` + +] [A bitfield of what metadata is available on this platform. This doesn't mean all is available for every filing system. ] [ + +][ + +] +] +[[``metadata_flags metadata_fastpath()`` + +] [A bitfield of what metadata is fast on this platform. This doesn't mean all is available for every filing system. ] [ + +][ + +] +] +[[``size_t compatibility_maximum()`` + +] [The maximum number of entries which is "usual" to fetch at once i.e. what your libc does. ] [ + +][ + +] +] +] + +[heading Header] +`#include <boost/afio/v2/afio.hpp>` + +[include generated/struct_directory_entry_hash.qbk] + +'''<?dbhtml-include href="disqus_comments.html"?>''' +[endsect] + diff --git a/attic/doc/generated/class_dispatcher.qbk b/attic/doc/generated/class_dispatcher.qbk new file mode 100644 index 00000000..5dc5395f --- /dev/null +++ b/attic/doc/generated/class_dispatcher.qbk @@ -0,0 +1,341 @@ +[/============================================================================ + Boost.AFIO + + Use, modification and distribution is subject to the Boost Software License, + Version 1.0. (See accompanying file LICENSE_1_0.txt or copy at + http://www.boost.org/LICENSE_1_0.txt) +=============================================================================/] + + +[/ Generated by doxygen_xml2qbk 1.1.1, don't change, will be overwritten automatically] +[/ Generated from doxy/doxygen_output/xml\classboost_1_1afio_1_1dispatcher.xml] +[section:dispatcher dispatcher] +'''<?dbhtml-include href="disqus_identifiers/dispatcher.html"?>''' + +'''<indexterm><primary>dispatcher</primary></indexterm>''' +Abstract base class for dispatching file i/o asynchronously. + +[heading Description] +This is a reference counted instance with platform-specific implementation in object code. Construct an instance using the [^`boost::afio::make_dispatcher()`] function. + +[heading Synopsis] +``class dispatcher + : public std::enable_shared_from_this< dispatcher > +{ + // ... +}; +`` + +[heading Constructor(s)] +[table +[[Function] [Description] [Parameters] ] +[[``~dispatcher()`` + +] [Destroys the dispatcher, blocking inefficiently if any ops are still in flight. ] [ + +]] +] + +[heading Member Function(s)] +[table +[[Function] [Description] [Parameters] [Returns]] +[[``void testing_flags(detail::unit_testing_flags flags)`` + +] [] [[* detail::unit_testing_flags]: ['flags]: + + + +][ + +] +] +[[``std::shared_ptr< thread_source > threadsource()`` + +] [Returns the thread source used by this dispatcher. ] [ + +][ + +] +] +[[``file_flags fileflags(file_flags flags)`` + +] [Returns file flags as would be used after forcing and masking bits passed during construction. ] [[* file_flags]: ['flags]: + + + +][ + +] +] +[[``size_t wait_queue_depth()`` + +] [Returns the current wait queue depth of this dispatcher. ] [ + +][ + +] +] +[[``size_t fd_count()`` + +] [Returns the number of open items in this dispatcher. ] [ + +][ + +] +] +[[``std::vector< future<> > dir(const std::vector< path_req > & reqs)`` + +] [Schedule a batch of asynchronous directory creations and opens after optional preconditions. ] [[* const std::vector< path_req > &]: ['reqs]: A batch of [^`path_req`] structures. + + + +][ +A batch of op handles. + +] +] +[[``std::vector< future<> > rmdir(const std::vector< path_req > & reqs)`` + +] [Schedule a batch of asynchronous directory deletions after optional preconditions. ] [[* const std::vector< path_req > &]: ['reqs]: A batch of [^`path_req`] structures. + + + +][ +A batch of op handles. + +] +] +[[``std::vector< future<> > file(const std::vector< path_req > & reqs)`` + +] [Schedule a batch of asynchronous file creations and opens after optional preconditions. ] [[* const std::vector< path_req > &]: ['reqs]: A batch of [^`path_req`] structures. + + + +][ +A batch of op handles. + +] +] +[[``std::vector< future<> > rmfile(const std::vector< path_req > & reqs)`` + +] [Schedule a batch of asynchronous file deletions after optional preconditions. ] [[* const std::vector< path_req > &]: ['reqs]: A batch of [^`path_req`] structures. + + + +][ +A batch of op handles. + +] +] +[[``std::vector< future<> > symlink(const std::vector< path_req > & reqs, const std::vector< future<>> & targets = std::vector< future<>>())`` + +] [Schedule a batch of asynchronous symlink creations and opens after a precondition. ] [[* const std::vector< path_req > &]: ['reqs]: A batch of [^`path_req`] structures. + +[* const std::vector< future<>> &]: ['targets]: An optional batch of targets if creating symlinks. + + + +][ +A batch of op handles. + +] +] +[[``std::vector< future<> > rmsymlink(const std::vector< path_req > & reqs)`` + +] [Schedule a batch of asynchronous symlink deletions after optional preconditions. ] [[* const std::vector< path_req > &]: ['reqs]: A batch of [^`path_req`] structures. + + + +][ +A batch of op handles. + +] +] +[[``std::vector< future<> > sync(const std::vector< future<>> & ops)`` + +] [Schedule a batch of asynchronous content synchronisations with physical storage after preceding operations. ] [[* const std::vector< future<>> &]: ['ops]: A batch of op handles. + + + +][ +A batch of op handles. + +] +] +[[``std::vector< future<> > zero(const std::vector< future<>> & ops, const std::vector< std::vector< std::pair< off_t, off_t >>> & ranges)`` + +] [Schedule a batch of asynchronous zeroing and deallocations of physical storage ("hole punching") after preceding operations. ] [[* const std::vector< future<>> &]: ['ops]: A batch of op handles. + +[* const std::vector< std::vector< std::pair< off_t, off_t >>> &]: ['ranges]: A batch of vectors of extents to zero and deallocate. + + + +][ +A batch of op handles. + +] +] +[[``std::vector< future<> > close(const std::vector< future<>> & ops)`` + +] [Schedule a batch of asynchronous file or directory handle closes after preceding operations. ] [[* const std::vector< future<>> &]: ['ops]: A batch of op handles. + + + +][ +A batch of op handles. + +] +] +[[``template<class T> +std::vector< future<> > read(const std::vector< io_req< T >> & ops)`` + +] [Schedule a batch of asynchronous data reads after preceding operations, where offset and total data read must not exceed the present file size. ] [[* const std::vector< io_req< T >> &]: ['ops]: A batch of io_req<T> structures. + + + +][ +A batch of op handles. + +] +] +[[``template<class T> +std::vector< future<> > write(const std::vector< io_req< const T >> & ops)`` + +] [Schedule a batch of asynchronous data writes after preceding operations, where offset and total data written must not exceed the present file size. ] [[* const std::vector< io_req< const T >> &]: ['ops]: A batch of io_req<const T> structures. + + + +][ +A batch of op handles. + +] +] +[[``std::vector< future<> > truncate(const std::vector< future<>> & ops, const std::vector< off_t > & sizes)`` + +] [Schedule a batch of asynchronous file length truncations after preceding operations. ] [[* const std::vector< future<>> &]: ['ops]: A batch of op handles. + +[* const std::vector< off_t > &]: ['sizes]: A batch of new lengths. + + + +][ +A batch of op handles. + +] +] +[[``std::vector< future< std::pair< std::vector< directory_entry >, bool > > > enumerate(const std::vector< enumerate_req > & reqs)`` + +] [Schedule a batch of asynchronous directory enumerations after preceding operations. ] [[* const std::vector< enumerate_req > &]: ['reqs]: A batch of enumeration requests. + + + +][ +A batch of stl_future vectors of directory entries with boolean returning false if done. + +] +] +[[``std::vector< future< std::vector< std::pair< off_t, off_t > > > > extents(const std::vector< future<>> & ops)`` + +] [Schedule a batch of asynchronous extent enumerations after preceding operations. ] [[* const std::vector< future<>> &]: ['ops]: A batch of op handles. + + + +][ +A batch of stl_future vectors of extents. + +] +] +[[``std::vector< future< statfs_t > > statfs(const std::vector< future<>> & ops, const std::vector< fs_metadata_flags > & reqs)`` + +] [Schedule a batch of asynchronous volume enumerations after preceding operations. ] [[* const std::vector< future<>> &]: ['ops]: A batch of op handles. + +[* const std::vector< fs_metadata_flags > &]: ['reqs]: A batch of metadata requests. + + + +][ +A batch of stl_future volume metadatas. + +] +] +[[``future depends(future<> precondition, future<> op)`` + +] [Schedule the return of an op handle after another op handle completes. This is useful when you need to supply one op handle to a function but it must not begin until another op handle has finished. ] [[* future<>]: ['precondition]: The op handle which must complete for op to be passed through. + +[* future<>]: ['op]: The op handle to return. + + + +][ +The op handle op. + +] +] +[[``void complete_async_op(size_t id, handle_ptr h, exception_ptr e = exception_ptr())`` + +] [Completes an operation with a handle or an error, usually used when an operation was previously deferred. ] [[* size_t]: ['id]: + +[* handle_ptr]: ['h]: + +[* exception_ptr]: ['e]: + + + +][ + +] +] +[[``void complete_async_op(size_t id, exception_ptr e)`` + +] [Completes an operation with an error, usually used when an operation was previously deferred. ] [[* size_t]: ['id]: + +[* exception_ptr]: ['e]: + + + +][ + +] +] +[[``template<class T> +std::vector< future<> > read(const std::vector< io_req< T >> & ops)`` + +] [] [[* const std::vector< io_req< T >> &]: ['ops]: + + + +][ + +] +] +[[``template<class T> +std::vector< future<> > write(const std::vector< io_req< T >> & ops)`` + +] [] [[* const std::vector< io_req< T >> &]: ['ops]: + + + +][ + +] +] +] + +[heading Header] +`#include <boost/afio/v2/afio.hpp>` + +[/ link afio.reference.functions.async_file_io_dispatcher `async_file_io_dispatcher()`] +[/ include generated/group_dispatcher__filter.qbk] +[/ include generated/group_dispatcher__completion.qbk] +[/ include generated/group_dispatcher__call.qbk] +[include generated/group_dispatcher__filedirops.qbk] +[include generated/group_dispatcher__enumerate.qbk] +[include generated/group_dispatcher__extents.qbk] +[include generated/group_dispatcher__statfs.qbk] +[/ include generated/group_dispatcher__depends.qbk] +[/ include generated/group_dispatcher__barrier.qbk] +[include generated/group_dispatcher__misc.qbk] + +'''<?dbhtml-include href="disqus_comments.html"?>''' +[endsect] + diff --git a/attic/doc/generated/class_enqueued_task.qbk b/attic/doc/generated/class_enqueued_task.qbk new file mode 100644 index 00000000..880c7fcf --- /dev/null +++ b/attic/doc/generated/class_enqueued_task.qbk @@ -0,0 +1,37 @@ +[/============================================================================ + Boost.AFIO + + Use, modification and distribution is subject to the Boost Software License, + Version 1.0. (See accompanying file LICENSE_1_0.txt or copy at + http://www.boost.org/LICENSE_1_0.txt) +=============================================================================/] + + +[/ Generated by doxygen_xml2qbk 1.1.1, don't change, will be overwritten automatically] +[/ Generated from doxy/doxygen_output/xml\classboost_1_1afio_1_1enqueued__task.xml] +[section:enqueued_task enqueued_task] +'''<?dbhtml-include href="disqus_identifiers/enqueued_task.html"?>''' + +'''<indexterm><primary>enqueued_task</primary></indexterm>''' +Effectively our own custom std::packaged_task<>, with copy semantics and letting us early set value to significantly improve performance. + +[heading Synopsis] +``template<class R> +class enqueued_task +{ + // ... +}; +`` + +[heading Template parameter(s)] +[table +[[Parameter] [Description]] +[[class R] [The return type of the callable which must be without parameters. Unlike [^`std::packaged_task<>`], this custom variant is copyable though each copy always refers to the same internal state. Early stl_future value setting is possible, with any subsequent value setting including that by the function being executed being ignored. Note that this behaviour opens the potential to lose exception state - if you set the stl_future value early and then an exception is later thrown, the exception is swallowed. ]] +] + +[heading Header] +`#include <boost/afio/v2/afio.hpp>` + +'''<?dbhtml-include href="disqus_comments.html"?>''' +[endsect] + diff --git a/attic/doc/generated/class_enqueued_task_3_01_r_07_08_4.qbk b/attic/doc/generated/class_enqueued_task_3_01_r_07_08_4.qbk new file mode 100644 index 00000000..43dedb0a --- /dev/null +++ b/attic/doc/generated/class_enqueued_task_3_01_r_07_08_4.qbk @@ -0,0 +1,144 @@ +[/============================================================================ + Boost.AFIO + + Use, modification and distribution is subject to the Boost Software License, + Version 1.0. (See accompanying file LICENSE_1_0.txt or copy at + http://www.boost.org/LICENSE_1_0.txt) +=============================================================================/] + + +[/ Generated by doxygen_xml2qbk 1.1.1, don't change, will be overwritten automatically] +[/ Generated from doxy/doxygen_output/xml\classboost_1_1afio_1_1enqueued__task_3_01_r_07_08_4.xml] +[section:enqueued_task_r___ enqueued_task< R()>] +'''<?dbhtml-include href="disqus_identifiers/enqueued_task_r___.html"?>''' + +'''<indexterm><primary>enqueued_task< R()></primary></indexterm>''' + + +[heading Synopsis] +``template<class R> +class enqueued_task< R()> + : public detail::enqueued_task_impl< R > +{ + // ... +}; +`` + +[heading Template parameter(s)] +[table +[[Parameter] [Description]] +[[class R] []] +] + +[heading Member Function(s)] +[table +[[Function] [Description] [Parameters] [Returns]] +[[``bool valid()`` + +] [Returns true if valid. ] [ + +][ + +] +] +[[``void swap(enqueued_task_impl & o)`` + +] [Swaps contents with another instance. ] [[* enqueued_task_impl &]: ['o]: + + + +][ + +] +] +[[``void reset()`` + +] [Resets the contents. ] [ + +][ + +] +] +[[``void set_task(std::function< R()> _task)`` + +] [Sets the task. ] [[* std::function< R()>]: ['_task]: + + + +][ + +] +] +[[``const shared_future< R > & get_future()`` + +] [Returns the shared stl_future corresponding to the stl_future return value of the task. ] [ + +][ + +] +] +[[``template<class T> +void set_future_value(T v)`` + +] [Sets the shared stl_future corresponding to the stl_future return value of the task. ] [[* T]: ['v]: + + + +][ + +] +] +[[``void set_future_value()`` + +] [] [ + +][ + +] +] +[[``void set_future_exception(exception_ptr e)`` + +] [Sets the shared stl_future corresponding to the stl_future return value of the task. ] [[* exception_ptr]: ['e]: + + + +][ + +] +] +[[``void disable_auto_set_future(bool v = true)`` + +] [Disables the task setting the shared stl_future return value. ] [[* bool]: ['v]: + + + +][ + +] +] +[[`` enqueued_task(std::function< R()> _task = std::function< R()>())`` + +] [Default constructor. ] [[* std::function< R()>]: ['_task]: + + + +][ + +] +] +[[``void operator()()`` + +] [Invokes the callable, setting the shared stl_future to the value it returns. ] [ + +][ + +] +] +] + +[heading Header] +`#include <boost/afio/v2/afio.hpp>` + +'''<?dbhtml-include href="disqus_comments.html"?>''' +[endsect] + diff --git a/attic/doc/generated/class_enqueued_task_3_01void_07_08_4.qbk b/attic/doc/generated/class_enqueued_task_3_01void_07_08_4.qbk new file mode 100644 index 00000000..cefcb808 --- /dev/null +++ b/attic/doc/generated/class_enqueued_task_3_01void_07_08_4.qbk @@ -0,0 +1,136 @@ +[/============================================================================ + Boost.AFIO + + Use, modification and distribution is subject to the Boost Software License, + Version 1.0. (See accompanying file LICENSE_1_0.txt or copy at + http://www.boost.org/LICENSE_1_0.txt) +=============================================================================/] + + +[/ Generated by doxygen_xml2qbk 1.1.1, don't change, will be overwritten automatically] +[/ Generated from doxy/doxygen_output/xml\classboost_1_1afio_1_1enqueued__task_3_01void_07_08_4.xml] +[section:enqueued_task_void___ enqueued_task< void()>] +'''<?dbhtml-include href="disqus_identifiers/enqueued_task_void___.html"?>''' + +'''<indexterm><primary>enqueued_task< void()></primary></indexterm>''' + + +[heading Synopsis] +``class enqueued_task< void()> + : public detail::enqueued_task_impl< void > +{ + // ... +}; +`` + +[heading Member Function(s)] +[table +[[Function] [Description] [Parameters] [Returns]] +[[``bool valid()`` + +] [Returns true if valid. ] [ + +][ + +] +] +[[``void swap(enqueued_task_impl & o)`` + +] [Swaps contents with another instance. ] [[* enqueued_task_impl &]: ['o]: + + + +][ + +] +] +[[``void reset()`` + +] [Resets the contents. ] [ + +][ + +] +] +[[``void set_task(std::function< void()> _task)`` + +] [Sets the task. ] [[* std::function< void()>]: ['_task]: + + + +][ + +] +] +[[``const shared_future< void > & get_future()`` + +] [Returns the shared stl_future corresponding to the stl_future return value of the task. ] [ + +][ + +] +] +[[``void set_future_value(T v)`` + +] [Sets the shared stl_future corresponding to the stl_future return value of the task. ] [[* T]: ['v]: + + + +][ + +] +] +[[``void set_future_value()`` + +] [] [ + +][ + +] +] +[[``void set_future_exception(exception_ptr e)`` + +] [Sets the shared stl_future corresponding to the stl_future return value of the task. ] [[* exception_ptr]: ['e]: + + + +][ + +] +] +[[``void disable_auto_set_future(bool v = true)`` + +] [Disables the task setting the shared stl_future return value. ] [[* bool]: ['v]: + + + +][ + +] +] +[[`` enqueued_task(std::function< void()> _task = std::function< void()>())`` + +] [Default constructor. ] [[* std::function< void()>]: ['_task]: + + + +][ + +] +] +[[``void operator()()`` + +] [Invokes the callable, setting the stl_future to the value it returns. ] [ + +][ + +] +] +] + +[heading Header] +`#include <boost/afio/v2/afio.hpp>` + +'''<?dbhtml-include href="disqus_comments.html"?>''' +[endsect] + diff --git a/attic/doc/generated/class_future.qbk b/attic/doc/generated/class_future.qbk new file mode 100644 index 00000000..2a770f7f --- /dev/null +++ b/attic/doc/generated/class_future.qbk @@ -0,0 +1,114 @@ +[/============================================================================ + Boost.AFIO + + Use, modification and distribution is subject to the Boost Software License, + Version 1.0. (See accompanying file LICENSE_1_0.txt or copy at + http://www.boost.org/LICENSE_1_0.txt) +=============================================================================/] + + +[/ Generated by doxygen_xml2qbk 1.1.1, don't change, will be overwritten automatically] +[/ Generated from doxy/doxygen_output/xml\classboost_1_1afio_1_1future.xml] +[section:future future] +'''<?dbhtml-include href="disqus_identifiers/future.html"?>''' + +'''<indexterm><primary>future</primary></indexterm>''' +The future status of a scheduled asynchronous operation. + +[heading Description] +Other than the fact that [^`get()`] returns a [^`T`] and [^`get_handle()`] returns a handle, the errored and excepted state for both is identical and non-consuming for both. + +Finally, note that there is a freely available type slice from [^`future<T>`] to [^`future<void>`] which moves/copies only the [^`future<void>`] part of the [^`future<T>`], leaving the [^`T`] behind. This is because the AFIO engine resides behind a stable ABI layer which cannot know anything about arbitrary types, and therefore it accepts only [^`future<void>`]. Equally, this means you can supply a [^`future<T>`] as a precondition to another op safe in the knowledge that any [^`T`] part will remain untouched for later consumption. + +[heading Synopsis] +``template<class T, > +class future +{ + // ... +}; +`` + +[heading Template parameter(s)] +[table +[[Parameter] [Default] [Description]] +[[class T] [void] []] +[[] [] [Any returned result. Note this is defaulted to [^`void`] for you, so usually you write [^`future<>`]. As of v1.4 of the AFIO engine, the legacy [^`async_io_op`] struct has been replaced with this custom future type based on the lightweight future-promise factory toolkit in forthcoming Boost.Monad. This custom future type consists of two pieces of future data each with different semantics:A [^`handle_ptr`] retrieved using [^`get_handle()`], [^`operator*`] and [^`operator->`] - this is the shared i/o handle returned by the asynchronous operation. This has non-consuming semantics i.e. you can call [^`get_handle()`] as many times as you like. Note that for legacy compatibility reasons, calling [^`get_handle()`] on an invalid instance returns a null shared pointer instead of an exception throw.If T is non-void, any type [^`T`] - this is any additional data returned by an asynchronous operation above and beyond the i/o handle (e.g. [^`enumerate()`] returns a [^`std::pair<std::vector<``directory_entry``>, bool>`]. This has ['consuming] semantics, so calling [^`get()`] returns the result exactly once.]] +] + +[heading Constructor(s)] +[table +[[Function] [Description] [Parameters] ] +[[``future()`` + +] [] [ + +]] +[[``future(dispatcher * parent, size_t id, shared_future< handle_ptr > handle, + stl_future< T > result, bool check_handle = true, bool validate = true)`` + +] [] [[* dispatcher *]: ['parent]: The dispatcher this op belongs to. + +[* size_t]: ['id]: The unique non-zero id of this op. + +[* shared_future< handle_ptr >]: ['handle]: A shared_future to shared state between all instances of this reference. + +[* stl_future< T >]: ['result]: A future to any result from the operation. + +[* bool]: ['check_handle]: Whether to have validation additionally check if a handle is not null + +[* bool]: ['validate]: Whether to check the inputs and shared state for valid (and not errored) values + + + +]] +[[``future(future< void > && o, stl_future< T > && result)`` + +] [] [[* future< void > &&]: ['o]: The future<void> + +[* stl_future< T > &&]: ['result]: The future<T> to add + + + +]] +] + +[heading Member Function(s)] +[table +[[Function] [Description] [Parameters] [Returns]] +[[``bool valid(bool just_handle = false)`` + +] [True if this future is valid. ] [[* bool]: ['just_handle]: + + + +][ + +] +] +[[``T get()`` + +] [Waits for the future to become ready, returning any value or rethrowing any exception found. Throws a [^`future_errc::no_state`] if this future is invalid. ] [ + +][ + +] +] +[[``template<class U> +auto then(U && f)`` + +] [Schedules a callable to be invoked after this future becomes ready. If this future is null, use the current async file i/o dispatcher. ] [[* U &&]: ['f]: + + + +][ + +] +] +] + +[heading Header] +`#include <boost/afio/v2/afio.hpp>` + +'''<?dbhtml-include href="disqus_comments.html"?>''' +[endsect] + diff --git a/attic/doc/generated/class_future_3_01void_01_4.qbk b/attic/doc/generated/class_future_3_01void_01_4.qbk new file mode 100644 index 00000000..66a81055 --- /dev/null +++ b/attic/doc/generated/class_future_3_01void_01_4.qbk @@ -0,0 +1,336 @@ +[/============================================================================ + Boost.AFIO + + Use, modification and distribution is subject to the Boost Software License, + Version 1.0. (See accompanying file LICENSE_1_0.txt or copy at + http://www.boost.org/LICENSE_1_0.txt) +=============================================================================/] + + +[/ Generated by doxygen_xml2qbk 1.1.1, don't change, will be overwritten automatically] +[/ Generated from doxy/doxygen_output/xml\classboost_1_1afio_1_1future_3_01void_01_4.xml] +[section:future_void_ future< void >] +'''<?dbhtml-include href="disqus_identifiers/future_void_.html"?>''' + +'''<indexterm><primary>future< void ></primary></indexterm>''' + + +[heading Description] +future + +[heading Synopsis] +``class future< void > +{ + // ... +}; +`` + +[heading Member Function(s)] +[table +[[Function] [Description] [Parameters] [Returns]] +[[`` future(future< void > && o, stl_future< void > && result)`` + +] [] [[* future< void > &&]: ['o]: + +[* stl_future< void > &&]: ['result]: + + + +][ + +] +] +[[`` future()`` + +] [Default constructor. ] [ + +][ + +] +] +[[`` future(const future & o)`` + +] [Copy constructor. ] [[* const future &]: ['o]: + + + +][ + +] +] +[[`` future(future && o)`` + +] [Move constructor. ] [[* future &&]: ['o]: + + + +][ + +] +] +[[`` future(dispatcher * parent, size_t id, shared_future< handle_ptr > handle, + bool check_handle = true, bool validate = true)`` + +] [] [[* dispatcher *]: ['parent]: The dispatcher this op belongs to. + +[* size_t]: ['id]: The unique non-zero id of this op. + +[* shared_future< handle_ptr >]: ['handle]: A shared_ptr to shared state between all instances of this reference. + +[* bool]: ['check_handle]: Whether to have validation additionally check if a handle is not null + +[* bool]: ['validate]: Whether to check the inputs and shared state for valid (and not errored) values + + + +][ + +] +] +[[`` future(handle_ptr _handle, bool check_handle = true, bool validate = true)`` + +] [] [[* handle_ptr]: ['_handle]: A shared_ptr to shared state between all instances of this reference. + +[* bool]: ['check_handle]: Whether to have validation additionally check if a handle is not null + +[* bool]: ['validate]: Whether to check the inputs and shared state for valid (and not errored) values + + + +][ + +] +] +[[`` future(dispatcher * parent, size_t id)`` + +] [] [[* dispatcher *]: ['parent]: The dispatcher this op belongs to. + +[* size_t]: ['id]: The unique non-zero id of this op. + + + +][ + +] +] +[[``future & operator=(const future & o)`` + +] [Copy assignment. ] [[* const future &]: ['o]: + + + +][ + +] +] +[[``future & operator=(future && o)`` + +] [Move assignment. ] [[* future &&]: ['o]: + + + +][ + +] +] +[[``bool valid()`` + +] [True if this future is valid. ] [ + +][ + +] +] +[[`` operator bool()`` + +] [Same as [^`true_(tribool(*this))`]] [ + +][ + +] +] +[[``bool is_ready()`` + +] [True if monad is not empty. ] [ + +][ + +] +] +[[``bool has_value()`` + +] [True if monad contains a value_type. ] [ + +][ + +] +] +[[``bool has_error()`` + +] [True if monad contains an error_type. ] [ + +][ + +] +] +[[``bool has_exception(bool only_exception = false)`` + +] [True if monad contains an exception_type or error_type (any error_type is returned as an exception_ptr by get_exception()). This needs to be true for both for compatibility with Boost.Thread's future. If you really want to test only for has exception only, pass true as the argument. ] [[* bool]: ['only_exception]: + + + +][ + +] +] +[[``dispatcher * parent()`` + +] [The parent dispatcher of this future. ] [ + +][ + +] +] +[[``size_t id()`` + +] [] [ + +][ + +] +] +[[``handle_ptr get_handle(bool return_null_if_errored = false)`` + +] [Retrieves the handle or exception from the shared state, rethrowing any exception. Returns a null shared pointer if this future is invalid. ] [[* bool]: ['return_null_if_errored]: + + + +][ + +] +] +[[``handle_ptr get_handle(error_type & ec)`` + +] [Retrieves the handle or exception from the shared state, rethrowing any exception but setting _ec if there is an error. Returns a null shared pointer if this future is invalid. ] [[* error_type &]: ['ec]: + + + +][ + +] +] +[[``const handle & operator*()`` + +] [Dereferences the handle from the shared state. Same as *h.get_handle(). ] [ + +][ + +] +] +[[``handle & operator*()`` + +] [Dereferences the handle from the shared state. Same as *h.get_handle(). ] [ + +][ + +] +] +[[``const handle * operator->()`` + +] [Dereferences the handle from the shared state. Same as h.get_handle()->get(). ] [ + +][ + +] +] +[[``handle * operator->()`` + +] [Dereferences the handle from the shared state. Same as h.get_handle()->get(). ] [ + +][ + +] +] +[[``void get()`` + +] [Waits for the future to become ready, rethrowing any exception found. Throws a [^`future_errc::no_state`] if this future is invalid. ] [ + +][ + +] +] +[[``error_type get_error()`` + +] [Waits for the future to become ready, returning any error state found. ] [ + +][ + +] +] +[[``exception_type get_exception()`` + +] [Waits for the future to become ready, returning any error state found. ] [ + +][ + +] +] +[[``void wait()`` + +] [Waits for the future to become ready. Throws a [^`future_errc::no_state`] if this future is invalid. ] [ + +][ + +] +] +[[``template<class Rep, class Period> +future_status wait_for(const chrono::duration< Rep, Period > & duration)`` + +] [Waits for the future to become ready for a period. Throws a [^`future_errc::no_state`] if this future is invalid. ] [[* const chrono::duration< Rep, Period > &]: ['duration]: + + + +][ + +] +] +[[``template<class Clock, class Duration> +future_status wait_until(const chrono::time_point< Clock, Duration > & deadline)`` + +] [Waits for the future to become ready until a deadline. Throws a [^`future_errc::no_state`] if this future is invalid. ] [[* const chrono::time_point< Clock, Duration > &]: ['deadline]: + + + +][ + +] +] +[[``template<class U> +auto then(U && f)`` + +] [Schedules a callable to be invoked after this future becomes ready. If this future is null, use the current async file i/o dispatcher. ] [[* U &&]: ['f]: + + + +][ + +] +] +[[``bool validate(bool check_handle = true)`` + +] [Validates contents. ] [[* bool]: ['check_handle]: + + + +][ + +] +] +] + +[heading Header] +`#include <boost/afio/v2/afio.hpp>` + +'''<?dbhtml-include href="disqus_comments.html"?>''' +[endsect] + diff --git a/attic/doc/generated/class_handle.qbk b/attic/doc/generated/class_handle.qbk new file mode 100644 index 00000000..6a5a8e41 --- /dev/null +++ b/attic/doc/generated/class_handle.qbk @@ -0,0 +1,276 @@ +[/============================================================================ + Boost.AFIO + + Use, modification and distribution is subject to the Boost Software License, + Version 1.0. (See accompanying file LICENSE_1_0.txt or copy at + http://www.boost.org/LICENSE_1_0.txt) +=============================================================================/] + + +[/ Generated by doxygen_xml2qbk 1.1.1, don't change, will be overwritten automatically] +[/ Generated from doxy/doxygen_output/xml\classboost_1_1afio_1_1handle.xml] +[section:handle handle] +'''<?dbhtml-include href="disqus_identifiers/handle.html"?>''' +[section:open_states open_states] +'''<?dbhtml-include href="disqus_identifiers/open_states.html"?>''' + +'''<indexterm><primary>open_states</primary></indexterm>''' +'''<indexterm><primary>closed</primary></indexterm>''' +'''<indexterm><primary>open</primary></indexterm>''' +'''<indexterm><primary>opendir</primary></indexterm>''' +In which way this handle is opened or not. + +[heading Synopsis] +``enum open_states {closed, open, opendir};`` + +[heading Values] + +[table +[[Value] [Description] ] +[[closed] [This handle is closed. ]] +[[open] [This handle is open as a normal handle. ]] +[[opendir] [This handle is open as a cached directory handle, and therefore closing it explicitly has no effect. ]] +] + + +[heading Header] +`#include <boost/afio/v2/afio.hpp>` + + +'''<?dbhtml-include href="disqus_comments.html"?>''' +[endsect] + + +'''<indexterm><primary>handle</primary></indexterm>''' +The abstract base class encapsulating a platform-specific file handle. + +[heading Description] +Note that failure to explicitly schedule closing a file handle in the dispatcher means it will be synchronously closed on last reference count by handle. This can consume considerable time, especially if SyncOnClose is enabled. + +[heading Synopsis] +``class handle + : public std::enable_shared_from_this< handle > +{ + // ... +}; +`` + +[heading Constructor(s)] +[table +[[Function] [Description] [Parameters] ] +[[``~handle()`` + +] [] [ + +]] +] + +[heading Member Function(s)] +[table +[[Function] [Description] [Parameters] [Returns]] +[[``dispatcher * parent()`` + +] [Returns the parent of this io handle. ] [ + +][ + +] +] +[[``handle_ptr container()`` + +] [Returns a handle to the directory containing this handle. Only works if [^`file_flags::hold_parent_open`] was specified when this handle was opened. ] [ + +][ + +] +] +[[``open_states is_open()`` + +] [Returns if this handle is opened or not. ] [ + +][ + +] +] +[[``void * native_handle()`` + +] [Returns the native handle of this io handle. On POSIX, you can cast this to a fd using [^`(int)(size_t) ``native_handle()`]. On Windows it's a simple [^`(HANDLE) ``native_handle()`]. ] [ + +][ + +] +] +[[``const chrono::system_clock::time_point & opened()`` + +] [Returns when this handle was opened. ] [ + +][ + +] +] +[[``boost::afio::path path(bool refresh = false)`` + +] [Returns the path of this i/o handle right now if the handle is open and ['refresh] is true, else last known good. May be null if the file has been deleted. ] [[* bool]: ['refresh]: Whether to ask the OS for the current path of this handle. + + + +][ +The path of this i/o handle right now. + +] +] +[[``boost::afio::path path()`` + +] [Returns the last known good path of this i/o handle. May be null if the file has been deleted. ] [ + +][ + +] +] +[[``file_flags flags()`` + +] [Returns the final flags used when this handle was opened. ] [ + +][ + +] +] +[[``bool opened_as_file()`` + +] [True if this handle was opened as a file. ] [ + +][ + +] +] +[[``bool opened_as_dir()`` + +] [True if this handle was opened as a directory. ] [ + +][ + +] +] +[[``bool opened_as_symlink()`` + +] [True if this handle was opened as a symlink. ] [ + +][ + +] +] +[[``bool available_to_directory_cache()`` + +] [True if this handle is used by the directory handle cache (not UniqueDirectoryHandle and is open for write and not open for write) ] [ + +][ + +] +] +[[``off_t read_count()`` + +] [Returns how many bytes have been read since this handle was opened. ] [ + +][ + +] +] +[[``off_t write_count()`` + +] [Returns how many bytes have been written since this handle was opened. ] [ + +][ + +] +] +[[``off_t write_count_since_fsync()`` + +] [Returns how many bytes have been written since this handle was last fsynced. ] [ + +][ + +] +] +[[``directory_entry direntry(metadata_flags wanted = directory_entry::metadata_fastpath())`` + +] [Returns a mostly filled directory_entry for the file or directory referenced by this handle. Use [^`metadata_flags::All`] if you want it as complete as your platform allows, even at the cost of severe performance loss. ] [[* metadata_flags]: ['wanted]: The metadata wanted. + + + +][ +A directory entry for this handle. + +] +] +[[``stat_t lstat(metadata_flags wanted = directory_entry::metadata_fastpath())`` + +] [Returns a mostly filled stat_t structure for the file or directory referenced by this handle. Use [^`metadata_flags::All`] if you want it as complete as your platform allows, even at the cost of severe performance loss. Calls direntry(), so same race guarantees as that call. ] [[* metadata_flags]: ['wanted]: + + + +][ + +] +] +[[``boost::afio::path target()`` + +] [Returns the target path of this handle if it is a symbolic link. ] [ + +][ +The path the symbolic link points to. May not exist or even be valid. + +] +] +[[``mapped_file_ptr map_file(size_t length = (size_t)-1, off_t offset = 0, bool read_only = false)`` + +] [Maps the file into memory, returning a null pointer if couldn't map (e.g. address space exhaustion). Do NOT mix this with [^`file_flags::os_direct`]! ] [[* size_t]: ['length]: + +[* off_t]: ['offset]: + +[* bool]: ['read_only]: + + + +][ + +] +] +[[``void link(const path_req & req)`` + +] [Hard links the file to a new location on the same volume. ] [[* const path_req &]: ['req]: The absolute or relative (in which case precondition specifies a directory) path to create a hard link at. + + + +][ + +] +] +[[``void unlink()`` + +] [Unlinks the file from its present location as determined by path(true), which could be any hard link on those operating systems with an unstable path(true). Other links may remain to the same file. ] [ + +][ + +] +] +[[``void atomic_relink(const path_req & req)`` + +] [Links the file to a new location and unlinks the file from its present location as determined by path(true), ['atomically overwriting any file entry at the new location]. Very useful for preparing file content elsewhere and once ready, atomically making it visible at some named location to other processes. Note that operating systems with an unstable path(true) may relink any hard link to the file to the new location. ] [[* const path_req &]: ['req]: The absolute or relative (in which case precondition specifies a directory) path to relink to. + + + +][ + +] +] +] + +[heading Header] +`#include <boost/afio/v2/afio.hpp>` + +[include generated/struct_handle_1_1mapped_file.qbk] +[include generated/group_async_io_handle__ops.qbk] + +'''<?dbhtml-include href="disqus_comments.html"?>''' +[endsect] + diff --git a/attic/doc/generated/class_path.qbk b/attic/doc/generated/class_path.qbk new file mode 100644 index 00000000..473bc102 --- /dev/null +++ b/attic/doc/generated/class_path.qbk @@ -0,0 +1,387 @@ +[/============================================================================ + Boost.AFIO + + Use, modification and distribution is subject to the Boost Software License, + Version 1.0. (See accompanying file LICENSE_1_0.txt or copy at + http://www.boost.org/LICENSE_1_0.txt) +=============================================================================/] + + +[/ Generated by doxygen_xml2qbk 1.1.1, don't change, will be overwritten automatically] +[/ Generated from doxy/doxygen_output/xml\classboost_1_1afio_1_1path.xml] +[section:path path] +'''<?dbhtml-include href="disqus_identifiers/path.html"?>''' + +'''<indexterm><primary>path</primary></indexterm>''' +An AFIO filesystem path, a thin wrapper of filesystem::path used to mark when a filesystem path has been prepared for AFIO usage. Note that on Windows this exclusively refers to a case sensitive NT kernel path, not a Win32 path (Win32 paths are converted in the constructor). + +[heading Synopsis] +``class path + : protected path +{ + // ... +}; +`` + +[heading Constructor(s)] +[table +[[Function] [Description] [Parameters] ] +[[``path()`` + +] [Default constructor. ] [ + +]] +[[``path(const path & p)`` + +] [Copy constructor. ] [[* const path &]: ['p]: + + + +]] +[[``path(const filesystem::path & p)`` + +] [Converts a filesystem::path to AFIO format. ] [[* const filesystem::path &]: ['p]: + + + +]] +[[``path(const char * p)`` + +] [Converts a filesystem::path to AFIO format. ] [[* const char *]: ['p]: + + + +]] +[[``path(const string_type & p)`` + +] [Converts a filesystem::path to AFIO format. ] [[* const string_type &]: ['p]: + + + +]] +[[``path(path && p)`` + +] [Move constructor. ] [[* path &&]: ['p]: + + + +]] +[[``path(filesystem::path && p)`` + +] [Converts a filesystem::path to AFIO format. ] [[* filesystem::path &&]: ['p]: + + + +]] +[[``path(string_type && p)`` + +] [Converts a filesystem::path to AFIO format. ] [[* string_type &&]: ['p]: + + + +]] +[[``template<class InputIterator> +path(InputIterator begin, InputIterator end)`` + +] [Converts source to AFIO path format. ] [[* InputIterator]: ['begin]: + +[* InputIterator]: ['end]: + + + +]] +] + +[heading Member Function(s)] +[table +[[Function] [Description] [Parameters] [Returns]] +[[``path & operator=(const path & p)`` + +] [Copy assignment. ] [[* const path &]: ['p]: + + + +][ + +] +] +[[``path & operator=(path && p)`` + +] [Move assignment. ] [[* path &&]: ['p]: + + + +][ + +] +] +[[``template<class Source> +path & assign(Source const & source)`` + +] [Converts source to AFIO path format. ] [[* Source const &]: ['source]: + + + +][ + +] +] +[[``template<class InputIterator> +path & assign(InputIterator begin, InputIterator end)`` + +] [] [[* InputIterator]: ['begin]: + +[* InputIterator]: ['end]: + + + +][ + +] +] +[[``path & operator/=(const path & p)`` + +] [] [[* const path &]: ['p]: + + + +][ + +] +] +[[``template<class Source> +path & operator/=(Source const & source)`` + +] [] [[* Source const &]: ['source]: + + + +][ + +] +] +[[``template<class Source> +path & append(Source const & source)`` + +] [] [[* Source const &]: ['source]: + + + +][ + +] +] +[[``template<class InputIterator> +path & append(InputIterator begin, InputIterator end)`` + +] [] [[* InputIterator]: ['begin]: + +[* InputIterator]: ['end]: + + + +][ + +] +] +[[``path & operator+=(const path & x)`` + +] [] [[* const path &]: ['x]: + + + +][ + +] +] +[[``path & operator+=(const string_type & x)`` + +] [] [[* const string_type &]: ['x]: + + + +][ + +] +] +[[``path & operator+=(const value_type * x)`` + +] [] [[* const value_type *]: ['x]: + + + +][ + +] +] +[[``path & operator+=(value_type x)`` + +] [] [[* value_type]: ['x]: + + + +][ + +] +] +[[``template<class Source> +path & operator+=(Source const & x)`` + +] [] [[* Source const &]: ['x]: + + + +][ + +] +] +[[``template<class Source> +path & concat(Source const & x)`` + +] [] [[* Source const &]: ['x]: + + + +][ + +] +] +[[``template<class InputIterator> +path & concat(InputIterator begin, InputIterator end)`` + +] [] [[* InputIterator]: ['begin]: + +[* InputIterator]: ['end]: + + + +][ + +] +] +[[``path & make_preferred()`` + +] [] [ + +][ + +] +] +[[``path & remove_filename()`` + +] [] [ + +][ + +] +] +[[``path & replace_extension(const path & new_extension = path())`` + +] [] [[* const path &]: ['new_extension]: + + + +][ + +] +] +[[``path root_name()`` + +] [] [ + +][ + +] +] +[[``path root_directory()`` + +] [] [ + +][ + +] +] +[[``path root_path()`` + +] [] [ + +][ + +] +] +[[``path relative_path()`` + +] [] [ + +][ + +] +] +[[``path parent_path()`` + +] [] [ + +][ + +] +] +[[``path filename()`` + +] [] [ + +][ + +] +] +[[``path stem()`` + +] [] [ + +][ + +] +] +[[``path extension()`` + +] [] [ + +][ + +] +] +[[``iterator begin()`` + +] [] [ + +][ + +] +] +[[``iterator end()`` + +] [] [ + +][ + +] +] +[[``filesystem::path filesystem_path()`` + +] [Return a normalised filesystem::path from an AFIO path. ] [ + +][ + +] +] +] + +[heading Header] +`#include <boost/afio/v2/afio.hpp>` + +[include generated/struct_path_1_1make_absolute.qbk] +[include generated/group_normalise_path.qbk] +[include generated/struct_path_hash.qbk] + +'''<?dbhtml-include href="disqus_comments.html"?>''' +[endsect] + diff --git a/attic/doc/generated/class_std_thread_pool.qbk b/attic/doc/generated/class_std_thread_pool.qbk new file mode 100644 index 00000000..a7c940b9 --- /dev/null +++ b/attic/doc/generated/class_std_thread_pool.qbk @@ -0,0 +1,105 @@ +[/============================================================================ + Boost.AFIO + + Use, modification and distribution is subject to the Boost Software License, + Version 1.0. (See accompanying file LICENSE_1_0.txt or copy at + http://www.boost.org/LICENSE_1_0.txt) +=============================================================================/] + + +[/ Generated by doxygen_xml2qbk 1.1.1, don't change, will be overwritten automatically] +[/ Generated from doxy/doxygen_output/xml\classboost_1_1afio_1_1std__thread__pool.xml] +[section:std_thread_pool std_thread_pool] +'''<?dbhtml-include href="disqus_identifiers/std_thread_pool.html"?>''' + +'''<indexterm><primary>std_thread_pool</primary></indexterm>''' +A very simple thread pool based on std::thread or boost::thread. + +[heading Description] +This instantiates a [^`asio::io_service`] and a latchable [^`asio::io_service::work`] to keep any threads working until the instance is destructed. + +[heading Synopsis] +``class std_thread_pool + : public thread_source +{ + // ... +}; +`` + +[heading Constructor(s)] +[table +[[Function] [Description] [Parameters] ] +[[``std_thread_pool(size_t no)`` + +] [Constructs a thread pool of ['no] workers. ] [[* size_t]: ['no]: The number of worker threads to create + + + +]] +[[``~std_thread_pool()`` + +] [] [ + +]] +] + +[heading Member Function(s)] +[table +[[Function] [Description] [Parameters] [Returns]] +[[``asio::io_service & io_service()`` + +] [Returns the underlying io_service. ] [ + +][ + +] +] +[[``template<class R> +void enqueue(enqueued_task< R > task)`` + +] [Sends a task to the thread pool for execution. ] [[* enqueued_task< R >]: ['task]: + + + +][ + +] +] +[[``template<class F> +shared_future< typename std::result_of< F()>::type > enqueue(F f)`` + +] [Sends some callable entity to the thread pool for execution. ] [[* F]: ['f]: Any instance of a callable type + + + +][ +An enqueued task for the enqueued callable + +] +] +[[``void add_workers(size_t no)`` + +] [Adds more workers to the thread pool. ] [[* size_t]: ['no]: The number of worker threads to add + + + +][ + +] +] +[[``void destroy()`` + +] [Destroys the thread pool, waiting for worker threads to exit beforehand. ] [ + +][ + +] +] +] + +[heading Header] +`#include <boost/afio/v2/afio.hpp>` + +'''<?dbhtml-include href="disqus_comments.html"?>''' +[endsect] + diff --git a/attic/doc/generated/class_std_thread_pool_1_1worker.qbk b/attic/doc/generated/class_std_thread_pool_1_1worker.qbk new file mode 100644 index 00000000..f720e495 --- /dev/null +++ b/attic/doc/generated/class_std_thread_pool_1_1worker.qbk @@ -0,0 +1,55 @@ +[/============================================================================ + Boost.AFIO + + Use, modification and distribution is subject to the Boost Software License, + Version 1.0. (See accompanying file LICENSE_1_0.txt or copy at + http://www.boost.org/LICENSE_1_0.txt) +=============================================================================/] + + +[/ Generated by doxygen_xml2qbk 1.1.1, don't change, will be overwritten automatically] +[/ Generated from doxy/doxygen_output/xml\classboost_1_1afio_1_1std__thread__pool_1_1worker.xml] +[section:std_thread_pool_worker std_thread_pool::worker] +'''<?dbhtml-include href="disqus_identifiers/std_thread_pool_worker.html"?>''' + +'''<indexterm><primary>std_thread_pool</primary></indexterm><indexterm><primary>worker</primary></indexterm>''' + + +[heading Synopsis] +``class std_thread_pool::worker +{ + // ... +}; +`` + +[heading Constructor(s)] +[table +[[Function] [Description] [Parameters] ] +[[``worker(std_thread_pool * p)`` + +] [] [[* std_thread_pool *]: ['p]: + + + +]] +] + +[heading Member Function(s)] +[table +[[Function] [Description] [Parameters] [Returns]] +[[``void operator()()`` + +] [] [ + +][ + +] +] +] + +[heading Header] +`#include <boost/afio/v2/afio.hpp>` + +'''<?dbhtml-include href="disqus_comments.html"?>''' +[endsect] + diff --git a/attic/doc/generated/class_thread_source.qbk b/attic/doc/generated/class_thread_source.qbk new file mode 100644 index 00000000..621b0696 --- /dev/null +++ b/attic/doc/generated/class_thread_source.qbk @@ -0,0 +1,70 @@ +[/============================================================================ + Boost.AFIO + + Use, modification and distribution is subject to the Boost Software License, + Version 1.0. (See accompanying file LICENSE_1_0.txt or copy at + http://www.boost.org/LICENSE_1_0.txt) +=============================================================================/] + + +[/ Generated by doxygen_xml2qbk 1.1.1, don't change, will be overwritten automatically] +[/ Generated from doxy/doxygen_output/xml\classboost_1_1afio_1_1thread__source.xml] +[section:thread_source thread_source] +'''<?dbhtml-include href="disqus_identifiers/thread_source.html"?>''' + +'''<indexterm><primary>thread_source</primary></indexterm>''' +Abstract base class for a source of thread workers. + +[heading Description] +Note that in Boost 1.54, and possibly later versions, [^`asio::io_service`] on Windows appears to dislike being destructed during static data deinit, hence why this inherits from [^`std::enable_shared_from_this<>`] in order that it may be reference count deleted before static data deinit occurs. + +[heading Synopsis] +``class thread_source + : public std::enable_shared_from_this< thread_source > +{ + // ... +}; +`` + +[heading Member Function(s)] +[table +[[Function] [Description] [Parameters] [Returns]] +[[``asio::io_service & io_service()`` + +] [Returns the underlying io_service. ] [ + +][ + +] +] +[[``template<class R> +void enqueue(enqueued_task< R > task)`` + +] [Sends a task to the thread pool for execution. ] [[* enqueued_task< R >]: ['task]: + + + +][ + +] +] +[[``template<class F> +shared_future< typename std::result_of< F()>::type > enqueue(F f)`` + +] [Sends some callable entity to the thread pool for execution. ] [[* F]: ['f]: Any instance of a callable type + + + +][ +An enqueued task for the enqueued callable + +] +] +] + +[heading Header] +`#include <boost/afio/v2/afio.hpp>` + +'''<?dbhtml-include href="disqus_comments.html"?>''' +[endsect] + diff --git a/attic/doc/generated/class_utils_1_1page_allocator.qbk b/attic/doc/generated/class_utils_1_1page_allocator.qbk new file mode 100644 index 00000000..38a4614f --- /dev/null +++ b/attic/doc/generated/class_utils_1_1page_allocator.qbk @@ -0,0 +1,141 @@ +[/============================================================================ + Boost.AFIO + + Use, modification and distribution is subject to the Boost Software License, + Version 1.0. (See accompanying file LICENSE_1_0.txt or copy at + http://www.boost.org/LICENSE_1_0.txt) +=============================================================================/] + + +[/ Generated by doxygen_xml2qbk 1.1.1, don't change, will be overwritten automatically] +[/ Generated from doxy/doxygen_output/xml\classboost_1_1afio_1_1utils_1_1page__allocator.xml] +[section:utils_page_allocator utils::page_allocator] +'''<?dbhtml-include href="disqus_identifiers/utils_page_allocator.html"?>''' + +'''<indexterm><primary>utils</primary></indexterm><indexterm><primary>page_allocator</primary></indexterm>''' +An STL allocator which allocates large TLB page memory.If the operating system is configured to allow it, this type of memory is particularly efficient for doing large scale file i/o. This is because the kernel must normally convert the scatter gather buffers you pass into extended scatter gather buffers as the memory you see as contiguous may not, and probably isn't, actually be contiguous in physical memory. Regions returned by this allocator ['may] be allocated contiguously in physical memory and therefore the kernel can pass through your scatter gather buffers unmodified. + +[heading Description] +A particularly useful combination with this allocator is with the page\u005fsizes() member function of [*afio_dispatcher]. This will return which pages sizes are possible, and which page sizes are enabled for this user. If writing a file copy routine for example, using this allocator with the largest page size as the copy chunk makes a great deal of sense. + +Be aware that as soon as the allocation exceeds a large page size, most systems allocate in multiples of the large page size, so if the large page size were 2Mb and you allocate 2Mb + 1 byte, 4Mb is actually consumed. + +[heading Synopsis] +``template<typename T> +class utils::page_allocator +{ + // ... +}; +`` + +[heading Template parameter(s)] +[table +[[Parameter] [Description]] +[[typename T] []] +] + +[heading Constructor(s)] +[table +[[Function] [Description] [Parameters] ] +[[``page_allocator()`` + +] [] [ + +]] +[[``template<class U> +page_allocator(const page_allocator< U > & )`` + +] [] [[* const page_allocator< U > &]: [']: + + + +]] +] + +[heading Member Function(s)] +[table +[[Function] [Description] [Parameters] [Returns]] +[[``size_type max_size()`` + +] [] [ + +][ + +] +] +[[``pointer address(reference x)`` + +] [] [[* reference]: ['x]: + + + +][ + +] +] +[[``const_pointer address(const_reference x)`` + +] [] [[* const_reference]: ['x]: + + + +][ + +] +] +[[``pointer allocate(size_type n, const void * hint = 0)`` + +] [] [[* size_type]: ['n]: + +[* const void *]: ['hint]: + + + +][ + +] +] +[[``void deallocate(pointer p, size_type n)`` + +] [] [[* pointer]: ['p]: + +[* size_type]: ['n]: + + + +][ + +] +] +[[``template<class U, class... Args> +void construct(U * p, Args &&... args)`` + +] [] [[* U *]: ['p]: + +[* Args &&...]: ['args]: + + + +][ + +] +] +[[``template<class U> +void destroy(U * p)`` + +] [] [[* U *]: ['p]: + + + +][ + +] +] +] + +[heading Header] +`#include <boost/afio/v2/afio.hpp>` + +'''<?dbhtml-include href="disqus_comments.html"?>''' +[endsect] + diff --git a/attic/doc/generated/class_utils_1_1page_allocator_3_01void_01_4.qbk b/attic/doc/generated/class_utils_1_1page_allocator_3_01void_01_4.qbk new file mode 100644 index 00000000..4619e36f --- /dev/null +++ b/attic/doc/generated/class_utils_1_1page_allocator_3_01void_01_4.qbk @@ -0,0 +1,30 @@ +[/============================================================================ + Boost.AFIO + + Use, modification and distribution is subject to the Boost Software License, + Version 1.0. (See accompanying file LICENSE_1_0.txt or copy at + http://www.boost.org/LICENSE_1_0.txt) +=============================================================================/] + + +[/ Generated by doxygen_xml2qbk 1.1.1, don't change, will be overwritten automatically] +[/ Generated from doxy/doxygen_output/xml\classboost_1_1afio_1_1utils_1_1page__allocator_3_01void_01_4.xml] +[section:utils_page_allocator< void > utils::page_allocator< void >] +'''<?dbhtml-include href="disqus_identifiers/utils_page_allocator_-void-_.html"?>''' + +'''<indexterm><primary>utils</primary></indexterm><indexterm><primary>page_allocator< void ></primary></indexterm>''' + + +[heading Synopsis] +``class utils::page_allocator< void > +{ + // ... +}; +`` + +[heading Header] +`#include <boost/afio/v2/afio.hpp>` + +'''<?dbhtml-include href="disqus_comments.html"?>''' +[endsect] + diff --git a/attic/doc/generated/class_utils_1_1secded_ecc.qbk b/attic/doc/generated/class_utils_1_1secded_ecc.qbk new file mode 100644 index 00000000..04d7ecf3 --- /dev/null +++ b/attic/doc/generated/class_utils_1_1secded_ecc.qbk @@ -0,0 +1,175 @@ +[/============================================================================ + Boost.AFIO + + Use, modification and distribution is subject to the Boost Software License, + Version 1.0. (See accompanying file LICENSE_1_0.txt or copy at + http://www.boost.org/LICENSE_1_0.txt) +=============================================================================/] + + +[/ Generated by doxygen_xml2qbk 1.1.1, don't change, will be overwritten automatically] +[/ Generated from doxy/doxygen_output/xml\classboost_1_1afio_1_1utils_1_1secded__ecc.xml] +[section:utils_secded_ecc utils::secded_ecc] +'''<?dbhtml-include href="disqus_identifiers/utils_secded_ecc.html"?>''' +[section:verify_status verify_status] +'''<?dbhtml-include href="disqus_identifiers/verify_status.html"?>''' + +'''<indexterm><primary>verify_status</primary></indexterm>''' +'''<indexterm><primary>corrupt</primary></indexterm>''' +'''<indexterm><primary>okay</primary></indexterm>''' +'''<indexterm><primary>healed</primary></indexterm>''' +The outcomes from verify() + +[heading Synopsis] +``enum verify_status {corrupt = 0, okay = 1, healed = 2};`` + +[heading Values] + +[table +[[Value] [Description] ] +[[corrupt] [The buffer had more than a single bit corrupted or the ECC was invalid. ]] +[[okay] [The buffer had no errors. ]] +[[healed] [The buffer was healed. ]] +] + + +[heading Header] +`#include <boost/afio/v2/afio.hpp>` + + +'''<?dbhtml-include href="disqus_comments.html"?>''' +[endsect] + + +'''<indexterm><primary>utils</primary></indexterm><indexterm><primary>secded_ecc</primary></indexterm>''' +Calculates the single error correcting double error detecting (SECDED) Hamming Error Correcting Code for a ['blocksize] block of bytes. For example, a secdec_ecc<8> would be the very common 72,64 Hamming code used in ECC RAM, or secdec_ecc<4096> would be for a 32784,32768 Hamming code. + +[heading Description] +Did you know that some non-ECC RAM systems can see 1e-12 flips/bit/hour, which is 3.3 bits flipped in a 16Gb RAM system per 24 hours). See Schroeder, Pinheiro and Weber (2009) 'DRAM Errors in the Wild: A Large-Scale Field Study'. + +After construction during which lookup tables are built, no state is modified and therefore this class is safe for static storage (indeed if C++ 14 is available, the constructor is constexpr). The maximum number of bits in a code is a good four billion, I did try limiting it to 65536 for performance but it wasn't worth it, and one might want > 8Kb blocks maybe. As with all SECDED ECC, undefined behaviour occurs when more than two bits of error are present or the ECC supplied is incorrect. You should combine this SECDED with a robust hash which can tell you definitively if a buffer is error free or not rather than relying on this to correctly do so. + +The main intended use case for this routine is calculating the ECC on data being written to disc, and hence that is where performance has been maximised. It is not expected that this routine will be frequently called on data being read from disc i.e. only when its hash doesn't match its contents which should be very rare, and then a single bit heal using this routine is attempted before trying again with the hash. Care was taken that really enormous SECDEDs are fast, in fact tuning was mostly done for the 32784,32768 code which can heal one bad bit per 4Kb page as the main thing we have in mind is achieving reliable filing system code on computers without ECC RAM and in which sustained large quantities of random disc i/o produce a worrying number of flipped bits in a 24 hour period (anywhere between 0 and 3 on my hardware here, average is about 0.8). + +Performance of the fixed block size routine where you supply whole chunks of ['blocksize] is therefore [*particularly] excellent as I spent a lot of time tuning it for Ivy Bridge and later out of order architectures: an amazing 22 cycles per byte for the 32784,32768 code, which is a testament to modern out of order CPUs (remember SECDED inherently must work a bit at a time, so that's just 2.75 amortised CPU cycles per bit which includes a table load, a bit test, and a conditional XOR) i.e. it's pushing about 1.5 ops per clock cycle. On my 3.9Ghz i7-3770K here, I see about 170Mb/sec per CPU core. + +The variable length routine is necessarily much slower as it must work in single bytes, and achieves 72 cycles per byte, or 9 cycles per bit (64Mb/sec per CPU core). + +[heading Synopsis] +``template<size_t blocksize> +class utils::secded_ecc +{ + // ... +}; +`` + +[heading Template parameter(s)] +[table +[[Parameter] [Description]] +[[size_t blocksize] []] +] + +[heading Constructor(s)] +[table +[[Function] [Description] [Parameters] ] +[[``secded_ecc()`` + +] [Constructs an instance, configuring the necessary lookup tables. ] [ + +]] +] + +[heading Member Function(s)] +[table +[[Function] [Description] [Parameters] [Returns]] +[[``constexpr result_type result_bits_valid()`` + +] [The number of bits valid in result_type. ] [ + +][ + +] +] +[[``result_type operator()(result_type ecc, const char * buffer)`` + +] [Accumulate ECC from fixed size buffer. ] [[* result_type]: ['ecc]: + +[* const char *]: ['buffer]: + + + +][ + +] +] +[[``result_type operator()(const char * buffer)`` + +] [] [[* const char *]: ['buffer]: + + + +][ + +] +] +[[``result_type operator()(result_type ecc, const char * buffer, size_t length)`` + +] [Accumulate ECC from partial buffer where ['length] <= ['blocksize]. ] [[* result_type]: ['ecc]: + +[* const char *]: ['buffer]: + +[* size_t]: ['length]: + + + +][ + +] +] +[[``result_type operator()(const char * buffer, size_t length)`` + +] [] [[* const char *]: ['buffer]: + +[* size_t]: ['length]: + + + +][ + +] +] +[[``result_type find_bad_bit(result_type good_ecc, result_type bad_ecc)`` + +] [Given the original ECC and the new ECC for a buffer, find the bad bit. Return (result_type)-1 if not found (e.g. ECC corrupt) ] [[* result_type]: ['good_ecc]: + +[* result_type]: ['bad_ecc]: + + + +][ + +] +] +[[``verify_status verify(char * buffer, result_type good_ecc)`` + +] [Verifies and heals when possible a buffer, returning non zero if the buffer is error free. ] [[* char *]: ['buffer]: + +[* result_type]: ['good_ecc]: + + + +][ + +] +] +] + +[heading Header] +`#include <boost/afio/v2/afio.hpp>` + +[heading Complexity]O(N) where N is the blocksize +[heading Exception Model]Throws constexpr exceptions in constructor only, otherwise entirely noexcept. + +'''<?dbhtml-include href="disqus_comments.html"?>''' +[endsect] + diff --git a/attic/doc/generated/group_async_file_io_dispatcher.qbk b/attic/doc/generated/group_async_file_io_dispatcher.qbk new file mode 100644 index 00000000..6ec3a4ea --- /dev/null +++ b/attic/doc/generated/group_async_file_io_dispatcher.qbk @@ -0,0 +1,109 @@ +[/============================================================================ + Boost.AFIO + + Use, modification and distribution is subject to the Boost Software License, + Version 1.0. (See accompanying file LICENSE_1_0.txt or copy at + http://www.boost.org/LICENSE_1_0.txt) +=============================================================================/] + + +[/ Generated by doxygen_xml2qbk 1.1.1, don't change, will be overwritten automatically] +[/ Generated from doxy/doxygen_output/xml\group__async__file__io__dispatcher.xml] +[section:current_dispatcher current_dispatcher] +'''<?dbhtml-include href="disqus_identifiers/current_dispatcher.html"?>''' + +'''<indexterm><primary>current_dispatcher</primary></indexterm>''' +Retrieves the currently set async\u005ffile\u005fio\u005fdispatcher for this thread, optionally setting it to a new dispatcher. + +[heading Synopsis] +``BOOST_AFIO_DECL dispatcher_ptr current_dispatcher(option< dispatcher_ptr > new_dispatcher = empty)`` + +[heading Parameters] + +[table +[[Type] [Concept] [Name] [Description] ] +[[option< dispatcher_ptr >] [] [new_dispatcher] [The new async_file_io_dispatcher to set. ]] +] + + +[heading Returns] +The current async\u005ffile\u005fio\u005fdispatcher. + +[heading Header] +`#include <boost/afio/v2/afio.hpp>` + + +'''<?dbhtml-include href="disqus_comments.html"?>''' +[endsect] + +[section:make_dispatcher make_dispatcher] +'''<?dbhtml-include href="disqus_identifiers/make_dispatcher.html"?>''' + +'''<indexterm><primary>make_dispatcher</primary></indexterm>''' +Instatiates the best available async\u005ffile\u005fio\u005fdispatcher implementation for this system for the given uri. + +[heading Description] +Note that the number of threads in the threadpool supplied is the maximum non-async op queue depth (e.g. file opens, closes etc.). For fast SSDs, there isn't much gain after eight-sixteen threads, so the process threadpool is set to eight by default. For slow hard drives, or worse, SANs, a queue depth of 64 or higher might deliver significant benefits. + +URIs currently supported by AFIO: + +* [*[^__fileurl__]] The dispatcher will refer to the local filesystem of this machine. + + + +[heading Synopsis] +``BOOST_AFIO_DECL outcome<dispatcher_ptr> make_dispatcher(std::string uri = "file : / / /", file_flags flagsforce = file_flags::none, file_flags flagsmask = file_flags::none, + std::shared_ptr< thread_source > threadpool = process_threadpool())`` + +[heading Parameters] + +[table +[[Type] [Concept] [Name] [Description] ] +[[std::string] [] [uri] [Where to open the dispatcher upon. ]] +[[file_flags] [] [flagsforce] [The flags to bitwise OR with any opened file flags. Used to force on certain flags. ]] +[[file_flags] [] [flagsmask] [The flags to bitwise AND with any opened file flags. Used to force off certain flags. ]] +[[std::shared_ptr< thread_source >] [] [threadpool] [The threadpool instance to use for asynchronous dispatch.]] +] + + +[heading Returns] +A shared\u005fptr to the best available async\u005ffile\u005fio\u005fdispatcher implementation for this system for the given uri. + +[heading Header] +`#include <boost/afio/v2/afio.hpp>` + +[heading Example] +[call_example] + + +'''<?dbhtml-include href="disqus_comments.html"?>''' +[endsect] + +[section:depends depends] +'''<?dbhtml-include href="disqus_identifiers/depends.html"?>''' + +'''<indexterm><primary>depends</primary></indexterm>''' +Make ready a future after a precondition future readies. + +[heading Synopsis] +``future depends(future<> precondition, future<> out)`` + +[heading Parameters] + +[table +[[Type] [Concept] [Name] [Description] ] +[[future<>] [] [precondition] [The future which must signal before the returned future signals. ]] +[[future<>] [] [out] [The future to return. ]] +] + + +[heading Returns] +A future which returns out after precondition signals. + +[heading Header] +`#include <boost/afio/v2/afio.hpp>` + + +'''<?dbhtml-include href="disqus_comments.html"?>''' +[endsect] + diff --git a/attic/doc/generated/group_async_io_handle__ops.qbk b/attic/doc/generated/group_async_io_handle__ops.qbk new file mode 100644 index 00000000..d8af2227 --- /dev/null +++ b/attic/doc/generated/group_async_io_handle__ops.qbk @@ -0,0 +1,237 @@ +[/============================================================================ + Boost.AFIO + + Use, modification and distribution is subject to the Boost Software License, + Version 1.0. (See accompanying file LICENSE_1_0.txt or copy at + http://www.boost.org/LICENSE_1_0.txt) +=============================================================================/] + + +[/ Generated by doxygen_xml2qbk 1.1.1, don't change, will be overwritten automatically] +[/ Generated from doxy/doxygen_output/xml\group__async__io__handle____ops.xml] +[section:path path] +'''<?dbhtml-include href="disqus_identifiers/path.html"?>''' + +'''<indexterm><primary>path</primary></indexterm>''' +Returns the path of this i/o handle right now if the handle is open and ['refresh] is true, else last known good. May be null if the file has been deleted. + +[heading Description] +Note the refreshed path completely dereferences any intermediate symbolic links to return a truly absolute canonical path, and therefore may look quite different to before. Some operating systems unfortunately also return any one of the hard links to the file, so if hard links is greater than one the path refreshed will randomly permute. + +Be aware that on Windows AFIO operates exclusively in the NT kernel namespace, NOT the Win32 namespace, and therefore paths you supply are converted by [^`afio::path`] in NT kernel namespace paths. [^`normalise_path()`] can convert an afio path back to a Filesystem TS path for you, but note that this may not be the path that was supplied originally. NT kernel namespace paths have a 32,767 character limit and an almost POSIX like lack of restrictions on naming or historical behaviour quirks, but as a result AFIO does not support DOS short names or any of the other historical Win32 filing system baggage. + +[heading Synopsis] +``virtual path handle::path(bool refresh = false)`` + +[heading Parameters] + +[table +[[Type] [Concept] [Name] [Description] ] +[[bool] [] [refresh] [Whether to ask the OS for the current path of this handle.]] +] + + +[heading Returns] +The path of this i/o handle right now. + +[heading Header] +`#include <boost/afio/v2/afio.hpp>` + +[heading Race Guarantees][raceguarantees +[raceguarantee FreeBSD..Paths are only refreshed for directories, not files.] +[raceguarantee Linux, Windows..Paths are always refreshed and ignore other hard links.] +[raceguarantee OS X..Paths are only refreshed for directories and files with a single hard link.] + ] + + +'''<?dbhtml-include href="disqus_comments.html"?>''' +[endsect] + +[section:direntry direntry] +'''<?dbhtml-include href="disqus_identifiers/direntry.html"?>''' + +'''<indexterm><primary>direntry</primary></indexterm>''' +Returns a mostly filled directory\u005fentry for the file or directory referenced by this handle. Use [^`metadata_flags::All`] if you want it as complete as your platform allows, even at the cost of severe performance loss. + +[heading Description] +Related types: [^`__afio_directory_entry__`], [^`__afio_stat_t__`] + +[heading Synopsis] +``virtual directory_entry handle::direntry(metadata_flags wanted = directory_entry::metadata_fastpath())`` + +[heading Parameters] + +[table +[[Type] [Concept] [Name] [Description] ] +[[metadata_flags] [] [wanted] [The metadata wanted.]] +] + + +[heading Returns] +A directory entry for this handle. + +[heading Header] +`#include <boost/afio/v2/afio.hpp>` + +[heading Race Guarantees][raceguarantees +[raceguarantee FreeBSD..Race free if handle open for directories and regular files only, else if handle closed or a symlink race free up to the containing directory. All metadata is fetched in a single shot.] +[raceguarantee Linux..Race free if handle open, else if handle closed race free up to the containing directory. All metadata is fetched in a single shot.] +[raceguarantee OS X..Race free if handle open for directories and regular files only. No guarantees if handle closed or a symlink.] +[raceguarantee Windows..Handle must be open and is always race free. Metadata may be fetched in a single shot if at least two categories requested, or else the following categories apply: (i) ino (ii) type, atim, mtim, ctim, birthtim, sparse, compressed (iii) nlink, size, allocated, blocks.] + ] + + +'''<?dbhtml-include href="disqus_comments.html"?>''' +[endsect] + +[section:target target] +'''<?dbhtml-include href="disqus_identifiers/target.html"?>''' + +'''<indexterm><primary>target</primary></indexterm>''' +Returns the target path of this handle if it is a symbolic link. + +[heading Description] +Be aware that on Windows AFIO operates exclusively in the NT kernel namespace, NOT the Win32 namespace, and therefore paths you supply are converted by [^`afio::path`] in NT kernel namespace paths. [^`normalise_path()`] can convert an afio path back to a Filesystem TS path for you, but note that this may not be the path that was supplied originally. NT kernel namespace paths have a 32,767 character limit and an almost POSIX like lack of restrictions on naming or historical behaviour quirks, but as a result AFIO does not support DOS short names or any of the other historical Win32 filing system baggage. + +[heading Synopsis] +``virtual path handle::target()`` + +[heading Parameters] + +[table +[[Type] [Concept] [Name] [Description] ] +] + + +[heading Returns] +The path the symbolic link points to. May not exist or even be valid. + +[heading Header] +`#include <boost/afio/v2/afio.hpp>` + +[heading Race Guarantees][raceguarantees +[raceguarantee FreeBSD..Race free up to the containing directory.] +[raceguarantee Linux, Windows..Race free if handle open, else up to the containing directory.] +[raceguarantee OS X..No guarantees.] + ] + + +'''<?dbhtml-include href="disqus_comments.html"?>''' +[endsect] + +[section:link link] +'''<?dbhtml-include href="disqus_identifiers/link.html"?>''' + +'''<indexterm><primary>link</primary></indexterm>''' +Hard links the file to a new location on the same volume. + +[heading Description] +If you wish to make a temporary file whose contents are ready appear at a location and error out if a file entry is already there, use link() and if success, unlink() on the former location. If you wish to always overwrite the destination, use atomic\u005frelink() instead. + +On Windows, the destination directory cannot have any handle opened to it with delete/rename privileges ([^`file_flags::write`]) anywhere in the system. This is an operating system limitation. + +Be aware that on Windows AFIO operates exclusively in the NT kernel namespace, NOT the Win32 namespace, and therefore paths you supply are converted by [^`afio::path`] in NT kernel namespace paths. [^`normalise_path()`] can convert an afio path back to a Filesystem TS path for you, but note that this may not be the path that was supplied originally. NT kernel namespace paths have a 32,767 character limit and an almost POSIX like lack of restrictions on naming or historical behaviour quirks, but as a result AFIO does not support DOS short names or any of the other historical Win32 filing system baggage. + +Related types: [^`__afio_path_req__`] + +[heading Synopsis] +``virtual void handle::link(const path_req & req)`` + +[heading Parameters] + +[table +[[Type] [Concept] [Name] [Description] ] +[[const path_req &] [] [req] [The absolute or relative (in which case precondition specifies a directory) path to create a hard link at.]] +] + + +[heading Header] +`#include <boost/afio/v2/afio.hpp>` + +[heading Race Guarantees][raceguarantees +[raceguarantee FreeBSD..Race free up to the containing directory for both source and target.] +[raceguarantee Linux, Windows..Race free for source if handle open, else up to the containing directory. Race free up to the target directory.] +[raceguarantee OS X..No guarantees.] + ] + + +'''<?dbhtml-include href="disqus_comments.html"?>''' +[endsect] + +[section:unlink unlink] +'''<?dbhtml-include href="disqus_identifiers/unlink.html"?>''' + +'''<indexterm><primary>unlink</primary></indexterm>''' +Unlinks the file from its present location as determined by path(true), which could be any hard link on those operating systems with an unstable path(true). Other links may remain to the same file. + +[heading Description] +On Microsoft Windows, this routine unlinks items as follows: + +The reason for such complexity is that this algorithm, if it renames successfully, neatly works around a number of annoying features in Windows, specifically that when you delete a file you actually don't delete it till an unknown amount of time later. This breaks code which tries to delete a directory tree, and finds that the directories won't delete because they still contain files supposedly deleted but actually not quite yet. By renaming the items as far away as possible, this problem ought to go away - unless of course that the user does not have permissions to write into any directory other than the one being eventually deleted, in which case you will still see the strange access denied and directory not empty errors from before. + +Be aware that on Windows AFIO operates exclusively in the NT kernel namespace, NOT the Win32 namespace, and therefore paths you supply are converted by [^`afio::path`] in NT kernel namespace paths. [^`normalise_path()`] can convert an afio path back to a Filesystem TS path for you, but note that this may not be the path that was supplied originally. NT kernel namespace paths have a 32,767 character limit and an almost POSIX like lack of restrictions on naming or historical behaviour quirks, but as a result AFIO does not support DOS short names or any of the other historical Win32 filing system baggage. + +Related types: [^`__afio_path_req__`] + +[heading Synopsis] +``virtual void handle::unlink()`` + +[heading Parameters] + +[table +[[Type] [Concept] [Name] [Description] ] +] + + +[heading Header] +`#include <boost/afio/v2/afio.hpp>` + +[heading Race Guarantees][raceguarantees +[raceguarantee FreeBSD, Linux..Race free up to the containing directory.] +[raceguarantee Windows..Race free if handle open, else up to the containing directory.] +[raceguarantee OS X..No guarantees.] + ] + + +'''<?dbhtml-include href="disqus_comments.html"?>''' +[endsect] + +[section:atomic_relink atomic_relink] +'''<?dbhtml-include href="disqus_identifiers/atomic_relink.html"?>''' + +'''<indexterm><primary>atomic_relink</primary></indexterm>''' +Links the file to a new location and unlinks the file from its present location as determined by path(true), ['atomically overwriting any file entry at the new location]. Very useful for preparing file content elsewhere and once ready, atomically making it visible at some named location to other processes. Note that operating systems with an unstable path(true) may relink any hard link to the file to the new location. + +[heading Description] +Note that not all filing systems guarantee the atomicity of the relink itself (i.e. the file may appear at two locations in the filing system for a period of time), though all supported platforms do guarantee the atomicity of the replaced location i.e. the location you are relinking to will always refer to some valid file to all readers, and will never be deleted or missing. Some filing systems may also fail to do the unlink if power is lost close to the relinking operation. + +On Windows, the destination directory cannot have any handle opened to it with delete/rename privileges ([^`file_flags::write`]) anywhere in the system. This is an operating system limitation. + +Be aware that on Windows AFIO operates exclusively in the NT kernel namespace, NOT the Win32 namespace, and therefore paths you supply are converted by [^`afio::path`] in NT kernel namespace paths. [^`normalise_path()`] can convert an afio path back to a Filesystem TS path for you, but note that this may not be the path that was supplied originally. NT kernel namespace paths have a 32,767 character limit and an almost POSIX like lack of restrictions on naming or historical behaviour quirks, but as a result AFIO does not support DOS short names or any of the other historical Win32 filing system baggage. + +Related types: [^`__afio_path_req__`] + +[heading Synopsis] +``virtual void handle::atomic_relink(const path_req & req)`` + +[heading Parameters] + +[table +[[Type] [Concept] [Name] [Description] ] +[[const path_req &] [] [req] [The absolute or relative (in which case precondition specifies a directory) path to relink to.]] +] + + +[heading Header] +`#include <boost/afio/v2/afio.hpp>` + +[heading Race Guarantees][raceguarantees +[raceguarantee FreeBSD, Linux..Race free up to the containing directory for both source and target.] +[raceguarantee OS X..No guarantees.] +[raceguarantee Windows..Race free for source if handle open, else up to the containing directory. Race free up to the target directory.] + ] + + +'''<?dbhtml-include href="disqus_comments.html"?>''' +[endsect] + diff --git a/attic/doc/generated/group_async_op_flags.qbk b/attic/doc/generated/group_async_op_flags.qbk new file mode 100644 index 00000000..57d6b52c --- /dev/null +++ b/attic/doc/generated/group_async_op_flags.qbk @@ -0,0 +1,38 @@ +[/============================================================================ + Boost.AFIO + + Use, modification and distribution is subject to the Boost Software License, + Version 1.0. (See accompanying file LICENSE_1_0.txt or copy at + http://www.boost.org/LICENSE_1_0.txt) +=============================================================================/] + + +[/ Generated by doxygen_xml2qbk 1.1.1, don't change, will be overwritten automatically] +[/ Generated from doxy/doxygen_output/xml\group__async__op__flags.xml] +[section:async_op_flags async_op_flags] +'''<?dbhtml-include href="disqus_identifiers/async_op_flags.html"?>''' + +'''<indexterm><primary>async_op_flags</primary></indexterm>''' +'''<indexterm><primary>none</primary></indexterm>''' +'''<indexterm><primary>immediate</primary></indexterm>''' +Bitwise async_op_flags flags. + +[heading Synopsis] +``enum async_op_flags {none = 0, immediate = 1};`` + +[heading Values] + +[table +[[Value] [Description] ] +[[none] [No flags set. ]] +[[immediate] [Call chained completion immediately instead of scheduling for later. Make SURE your completion can not block! ]] +] + + +[heading Header] +`#include <boost/afio/v2/afio.hpp>` + + +'''<?dbhtml-include href="disqus_comments.html"?>''' +[endsect] + diff --git a/attic/doc/generated/group_close.qbk b/attic/doc/generated/group_close.qbk new file mode 100644 index 00000000..32edb99d --- /dev/null +++ b/attic/doc/generated/group_close.qbk @@ -0,0 +1,142 @@ +[/============================================================================ + Boost.AFIO + + Use, modification and distribution is subject to the Boost Software License, + Version 1.0. (See accompanying file LICENSE_1_0.txt or copy at + http://www.boost.org/LICENSE_1_0.txt) +=============================================================================/] + + +[/ Generated by doxygen_xml2qbk 1.1.1, don't change, will be overwritten automatically] +[/ Generated from doxy/doxygen_output/xml\group__close.xml] +[section:close_1_batch close (batch)] +'''<?dbhtml-include href="disqus_identifiers/close_1_batch.html"?>''' + +'''<indexterm><primary>close</primary></indexterm>''' +Schedule a batch of asynchronous file or directory handle closes after preceding operations. + +[heading Description] +Note this is ignored for handles where available\u005fto\u005fdirectory\u005fcache() is true as those cannot be explicitly closed. Note that failure to explicitly schedule closing a file handle using this call means it will be [*synchronously] closed on last reference count by [^`__afio_handle__`]. This can consume considerable time, especially if SyncOnClose is enabled. + +[heading Synopsis] +``future dispatcher::close(const std::vector< future<>> & ops)`` + +[heading Parameters] + +[table +[[Type] [Concept] [Name] [Description] ] +[[const std::vector< future<>> &] [] [ops] [A batch of op handles.]] +] + + +[heading Returns] +A batch of op handles. + +[heading Header] +`#include <boost/afio/v2/afio.hpp>` + +[heading Complexity]Amortised O(N) to dispatch. Amortised O(N/threadpool) to complete if closing handles is constant time. +[heading Exception Model]Propagates exceptions of any input preconditions with an errored state at the point of dispatch, and throws a `std::invalid_argument` if any inputs have values which could not possibly be correct. Once a batch of input ops has been verified at the point of entry as not errored, you are guaranteed that the batch is atomically scheduled as a whole, unless a failure to allocate memory occurs. +[heading Example][filedir_example] + + +'''<?dbhtml-include href="disqus_comments.html"?>''' +[endsect] + +[section:async_close async_close] +'''<?dbhtml-include href="disqus_identifiers/async_close.html"?>''' + +'''<indexterm><primary>async_close</primary></indexterm>''' +Asynchronous file or directory handle close after a preceding operation. + +[heading Description] +Note this is ignored for handles where available\u005fto\u005fdirectory\u005fcache() is true as those cannot be explicitly closed. Note that failure to explicitly schedule closing a file handle using this call means it will be [*synchronously] closed on last reference count by [^`__afio_handle__`]. This can consume considerable time, especially if SyncOnClose is enabled. + +[heading Synopsis] +``future async_close(future<> _precondition)`` + +[heading Parameters] + +[table +[[Type] [Concept] [Name] [Description] ] +[[future<>] [] [_precondition] [The precondition to use.]] +] + + +[heading Returns] +A future<void> + +[heading Header] +`#include <boost/afio/v2/afio.hpp>` + +[heading Complexity]Amortised O(1) to dispatch. Amortised O(1) to complete if closing handles is constant time. +[heading Exception Model]Propagates the exception of any input precondition with an errored state at the point of dispatch, and throws a `std::invalid_argument` if any inputs have values which could not possibly be correct. Note that error code returning functions may still throw exceptions e.g. failure to allocate memory. +[heading Example][filedir_example] + + +'''<?dbhtml-include href="disqus_comments.html"?>''' +[endsect] + +[section:close_1_throwing close (throwing)] +'''<?dbhtml-include href="disqus_identifiers/close_1_throwing.html"?>''' + +'''<indexterm><primary>close</primary></indexterm>''' +Synchronous file or directory handle close after a preceding operation. + +[heading Description] +Note this is ignored for handles where available\u005fto\u005fdirectory\u005fcache() is true as those cannot be explicitly closed. Note that failure to explicitly schedule closing a file handle using this call means it will be [*synchronously] closed on last reference count by [^`__afio_handle__`]. This can consume considerable time, especially if SyncOnClose is enabled. + +[heading Synopsis] +``void close(future<> _precondition)`` + +[heading Parameters] + +[table +[[Type] [Concept] [Name] [Description] ] +[[future<>] [] [_precondition] [The precondition to use.]] +] + + +[heading Header] +`#include <boost/afio/v2/afio.hpp>` + +[heading Complexity]Amortised O(1) to dispatch. Amortised O(1) to complete if closing handles is constant time. +[heading Exception Model]Propagates the exception of any input precondition with an errored state at the point of dispatch, and throws a `std::invalid_argument` if any inputs have values which could not possibly be correct. Note that error code returning functions may still throw exceptions e.g. failure to allocate memory. +[heading Example][filedir_example] + + +'''<?dbhtml-include href="disqus_comments.html"?>''' +[endsect] + +[section:close_2_non_throwing close (non throwing)] +'''<?dbhtml-include href="disqus_identifiers/close_2_non_throwing.html"?>''' + +'''<indexterm><primary>close</primary></indexterm>''' +Synchronous file or directory handle close after a preceding operation. + +[heading Description] +Note this is ignored for handles where available\u005fto\u005fdirectory\u005fcache() is true as those cannot be explicitly closed. Note that failure to explicitly schedule closing a file handle using this call means it will be [*synchronously] closed on last reference count by [^`__afio_handle__`]. This can consume considerable time, especially if SyncOnClose is enabled. + +[heading Synopsis] +``void close(error_code & _ec, future<> _precondition)`` + +[heading Parameters] + +[table +[[Type] [Concept] [Name] [Description] ] +[[error_code &] [] [_ec] [Error code to set. ]] +[[future<>] [] [_precondition] [The precondition to use.]] +] + + +[heading Header] +`#include <boost/afio/v2/afio.hpp>` + +[heading Complexity]Amortised O(1) to dispatch. Amortised O(1) to complete if closing handles is constant time. +[heading Exception Model]Propagates the exception of any input precondition with an errored state at the point of dispatch, and throws a `std::invalid_argument` if any inputs have values which could not possibly be correct. Note that error code returning functions may still throw exceptions e.g. failure to allocate memory. +[heading Example][filedir_example] + + +'''<?dbhtml-include href="disqus_comments.html"?>''' +[endsect] + diff --git a/attic/doc/generated/group_dir.qbk b/attic/doc/generated/group_dir.qbk new file mode 100644 index 00000000..73aaa7f7 --- /dev/null +++ b/attic/doc/generated/group_dir.qbk @@ -0,0 +1,298 @@ +[/============================================================================ + Boost.AFIO + + Use, modification and distribution is subject to the Boost Software License, + Version 1.0. (See accompanying file LICENSE_1_0.txt or copy at + http://www.boost.org/LICENSE_1_0.txt) +=============================================================================/] + + +[/ Generated by doxygen_xml2qbk 1.1.1, don't change, will be overwritten automatically] +[/ Generated from doxy/doxygen_output/xml\group__dir.xml] +[section:dir_1_batch dir (batch)] +'''<?dbhtml-include href="disqus_identifiers/dir_1_batch.html"?>''' + +'''<indexterm><primary>dir</primary></indexterm>''' +Schedule a batch of asynchronous directory creations and opens after optional preconditions. + +[heading Description] +Note that if there is already a handle open to the directory requested, that will be returned instead of a new handle unless file\u005fflags::unique\u005fdirectory\u005fhandle is specified. For such handles where available\u005fto\u005fdirectory\u005fcache() is true, they cannot be explicitly closed either, you must let the reference count reach zero for that to happen. Related types: [^`__afio_path_req__`] Be aware that on Windows AFIO operates exclusively in the NT kernel namespace, NOT the Win32 namespace, and therefore paths you supply are converted by [^`afio::path`] in NT kernel namespace paths. [^`normalise_path()`] can convert an afio path back to a Filesystem TS path for you, but note that this may not be the path that was supplied originally. NT kernel namespace paths have a 32,767 character limit and an almost POSIX like lack of restrictions on naming or historical behaviour quirks, but as a result AFIO does not support DOS short names or any of the other historical Win32 filing system baggage. + +[heading Synopsis] +``future dispatcher::dir(const std::vector< path_req > & reqs)`` + +[heading Parameters] + +[table +[[Type] [Concept] [Name] [Description] ] +[[const std::vector< path_req > &] [] [reqs] [A batch of [^`path_req`] structures.]] +] + + +[heading Returns] +A batch of op handles. + +[heading Header] +`#include <boost/afio/v2/afio.hpp>` + +[heading Race Guarantees][raceguarantees +[raceguarantee FreeBSD, Linux, Windows..Race free up to the containing directory.] +[raceguarantee OS X..No guarantees.] + ] +[heading Complexity]Amortised O(N) to dispatch. Amortised O(N/threadpool) to complete if directory creation is constant time. +[heading Exception Model]Propagates exceptions of any input preconditions with an errored state at the point of dispatch, and throws a `std::invalid_argument` if any inputs have values which could not possibly be correct. Once a batch of input ops has been verified at the point of entry as not errored, you are guaranteed that the batch is atomically scheduled as a whole, unless a failure to allocate memory occurs. +[heading Example][filedir_example] + + +'''<?dbhtml-include href="disqus_comments.html"?>''' +[endsect] + +[section:async_dir_3_relative async_dir (relative)] +'''<?dbhtml-include href="disqus_identifiers/async_dir_3_relative.html"?>''' + +'''<indexterm><primary>async_dir</primary></indexterm>''' +Asynchronous directory creation and open after an optional precondition. + +[heading Description] +Note that if there is already a handle open to the directory requested, that will be returned instead of a new handle unless file\u005fflags::unique\u005fdirectory\u005fhandle is specified. For such handles where available\u005fto\u005fdirectory\u005fcache() is true, they cannot be explicitly closed either, you must let the reference count reach zero for that to happen. Related types: [^`__afio_path_req__`] Be aware that on Windows AFIO operates exclusively in the NT kernel namespace, NOT the Win32 namespace, and therefore paths you supply are converted by [^`afio::path`] in NT kernel namespace paths. [^`normalise_path()`] can convert an afio path back to a Filesystem TS path for you, but note that this may not be the path that was supplied originally. NT kernel namespace paths have a 32,767 character limit and an almost POSIX like lack of restrictions on naming or historical behaviour quirks, but as a result AFIO does not support DOS short names or any of the other historical Win32 filing system baggage. + +[heading Synopsis] +``template<class T> +future async_dir(future<> _precondition, T _path, file_flags _flags = file_flags::none)`` + +[heading Parameters] + +[table +[[Type] [Concept] [Name] [Description] ] +[[class T] [The type of path to be used. ] [ - ] [Must be specified]] +[[future<>] [] [_precondition] [The precondition to use. ]] +[[T] [] [_path] [The filing system path to be used. ]] +[[file_flags] [] [_flags] [The flags to be used.]] +] + + +[heading Returns] +A future<void> + +[heading Header] +`#include <boost/afio/v2/afio.hpp>` + +[heading Race Guarantees][raceguarantees +[raceguarantee FreeBSD, Linux, OS X, Windows..Race free up to the containing directory.] + ] +[heading Complexity]Amortised O(1) to dispatch. Amortised O(1) to complete if directory creation is constant time. +[heading Exception Model]Propagates the exception of any input precondition with an errored state at the point of dispatch, and throws a `std::invalid_argument` if any inputs have values which could not possibly be correct. Note that error code returning functions may still throw exceptions e.g. failure to allocate memory. +[heading Example][filedir_example] + + +'''<?dbhtml-include href="disqus_comments.html"?>''' +[endsect] + +[section:async_dir_2_absolute async_dir (absolute)] +'''<?dbhtml-include href="disqus_identifiers/async_dir_2_absolute.html"?>''' + +'''<indexterm><primary>async_dir</primary></indexterm>''' +Asynchronous directory creation and open after an optional precondition. + +[heading Description] +Note that if there is already a handle open to the directory requested, that will be returned instead of a new handle unless file\u005fflags::unique\u005fdirectory\u005fhandle is specified. For such handles where available\u005fto\u005fdirectory\u005fcache() is true, they cannot be explicitly closed either, you must let the reference count reach zero for that to happen. Related types: [^`__afio_path_req__`] Be aware that on Windows AFIO operates exclusively in the NT kernel namespace, NOT the Win32 namespace, and therefore paths you supply are converted by [^`afio::path`] in NT kernel namespace paths. [^`normalise_path()`] can convert an afio path back to a Filesystem TS path for you, but note that this may not be the path that was supplied originally. NT kernel namespace paths have a 32,767 character limit and an almost POSIX like lack of restrictions on naming or historical behaviour quirks, but as a result AFIO does not support DOS short names or any of the other historical Win32 filing system baggage. + +[heading Synopsis] +``template<class T, typename> +future async_dir(T _path, file_flags _flags = file_flags::none)`` + +[heading Parameters] + +[table +[[Type] [Concept] [Name] [Description] ] +[[class T] [The type of path to be used. ] [ - ] [Must be specified]] +[[] [] [ - ] [Must be specified]] +[[T] [] [_path] [The filing system path to be used. ]] +[[file_flags] [] [_flags] [The flags to be used.]] +] + + +[heading Returns] +A future<void> + +[heading Header] +`#include <boost/afio/v2/afio.hpp>` + +[heading Race Guarantees][raceguarantees +[raceguarantee FreeBSD, Linux, OS X, Windows..No guarantees.] + ] +[heading Complexity]Amortised O(1) to dispatch. Amortised O(1) to complete if directory creation is constant time. +[heading Exception Model]Propagates the exception of any input precondition with an errored state at the point of dispatch, and throws a `std::invalid_argument` if any inputs have values which could not possibly be correct. Note that error code returning functions may still throw exceptions e.g. failure to allocate memory. +[heading Example][filedir_example] + + +'''<?dbhtml-include href="disqus_comments.html"?>''' +[endsect] + +[section:dir_3_relative_throwing dir (relative throwing)] +'''<?dbhtml-include href="disqus_identifiers/dir_3_relative_throwing.html"?>''' + +'''<indexterm><primary>dir</primary></indexterm>''' +Synchronous directory creation and open after an optional precondition. + +[heading Description] +Note that if there is already a handle open to the directory requested, that will be returned instead of a new handle unless file\u005fflags::unique\u005fdirectory\u005fhandle is specified. For such handles where available\u005fto\u005fdirectory\u005fcache() is true, they cannot be explicitly closed either, you must let the reference count reach zero for that to happen. Related types: [^`__afio_path_req__`] Be aware that on Windows AFIO operates exclusively in the NT kernel namespace, NOT the Win32 namespace, and therefore paths you supply are converted by [^`afio::path`] in NT kernel namespace paths. [^`normalise_path()`] can convert an afio path back to a Filesystem TS path for you, but note that this may not be the path that was supplied originally. NT kernel namespace paths have a 32,767 character limit and an almost POSIX like lack of restrictions on naming or historical behaviour quirks, but as a result AFIO does not support DOS short names or any of the other historical Win32 filing system baggage. + +[heading Synopsis] +``template<class T> +handle_ptr dir(future<> _precondition, T _path, file_flags _flags = file_flags::none)`` + +[heading Parameters] + +[table +[[Type] [Concept] [Name] [Description] ] +[[class T] [The type of path to use. ] [ - ] [Must be specified]] +[[future<>] [] [_precondition] [The precondition to use. ]] +[[T] [] [_path] [The filing system path to use. ]] +[[file_flags] [] [_flags] [The flags to use.]] +] + + +[heading Returns] +A handle to the directory. + +[heading Header] +`#include <boost/afio/v2/afio.hpp>` + +[heading Race Guarantees][raceguarantees +[raceguarantee FreeBSD, Linux, OS X, Windows..Race free up to the containing directory.] + ] +[heading Complexity]Amortised O(1) to dispatch. Amortised O(1) to complete if directory creation is constant time. +[heading Exception Model]Propagates the exception of any input precondition with an errored state at the point of dispatch, and throws a `std::invalid_argument` if any inputs have values which could not possibly be correct. Note that error code returning functions may still throw exceptions e.g. failure to allocate memory. +[heading Example][filedir_example] + + +'''<?dbhtml-include href="disqus_comments.html"?>''' +[endsect] + +[section:dir_2_absolute_throwing dir (absolute throwing)] +'''<?dbhtml-include href="disqus_identifiers/dir_2_absolute_throwing.html"?>''' + +'''<indexterm><primary>dir</primary></indexterm>''' +Synchronous directory creation and open after an optional precondition. + +[heading Description] +Note that if there is already a handle open to the directory requested, that will be returned instead of a new handle unless file\u005fflags::unique\u005fdirectory\u005fhandle is specified. For such handles where available\u005fto\u005fdirectory\u005fcache() is true, they cannot be explicitly closed either, you must let the reference count reach zero for that to happen. Related types: [^`__afio_path_req__`] Be aware that on Windows AFIO operates exclusively in the NT kernel namespace, NOT the Win32 namespace, and therefore paths you supply are converted by [^`afio::path`] in NT kernel namespace paths. [^`normalise_path()`] can convert an afio path back to a Filesystem TS path for you, but note that this may not be the path that was supplied originally. NT kernel namespace paths have a 32,767 character limit and an almost POSIX like lack of restrictions on naming or historical behaviour quirks, but as a result AFIO does not support DOS short names or any of the other historical Win32 filing system baggage. + +[heading Synopsis] +``template<class T, typename> +handle_ptr dir(T _path, file_flags _flags = file_flags::none)`` + +[heading Parameters] + +[table +[[Type] [Concept] [Name] [Description] ] +[[class T] [The type of path to use. ] [ - ] [Must be specified]] +[[] [] [ - ] [Must be specified]] +[[T] [] [_path] [The filing system path to use. ]] +[[file_flags] [] [_flags] [The flags to use.]] +] + + +[heading Returns] +A handle to the directory. + +[heading Header] +`#include <boost/afio/v2/afio.hpp>` + +[heading Race Guarantees][raceguarantees +[raceguarantee FreeBSD, Linux, OS X, Windows..No guarantees.] + ] +[heading Complexity]Amortised O(1) to dispatch. Amortised O(1) to complete if directory creation is constant time. +[heading Exception Model]Propagates the exception of any input precondition with an errored state at the point of dispatch, and throws a `std::invalid_argument` if any inputs have values which could not possibly be correct. Note that error code returning functions may still throw exceptions e.g. failure to allocate memory. +[heading Example][filedir_example] + + +'''<?dbhtml-include href="disqus_comments.html"?>''' +[endsect] + +[section:dir_4_relative_non_throwing dir (relative non throwing)] +'''<?dbhtml-include href="disqus_identifiers/dir_4_relative_non_throwing.html"?>''' + +'''<indexterm><primary>dir</primary></indexterm>''' +Synchronous directory creation and open after an optional precondition. + +[heading Description] +Note that if there is already a handle open to the directory requested, that will be returned instead of a new handle unless file\u005fflags::unique\u005fdirectory\u005fhandle is specified. For such handles where available\u005fto\u005fdirectory\u005fcache() is true, they cannot be explicitly closed either, you must let the reference count reach zero for that to happen. Related types: [^`__afio_path_req__`] Be aware that on Windows AFIO operates exclusively in the NT kernel namespace, NOT the Win32 namespace, and therefore paths you supply are converted by [^`afio::path`] in NT kernel namespace paths. [^`normalise_path()`] can convert an afio path back to a Filesystem TS path for you, but note that this may not be the path that was supplied originally. NT kernel namespace paths have a 32,767 character limit and an almost POSIX like lack of restrictions on naming or historical behaviour quirks, but as a result AFIO does not support DOS short names or any of the other historical Win32 filing system baggage. + +[heading Synopsis] +``template<class T> +handle_ptr dir(error_code & _ec, future<> _precondition, T _path, + file_flags _flags = file_flags::none)`` + +[heading Parameters] + +[table +[[Type] [Concept] [Name] [Description] ] +[[class T] [The type of path to use. ] [ - ] [Must be specified]] +[[error_code &] [] [_ec] [Error code to set. ]] +[[future<>] [] [_precondition] [The precondition to use. ]] +[[T] [] [_path] [The filing system path to use. ]] +[[file_flags] [] [_flags] [The flags to use.]] +] + + +[heading Returns] +A handle to the directory. + +[heading Header] +`#include <boost/afio/v2/afio.hpp>` + +[heading Race Guarantees][raceguarantees +[raceguarantee FreeBSD, Linux, OS X, Windows..Race free up to the containing directory.] + ] +[heading Complexity]Amortised O(1) to dispatch. Amortised O(1) to complete if directory creation is constant time. +[heading Exception Model]Propagates the exception of any input precondition with an errored state at the point of dispatch, and throws a `std::invalid_argument` if any inputs have values which could not possibly be correct. Note that error code returning functions may still throw exceptions e.g. failure to allocate memory. +[heading Example][filedir_example] + + +'''<?dbhtml-include href="disqus_comments.html"?>''' +[endsect] + +[section:dir_3_absolute_non_throwing dir (absolute non throwing)] +'''<?dbhtml-include href="disqus_identifiers/dir_3_absolute_non_throwing.html"?>''' + +'''<indexterm><primary>dir</primary></indexterm>''' +Synchronous directory creation and open after an optional precondition. + +[heading Description] +Note that if there is already a handle open to the directory requested, that will be returned instead of a new handle unless file\u005fflags::unique\u005fdirectory\u005fhandle is specified. For such handles where available\u005fto\u005fdirectory\u005fcache() is true, they cannot be explicitly closed either, you must let the reference count reach zero for that to happen. Related types: [^`__afio_path_req__`] Be aware that on Windows AFIO operates exclusively in the NT kernel namespace, NOT the Win32 namespace, and therefore paths you supply are converted by [^`afio::path`] in NT kernel namespace paths. [^`normalise_path()`] can convert an afio path back to a Filesystem TS path for you, but note that this may not be the path that was supplied originally. NT kernel namespace paths have a 32,767 character limit and an almost POSIX like lack of restrictions on naming or historical behaviour quirks, but as a result AFIO does not support DOS short names or any of the other historical Win32 filing system baggage. + +[heading Synopsis] +``template<class T, typename> +handle_ptr dir(error_code & _ec, T _path, file_flags _flags = file_flags::none)`` + +[heading Parameters] + +[table +[[Type] [Concept] [Name] [Description] ] +[[class T] [The type of path to use. ] [ - ] [Must be specified]] +[[] [] [ - ] [Must be specified]] +[[error_code &] [] [_ec] [Error code to set. ]] +[[T] [] [_path] [The filing system path to use. ]] +[[file_flags] [] [_flags] [The flags to use.]] +] + + +[heading Returns] +A handle to the directory. + +[heading Header] +`#include <boost/afio/v2/afio.hpp>` + +[heading Race Guarantees][raceguarantees +[raceguarantee FreeBSD, Linux, OS X, Windows..No guarantees.] + ] +[heading Complexity]Amortised O(1) to dispatch. Amortised O(1) to complete if directory creation is constant time. +[heading Exception Model]Propagates the exception of any input precondition with an errored state at the point of dispatch, and throws a `std::invalid_argument` if any inputs have values which could not possibly be correct. Note that error code returning functions may still throw exceptions e.g. failure to allocate memory. +[heading Example][filedir_example] + + +'''<?dbhtml-include href="disqus_comments.html"?>''' +[endsect] + diff --git a/attic/doc/generated/group_dispatcher__barrier.qbk b/attic/doc/generated/group_dispatcher__barrier.qbk new file mode 100644 index 00000000..6e5ee3f2 --- /dev/null +++ b/attic/doc/generated/group_dispatcher__barrier.qbk @@ -0,0 +1,11 @@ +[/============================================================================ + Boost.AFIO + + Use, modification and distribution is subject to the Boost Software License, + Version 1.0. (See accompanying file LICENSE_1_0.txt or copy at + http://www.boost.org/LICENSE_1_0.txt) +=============================================================================/] + + +[/ Generated by doxygen_xml2qbk 1.1.1, don't change, will be overwritten automatically] +[/ Generated from doxy/doxygen_output/xml\group__dispatcher____barrier.xml] diff --git a/attic/doc/generated/group_dispatcher__call.qbk b/attic/doc/generated/group_dispatcher__call.qbk new file mode 100644 index 00000000..8773a70d --- /dev/null +++ b/attic/doc/generated/group_dispatcher__call.qbk @@ -0,0 +1,11 @@ +[/============================================================================ + Boost.AFIO + + Use, modification and distribution is subject to the Boost Software License, + Version 1.0. (See accompanying file LICENSE_1_0.txt or copy at + http://www.boost.org/LICENSE_1_0.txt) +=============================================================================/] + + +[/ Generated by doxygen_xml2qbk 1.1.1, don't change, will be overwritten automatically] +[/ Generated from doxy/doxygen_output/xml\group__dispatcher____call.xml] diff --git a/attic/doc/generated/group_dispatcher__completion.qbk b/attic/doc/generated/group_dispatcher__completion.qbk new file mode 100644 index 00000000..04cf467b --- /dev/null +++ b/attic/doc/generated/group_dispatcher__completion.qbk @@ -0,0 +1,11 @@ +[/============================================================================ + Boost.AFIO + + Use, modification and distribution is subject to the Boost Software License, + Version 1.0. (See accompanying file LICENSE_1_0.txt or copy at + http://www.boost.org/LICENSE_1_0.txt) +=============================================================================/] + + +[/ Generated by doxygen_xml2qbk 1.1.1, don't change, will be overwritten automatically] +[/ Generated from doxy/doxygen_output/xml\group__dispatcher____completion.xml] diff --git a/attic/doc/generated/group_dispatcher__depends.qbk b/attic/doc/generated/group_dispatcher__depends.qbk new file mode 100644 index 00000000..c12823f0 --- /dev/null +++ b/attic/doc/generated/group_dispatcher__depends.qbk @@ -0,0 +1,43 @@ +[/============================================================================ + Boost.AFIO + + Use, modification and distribution is subject to the Boost Software License, + Version 1.0. (See accompanying file LICENSE_1_0.txt or copy at + http://www.boost.org/LICENSE_1_0.txt) +=============================================================================/] + + +[/ Generated by doxygen_xml2qbk 1.1.1, don't change, will be overwritten automatically] +[/ Generated from doxy/doxygen_output/xml\group__dispatcher____depends.xml] +[section:depends depends] +'''<?dbhtml-include href="disqus_identifiers/depends.html"?>''' + +'''<indexterm><primary>depends</primary></indexterm>''' +Schedule the return of an op handle after another op handle completes. This is useful when you need to supply one op handle to a function but it must not begin until another op handle has finished. + +[heading Synopsis] +``future dispatcher::depends(future<> precondition, future<> op)`` + +[heading Parameters] + +[table +[[Type] [Concept] [Name] [Description] ] +[[future<>] [] [precondition] [The op handle which must complete for op to be passed through. ]] +[[future<>] [] [op] [The op handle to return.]] +] + + +[heading Returns] +The op handle op. + +[heading Header] +`#include <boost/afio/v2/afio.hpp>` + +[heading Complexity]Amortised O(1) to dispatch. Amortised O(1) to complete. +[heading Exception Model]Propagates exceptions of any input preconditions with an errored state at the point of dispatch, and throws a `std::invalid_argument` if any inputs have values which could not possibly be correct. Once a batch of input ops has been verified at the point of entry as not errored, you are guaranteed that the batch is atomically scheduled as a whole, unless a failure to allocate memory occurs. +[heading Example][filecopy_example] + + +'''<?dbhtml-include href="disqus_comments.html"?>''' +[endsect] + diff --git a/attic/doc/generated/group_dispatcher__enumerate.qbk b/attic/doc/generated/group_dispatcher__enumerate.qbk new file mode 100644 index 00000000..aa907da4 --- /dev/null +++ b/attic/doc/generated/group_dispatcher__enumerate.qbk @@ -0,0 +1,11 @@ +[/============================================================================ + Boost.AFIO + + Use, modification and distribution is subject to the Boost Software License, + Version 1.0. (See accompanying file LICENSE_1_0.txt or copy at + http://www.boost.org/LICENSE_1_0.txt) +=============================================================================/] + + +[/ Generated by doxygen_xml2qbk 1.1.1, don't change, will be overwritten automatically] +[/ Generated from doxy/doxygen_output/xml\group__dispatcher____enumerate.xml] diff --git a/attic/doc/generated/group_dispatcher__extents.qbk b/attic/doc/generated/group_dispatcher__extents.qbk new file mode 100644 index 00000000..9d0b6b64 --- /dev/null +++ b/attic/doc/generated/group_dispatcher__extents.qbk @@ -0,0 +1,11 @@ +[/============================================================================ + Boost.AFIO + + Use, modification and distribution is subject to the Boost Software License, + Version 1.0. (See accompanying file LICENSE_1_0.txt or copy at + http://www.boost.org/LICENSE_1_0.txt) +=============================================================================/] + + +[/ Generated by doxygen_xml2qbk 1.1.1, don't change, will be overwritten automatically] +[/ Generated from doxy/doxygen_output/xml\group__dispatcher____extents.xml] diff --git a/attic/doc/generated/group_dispatcher__filedirops.qbk b/attic/doc/generated/group_dispatcher__filedirops.qbk new file mode 100644 index 00000000..db5169d7 --- /dev/null +++ b/attic/doc/generated/group_dispatcher__filedirops.qbk @@ -0,0 +1,11 @@ +[/============================================================================ + Boost.AFIO + + Use, modification and distribution is subject to the Boost Software License, + Version 1.0. (See accompanying file LICENSE_1_0.txt or copy at + http://www.boost.org/LICENSE_1_0.txt) +=============================================================================/] + + +[/ Generated by doxygen_xml2qbk 1.1.1, don't change, will be overwritten automatically] +[/ Generated from doxy/doxygen_output/xml\group__dispatcher____filedirops.xml] diff --git a/attic/doc/generated/group_dispatcher__filter.qbk b/attic/doc/generated/group_dispatcher__filter.qbk new file mode 100644 index 00000000..3cc4cd16 --- /dev/null +++ b/attic/doc/generated/group_dispatcher__filter.qbk @@ -0,0 +1,11 @@ +[/============================================================================ + Boost.AFIO + + Use, modification and distribution is subject to the Boost Software License, + Version 1.0. (See accompanying file LICENSE_1_0.txt or copy at + http://www.boost.org/LICENSE_1_0.txt) +=============================================================================/] + + +[/ Generated by doxygen_xml2qbk 1.1.1, don't change, will be overwritten automatically] +[/ Generated from doxy/doxygen_output/xml\group__dispatcher____filter.xml] diff --git a/attic/doc/generated/group_dispatcher__misc.qbk b/attic/doc/generated/group_dispatcher__misc.qbk new file mode 100644 index 00000000..c187457d --- /dev/null +++ b/attic/doc/generated/group_dispatcher__misc.qbk @@ -0,0 +1,68 @@ +[/============================================================================ + Boost.AFIO + + Use, modification and distribution is subject to the Boost Software License, + Version 1.0. (See accompanying file LICENSE_1_0.txt or copy at + http://www.boost.org/LICENSE_1_0.txt) +=============================================================================/] + + +[/ Generated by doxygen_xml2qbk 1.1.1, don't change, will be overwritten automatically] +[/ Generated from doxy/doxygen_output/xml\group__dispatcher____misc.xml] +[section:complete_async_op_3_normal complete_async_op (normal)] +'''<?dbhtml-include href="disqus_identifiers/complete_async_op_3_normal.html"?>''' + +'''<indexterm><primary>complete_async_op</primary></indexterm>''' +Completes an operation with a handle or an error, usually used when an operation was previously deferred. + +[heading Synopsis] +``void dispatcher::complete_async_op(size_t id, handle_ptr h, exception_ptr e = exception_ptr())`` + +[heading Parameters] + +[table +[[Type] [Concept] [Name] [Description] ] +[[size_t] [] [id] []] +[[handle_ptr] [] [h] []] +[[exception_ptr] [] [e] []] +] + + +[heading Header] +`#include <boost/afio/v2/afio.hpp>` + +[heading Complexity]O(N) where N is the number of completions dependent on this op. +[heading Exception Model]Should not throw any exception except for out of memory. + + +'''<?dbhtml-include href="disqus_comments.html"?>''' +[endsect] + +[section:complete_async_op_2_errored complete_async_op (errored)] +'''<?dbhtml-include href="disqus_identifiers/complete_async_op_2_errored.html"?>''' + +'''<indexterm><primary>complete_async_op</primary></indexterm>''' +Completes an operation with an error, usually used when an operation was previously deferred. + +[heading Synopsis] +``void dispatcher::complete_async_op(size_t id, exception_ptr e)`` + +[heading Parameters] + +[table +[[Type] [Concept] [Name] [Description] ] +[[size_t] [] [id] []] +[[exception_ptr] [] [e] []] +] + + +[heading Header] +`#include <boost/afio/v2/afio.hpp>` + +[heading Complexity]O(N) where N is the number of completions dependent on this op. +[heading Exception Model]Should not throw any exception except for out of memory. + + +'''<?dbhtml-include href="disqus_comments.html"?>''' +[endsect] + diff --git a/attic/doc/generated/group_dispatcher__statfs.qbk b/attic/doc/generated/group_dispatcher__statfs.qbk new file mode 100644 index 00000000..3df8a8fe --- /dev/null +++ b/attic/doc/generated/group_dispatcher__statfs.qbk @@ -0,0 +1,11 @@ +[/============================================================================ + Boost.AFIO + + Use, modification and distribution is subject to the Boost Software License, + Version 1.0. (See accompanying file LICENSE_1_0.txt or copy at + http://www.boost.org/LICENSE_1_0.txt) +=============================================================================/] + + +[/ Generated by doxygen_xml2qbk 1.1.1, don't change, will be overwritten automatically] +[/ Generated from doxy/doxygen_output/xml\group__dispatcher____statfs.xml] diff --git a/attic/doc/generated/group_enumerate.qbk b/attic/doc/generated/group_enumerate.qbk new file mode 100644 index 00000000..4f78c141 --- /dev/null +++ b/attic/doc/generated/group_enumerate.qbk @@ -0,0 +1,481 @@ +[/============================================================================ + Boost.AFIO + + Use, modification and distribution is subject to the Boost Software License, + Version 1.0. (See accompanying file LICENSE_1_0.txt or copy at + http://www.boost.org/LICENSE_1_0.txt) +=============================================================================/] + + +[/ Generated by doxygen_xml2qbk 1.1.1, don't change, will be overwritten automatically] +[/ Generated from doxy/doxygen_output/xml\group__enumerate.xml] +[section:enumerate_1_batch enumerate (batch)] +'''<?dbhtml-include href="disqus_identifiers/enumerate_1_batch.html"?>''' + +'''<indexterm><primary>enumerate</primary></indexterm>''' +Schedule a batch of asynchronous directory enumerations after preceding operations. + +[heading Description] +By default dir() returns shared handles i.e. dir( foo) and dir( foo) will return the exact same handle, and therefore enumerating not all of the entries at once is a race condition. The solution is to either set maxitems to a value large enough to guarantee a directory will be enumerated in a single shot, or to open a separate directory handle using the file\u005fflags::unique\u005fdirectory\u005fhandle flag. Note that setting maxitems=1 will often cause a buffer space exhaustion, causing a second syscall with an enlarged buffer. This is because AFIO cannot know if the allocated buffer can hold all of the filename being retrieved, so it may have to retry. Put another way, setting maxitems=1 will give you the worst performance possible, whereas maxitems=2 will probably only return one item most of the time. Related types: [^`__afio_enumerate_req__`], [^`__afio_directory_entry__`], [^`__afio_stat_t__`] + +[heading Synopsis] +``future< std::pair< std::vector< directory_entry >, bool > > dispatcher::enumerate(const std::vector< enumerate_req > & reqs)`` + +[heading Parameters] + +[table +[[Type] [Concept] [Name] [Description] ] +[[const std::vector< enumerate_req > &] [] [reqs] [A batch of enumeration requests.]] +] + + +[heading Returns] +A batch of stl\u005ffuture vectors of directory entries with boolean returning false if done. + +[heading Header] +`#include <boost/afio/v2/afio.hpp>` + +[heading Race Guarantees][raceguarantees +[raceguarantee FreeBSD, Linux, OS X..Race free per batch of up to ['maxitems] for ino and type only. Remember that +many filing systems will recycle inodes such that a created file will get the inode of a just deleted file, so +comparing inodes for equivalence to a direntry() won't help you.] +[raceguarantee Windows..Race free per batch of up to ['maxitems] for ino, type, atim, mtim, ctim, size, allocated, +birthtim, sparse, compressed.] + ] +[heading Complexity]Amortised O(N) to dispatch. Amortised O(N/threadpool*M) to complete where M is the average number of entries in each directory. +[heading Exception Model]Propagates exceptions of any input preconditions with an errored state at the point of dispatch, and throws a `std::invalid_argument` if any inputs have values which could not possibly be correct. Once a batch of input ops has been verified at the point of entry as not errored, you are guaranteed that the batch is atomically scheduled as a whole, unless a failure to allocate memory occurs. +[heading Example][enumerate_example] + + +'''<?dbhtml-include href="disqus_comments.html"?>''' +[endsect] + +[section:async_enumerate_6_maxitems_first async_enumerate (maxitems first)] +'''<?dbhtml-include href="disqus_identifiers/async_enumerate_6_maxitems_first.html"?>''' + +'''<indexterm><primary>async_enumerate</primary></indexterm>''' +Asynchronous directory enumeration after a preceding operation. + +[heading Description] +By default dir() returns shared handles i.e. dir( foo) and dir( foo) will return the exact same handle, and therefore enumerating not all of the entries at once is a race condition. The solution is to either set maxitems to a value large enough to guarantee a directory will be enumerated in a single shot, or to open a separate directory handle using the file\u005fflags::unique\u005fdirectory\u005fhandle flag. Note that setting maxitems=1 will often cause a buffer space exhaustion, causing a second syscall with an enlarged buffer. This is because AFIO cannot know if the allocated buffer can hold all of the filename being retrieved, so it may have to retry. Put another way, setting maxitems=1 will give you the worst performance possible, whereas maxitems=2 will probably only return one item most of the time. Related types: [^`__afio_enumerate_req__`], [^`__afio_directory_entry__`], [^`__afio_stat_t__`] + +[heading Synopsis] +``future<std::pair<std::vector<directory_entry>, bool> > async_enumerate(future<> _precondition, size_t _maxitems = 2, bool _restart = true, + path _glob = path(), metadata_flags _metadata = metadata_flags::None, enumerate_req::filter _filtering = enumerate_req::filter::fastdeleted)`` + +[heading Parameters] + +[table +[[Type] [Concept] [Name] [Description] ] +[[future<>] [] [_precondition] [The precondition to use. ]] +[[size_t] [] [_maxitems] [The maximum number of items to return in this request. Note that setting to one will often invoke two syscalls. ]] +[[bool] [] [_restart] [Restarts the enumeration for this open directory handle. ]] +[[path] [] [_glob] [An optional shell glob by which to filter the items returned. Done kernel side on Windows, user side on POSIX. ]] +[[metadata_flags] [] [_metadata] [The metadata to prefetch for each item enumerated. AFIO may fetch more metadata than requested if it is cost free. ]] +[[enumerate_req::filter] [] [_filtering] [Any filtering you want AFIO to do for you.]] +] + + +[heading Returns] +A [^`future<std::pair<std::vector<``directory_entry``>, bool>>`] + +[heading Header] +`#include <boost/afio/v2/afio.hpp>` + +[heading Race Guarantees][raceguarantees +[raceguarantee FreeBSD, Linux, OS X..Race free per batch of up to ['maxitems] for ino and type only. Remember that +many filing systems will recycle inodes such that a created file will get the inode of a just deleted file, so +comparing inodes for equivalence to a direntry() won't help you.] +[raceguarantee Windows..Race free per batch of up to ['maxitems] for ino, type, atim, mtim, ctim, size, allocated, +birthtim, sparse, compressed.] + ] +[heading Complexity]Amortised O(1) to dispatch. Amortised O(M) to complete where M is the average number of entries in each directory. +[heading Exception Model]Propagates the exception of any input precondition with an errored state at the point of dispatch, and throws a `std::invalid_argument` if any inputs have values which could not possibly be correct. Note that error code returning functions may still throw exceptions e.g. failure to allocate memory. +[heading Example][enumerate_example] + + +'''<?dbhtml-include href="disqus_comments.html"?>''' +[endsect] + +[section:enumerate_6_max_items_first_throwing enumerate (max items first throwing)] +'''<?dbhtml-include href="disqus_identifiers/enumerate_6_max_items_first_throwing.html"?>''' + +'''<indexterm><primary>enumerate</primary></indexterm>''' +Synchronous directory enumeration after a preceding operation. + +[heading Description] +By default dir() returns shared handles i.e. dir( foo) and dir( foo) will return the exact same handle, and therefore enumerating not all of the entries at once is a race condition. The solution is to either set maxitems to a value large enough to guarantee a directory will be enumerated in a single shot, or to open a separate directory handle using the file\u005fflags::unique\u005fdirectory\u005fhandle flag. Note that setting maxitems=1 will often cause a buffer space exhaustion, causing a second syscall with an enlarged buffer. This is because AFIO cannot know if the allocated buffer can hold all of the filename being retrieved, so it may have to retry. Put another way, setting maxitems=1 will give you the worst performance possible, whereas maxitems=2 will probably only return one item most of the time. Related types: [^`__afio_enumerate_req__`], [^`__afio_directory_entry__`], [^`__afio_stat_t__`] + +[heading Synopsis] +``std::pair<std::vector<directory_entry>, bool> enumerate(future<> _precondition, size_t _maxitems = 2, bool _restart = true, + path _glob = path(), metadata_flags _metadata = metadata_flags::None, enumerate_req::filter _filtering = enumerate_req::filter::fastdeleted)`` + +[heading Parameters] + +[table +[[Type] [Concept] [Name] [Description] ] +[[future<>] [] [_precondition] [The precondition to use. ]] +[[size_t] [] [_maxitems] [The maximum number of items to return in this request. Note that setting to one will often invoke two syscalls. ]] +[[bool] [] [_restart] [Restarts the enumeration for this open directory handle. ]] +[[path] [] [_glob] [An optional shell glob by which to filter the items returned. Done kernel side on Windows, user side on POSIX. ]] +[[metadata_flags] [] [_metadata] [The metadata to prefetch for each item enumerated. AFIO may fetch more metadata than requested if it is cost free. ]] +[[enumerate_req::filter] [] [_filtering] [Any filtering you want AFIO to do for you.]] +] + + +[heading Returns] +A vector of results and a bool indicating if there is more. + +[heading Header] +`#include <boost/afio/v2/afio.hpp>` + +[heading Race Guarantees][raceguarantees +[raceguarantee FreeBSD, Linux, OS X..Race free per batch of up to ['maxitems] for ino and type only. Remember that +many filing systems will recycle inodes such that a created file will get the inode of a just deleted file, so +comparing inodes for equivalence to a direntry() won't help you.] +[raceguarantee Windows..Race free per batch of up to ['maxitems] for ino, type, atim, mtim, ctim, size, allocated, +birthtim, sparse, compressed.] + ] +[heading Complexity]Amortised O(1) to dispatch. Amortised O(M) to complete where M is the average number of entries in each directory. +[heading Exception Model]Propagates the exception of any input precondition with an errored state at the point of dispatch, and throws a `std::invalid_argument` if any inputs have values which could not possibly be correct. Note that error code returning functions may still throw exceptions e.g. failure to allocate memory. +[heading Example][enumerate_example] + + +'''<?dbhtml-include href="disqus_comments.html"?>''' +[endsect] + +[section:enumerate_7_max_items_first_non_throwing enumerate (max items first non throwing)] +'''<?dbhtml-include href="disqus_identifiers/enumerate_7_max_items_first_non_throwing.html"?>''' + +'''<indexterm><primary>enumerate</primary></indexterm>''' +Synchronous directory enumeration after a preceding operation. + +[heading Description] +By default dir() returns shared handles i.e. dir( foo) and dir( foo) will return the exact same handle, and therefore enumerating not all of the entries at once is a race condition. The solution is to either set maxitems to a value large enough to guarantee a directory will be enumerated in a single shot, or to open a separate directory handle using the file\u005fflags::unique\u005fdirectory\u005fhandle flag. Note that setting maxitems=1 will often cause a buffer space exhaustion, causing a second syscall with an enlarged buffer. This is because AFIO cannot know if the allocated buffer can hold all of the filename being retrieved, so it may have to retry. Put another way, setting maxitems=1 will give you the worst performance possible, whereas maxitems=2 will probably only return one item most of the time. Related types: [^`__afio_enumerate_req__`], [^`__afio_directory_entry__`], [^`__afio_stat_t__`] + +[heading Synopsis] +``std::pair<std::vector<directory_entry>, bool> enumerate(error_code & _ec, future<> _precondition, size_t _maxitems = 2, + bool _restart = true, path _glob = path(), metadata_flags _metadata = metadata_flags::None, + enumerate_req::filter _filtering = enumerate_req::filter::fastdeleted)`` + +[heading Parameters] + +[table +[[Type] [Concept] [Name] [Description] ] +[[error_code &] [] [_ec] [Error code to set. ]] +[[future<>] [] [_precondition] [The precondition to use. ]] +[[size_t] [] [_maxitems] [The maximum number of items to return in this request. Note that setting to one will often invoke two syscalls. ]] +[[bool] [] [_restart] [Restarts the enumeration for this open directory handle. ]] +[[path] [] [_glob] [An optional shell glob by which to filter the items returned. Done kernel side on Windows, user side on POSIX. ]] +[[metadata_flags] [] [_metadata] [The metadata to prefetch for each item enumerated. AFIO may fetch more metadata than requested if it is cost free. ]] +[[enumerate_req::filter] [] [_filtering] [Any filtering you want AFIO to do for you.]] +] + + +[heading Returns] +A vector of results and a bool indicating if there is more. + +[heading Header] +`#include <boost/afio/v2/afio.hpp>` + +[heading Race Guarantees][raceguarantees +[raceguarantee FreeBSD, Linux, OS X..Race free per batch of up to ['maxitems] for ino and type only. Remember that +many filing systems will recycle inodes such that a created file will get the inode of a just deleted file, so +comparing inodes for equivalence to a direntry() won't help you.] +[raceguarantee Windows..Race free per batch of up to ['maxitems] for ino, type, atim, mtim, ctim, size, allocated, +birthtim, sparse, compressed.] + ] +[heading Complexity]Amortised O(1) to dispatch. Amortised O(M) to complete where M is the average number of entries in each directory. +[heading Exception Model]Propagates the exception of any input precondition with an errored state at the point of dispatch, and throws a `std::invalid_argument` if any inputs have values which could not possibly be correct. Note that error code returning functions may still throw exceptions e.g. failure to allocate memory. +[heading Example][enumerate_example] + + +'''<?dbhtml-include href="disqus_comments.html"?>''' +[endsect] + +[section:async_enumerate_6_glob_first async_enumerate (glob first)] +'''<?dbhtml-include href="disqus_identifiers/async_enumerate_6_glob_first.html"?>''' + +'''<indexterm><primary>async_enumerate</primary></indexterm>''' +Asynchronous directory enumeration after a preceding operation. + +[heading Description] +By default dir() returns shared handles i.e. dir( foo) and dir( foo) will return the exact same handle, and therefore enumerating not all of the entries at once is a race condition. The solution is to either set maxitems to a value large enough to guarantee a directory will be enumerated in a single shot, or to open a separate directory handle using the file\u005fflags::unique\u005fdirectory\u005fhandle flag. Note that setting maxitems=1 will often cause a buffer space exhaustion, causing a second syscall with an enlarged buffer. This is because AFIO cannot know if the allocated buffer can hold all of the filename being retrieved, so it may have to retry. Put another way, setting maxitems=1 will give you the worst performance possible, whereas maxitems=2 will probably only return one item most of the time. Related types: [^`__afio_enumerate_req__`], [^`__afio_directory_entry__`], [^`__afio_stat_t__`] + +[heading Synopsis] +``future<std::pair<std::vector<directory_entry>, bool> > async_enumerate(future<> _precondition, path _glob, size_t _maxitems = 2, + bool _restart = true, metadata_flags _metadata = metadata_flags::None, enumerate_req::filter _filtering = enumerate_req::filter::fastdeleted)`` + +[heading Parameters] + +[table +[[Type] [Concept] [Name] [Description] ] +[[future<>] [] [_precondition] [The precondition to use. ]] +[[path] [] [_glob] [A shell glob by which to filter the items returned. Done kernel side on Windows, user side on POSIX. ]] +[[size_t] [] [_maxitems] [The maximum number of items to return in this request. Note that setting to one will often invoke two syscalls. ]] +[[bool] [] [_restart] [Restarts the enumeration for this open directory handle. ]] +[[metadata_flags] [] [_metadata] [The metadata to prefetch for each item enumerated. AFIO may fetch more metadata than requested if it is cost free. ]] +[[enumerate_req::filter] [] [_filtering] [Any filtering you want AFIO to do for you.]] +] + + +[heading Returns] +A [^`future<std::pair<std::vector<``directory_entry``>, bool>>`] + +[heading Header] +`#include <boost/afio/v2/afio.hpp>` + +[heading Race Guarantees][raceguarantees +[raceguarantee FreeBSD, Linux, OS X..Race free per batch of up to ['maxitems] for ino and type only. Remember that +many filing systems will recycle inodes such that a created file will get the inode of a just deleted file, so +comparing inodes for equivalence to a direntry() won't help you.] +[raceguarantee Windows..Race free per batch of up to ['maxitems] for ino, type, atim, mtim, ctim, size, allocated, +birthtim, sparse, compressed.] + ] +[heading Complexity]Amortised O(1) to dispatch. Amortised O(M) to complete where M is the average number of entries in each directory. +[heading Exception Model]Propagates the exception of any input precondition with an errored state at the point of dispatch, and throws a `std::invalid_argument` if any inputs have values which could not possibly be correct. Note that error code returning functions may still throw exceptions e.g. failure to allocate memory. +[heading Example][enumerate_example] + + +'''<?dbhtml-include href="disqus_comments.html"?>''' +[endsect] + +[section:enumerate_6_glob_first_throwing enumerate (glob first throwing)] +'''<?dbhtml-include href="disqus_identifiers/enumerate_6_glob_first_throwing.html"?>''' + +'''<indexterm><primary>enumerate</primary></indexterm>''' +Synchronous directory enumeration after a preceding operation. + +[heading Description] +By default dir() returns shared handles i.e. dir( foo) and dir( foo) will return the exact same handle, and therefore enumerating not all of the entries at once is a race condition. The solution is to either set maxitems to a value large enough to guarantee a directory will be enumerated in a single shot, or to open a separate directory handle using the file\u005fflags::unique\u005fdirectory\u005fhandle flag. Note that setting maxitems=1 will often cause a buffer space exhaustion, causing a second syscall with an enlarged buffer. This is because AFIO cannot know if the allocated buffer can hold all of the filename being retrieved, so it may have to retry. Put another way, setting maxitems=1 will give you the worst performance possible, whereas maxitems=2 will probably only return one item most of the time. Related types: [^`__afio_enumerate_req__`], [^`__afio_directory_entry__`], [^`__afio_stat_t__`] + +[heading Synopsis] +``std::pair<std::vector<directory_entry>, bool> enumerate(future<> _precondition, path _glob, size_t _maxitems = 2, + bool _restart = true, metadata_flags _metadata = metadata_flags::None, enumerate_req::filter _filtering = enumerate_req::filter::fastdeleted)`` + +[heading Parameters] + +[table +[[Type] [Concept] [Name] [Description] ] +[[future<>] [] [_precondition] [The precondition to use. ]] +[[path] [] [_glob] [A shell glob by which to filter the items returned. Done kernel side on Windows, user side on POSIX. ]] +[[size_t] [] [_maxitems] [The maximum number of items to return in this request. Note that setting to one will often invoke two syscalls. ]] +[[bool] [] [_restart] [Restarts the enumeration for this open directory handle. ]] +[[metadata_flags] [] [_metadata] [The metadata to prefetch for each item enumerated. AFIO may fetch more metadata than requested if it is cost free. ]] +[[enumerate_req::filter] [] [_filtering] [Any filtering you want AFIO to do for you.]] +] + + +[heading Returns] +A vector of results and a bool indicating if there is more. + +[heading Header] +`#include <boost/afio/v2/afio.hpp>` + +[heading Race Guarantees][raceguarantees +[raceguarantee FreeBSD, Linux, OS X..Race free per batch of up to ['maxitems] for ino and type only. Remember that +many filing systems will recycle inodes such that a created file will get the inode of a just deleted file, so +comparing inodes for equivalence to a direntry() won't help you.] +[raceguarantee Windows..Race free per batch of up to ['maxitems] for ino, type, atim, mtim, ctim, size, allocated, +birthtim, sparse, compressed.] + ] +[heading Complexity]Amortised O(1) to dispatch. Amortised O(M) to complete where M is the average number of entries in each directory. +[heading Exception Model]Propagates the exception of any input precondition with an errored state at the point of dispatch, and throws a `std::invalid_argument` if any inputs have values which could not possibly be correct. Note that error code returning functions may still throw exceptions e.g. failure to allocate memory. +[heading Example][enumerate_example] + + +'''<?dbhtml-include href="disqus_comments.html"?>''' +[endsect] + +[section:enumerate_7_glob_first_non_throwing enumerate (glob first non throwing)] +'''<?dbhtml-include href="disqus_identifiers/enumerate_7_glob_first_non_throwing.html"?>''' + +'''<indexterm><primary>enumerate</primary></indexterm>''' +Synchronous directory enumeration after a preceding operation. + +[heading Description] +By default dir() returns shared handles i.e. dir( foo) and dir( foo) will return the exact same handle, and therefore enumerating not all of the entries at once is a race condition. The solution is to either set maxitems to a value large enough to guarantee a directory will be enumerated in a single shot, or to open a separate directory handle using the file\u005fflags::unique\u005fdirectory\u005fhandle flag. Note that setting maxitems=1 will often cause a buffer space exhaustion, causing a second syscall with an enlarged buffer. This is because AFIO cannot know if the allocated buffer can hold all of the filename being retrieved, so it may have to retry. Put another way, setting maxitems=1 will give you the worst performance possible, whereas maxitems=2 will probably only return one item most of the time. Related types: [^`__afio_enumerate_req__`], [^`__afio_directory_entry__`], [^`__afio_stat_t__`] + +[heading Synopsis] +``std::pair<std::vector<directory_entry>, bool> enumerate(error_code & _ec, future<> _precondition, path _glob, + size_t _maxitems = 2, bool _restart = true, metadata_flags _metadata = metadata_flags::None, + enumerate_req::filter _filtering = enumerate_req::filter::fastdeleted)`` + +[heading Parameters] + +[table +[[Type] [Concept] [Name] [Description] ] +[[error_code &] [] [_ec] [Error code to set. ]] +[[future<>] [] [_precondition] [The precondition to use. ]] +[[path] [] [_glob] [A shell glob by which to filter the items returned. Done kernel side on Windows, user side on POSIX. ]] +[[size_t] [] [_maxitems] [The maximum number of items to return in this request. Note that setting to one will often invoke two syscalls. ]] +[[bool] [] [_restart] [Restarts the enumeration for this open directory handle. ]] +[[metadata_flags] [] [_metadata] [The metadata to prefetch for each item enumerated. AFIO may fetch more metadata than requested if it is cost free. ]] +[[enumerate_req::filter] [] [_filtering] [Any filtering you want AFIO to do for you.]] +] + + +[heading Returns] +A vector of results and a bool indicating if there is more. + +[heading Header] +`#include <boost/afio/v2/afio.hpp>` + +[heading Race Guarantees][raceguarantees +[raceguarantee FreeBSD, Linux, OS X..Race free per batch of up to ['maxitems] for ino and type only. Remember that +many filing systems will recycle inodes such that a created file will get the inode of a just deleted file, so +comparing inodes for equivalence to a direntry() won't help you.] +[raceguarantee Windows..Race free per batch of up to ['maxitems] for ino, type, atim, mtim, ctim, size, allocated, +birthtim, sparse, compressed.] + ] +[heading Complexity]Amortised O(1) to dispatch. Amortised O(M) to complete where M is the average number of entries in each directory. +[heading Exception Model]Propagates the exception of any input precondition with an errored state at the point of dispatch, and throws a `std::invalid_argument` if any inputs have values which could not possibly be correct. Note that error code returning functions may still throw exceptions e.g. failure to allocate memory. +[heading Example][enumerate_example] + + +'''<?dbhtml-include href="disqus_comments.html"?>''' +[endsect] + +[section:async_enumerate_6_metadata_first async_enumerate (metadata first)] +'''<?dbhtml-include href="disqus_identifiers/async_enumerate_6_metadata_first.html"?>''' + +'''<indexterm><primary>async_enumerate</primary></indexterm>''' +Asynchronous directory enumeration after a preceding operation. + +[heading Description] +By default dir() returns shared handles i.e. dir( foo) and dir( foo) will return the exact same handle, and therefore enumerating not all of the entries at once is a race condition. The solution is to either set maxitems to a value large enough to guarantee a directory will be enumerated in a single shot, or to open a separate directory handle using the file\u005fflags::unique\u005fdirectory\u005fhandle flag. Note that setting maxitems=1 will often cause a buffer space exhaustion, causing a second syscall with an enlarged buffer. This is because AFIO cannot know if the allocated buffer can hold all of the filename being retrieved, so it may have to retry. Put another way, setting maxitems=1 will give you the worst performance possible, whereas maxitems=2 will probably only return one item most of the time. Related types: [^`__afio_enumerate_req__`], [^`__afio_directory_entry__`], [^`__afio_stat_t__`] + +[heading Synopsis] +``future<std::pair<std::vector<directory_entry>, bool> > async_enumerate(future<> _precondition, metadata_flags _metadata, size_t _maxitems = 2, + bool _restart = true, path _glob = path(), enumerate_req::filter _filtering = enumerate_req::filter::fastdeleted)`` + +[heading Parameters] + +[table +[[Type] [Concept] [Name] [Description] ] +[[future<>] [] [_precondition] [The precondition to use. ]] +[[metadata_flags] [] [_metadata] [The metadata to prefetch for each item enumerated. AFIO may fetch more metadata than requested if it is cost free. ]] +[[size_t] [] [_maxitems] [The maximum number of items to return in this request. Note that setting to one will often invoke two syscalls. ]] +[[bool] [] [_restart] [Restarts the enumeration for this open directory handle. ]] +[[path] [] [_glob] [An optional shell glob by which to filter the items returned. Done kernel side on Windows, user side on POSIX. ]] +[[enumerate_req::filter] [] [_filtering] [Any filtering you want AFIO to do for you.]] +] + + +[heading Returns] +A [^`future<std::pair<std::vector<``directory_entry``>, bool>>`] + +[heading Header] +`#include <boost/afio/v2/afio.hpp>` + +[heading Race Guarantees][raceguarantees +[raceguarantee FreeBSD, Linux, OS X..Race free per batch of up to ['maxitems] for ino and type only. Remember that +many filing systems will recycle inodes such that a created file will get the inode of a just deleted file, so +comparing inodes for equivalence to a direntry() won't help you.] +[raceguarantee Windows..Race free per batch of up to ['maxitems] for ino, type, atim, mtim, ctim, size, allocated, +birthtim, sparse, compressed.] + ] +[heading Complexity]Amortised O(1) to dispatch. Amortised O(M) to complete where M is the average number of entries in each directory. +[heading Exception Model]Propagates the exception of any input precondition with an errored state at the point of dispatch, and throws a `std::invalid_argument` if any inputs have values which could not possibly be correct. Note that error code returning functions may still throw exceptions e.g. failure to allocate memory. +[heading Example][enumerate_example] + + +'''<?dbhtml-include href="disqus_comments.html"?>''' +[endsect] + +[section:enumerate_6_metadata_first_throwing enumerate (metadata first throwing)] +'''<?dbhtml-include href="disqus_identifiers/enumerate_6_metadata_first_throwing.html"?>''' + +'''<indexterm><primary>enumerate</primary></indexterm>''' +Synchronous directory enumeration after a preceding operation. + +[heading Description] +By default dir() returns shared handles i.e. dir( foo) and dir( foo) will return the exact same handle, and therefore enumerating not all of the entries at once is a race condition. The solution is to either set maxitems to a value large enough to guarantee a directory will be enumerated in a single shot, or to open a separate directory handle using the file\u005fflags::unique\u005fdirectory\u005fhandle flag. Note that setting maxitems=1 will often cause a buffer space exhaustion, causing a second syscall with an enlarged buffer. This is because AFIO cannot know if the allocated buffer can hold all of the filename being retrieved, so it may have to retry. Put another way, setting maxitems=1 will give you the worst performance possible, whereas maxitems=2 will probably only return one item most of the time. Related types: [^`__afio_enumerate_req__`], [^`__afio_directory_entry__`], [^`__afio_stat_t__`] + +[heading Synopsis] +``std::pair<std::vector<directory_entry>, bool> enumerate(future<> _precondition, metadata_flags _metadata, size_t _maxitems = 2, + bool _restart = true, path _glob = path(), enumerate_req::filter _filtering = enumerate_req::filter::fastdeleted)`` + +[heading Parameters] + +[table +[[Type] [Concept] [Name] [Description] ] +[[future<>] [] [_precondition] [The precondition to use. ]] +[[metadata_flags] [] [_metadata] [The metadata to prefetch for each item enumerated. AFIO may fetch more metadata than requested if it is cost free. ]] +[[size_t] [] [_maxitems] [The maximum number of items to return in this request. Note that setting to one will often invoke two syscalls. ]] +[[bool] [] [_restart] [Restarts the enumeration for this open directory handle. ]] +[[path] [] [_glob] [An optional shell glob by which to filter the items returned. Done kernel side on Windows, user side on POSIX. ]] +[[enumerate_req::filter] [] [_filtering] [Any filtering you want AFIO to do for you.]] +] + + +[heading Returns] +A vector of results and a bool indicating if there is more. + +[heading Header] +`#include <boost/afio/v2/afio.hpp>` + +[heading Race Guarantees][raceguarantees +[raceguarantee FreeBSD, Linux, OS X..Race free per batch of up to ['maxitems] for ino and type only. Remember that +many filing systems will recycle inodes such that a created file will get the inode of a just deleted file, so +comparing inodes for equivalence to a direntry() won't help you.] +[raceguarantee Windows..Race free per batch of up to ['maxitems] for ino, type, atim, mtim, ctim, size, allocated, +birthtim, sparse, compressed.] + ] +[heading Complexity]Amortised O(1) to dispatch. Amortised O(M) to complete where M is the average number of entries in each directory. +[heading Exception Model]Propagates the exception of any input precondition with an errored state at the point of dispatch, and throws a `std::invalid_argument` if any inputs have values which could not possibly be correct. Note that error code returning functions may still throw exceptions e.g. failure to allocate memory. +[heading Example][enumerate_example] + + +'''<?dbhtml-include href="disqus_comments.html"?>''' +[endsect] + +[section:enumerate_7_metadata_first_non_throwing enumerate (metadata first non throwing)] +'''<?dbhtml-include href="disqus_identifiers/enumerate_7_metadata_first_non_throwing.html"?>''' + +'''<indexterm><primary>enumerate</primary></indexterm>''' +Synchronous directory enumeration after a preceding operation. + +[heading Description] +By default dir() returns shared handles i.e. dir( foo) and dir( foo) will return the exact same handle, and therefore enumerating not all of the entries at once is a race condition. The solution is to either set maxitems to a value large enough to guarantee a directory will be enumerated in a single shot, or to open a separate directory handle using the file\u005fflags::unique\u005fdirectory\u005fhandle flag. Note that setting maxitems=1 will often cause a buffer space exhaustion, causing a second syscall with an enlarged buffer. This is because AFIO cannot know if the allocated buffer can hold all of the filename being retrieved, so it may have to retry. Put another way, setting maxitems=1 will give you the worst performance possible, whereas maxitems=2 will probably only return one item most of the time. Related types: [^`__afio_enumerate_req__`], [^`__afio_directory_entry__`], [^`__afio_stat_t__`] + +[heading Synopsis] +``std::pair<std::vector<directory_entry>, bool> enumerate(error_code & _ec, future<> _precondition, metadata_flags _metadata, + size_t _maxitems = 2, bool _restart = true, path _glob = path(), + enumerate_req::filter _filtering = enumerate_req::filter::fastdeleted)`` + +[heading Parameters] + +[table +[[Type] [Concept] [Name] [Description] ] +[[error_code &] [] [_ec] [Error code to set. ]] +[[future<>] [] [_precondition] [The precondition to use. ]] +[[metadata_flags] [] [_metadata] [The metadata to prefetch for each item enumerated. AFIO may fetch more metadata than requested if it is cost free. ]] +[[size_t] [] [_maxitems] [The maximum number of items to return in this request. Note that setting to one will often invoke two syscalls. ]] +[[bool] [] [_restart] [Restarts the enumeration for this open directory handle. ]] +[[path] [] [_glob] [An optional shell glob by which to filter the items returned. Done kernel side on Windows, user side on POSIX. ]] +[[enumerate_req::filter] [] [_filtering] [Any filtering you want AFIO to do for you.]] +] + + +[heading Returns] +A vector of results and a bool indicating if there is more. + +[heading Header] +`#include <boost/afio/v2/afio.hpp>` + +[heading Race Guarantees][raceguarantees +[raceguarantee FreeBSD, Linux, OS X..Race free per batch of up to ['maxitems] for ino and type only. Remember that +many filing systems will recycle inodes such that a created file will get the inode of a just deleted file, so +comparing inodes for equivalence to a direntry() won't help you.] +[raceguarantee Windows..Race free per batch of up to ['maxitems] for ino, type, atim, mtim, ctim, size, allocated, +birthtim, sparse, compressed.] + ] +[heading Complexity]Amortised O(1) to dispatch. Amortised O(M) to complete where M is the average number of entries in each directory. +[heading Exception Model]Propagates the exception of any input precondition with an errored state at the point of dispatch, and throws a `std::invalid_argument` if any inputs have values which could not possibly be correct. Note that error code returning functions may still throw exceptions e.g. failure to allocate memory. +[heading Example][enumerate_example] + + +'''<?dbhtml-include href="disqus_comments.html"?>''' +[endsect] + diff --git a/attic/doc/generated/group_extents.qbk b/attic/doc/generated/group_extents.qbk new file mode 100644 index 00000000..e3da8fe3 --- /dev/null +++ b/attic/doc/generated/group_extents.qbk @@ -0,0 +1,172 @@ +[/============================================================================ + Boost.AFIO + + Use, modification and distribution is subject to the Boost Software License, + Version 1.0. (See accompanying file LICENSE_1_0.txt or copy at + http://www.boost.org/LICENSE_1_0.txt) +=============================================================================/] + + +[/ Generated by doxygen_xml2qbk 1.1.1, don't change, will be overwritten automatically] +[/ Generated from doxy/doxygen_output/xml\group__extents.xml] +[section:extents_1_batch extents (batch)] +'''<?dbhtml-include href="disqus_identifiers/extents_1_batch.html"?>''' + +'''<indexterm><primary>extents</primary></indexterm>''' +Schedule a batch of asynchronous extent enumerations after preceding operations. + +[heading Description] +In a sparsely allocated file, it can be useful to know which extents contain non-zero data. Note that this call is racy (i.e. the extents are enumerated one by one on some platforms, this means they may be out of date with respect to one another) when other threads or processes are concurrently calling zero() or write() - this is a host OS API limitation. + +[heading Synopsis] +``future< std::vector< std::pair< off_t, off_t > > > dispatcher::extents(const std::vector< future<>> & ops)`` + +[heading Parameters] + +[table +[[Type] [Concept] [Name] [Description] ] +[[const std::vector< future<>> &] [] [ops] [A batch of op handles.]] +] + + +[heading Returns] +A batch of stl\u005ffuture vectors of extents. + +[heading Header] +`#include <boost/afio/v2/afio.hpp>` + +[heading Race Guarantees][raceguarantees +[raceguarantee FreeBSD, Linux, OS X..Very racy, even individual extent offset and length can race. The following filters are applied +before returning results: (i) Any extent whose end appears before its start is retried (ii) Sequences of contiguous extents are merged +into single extents.] +[raceguarantee Windows..Race free.] + ] +[heading Complexity]Amortised O(N) to dispatch. Amortised O(N/threadpool*M) to complete where M is the average number of extents in each file. +[heading Exception Model]Propagates exceptions of any input preconditions with an errored state at the point of dispatch, and throws a `std::invalid_argument` if any inputs have values which could not possibly be correct. Once a batch of input ops has been verified at the point of entry as not errored, you are guaranteed that the batch is atomically scheduled as a whole, unless a failure to allocate memory occurs. +[heading Example][extents_example] + + +'''<?dbhtml-include href="disqus_comments.html"?>''' +[endsect] + +[section:async_extents async_extents] +'''<?dbhtml-include href="disqus_identifiers/async_extents.html"?>''' + +'''<indexterm><primary>async_extents</primary></indexterm>''' +Asynchronous extent enumeration after a preceding operation. + +[heading Description] +In a sparsely allocated file, it can be useful to know which extents contain non-zero data. Note that this call is racy (i.e. the extents are enumerated one by one on some platforms, this means they may be out of date with respect to one another) when other threads or processes are concurrently calling zero() or write() - this is a host OS API limitation. + +[heading Synopsis] +``future<std::vector<std::pair<off_t, off_t> > > async_extents(future<> _precondition)`` + +[heading Parameters] + +[table +[[Type] [Concept] [Name] [Description] ] +[[future<>] [] [_precondition] [The precondition to use.]] +] + + +[heading Returns] +A [^`future<std::vector<std::pair<off_t, off_t>>>`] + +[heading Header] +`#include <boost/afio/v2/afio.hpp>` + +[heading Race Guarantees][raceguarantees +[raceguarantee FreeBSD, Linux, OS X..Very racy, even individual extent offset and length can race. The following filters are applied +before returning results: (i) Any extent whose end appears before its start is retried (ii) Sequences of contiguous extents are merged +into single extents.] +[raceguarantee Windows..Race free.] + ] +[heading Complexity]Amortised O(1) to dispatch. Amortised O(M) to complete where M is the average number of extents in each file. +[heading Exception Model]Propagates the exception of any input precondition with an errored state at the point of dispatch, and throws a `std::invalid_argument` if any inputs have values which could not possibly be correct. Note that error code returning functions may still throw exceptions e.g. failure to allocate memory. +[heading Example][extents_example] + + +'''<?dbhtml-include href="disqus_comments.html"?>''' +[endsect] + +[section:extents_1_throwing extents (throwing)] +'''<?dbhtml-include href="disqus_identifiers/extents_1_throwing.html"?>''' + +'''<indexterm><primary>extents</primary></indexterm>''' +Synchronous extent enumeration after a preceding operation. + +[heading Description] +In a sparsely allocated file, it can be useful to know which extents contain non-zero data. Note that this call is racy (i.e. the extents are enumerated one by one on some platforms, this means they may be out of date with respect to one another) when other threads or processes are concurrently calling zero() or write() - this is a host OS API limitation. + +[heading Synopsis] +``std::vector<std::pair<off_t, off_t> > extents(future<> _precondition)`` + +[heading Parameters] + +[table +[[Type] [Concept] [Name] [Description] ] +[[future<>] [] [_precondition] [The precondition to use.]] +] + + +[heading Returns] +A vector of extents + +[heading Header] +`#include <boost/afio/v2/afio.hpp>` + +[heading Race Guarantees][raceguarantees +[raceguarantee FreeBSD, Linux, OS X..Very racy, even individual extent offset and length can race. The following filters are applied +before returning results: (i) Any extent whose end appears before its start is retried (ii) Sequences of contiguous extents are merged +into single extents.] +[raceguarantee Windows..Race free.] + ] +[heading Complexity]Amortised O(1) to dispatch. Amortised O(M) to complete where M is the average number of extents in each file. +[heading Exception Model]Propagates the exception of any input precondition with an errored state at the point of dispatch, and throws a `std::invalid_argument` if any inputs have values which could not possibly be correct. Note that error code returning functions may still throw exceptions e.g. failure to allocate memory. +[heading Example][extents_example] + + +'''<?dbhtml-include href="disqus_comments.html"?>''' +[endsect] + +[section:extents_2_non_throwing extents (non throwing)] +'''<?dbhtml-include href="disqus_identifiers/extents_2_non_throwing.html"?>''' + +'''<indexterm><primary>extents</primary></indexterm>''' +Synchronous extent enumeration after a preceding operation. + +[heading Description] +In a sparsely allocated file, it can be useful to know which extents contain non-zero data. Note that this call is racy (i.e. the extents are enumerated one by one on some platforms, this means they may be out of date with respect to one another) when other threads or processes are concurrently calling zero() or write() - this is a host OS API limitation. + +[heading Synopsis] +``std::vector<std::pair<off_t, off_t> > extents(error_code & _ec, future<> _precondition)`` + +[heading Parameters] + +[table +[[Type] [Concept] [Name] [Description] ] +[[error_code &] [] [_ec] [Error code to set. ]] +[[future<>] [] [_precondition] [The precondition to use.]] +] + + +[heading Returns] +A vector of extents + +[heading Header] +`#include <boost/afio/v2/afio.hpp>` + +[heading Race Guarantees][raceguarantees +[raceguarantee FreeBSD, Linux, OS X..Very racy, even individual extent offset and length can race. The following filters are applied +before returning results: (i) Any extent whose end appears before its start is retried (ii) Sequences of contiguous extents are merged +into single extents.] +[raceguarantee Windows..Race free.] + ] +[heading Complexity]Amortised O(1) to dispatch. Amortised O(M) to complete where M is the average number of extents in each file. +[heading Exception Model]Propagates the exception of any input precondition with an errored state at the point of dispatch, and throws a `std::invalid_argument` if any inputs have values which could not possibly be correct. Note that error code returning functions may still throw exceptions e.g. failure to allocate memory. +[heading Example][extents_example] + + +'''<?dbhtml-include href="disqus_comments.html"?>''' +[endsect] + diff --git a/attic/doc/generated/group_file.qbk b/attic/doc/generated/group_file.qbk new file mode 100644 index 00000000..e616497c --- /dev/null +++ b/attic/doc/generated/group_file.qbk @@ -0,0 +1,301 @@ +[/============================================================================ + Boost.AFIO + + Use, modification and distribution is subject to the Boost Software License, + Version 1.0. (See accompanying file LICENSE_1_0.txt or copy at + http://www.boost.org/LICENSE_1_0.txt) +=============================================================================/] + + +[/ Generated by doxygen_xml2qbk 1.1.1, don't change, will be overwritten automatically] +[/ Generated from doxy/doxygen_output/xml\group__file.xml] +[section:file_1_batch file (batch)] +'''<?dbhtml-include href="disqus_identifiers/file_1_batch.html"?>''' + +'''<indexterm><primary>file</primary></indexterm>''' +Schedule a batch of asynchronous file creations and opens after optional preconditions. + +[heading Description] +Be aware that any files created are by default sparse if supported on the local filing system. On Windows opening any file for writing converts it to sparse. Use file\u005fflags::no\u005fsparse to prevent this on those filing systems which permit it. Related types: [^`__afio_path_req__`] Be aware that on Windows AFIO operates exclusively in the NT kernel namespace, NOT the Win32 namespace, and therefore paths you supply are converted by [^`afio::path`] in NT kernel namespace paths. [^`normalise_path()`] can convert an afio path back to a Filesystem TS path for you, but note that this may not be the path that was supplied originally. NT kernel namespace paths have a 32,767 character limit and an almost POSIX like lack of restrictions on naming or historical behaviour quirks, but as a result AFIO does not support DOS short names or any of the other historical Win32 filing system baggage. + +[heading Synopsis] +``future dispatcher::file(const std::vector< path_req > & reqs)`` + +[heading Parameters] + +[table +[[Type] [Concept] [Name] [Description] ] +[[const std::vector< path_req > &] [] [reqs] [A batch of [^`path_req`] structures.]] +] + + +[heading Returns] +A batch of op handles. + +[heading Header] +`#include <boost/afio/v2/afio.hpp>` + +[heading Race Guarantees][raceguarantees +[raceguarantee FreeBSD, Linux, Windows..Race free up to the containing directory.] +[raceguarantee OS X..No guarantees.] + ] +[heading Complexity]Amortised O(N) to dispatch. Amortised O(N/threadpool) to complete if file creation is constant time. +[heading Exception Model]Propagates exceptions of any input preconditions with an errored state at the point of dispatch, and throws a `std::invalid_argument` if any inputs have values which could not possibly be correct. Once a batch of input ops has been verified at the point of entry as not errored, you are guaranteed that the batch is atomically scheduled as a whole, unless a failure to allocate memory occurs. +[heading Example][filedir_example] + + +'''<?dbhtml-include href="disqus_comments.html"?>''' +[endsect] + +[section:async_file_3_relative async_file (relative)] +'''<?dbhtml-include href="disqus_identifiers/async_file_3_relative.html"?>''' + +'''<indexterm><primary>async_file</primary></indexterm>''' +Asynchronous file creation and open after an optional precondition. + +[heading Description] +Be aware that any files created are by default sparse if supported on the local filing system. On Windows opening any file for writing converts it to sparse. Use file\u005fflags::no\u005fsparse to prevent this on those filing systems which permit it. Related types: [^`__afio_path_req__`] Be aware that on Windows AFIO operates exclusively in the NT kernel namespace, NOT the Win32 namespace, and therefore paths you supply are converted by [^`afio::path`] in NT kernel namespace paths. [^`normalise_path()`] can convert an afio path back to a Filesystem TS path for you, but note that this may not be the path that was supplied originally. NT kernel namespace paths have a 32,767 character limit and an almost POSIX like lack of restrictions on naming or historical behaviour quirks, but as a result AFIO does not support DOS short names or any of the other historical Win32 filing system baggage. + +[heading Synopsis] +``template<class T> +future async_file(future<> _precondition, T _path, file_flags _flags = file_flags::none)`` + +[heading Parameters] + +[table +[[Type] [Concept] [Name] [Description] ] +[[class T] [The type of path to use. ] [ - ] [Must be specified]] +[[future<>] [] [_precondition] [The precondition to use. ]] +[[T] [] [_path] [The filing system path to use. ]] +[[file_flags] [] [_flags] [The flags to use.]] +] + + +[heading Returns] +A future<void> + +[heading Header] +`#include <boost/afio/v2/afio.hpp>` + +[heading Race Guarantees][raceguarantees +[raceguarantee FreeBSD, Linux, Windows..Race free up to the containing directory.] +[raceguarantee OS X..No guarantees.] + ] +[heading Complexity]Amortised O(1) to dispatch. Amortised O(1) to complete if file creation is constant time. +[heading Exception Model]Propagates the exception of any input precondition with an errored state at the point of dispatch, and throws a `std::invalid_argument` if any inputs have values which could not possibly be correct. Note that error code returning functions may still throw exceptions e.g. failure to allocate memory. +[heading Example][filedir_example] + + +'''<?dbhtml-include href="disqus_comments.html"?>''' +[endsect] + +[section:async_file_2_absolute async_file (absolute)] +'''<?dbhtml-include href="disqus_identifiers/async_file_2_absolute.html"?>''' + +'''<indexterm><primary>async_file</primary></indexterm>''' +Asynchronous file creation and open after an optional precondition. + +[heading Description] +Be aware that any files created are by default sparse if supported on the local filing system. On Windows opening any file for writing converts it to sparse. Use file\u005fflags::no\u005fsparse to prevent this on those filing systems which permit it. Related types: [^`__afio_path_req__`] Be aware that on Windows AFIO operates exclusively in the NT kernel namespace, NOT the Win32 namespace, and therefore paths you supply are converted by [^`afio::path`] in NT kernel namespace paths. [^`normalise_path()`] can convert an afio path back to a Filesystem TS path for you, but note that this may not be the path that was supplied originally. NT kernel namespace paths have a 32,767 character limit and an almost POSIX like lack of restrictions on naming or historical behaviour quirks, but as a result AFIO does not support DOS short names or any of the other historical Win32 filing system baggage. + +[heading Synopsis] +``template<class T, typename> +future async_file(T _path, file_flags _flags = file_flags::none)`` + +[heading Parameters] + +[table +[[Type] [Concept] [Name] [Description] ] +[[class T] [The type of path to use. ] [ - ] [Must be specified]] +[[] [] [ - ] [Must be specified]] +[[T] [] [_path] [The filing system path to use. ]] +[[file_flags] [] [_flags] [The flags to use.]] +] + + +[heading Returns] +A future<void> + +[heading Header] +`#include <boost/afio/v2/afio.hpp>` + +[heading Race Guarantees][raceguarantees +[raceguarantee FreeBSD, Linux, OS X, Windows..No guarantees.] + ] +[heading Complexity]Amortised O(1) to dispatch. Amortised O(1) to complete if file creation is constant time. +[heading Exception Model]Propagates the exception of any input precondition with an errored state at the point of dispatch, and throws a `std::invalid_argument` if any inputs have values which could not possibly be correct. Note that error code returning functions may still throw exceptions e.g. failure to allocate memory. +[heading Example][filedir_example] + + +'''<?dbhtml-include href="disqus_comments.html"?>''' +[endsect] + +[section:file_3_relative_throwing file (relative throwing)] +'''<?dbhtml-include href="disqus_identifiers/file_3_relative_throwing.html"?>''' + +'''<indexterm><primary>file</primary></indexterm>''' +Synchronous file creation and open after an optional precondition. + +[heading Description] +Be aware that any files created are by default sparse if supported on the local filing system. On Windows opening any file for writing converts it to sparse. Use file\u005fflags::no\u005fsparse to prevent this on those filing systems which permit it. Related types: [^`__afio_path_req__`] Be aware that on Windows AFIO operates exclusively in the NT kernel namespace, NOT the Win32 namespace, and therefore paths you supply are converted by [^`afio::path`] in NT kernel namespace paths. [^`normalise_path()`] can convert an afio path back to a Filesystem TS path for you, but note that this may not be the path that was supplied originally. NT kernel namespace paths have a 32,767 character limit and an almost POSIX like lack of restrictions on naming or historical behaviour quirks, but as a result AFIO does not support DOS short names or any of the other historical Win32 filing system baggage. + +[heading Synopsis] +``template<class T> +handle_ptr file(future<> _precondition, T _path, file_flags _flags = file_flags::none)`` + +[heading Parameters] + +[table +[[Type] [Concept] [Name] [Description] ] +[[class T] [The type of path to use. ] [ - ] [Must be specified]] +[[future<>] [] [_precondition] [The precondition to use. ]] +[[T] [] [_path] [The filing system path to use. ]] +[[file_flags] [] [_flags] [The flags to use.]] +] + + +[heading Returns] +A handle to the file. + +[heading Header] +`#include <boost/afio/v2/afio.hpp>` + +[heading Race Guarantees][raceguarantees +[raceguarantee FreeBSD, Linux, Windows..Race free up to the containing directory.] +[raceguarantee OS X..No guarantees.] + ] +[heading Complexity]Amortised O(1) to dispatch. Amortised O(1) to complete if file creation is constant time. +[heading Exception Model]Propagates the exception of any input precondition with an errored state at the point of dispatch, and throws a `std::invalid_argument` if any inputs have values which could not possibly be correct. Note that error code returning functions may still throw exceptions e.g. failure to allocate memory. +[heading Example][filedir_example] + + +'''<?dbhtml-include href="disqus_comments.html"?>''' +[endsect] + +[section:file_2_absolute_throwing file (absolute throwing)] +'''<?dbhtml-include href="disqus_identifiers/file_2_absolute_throwing.html"?>''' + +'''<indexterm><primary>file</primary></indexterm>''' +Synchronous file creation and open after an optional precondition. + +[heading Description] +Be aware that any files created are by default sparse if supported on the local filing system. On Windows opening any file for writing converts it to sparse. Use file\u005fflags::no\u005fsparse to prevent this on those filing systems which permit it. Related types: [^`__afio_path_req__`] Be aware that on Windows AFIO operates exclusively in the NT kernel namespace, NOT the Win32 namespace, and therefore paths you supply are converted by [^`afio::path`] in NT kernel namespace paths. [^`normalise_path()`] can convert an afio path back to a Filesystem TS path for you, but note that this may not be the path that was supplied originally. NT kernel namespace paths have a 32,767 character limit and an almost POSIX like lack of restrictions on naming or historical behaviour quirks, but as a result AFIO does not support DOS short names or any of the other historical Win32 filing system baggage. + +[heading Synopsis] +``template<class T, typename> +handle_ptr file(T _path, file_flags _flags = file_flags::none)`` + +[heading Parameters] + +[table +[[Type] [Concept] [Name] [Description] ] +[[class T] [The type of path to use. ] [ - ] [Must be specified]] +[[] [] [ - ] [Must be specified]] +[[T] [] [_path] [The filing system path to use. ]] +[[file_flags] [] [_flags] [The flags to use.]] +] + + +[heading Returns] +A handle to the file. + +[heading Header] +`#include <boost/afio/v2/afio.hpp>` + +[heading Race Guarantees][raceguarantees +[raceguarantee FreeBSD, Linux, OS X, Windows..No guarantees.] + ] +[heading Complexity]Amortised O(1) to dispatch. Amortised O(1) to complete if file creation is constant time. +[heading Exception Model]Propagates the exception of any input precondition with an errored state at the point of dispatch, and throws a `std::invalid_argument` if any inputs have values which could not possibly be correct. Note that error code returning functions may still throw exceptions e.g. failure to allocate memory. +[heading Example][filedir_example] + + +'''<?dbhtml-include href="disqus_comments.html"?>''' +[endsect] + +[section:file_4_relative_non_throwing file (relative non throwing)] +'''<?dbhtml-include href="disqus_identifiers/file_4_relative_non_throwing.html"?>''' + +'''<indexterm><primary>file</primary></indexterm>''' +Synchronous file creation and open after an optional precondition. + +[heading Description] +Be aware that any files created are by default sparse if supported on the local filing system. On Windows opening any file for writing converts it to sparse. Use file\u005fflags::no\u005fsparse to prevent this on those filing systems which permit it. Related types: [^`__afio_path_req__`] Be aware that on Windows AFIO operates exclusively in the NT kernel namespace, NOT the Win32 namespace, and therefore paths you supply are converted by [^`afio::path`] in NT kernel namespace paths. [^`normalise_path()`] can convert an afio path back to a Filesystem TS path for you, but note that this may not be the path that was supplied originally. NT kernel namespace paths have a 32,767 character limit and an almost POSIX like lack of restrictions on naming or historical behaviour quirks, but as a result AFIO does not support DOS short names or any of the other historical Win32 filing system baggage. + +[heading Synopsis] +``template<class T> +handle_ptr file(error_code & _ec, future<> _precondition, T _path, + file_flags _flags = file_flags::none)`` + +[heading Parameters] + +[table +[[Type] [Concept] [Name] [Description] ] +[[class T] [The type of path to use. ] [ - ] [Must be specified]] +[[error_code &] [] [_ec] [Error code to set. ]] +[[future<>] [] [_precondition] [The precondition to use. ]] +[[T] [] [_path] [The filing system path to use. ]] +[[file_flags] [] [_flags] [The flags to use.]] +] + + +[heading Returns] +A handle to the file. + +[heading Header] +`#include <boost/afio/v2/afio.hpp>` + +[heading Race Guarantees][raceguarantees +[raceguarantee FreeBSD, Linux, Windows..Race free up to the containing directory.] +[raceguarantee OS X..No guarantees.] + ] +[heading Complexity]Amortised O(1) to dispatch. Amortised O(1) to complete if file creation is constant time. +[heading Exception Model]Propagates the exception of any input precondition with an errored state at the point of dispatch, and throws a `std::invalid_argument` if any inputs have values which could not possibly be correct. Note that error code returning functions may still throw exceptions e.g. failure to allocate memory. +[heading Example][filedir_example] + + +'''<?dbhtml-include href="disqus_comments.html"?>''' +[endsect] + +[section:file_3_absolute_non_throwing file (absolute non throwing)] +'''<?dbhtml-include href="disqus_identifiers/file_3_absolute_non_throwing.html"?>''' + +'''<indexterm><primary>file</primary></indexterm>''' +Synchronous file creation and open after an optional precondition. + +[heading Description] +Be aware that any files created are by default sparse if supported on the local filing system. On Windows opening any file for writing converts it to sparse. Use file\u005fflags::no\u005fsparse to prevent this on those filing systems which permit it. Related types: [^`__afio_path_req__`] Be aware that on Windows AFIO operates exclusively in the NT kernel namespace, NOT the Win32 namespace, and therefore paths you supply are converted by [^`afio::path`] in NT kernel namespace paths. [^`normalise_path()`] can convert an afio path back to a Filesystem TS path for you, but note that this may not be the path that was supplied originally. NT kernel namespace paths have a 32,767 character limit and an almost POSIX like lack of restrictions on naming or historical behaviour quirks, but as a result AFIO does not support DOS short names or any of the other historical Win32 filing system baggage. + +[heading Synopsis] +``template<class T, typename> +handle_ptr file(error_code & _ec, T _path, file_flags _flags = file_flags::none)`` + +[heading Parameters] + +[table +[[Type] [Concept] [Name] [Description] ] +[[class T] [The type of path to use. ] [ - ] [Must be specified]] +[[] [] [ - ] [Must be specified]] +[[error_code &] [] [_ec] [Error code to set. ]] +[[T] [] [_path] [The filing system path to use. ]] +[[file_flags] [] [_flags] [The flags to use.]] +] + + +[heading Returns] +A handle to the file. + +[heading Header] +`#include <boost/afio/v2/afio.hpp>` + +[heading Race Guarantees][raceguarantees +[raceguarantee FreeBSD, Linux, OS X, Windows..No guarantees.] + ] +[heading Complexity]Amortised O(1) to dispatch. Amortised O(1) to complete if file creation is constant time. +[heading Exception Model]Propagates the exception of any input precondition with an errored state at the point of dispatch, and throws a `std::invalid_argument` if any inputs have values which could not possibly be correct. Note that error code returning functions may still throw exceptions e.g. failure to allocate memory. +[heading Example][filedir_example] + + +'''<?dbhtml-include href="disqus_comments.html"?>''' +[endsect] + diff --git a/attic/doc/generated/group_file_flags.qbk b/attic/doc/generated/group_file_flags.qbk new file mode 100644 index 00000000..ca606662 --- /dev/null +++ b/attic/doc/generated/group_file_flags.qbk @@ -0,0 +1,84 @@ +[/============================================================================ + Boost.AFIO + + Use, modification and distribution is subject to the Boost Software License, + Version 1.0. (See accompanying file LICENSE_1_0.txt or copy at + http://www.boost.org/LICENSE_1_0.txt) +=============================================================================/] + + +[/ Generated by doxygen_xml2qbk 1.1.1, don't change, will be overwritten automatically] +[/ Generated from doxy/doxygen_output/xml\group__file__flags.xml] +[section:file_flags file_flags] +'''<?dbhtml-include href="disqus_identifiers/file_flags.html"?>''' + +'''<indexterm><primary>file_flags</primary></indexterm>''' +'''<indexterm><primary>none</primary></indexterm>''' +'''<indexterm><primary>read</primary></indexterm>''' +'''<indexterm><primary>write</primary></indexterm>''' +'''<indexterm><primary>read_write</primary></indexterm>''' +'''<indexterm><primary>append</primary></indexterm>''' +'''<indexterm><primary>truncate</primary></indexterm>''' +'''<indexterm><primary>create</primary></indexterm>''' +'''<indexterm><primary>create_only_if_not_exist</primary></indexterm>''' +'''<indexterm><primary>create_compressed</primary></indexterm>''' +'''<indexterm><primary>will_be_sequentially_accessed</primary></indexterm>''' +'''<indexterm><primary>will_be_randomly_accessed</primary></indexterm>''' +'''<indexterm><primary>no_sparse</primary></indexterm>''' +'''<indexterm><primary>hold_parent_open</primary></indexterm>''' +'''<indexterm><primary>unique_directory_handle</primary></indexterm>''' +'''<indexterm><primary>no_race_protection</primary></indexterm>''' +'''<indexterm><primary>temporary_file</primary></indexterm>''' +'''<indexterm><primary>delete_on_close</primary></indexterm>''' +'''<indexterm><primary>os_direct</primary></indexterm>''' +'''<indexterm><primary>os_lockable</primary></indexterm>''' +'''<indexterm><primary>always_sync</primary></indexterm>''' +'''<indexterm><primary>sync_on_close</primary></indexterm>''' +'''<indexterm><primary>int_hold_parent_open_nested</primary></indexterm>''' +'''<indexterm><primary>int_file_share_delete</primary></indexterm>''' +'''<indexterm><primary>int_opening_link</primary></indexterm>''' +'''<indexterm><primary>int_opening_dir</primary></indexterm>''' +Bitwise file and directory open flags. + +[heading Synopsis] +``enum file_flags {none = 0, read = 1, write = 2, read_write = 3, append = 4, truncate = 8, create = 16, create_only_if_not_exist = 32, create_compressed = 64, will_be_sequentially_accessed = 128, will_be_randomly_accessed = 256, no_sparse = 512, hold_parent_open = (1<<10), unique_directory_handle = (1<<11), no_race_protection = (1<<12), temporary_file = (1<<13), delete_on_close = (1<<14), os_direct = (1<<16), os_lockable = (1<<17), always_sync = (1<<24), sync_on_close = (1<<25), int_hold_parent_open_nested = (1<<27), int_file_share_delete = (1<<28), int_opening_link = (1<<29), int_opening_dir = (1<<30)};`` + +[heading Values] + +[table +[[Value] [Description] ] +[[none] [No flags set. ]] +[[read] [Read access. ]] +[[write] [Write access. ]] +[[read_write] [Read and write access. ]] +[[append] [Append only. ]] +[[truncate] [Truncate existing file to zero. ]] +[[create] [Open and create if doesn't exist. Always creates sparse files if possible. ]] +[[create_only_if_not_exist] [Create and open only if doesn't exist. ]] +[[create_compressed] [Create a compressed file, needs to be combined with one of the other create flags. Only succeeds if supported by the underlying filing system. ]] +[[will_be_sequentially_accessed] [Will be ['exclusively] either read or written sequentially. If you're exclusively writing sequentially, ['strongly] consider turning on [^`os_direct`] too. ]] +[[will_be_randomly_accessed] [Will be randomly accessed, so don't bother with read-ahead. If you're using this, ['strongly] consider turning on [^`os_direct`] too. ]] +[[no_sparse] [Don't create sparse files. May be ignored by some filing systems (e.g. ext4). ]] +[[hold_parent_open] [Hold a file handle open to the containing directory of each open file for fast directory enumeration and fast relative path ops. ]] +[[unique_directory_handle] [Return a unique directory handle rather than a shared directory handle. ]] +[[no_race_protection] [Skip taking steps to avoid destruction of data due to filing system races. Most of the performance benefit of enabling this goes away if you enable HoldParentOpen instead, so be especially careful when considering turning this on. ]] +[[temporary_file] [On some systems causes dirty cache data to not be written to physical storage until file close. Useful for temporary files and lock files, especially on Windows when combined with [^`delete_on_close`] as this avoids an fsync of the containing directory on file close. ]] +[[delete_on_close] [Only when combined with [^`create_only_if_not_exist`], deletes the file on close. This is especially useful on Windows with temporary and lock files where normally closing a file is an implicit fsync of its containing directory. Note on POSIX this unlinks the file on first close by AFIO, whereas on Windows the operating system unlinks the file on last close including sudden application exit. Note also that AFIO permits you to delete files which are currently open on Windows and the file entry disappears immediately just as on POSIX. ]] +[[os_direct] [Bypass the OS file buffers (only really useful for writing large files, or a lot of random reads and writes. Note you must 4Kb align everything if this is on). Be VERY careful mixing this with memory mapped files. ]] +[[os_lockable] []] +[[always_sync] [Ask the OS to not complete until the data is on the physical storage. Some filing systems do much better with this than [^`sync_on_close`]. ]] +[[sync_on_close] [Automatically initiate an asynchronous flush just before file close, and fuse both operations so both must complete for close to complete. ]] +[[int_hold_parent_open_nested] [Internal use only. Don't use. ]] +[[int_file_share_delete] [Internal use only. Don't use. ]] +[[int_opening_link] [Internal use only. Don't use. ]] +[[int_opening_dir] [Internal use only. Don't use. ]] +] + + +[heading Header] +`#include <boost/afio/v2/afio.hpp>` + + +'''<?dbhtml-include href="disqus_comments.html"?>''' +[endsect] + diff --git a/attic/doc/generated/group_fs_metadata_flags.qbk b/attic/doc/generated/group_fs_metadata_flags.qbk new file mode 100644 index 00000000..ba555fbe --- /dev/null +++ b/attic/doc/generated/group_fs_metadata_flags.qbk @@ -0,0 +1,66 @@ +[/============================================================================ + Boost.AFIO + + Use, modification and distribution is subject to the Boost Software License, + Version 1.0. (See accompanying file LICENSE_1_0.txt or copy at + http://www.boost.org/LICENSE_1_0.txt) +=============================================================================/] + + +[/ Generated by doxygen_xml2qbk 1.1.1, don't change, will be overwritten automatically] +[/ Generated from doxy/doxygen_output/xml\group__fs__metadata__flags.xml] +[section:fs_metadata_flags fs_metadata_flags] +'''<?dbhtml-include href="disqus_identifiers/fs_metadata_flags.html"?>''' + +'''<indexterm><primary>fs_metadata_flags</primary></indexterm>''' +'''<indexterm><primary>None</primary></indexterm>''' +'''<indexterm><primary>flags</primary></indexterm>''' +'''<indexterm><primary>bsize</primary></indexterm>''' +'''<indexterm><primary>iosize</primary></indexterm>''' +'''<indexterm><primary>blocks</primary></indexterm>''' +'''<indexterm><primary>bfree</primary></indexterm>''' +'''<indexterm><primary>bavail</primary></indexterm>''' +'''<indexterm><primary>files</primary></indexterm>''' +'''<indexterm><primary>ffree</primary></indexterm>''' +'''<indexterm><primary>namemax</primary></indexterm>''' +'''<indexterm><primary>owner</primary></indexterm>''' +'''<indexterm><primary>fsid</primary></indexterm>''' +'''<indexterm><primary>fstypename</primary></indexterm>''' +'''<indexterm><primary>mntfromname</primary></indexterm>''' +'''<indexterm><primary>mntonname</primary></indexterm>''' +'''<indexterm><primary>All</primary></indexterm>''' +Bitflags for availability of metadata from [^`struct ``statfs_t`] + +[heading Synopsis] +``enum fs_metadata_flags {None = 0, flags = 1<<1, bsize = 1<<2, iosize = 1<<3, blocks = 1<<4, bfree = 1<<5, bavail = 1<<6, files = 1<<7, ffree = 1<<8, namemax = 1<<9, owner = 1<<10, fsid = 1<<11, fstypename = 1<<12, mntfromname = 1<<13, mntonname = 1<<14, All = (size_t)-1};`` + +[heading Values] + +[table +[[Value] [Description] ] +[[None] []] +[[flags] []] +[[bsize] []] +[[iosize] []] +[[blocks] []] +[[bfree] []] +[[bavail] []] +[[files] []] +[[ffree] []] +[[namemax] []] +[[owner] []] +[[fsid] []] +[[fstypename] []] +[[mntfromname] []] +[[mntonname] []] +[[All] [Return the maximum possible metadata. ]] +] + + +[heading Header] +`#include <boost/afio/v2/afio.hpp>` + + +'''<?dbhtml-include href="disqus_comments.html"?>''' +[endsect] + diff --git a/attic/doc/generated/group_io_req.qbk b/attic/doc/generated/group_io_req.qbk new file mode 100644 index 00000000..27a53414 --- /dev/null +++ b/attic/doc/generated/group_io_req.qbk @@ -0,0 +1,11 @@ +[/============================================================================ + Boost.AFIO + + Use, modification and distribution is subject to the Boost Software License, + Version 1.0. (See accompanying file LICENSE_1_0.txt or copy at + http://www.boost.org/LICENSE_1_0.txt) +=============================================================================/] + + +[/ Generated by doxygen_xml2qbk 1.1.1, don't change, will be overwritten automatically] +[/ Generated from doxy/doxygen_output/xml\group__io__req.xml] diff --git a/attic/doc/generated/group_macros.qbk b/attic/doc/generated/group_macros.qbk new file mode 100644 index 00000000..1bc006c4 --- /dev/null +++ b/attic/doc/generated/group_macros.qbk @@ -0,0 +1,37 @@ +[/============================================================================ + Boost.AFIO + + Use, modification and distribution is subject to the Boost Software License, + Version 1.0. (See accompanying file LICENSE_1_0.txt or copy at + http://www.boost.org/LICENSE_1_0.txt) +=============================================================================/] + + +[/ Generated by doxygen_xml2qbk 1.1.1, don't change, will be overwritten automatically] +[/ Generated from doxy/doxygen_output/xml\group__macros.xml] +[section:boost_afio_validate_inputs BOOST_AFIO_VALIDATE_INPUTS] +'''<?dbhtml-include href="disqus_identifiers/boost_afio_validate_inputs.html"?>''' + +'''<indexterm><primary>BOOST_AFIO_VALIDATE_INPUTS</primary></indexterm>''' +Validate inputs at the point of instantiation. + +[heading Description] +Turns on the checking of inputs for validity and throwing of exception conditions at the point of instantiation rather than waiting until those inputs are sent for dispatch. This, being very useful for debugging, defaults to 1 except when [^`NDEBUG`] is defined i.e. final release builds. + +[heading Synopsis] +``#define BOOST_AFIO_VALIDATE_INPUTS`` + +[heading Parameters] + +[table +[[Name] [Description] ] +] + + +[heading Header] +`#include <boost/afio/v2/afio.hpp>` + + +'''<?dbhtml-include href="disqus_comments.html"?>''' +[endsect] + diff --git a/attic/doc/generated/group_make_io_req.qbk b/attic/doc/generated/group_make_io_req.qbk new file mode 100644 index 00000000..02e5d43e --- /dev/null +++ b/attic/doc/generated/group_make_io_req.qbk @@ -0,0 +1,115 @@ +[/============================================================================ + Boost.AFIO + + Use, modification and distribution is subject to the Boost Software License, + Version 1.0. (See accompanying file LICENSE_1_0.txt or copy at + http://www.boost.org/LICENSE_1_0.txt) +=============================================================================/] + + +[/ Generated by doxygen_xml2qbk 1.1.1, don't change, will be overwritten automatically] +[/ Generated from doxy/doxygen_output/xml\group__make__io__req.xml] +[section:make_io_req_3_length_deducing make_io_req (length deducing)] +'''<?dbhtml-include href="disqus_identifiers/make_io_req_3_length_deducing.html"?>''' + +'''<indexterm><primary>make_io_req</primary></indexterm>''' +Convenience instantiator of a io\u005freq, letting the compiler deduce the template specialisation to use. + +[heading Synopsis] +``template<class T> +auto make_io_req(future<> _precondition, T && v, off_t _where)`` + +[heading Parameters] + +[table +[[Type] [Concept] [Name] [Description] ] +[[class T] [] [ - ] [Must be specified]] +[[future<>] [] [_precondition] [An optional precondition for this operation]] +[[T &&] [] [v] [A pointer to memory or reference to object into which to read or write]] +[[off_t] [] [_where] [The offset at which to transfer]] +] + + +[heading Returns] +An io\u005freq matching the supplied parameter type. Constructs an instance. + +[heading Header] +`#include <boost/afio/v2/afio.hpp>` + +[heading Example] +[readwrite_example] + + +'''<?dbhtml-include href="disqus_comments.html"?>''' +[endsect] + +[section:make_io_req_3_length_deducing make_io_req (length deducing)] +'''<?dbhtml-include href="disqus_identifiers/make_io_req_3_length_deducing.html"?>''' + +'''<indexterm><primary>make_io_req</primary></indexterm>''' +Convenience instantiator of a io\u005freq, letting the compiler deduce the template specialisation to use. + +[heading Synopsis] +``template<class T> +io_req<const std::initializer_list<T> > make_io_req(future<> _precondition, const std::initializer_list< T > & v, off_t _where)`` + +[heading Parameters] + +[table +[[Type] [Concept] [Name] [Description] ] +[[class T] [] [ - ] [Must be specified]] +[[future<>] [] [_precondition] [An optional precondition for this operation]] +[[const std::initializer_list< T > &] [] [v] [A pointer to memory or reference to object into which to read or write]] +[[off_t] [] [_where] [The offset at which to transfer]] +] + + +[heading Returns] +An io\u005freq matching the supplied parameter type. Constructs an instance. + +[heading Header] +`#include <boost/afio/v2/afio.hpp>` + +[heading Example] +[readwrite_example] + + +'''<?dbhtml-include href="disqus_comments.html"?>''' +[endsect] + +[section:make_io_req_4_length_specifying make_io_req (length specifying)] +'''<?dbhtml-include href="disqus_identifiers/make_io_req_4_length_specifying.html"?>''' + +'''<indexterm><primary>make_io_req</primary></indexterm>''' +Convenience instantiator of a io\u005freq, letting the compiler deduce the template specialisation to use. + +[heading Synopsis] +``template<class T> +auto make_io_req(future<> _precondition, T && v, size_t _length, + off_t _where)`` + +[heading Parameters] + +[table +[[Type] [Concept] [Name] [Description] ] +[[class T] [] [ - ] [Must be specified]] +[[future<>] [] [_precondition] [An optional precondition for this operation]] +[[T &&] [] [v] [A pointer to memory or reference to object into which to read or write]] +[[size_t] [] [_length] [The number of bytes to transfer]] +[[off_t] [] [_where] [The offset at which to transfer ]] +] + + +[heading Returns] +An io\u005freq matching the supplied parameter type. Constructs an instance. + +[heading Header] +`#include <boost/afio/v2/afio.hpp>` + +[heading Example] +[readwrite_example] + + +'''<?dbhtml-include href="disqus_comments.html"?>''' +[endsect] + diff --git a/attic/doc/generated/group_metadata_flags.qbk b/attic/doc/generated/group_metadata_flags.qbk new file mode 100644 index 00000000..9cd6315f --- /dev/null +++ b/attic/doc/generated/group_metadata_flags.qbk @@ -0,0 +1,80 @@ +[/============================================================================ + Boost.AFIO + + Use, modification and distribution is subject to the Boost Software License, + Version 1.0. (See accompanying file LICENSE_1_0.txt or copy at + http://www.boost.org/LICENSE_1_0.txt) +=============================================================================/] + + +[/ Generated by doxygen_xml2qbk 1.1.1, don't change, will be overwritten automatically] +[/ Generated from doxy/doxygen_output/xml\group__metadata__flags.xml] +[section:metadata_flags metadata_flags] +'''<?dbhtml-include href="disqus_identifiers/metadata_flags.html"?>''' + +'''<indexterm><primary>metadata_flags</primary></indexterm>''' +'''<indexterm><primary>None</primary></indexterm>''' +'''<indexterm><primary>dev</primary></indexterm>''' +'''<indexterm><primary>ino</primary></indexterm>''' +'''<indexterm><primary>type</primary></indexterm>''' +'''<indexterm><primary>perms</primary></indexterm>''' +'''<indexterm><primary>nlink</primary></indexterm>''' +'''<indexterm><primary>uid</primary></indexterm>''' +'''<indexterm><primary>gid</primary></indexterm>''' +'''<indexterm><primary>rdev</primary></indexterm>''' +'''<indexterm><primary>atim</primary></indexterm>''' +'''<indexterm><primary>mtim</primary></indexterm>''' +'''<indexterm><primary>ctim</primary></indexterm>''' +'''<indexterm><primary>size</primary></indexterm>''' +'''<indexterm><primary>allocated</primary></indexterm>''' +'''<indexterm><primary>blocks</primary></indexterm>''' +'''<indexterm><primary>blksize</primary></indexterm>''' +'''<indexterm><primary>flags</primary></indexterm>''' +'''<indexterm><primary>gen</primary></indexterm>''' +'''<indexterm><primary>birthtim</primary></indexterm>''' +'''<indexterm><primary>sparse</primary></indexterm>''' +'''<indexterm><primary>compressed</primary></indexterm>''' +'''<indexterm><primary>reparse_point</primary></indexterm>''' +'''<indexterm><primary>All</primary></indexterm>''' +Bitflags for availability of metadata from [^`struct ``stat_t`]See [*afio_stat_t] for explanation of meaning. + +[heading Synopsis] +``enum metadata_flags {None = 0, dev = 1<<0, ino = 1<<1, type = 1<<2, perms = 1<<3, nlink = 1<<4, uid = 1<<5, gid = 1<<6, rdev = 1<<7, atim = 1<<8, mtim = 1<<9, ctim = 1<<10, size = 1<<11, allocated = 1<<12, blocks = 1<<13, blksize = 1<<14, flags = 1<<15, gen = 1<<16, birthtim = 1<<17, sparse = 1<<24, compressed = 1<<25, reparse_point = 1<<26, All = (size_t)-1};`` + +[heading Values] + +[table +[[Value] [Description] ] +[[None] []] +[[dev] []] +[[ino] []] +[[type] []] +[[perms] []] +[[nlink] []] +[[uid] []] +[[gid] []] +[[rdev] []] +[[atim] []] +[[mtim] []] +[[ctim] []] +[[size] []] +[[allocated] []] +[[blocks] []] +[[blksize] []] +[[flags] []] +[[gen] []] +[[birthtim] []] +[[sparse] []] +[[compressed] []] +[[reparse_point] []] +[[All] [Return the maximum possible metadata. ]] +] + + +[heading Header] +`#include <boost/afio/v2/afio.hpp>` + + +'''<?dbhtml-include href="disqus_comments.html"?>''' +[endsect] + diff --git a/attic/doc/generated/group_normalise_path.qbk b/attic/doc/generated/group_normalise_path.qbk new file mode 100644 index 00000000..12adb576 --- /dev/null +++ b/attic/doc/generated/group_normalise_path.qbk @@ -0,0 +1,41 @@ +[/============================================================================ + Boost.AFIO + + Use, modification and distribution is subject to the Boost Software License, + Version 1.0. (See accompanying file LICENSE_1_0.txt or copy at + http://www.boost.org/LICENSE_1_0.txt) +=============================================================================/] + + +[/ Generated by doxygen_xml2qbk 1.1.1, don't change, will be overwritten automatically] +[/ Generated from doxy/doxygen_output/xml\group__normalise__path.xml] +[section:normalise_path normalise_path] +'''<?dbhtml-include href="disqus_identifiers/normalise_path.html"?>''' + +'''<indexterm><primary>normalise_path</primary></indexterm>''' +Return a normalised filesystem::path from an AFIO path. + +[heading Description] +On POSIX this passes through its input unchanged. + +On Windows AFIO exclusively uses NT kernel paths which are not necessarily trivially convertible to Win32 paths. As an example, the Win32 path [^`C:\\Foo`] might be [^`\\??\\C:\\Foo`] or even [^`\\Device\\HarddiskVolume1\\Foo`]. This function will convert any NT kernel path into something which can be fed to normal Win32 APIs - a drive letter if available, else a GUID volume path, and with an extended path prefix if the path is sufficiently long. It also scans the path for characters illegal under Win32 or paths which begin with a space or end with a period, and will extended path prefix such paths as well. + +[heading Synopsis] +``filesystem::path normalise_path(path p, path_normalise type = path_normalise::dos)`` + +[heading Parameters] + +[table +[[Type] [Concept] [Name] [Description] ] +[[path] [] [p] [Path to be normalised ]] +[[path_normalise] [] [type] [A path_normalise enum ]] +] + + +[heading Header] +`#include <boost/afio/v2/afio.hpp>` + + +'''<?dbhtml-include href="disqus_comments.html"?>''' +[endsect] + diff --git a/attic/doc/generated/group_process_threadpool.qbk b/attic/doc/generated/group_process_threadpool.qbk new file mode 100644 index 00000000..44e56b77 --- /dev/null +++ b/attic/doc/generated/group_process_threadpool.qbk @@ -0,0 +1,37 @@ +[/============================================================================ + Boost.AFIO + + Use, modification and distribution is subject to the Boost Software License, + Version 1.0. (See accompanying file LICENSE_1_0.txt or copy at + http://www.boost.org/LICENSE_1_0.txt) +=============================================================================/] + + +[/ Generated by doxygen_xml2qbk 1.1.1, don't change, will be overwritten automatically] +[/ Generated from doxy/doxygen_output/xml\group__process__threadpool.xml] +[section:process_threadpool process_threadpool] +'''<?dbhtml-include href="disqus_identifiers/process_threadpool.html"?>''' + +'''<indexterm><primary>process_threadpool</primary></indexterm>''' +Returns the process threadpool. + +[heading Description] +On first use, this instantiates a default std\u005fthread\u005fpool running [^`BOOST_AFIO_MAX_NON_ASYNC_QUEUE_DEPTH`] threads which will remain until its shared count reaches zero. + +[heading Synopsis] +``BOOST_AFIO_DECL std::shared_ptr<std_thread_pool> process_threadpool()`` + +[heading Parameters] + +[table +[[Type] [Concept] [Name] [Description] ] +] + + +[heading Header] +`#include <boost/afio/v2/afio.hpp>` + + +'''<?dbhtml-include href="disqus_comments.html"?>''' +[endsect] + diff --git a/attic/doc/generated/group_read.qbk b/attic/doc/generated/group_read.qbk new file mode 100644 index 00000000..379e0605 --- /dev/null +++ b/attic/doc/generated/group_read.qbk @@ -0,0 +1,272 @@ +[/============================================================================ + Boost.AFIO + + Use, modification and distribution is subject to the Boost Software License, + Version 1.0. (See accompanying file LICENSE_1_0.txt or copy at + http://www.boost.org/LICENSE_1_0.txt) +=============================================================================/] + + +[/ Generated by doxygen_xml2qbk 1.1.1, don't change, will be overwritten automatically] +[/ Generated from doxy/doxygen_output/xml\group__read.xml] +[section:read_1_batch read (batch)] +'''<?dbhtml-include href="disqus_identifiers/read_1_batch.html"?>''' + +'''<indexterm><primary>read</primary></indexterm>''' +Schedule a batch of asynchronous data reads after preceding operations, where offset and total data read must not exceed the present file size. + +[heading Description] +Related types: [^`__afio_io_req__`] Note that on Windows this call issues a separate async file operation for each buffer supplied, thus making scatter/gather i/o no more efficient than making separate calls. The big exception to this is when doing unbuffered page aligned i/o for which Windows provides special scatter/gather i/o functions. You should therefore assume that only each buffer is atomically read or written rather than the full sequence of buffers at once (this also applies to POSIX systems without the preadv()/pwritev() operations). + +[heading Synopsis] +``template<class T> +virtual std::vector<future<> > dispatcher::read(const std::vector< io_req< T >> & ops)`` + +[heading Parameters] + +[table +[[Type] [Concept] [Name] [Description] ] +[[class T] [Any type. ] [ - ] [Must be specified]] +[[const std::vector< io_req< T >> &] [] [ops] [A batch of io_req<T> structures.]] +] + + +[heading Returns] +A batch of op handles. + +[heading Header] +`#include <boost/afio/v2/afio.hpp>` + +[heading Complexity]Amortised O(N) to dispatch. Amortised O(N/threadpool) to complete if reading data is constant time. +[heading Exception Model]Propagates exceptions of any input preconditions with an errored state at the point of dispatch, and throws a `std::invalid_argument` if any inputs have values which could not possibly be correct. Once a batch of input ops has been verified at the point of entry as not errored, you are guaranteed that the batch is atomically scheduled as a whole, unless a failure to allocate memory occurs. +[heading Example][readwrite_example] + + +'''<?dbhtml-include href="disqus_comments.html"?>''' +[endsect] + +[section:async_read_3_length_deducing async_read (length deducing)] +'''<?dbhtml-include href="disqus_identifiers/async_read_3_length_deducing.html"?>''' + +'''<indexterm><primary>async_read</primary></indexterm>''' +Asynchronous data read after a preceding operation, where offset and total data read must not exceed the present file size. + +[heading Description] +Related types: [^`__afio_io_req__`] Note that on Windows this call issues a separate async file operation for each buffer supplied, thus making scatter/gather i/o no more efficient than making separate calls. The big exception to this is when doing unbuffered page aligned i/o for which Windows provides special scatter/gather i/o functions. You should therefore assume that only each buffer is atomically read or written rather than the full sequence of buffers at once (this also applies to POSIX systems without the preadv()/pwritev() operations). + +[heading Synopsis] +``template<class T> +future async_read(future<> _precondition, T && v, off_t _where)`` + +[heading Parameters] + +[table +[[Type] [Concept] [Name] [Description] ] +[[class T] [Any type. ] [ - ] [Must be specified]] +[[future<>] [] [_precondition] [The precondition to use. ]] +[[T &&] [] [v] [Some item understood by [^`to_asio_buffers()`]]] +[[off_t] [] [_where] [The file offset to do the i/o]] +] + + +[heading Returns] +A future<void> + +[heading Header] +`#include <boost/afio/v2/afio.hpp>` + +[heading Complexity]Amortised O(1) to dispatch. Amortised O(1) to complete if reading data is constant time. +[heading Exception Model]Propagates the exception of any input precondition with an errored state at the point of dispatch, and throws a `std::invalid_argument` if any inputs have values which could not possibly be correct. Note that error code returning functions may still throw exceptions e.g. failure to allocate memory. +[heading Example][readwrite_example] + + +'''<?dbhtml-include href="disqus_comments.html"?>''' +[endsect] + +[section:async_read_4_length_specifying async_read (length specifying)] +'''<?dbhtml-include href="disqus_identifiers/async_read_4_length_specifying.html"?>''' + +'''<indexterm><primary>async_read</primary></indexterm>''' +Asynchronous data read after a preceding operation, where offset and total data read must not exceed the present file size. + +[heading Description] +Related types: [^`__afio_io_req__`] Note that on Windows this call issues a separate async file operation for each buffer supplied, thus making scatter/gather i/o no more efficient than making separate calls. The big exception to this is when doing unbuffered page aligned i/o for which Windows provides special scatter/gather i/o functions. You should therefore assume that only each buffer is atomically read or written rather than the full sequence of buffers at once (this also applies to POSIX systems without the preadv()/pwritev() operations). + +[heading Synopsis] +``template<class T> +future async_read(future<> _precondition, T && v, size_t _length, + off_t _where)`` + +[heading Parameters] + +[table +[[Type] [Concept] [Name] [Description] ] +[[class T] [Any type. ] [ - ] [Must be specified]] +[[future<>] [] [_precondition] [The precondition to use. ]] +[[T &&] [] [v] [Some item understood by [^`to_asio_buffers()`]]] +[[size_t] [] [_length] [The length of the item ]] +[[off_t] [] [_where] [The file offset to do the i/o]] +] + + +[heading Returns] +A future<void> + +[heading Header] +`#include <boost/afio/v2/afio.hpp>` + +[heading Complexity]Amortised O(1) to dispatch. Amortised O(1) to complete if reading data is constant time. +[heading Exception Model]Propagates the exception of any input precondition with an errored state at the point of dispatch, and throws a `std::invalid_argument` if any inputs have values which could not possibly be correct. Note that error code returning functions may still throw exceptions e.g. failure to allocate memory. +[heading Example][readwrite_example] + + +'''<?dbhtml-include href="disqus_comments.html"?>''' +[endsect] + +[section:read_3_length_deducing_throwing read (length deducing throwing)] +'''<?dbhtml-include href="disqus_identifiers/read_3_length_deducing_throwing.html"?>''' + +'''<indexterm><primary>read</primary></indexterm>''' +Synchronous data read after a preceding operation, where offset and total data read must not exceed the present file size. + +[heading Description] +Related types: [^`__afio_io_req__`] Note that on Windows this call issues a separate async file operation for each buffer supplied, thus making scatter/gather i/o no more efficient than making separate calls. The big exception to this is when doing unbuffered page aligned i/o for which Windows provides special scatter/gather i/o functions. You should therefore assume that only each buffer is atomically read or written rather than the full sequence of buffers at once (this also applies to POSIX systems without the preadv()/pwritev() operations). + +[heading Synopsis] +``template<class T> +void read(future<> _precondition, T && v, off_t _where)`` + +[heading Parameters] + +[table +[[Type] [Concept] [Name] [Description] ] +[[class T] [Any type. ] [ - ] [Must be specified]] +[[future<>] [] [_precondition] [The precondition to use. ]] +[[T &&] [] [v] [Some item understood by [^`to_asio_buffers()`]]] +[[off_t] [] [_where] [The file offset to do the i/o]] +] + + +[heading Header] +`#include <boost/afio/v2/afio.hpp>` + +[heading Complexity]Amortised O(1) to dispatch. Amortised O(1) to complete if reading data is constant time. +[heading Exception Model]Propagates the exception of any input precondition with an errored state at the point of dispatch, and throws a `std::invalid_argument` if any inputs have values which could not possibly be correct. Note that error code returning functions may still throw exceptions e.g. failure to allocate memory. +[heading Example][readwrite_example] + + +'''<?dbhtml-include href="disqus_comments.html"?>''' +[endsect] + +[section:read_4_length_specifying_throwing read (length specifying throwing)] +'''<?dbhtml-include href="disqus_identifiers/read_4_length_specifying_throwing.html"?>''' + +'''<indexterm><primary>read</primary></indexterm>''' +Synchronous data read after a preceding operation, where offset and total data read must not exceed the present file size. + +[heading Description] +Related types: [^`__afio_io_req__`] Note that on Windows this call issues a separate async file operation for each buffer supplied, thus making scatter/gather i/o no more efficient than making separate calls. The big exception to this is when doing unbuffered page aligned i/o for which Windows provides special scatter/gather i/o functions. You should therefore assume that only each buffer is atomically read or written rather than the full sequence of buffers at once (this also applies to POSIX systems without the preadv()/pwritev() operations). + +[heading Synopsis] +``template<class T> +void read(future<> _precondition, T && v, size_t _length, + off_t _where)`` + +[heading Parameters] + +[table +[[Type] [Concept] [Name] [Description] ] +[[class T] [Any type. ] [ - ] [Must be specified]] +[[future<>] [] [_precondition] [The precondition to use. ]] +[[T &&] [] [v] [Some item understood by [^`to_asio_buffers()`]]] +[[size_t] [] [_length] [The length of the item ]] +[[off_t] [] [_where] [The file offset to do the i/o]] +] + + +[heading Header] +`#include <boost/afio/v2/afio.hpp>` + +[heading Complexity]Amortised O(1) to dispatch. Amortised O(1) to complete if reading data is constant time. +[heading Exception Model]Propagates the exception of any input precondition with an errored state at the point of dispatch, and throws a `std::invalid_argument` if any inputs have values which could not possibly be correct. Note that error code returning functions may still throw exceptions e.g. failure to allocate memory. +[heading Example][readwrite_example] + + +'''<?dbhtml-include href="disqus_comments.html"?>''' +[endsect] + +[section:read_4_length_deducing_non_throwing read (length deducing non throwing)] +'''<?dbhtml-include href="disqus_identifiers/read_4_length_deducing_non_throwing.html"?>''' + +'''<indexterm><primary>read</primary></indexterm>''' +Synchronous data read after a preceding operation, where offset and total data read must not exceed the present file size. + +[heading Description] +Related types: [^`__afio_io_req__`] Note that on Windows this call issues a separate async file operation for each buffer supplied, thus making scatter/gather i/o no more efficient than making separate calls. The big exception to this is when doing unbuffered page aligned i/o for which Windows provides special scatter/gather i/o functions. You should therefore assume that only each buffer is atomically read or written rather than the full sequence of buffers at once (this also applies to POSIX systems without the preadv()/pwritev() operations). + +[heading Synopsis] +``template<class T> +void read(error_code & _ec, future<> _precondition, T && v, + off_t _where)`` + +[heading Parameters] + +[table +[[Type] [Concept] [Name] [Description] ] +[[class T] [Any type. ] [ - ] [Must be specified]] +[[error_code &] [] [_ec] [Error code to set. ]] +[[future<>] [] [_precondition] [The precondition to use. ]] +[[T &&] [] [v] [Some item understood by [^`to_asio_buffers()`]]] +[[off_t] [] [_where] [The file offset to do the i/o]] +] + + +[heading Header] +`#include <boost/afio/v2/afio.hpp>` + +[heading Complexity]Amortised O(1) to dispatch. Amortised O(1) to complete if reading data is constant time. +[heading Exception Model]Propagates the exception of any input precondition with an errored state at the point of dispatch, and throws a `std::invalid_argument` if any inputs have values which could not possibly be correct. Note that error code returning functions may still throw exceptions e.g. failure to allocate memory. +[heading Example][readwrite_example] + + +'''<?dbhtml-include href="disqus_comments.html"?>''' +[endsect] + +[section:read_5_length_specifying_non_throwing read (length specifying non throwing)] +'''<?dbhtml-include href="disqus_identifiers/read_5_length_specifying_non_throwing.html"?>''' + +'''<indexterm><primary>read</primary></indexterm>''' +Synchronous data read after a preceding operation, where offset and total data read must not exceed the present file size. + +[heading Description] +Related types: [^`__afio_io_req__`] Note that on Windows this call issues a separate async file operation for each buffer supplied, thus making scatter/gather i/o no more efficient than making separate calls. The big exception to this is when doing unbuffered page aligned i/o for which Windows provides special scatter/gather i/o functions. You should therefore assume that only each buffer is atomically read or written rather than the full sequence of buffers at once (this also applies to POSIX systems without the preadv()/pwritev() operations). + +[heading Synopsis] +``template<class T> +void read(error_code & _ec, future<> _precondition, T && v, + size_t _length, off_t _where)`` + +[heading Parameters] + +[table +[[Type] [Concept] [Name] [Description] ] +[[class T] [Any type. ] [ - ] [Must be specified]] +[[error_code &] [] [_ec] [Error code to set. ]] +[[future<>] [] [_precondition] [The precondition to use. ]] +[[T &&] [] [v] [Some item understood by [^`to_asio_buffers()`]]] +[[size_t] [] [_length] [The length of the item ]] +[[off_t] [] [_where] [The file offset to do the i/o]] +] + + +[heading Header] +`#include <boost/afio/v2/afio.hpp>` + +[heading Complexity]Amortised O(1) to dispatch. Amortised O(1) to complete if reading data is constant time. +[heading Exception Model]Propagates the exception of any input precondition with an errored state at the point of dispatch, and throws a `std::invalid_argument` if any inputs have values which could not possibly be correct. Note that error code returning functions may still throw exceptions e.g. failure to allocate memory. +[heading Example][readwrite_example] + + +'''<?dbhtml-include href="disqus_comments.html"?>''' +[endsect] + diff --git a/attic/doc/generated/group_rmdir.qbk b/attic/doc/generated/group_rmdir.qbk new file mode 100644 index 00000000..4944d1a3 --- /dev/null +++ b/attic/doc/generated/group_rmdir.qbk @@ -0,0 +1,293 @@ +[/============================================================================ + Boost.AFIO + + Use, modification and distribution is subject to the Boost Software License, + Version 1.0. (See accompanying file LICENSE_1_0.txt or copy at + http://www.boost.org/LICENSE_1_0.txt) +=============================================================================/] + + +[/ Generated by doxygen_xml2qbk 1.1.1, don't change, will be overwritten automatically] +[/ Generated from doxy/doxygen_output/xml\group__rmdir.xml] +[section:rmdir_1_batch rmdir (batch)] +'''<?dbhtml-include href="disqus_identifiers/rmdir_1_batch.html"?>''' + +'''<indexterm><primary>rmdir</primary></indexterm>''' +Schedule a batch of asynchronous directory deletions after optional preconditions. + +[heading Description] +Make sure you read the docs for [^`__afio_handle__::unlink()`] for important caveats. Note that on operating systems with an unstable [^`__afio_handle__::path(true)`] you need to be cautious of deleting files by handle as any hard link to that file may be deleted instead of the one you intended. To work around this, portable code should delete by directory handle as the precondition and known leafname. Related types: [^`__afio_path_req__`] Be aware that on Windows AFIO operates exclusively in the NT kernel namespace, NOT the Win32 namespace, and therefore paths you supply are converted by [^`afio::path`] in NT kernel namespace paths. [^`normalise_path()`] can convert an afio path back to a Filesystem TS path for you, but note that this may not be the path that was supplied originally. NT kernel namespace paths have a 32,767 character limit and an almost POSIX like lack of restrictions on naming or historical behaviour quirks, but as a result AFIO does not support DOS short names or any of the other historical Win32 filing system baggage. + +[heading Synopsis] +``future dispatcher::rmdir(const std::vector< path_req > & reqs)`` + +[heading Parameters] + +[table +[[Type] [Concept] [Name] [Description] ] +[[const std::vector< path_req > &] [] [reqs] [A batch of [^`path_req`] structures.]] +] + + +[heading Returns] +A batch of op handles. + +[heading Header] +`#include <boost/afio/v2/afio.hpp>` + +[heading Race Guarantees][raceguarantees +[raceguarantee FreeBSD, Linux..Race free up to the containing directory.] +[raceguarantee Windows..Race free if handle open, else up to the containing directory.] +[raceguarantee OS X..No guarantees.] + ] +[heading Complexity]Amortised O(N) to dispatch. Amortised O(N/threadpool) to complete if directory deletion is constant time. +[heading Exception Model]Propagates exceptions of any input preconditions with an errored state at the point of dispatch, and throws a `std::invalid_argument` if any inputs have values which could not possibly be correct. Once a batch of input ops has been verified at the point of entry as not errored, you are guaranteed that the batch is atomically scheduled as a whole, unless a failure to allocate memory occurs. +[heading Example][filedir_example] + + +'''<?dbhtml-include href="disqus_comments.html"?>''' +[endsect] + +[section:async_rmdir_3_relative async_rmdir (relative)] +'''<?dbhtml-include href="disqus_identifiers/async_rmdir_3_relative.html"?>''' + +'''<indexterm><primary>async_rmdir</primary></indexterm>''' +Asynchronous directory deletion after an optional precondition. + +[heading Description] +Make sure you read the docs for [^`__afio_handle__::unlink()`] for important caveats. Note that on operating systems with an unstable [^`__afio_handle__::path(true)`] you need to be cautious of deleting files by handle as any hard link to that file may be deleted instead of the one you intended. To work around this, portable code should delete by directory handle as the precondition and known leafname. Related types: [^`__afio_path_req__`] Be aware that on Windows AFIO operates exclusively in the NT kernel namespace, NOT the Win32 namespace, and therefore paths you supply are converted by [^`afio::path`] in NT kernel namespace paths. [^`normalise_path()`] can convert an afio path back to a Filesystem TS path for you, but note that this may not be the path that was supplied originally. NT kernel namespace paths have a 32,767 character limit and an almost POSIX like lack of restrictions on naming or historical behaviour quirks, but as a result AFIO does not support DOS short names or any of the other historical Win32 filing system baggage. + +[heading Synopsis] +``template<class T> +future async_rmdir(future<> _precondition, T _path = path(), file_flags _flags = file_flags::none)`` + +[heading Parameters] + +[table +[[Type] [Concept] [Name] [Description] ] +[[class T] [The type of path to use. ] [ - ] [Must be specified]] +[[future<>] [] [_precondition] [The precondition to use. ]] +[[T] [] [_path] [The filing system path to use. ]] +[[file_flags] [] [_flags] [The flags to use.]] +] + + +[heading Returns] +A future<void> + +[heading Header] +`#include <boost/afio/v2/afio.hpp>` + +[heading Race Guarantees][raceguarantees +[raceguarantee FreeBSD, Linux..Race free up to the containing directory.] +[raceguarantee Windows..Race free if handle open, else up to the containing directory.] +[raceguarantee OS X..No guarantees.] + ] +[heading Complexity]Amortised O(1) to dispatch. Amortised O(1) to complete if directory deletion is constant time. +[heading Exception Model]Propagates the exception of any input precondition with an errored state at the point of dispatch, and throws a `std::invalid_argument` if any inputs have values which could not possibly be correct. Note that error code returning functions may still throw exceptions e.g. failure to allocate memory. +[heading Example][filedir_example] + + +'''<?dbhtml-include href="disqus_comments.html"?>''' +[endsect] + +[section:async_rmdir_2_absolute async_rmdir (absolute)] +'''<?dbhtml-include href="disqus_identifiers/async_rmdir_2_absolute.html"?>''' + +'''<indexterm><primary>async_rmdir</primary></indexterm>''' +Asynchronous directory deletion after an optional precondition. + +[heading Description] +Make sure you read the docs for [^`__afio_handle__::unlink()`] for important caveats. Note that on operating systems with an unstable [^`__afio_handle__::path(true)`] you need to be cautious of deleting files by handle as any hard link to that file may be deleted instead of the one you intended. To work around this, portable code should delete by directory handle as the precondition and known leafname. Related types: [^`__afio_path_req__`] Be aware that on Windows AFIO operates exclusively in the NT kernel namespace, NOT the Win32 namespace, and therefore paths you supply are converted by [^`afio::path`] in NT kernel namespace paths. [^`normalise_path()`] can convert an afio path back to a Filesystem TS path for you, but note that this may not be the path that was supplied originally. NT kernel namespace paths have a 32,767 character limit and an almost POSIX like lack of restrictions on naming or historical behaviour quirks, but as a result AFIO does not support DOS short names or any of the other historical Win32 filing system baggage. + +[heading Synopsis] +``template<class T, typename> +future async_rmdir(T _path, file_flags _flags = file_flags::none)`` + +[heading Parameters] + +[table +[[Type] [Concept] [Name] [Description] ] +[[class T] [The type of path to use. ] [ - ] [Must be specified]] +[[] [] [ - ] [Must be specified]] +[[T] [] [_path] [The filing system path to use. ]] +[[file_flags] [] [_flags] [The flags to use.]] +] + + +[heading Returns] +A future<void> + +[heading Header] +`#include <boost/afio/v2/afio.hpp>` + +[heading Race Guarantees][raceguarantees +[raceguarantee FreeBSD, Linux, OS X, Windows..No guarantees.] + ] +[heading Complexity]Amortised O(1) to dispatch. Amortised O(1) to complete if directory deletion is constant time. +[heading Exception Model]Propagates the exception of any input precondition with an errored state at the point of dispatch, and throws a `std::invalid_argument` if any inputs have values which could not possibly be correct. Note that error code returning functions may still throw exceptions e.g. failure to allocate memory. +[heading Example][filedir_example] + + +'''<?dbhtml-include href="disqus_comments.html"?>''' +[endsect] + +[section:rmdir_3_relative_throwing rmdir (relative throwing)] +'''<?dbhtml-include href="disqus_identifiers/rmdir_3_relative_throwing.html"?>''' + +'''<indexterm><primary>rmdir</primary></indexterm>''' +Synchronous directory deletion after an optional precondition. + +[heading Description] +Make sure you read the docs for [^`__afio_handle__::unlink()`] for important caveats. Note that on operating systems with an unstable [^`__afio_handle__::path(true)`] you need to be cautious of deleting files by handle as any hard link to that file may be deleted instead of the one you intended. To work around this, portable code should delete by directory handle as the precondition and known leafname. Related types: [^`__afio_path_req__`] Be aware that on Windows AFIO operates exclusively in the NT kernel namespace, NOT the Win32 namespace, and therefore paths you supply are converted by [^`afio::path`] in NT kernel namespace paths. [^`normalise_path()`] can convert an afio path back to a Filesystem TS path for you, but note that this may not be the path that was supplied originally. NT kernel namespace paths have a 32,767 character limit and an almost POSIX like lack of restrictions on naming or historical behaviour quirks, but as a result AFIO does not support DOS short names or any of the other historical Win32 filing system baggage. + +[heading Synopsis] +``template<class T> +void rmdir(future<> _precondition, T _path = path(), file_flags _flags = file_flags::none)`` + +[heading Parameters] + +[table +[[Type] [Concept] [Name] [Description] ] +[[class T] [The type of path to use. ] [ - ] [Must be specified]] +[[future<>] [] [_precondition] [The precondition to use. ]] +[[T] [] [_path] [The filing system path to use. ]] +[[file_flags] [] [_flags] [The flags to use.]] +] + + +[heading Header] +`#include <boost/afio/v2/afio.hpp>` + +[heading Race Guarantees][raceguarantees +[raceguarantee FreeBSD, Linux..Race free up to the containing directory.] +[raceguarantee Windows..Race free if handle open, else up to the containing directory.] +[raceguarantee OS X..No guarantees.] + ] +[heading Complexity]Amortised O(1) to dispatch. Amortised O(1) to complete if directory deletion is constant time. +[heading Exception Model]Propagates the exception of any input precondition with an errored state at the point of dispatch, and throws a `std::invalid_argument` if any inputs have values which could not possibly be correct. Note that error code returning functions may still throw exceptions e.g. failure to allocate memory. +[heading Example][filedir_example] + + +'''<?dbhtml-include href="disqus_comments.html"?>''' +[endsect] + +[section:rmdir_2_absolute_throwing rmdir (absolute throwing)] +'''<?dbhtml-include href="disqus_identifiers/rmdir_2_absolute_throwing.html"?>''' + +'''<indexterm><primary>rmdir</primary></indexterm>''' +Synchronous directory deletion after an optional precondition. + +[heading Description] +Make sure you read the docs for [^`__afio_handle__::unlink()`] for important caveats. Note that on operating systems with an unstable [^`__afio_handle__::path(true)`] you need to be cautious of deleting files by handle as any hard link to that file may be deleted instead of the one you intended. To work around this, portable code should delete by directory handle as the precondition and known leafname. Related types: [^`__afio_path_req__`] Be aware that on Windows AFIO operates exclusively in the NT kernel namespace, NOT the Win32 namespace, and therefore paths you supply are converted by [^`afio::path`] in NT kernel namespace paths. [^`normalise_path()`] can convert an afio path back to a Filesystem TS path for you, but note that this may not be the path that was supplied originally. NT kernel namespace paths have a 32,767 character limit and an almost POSIX like lack of restrictions on naming or historical behaviour quirks, but as a result AFIO does not support DOS short names or any of the other historical Win32 filing system baggage. + +[heading Synopsis] +``template<class T, typename> +void rmdir(T _path, file_flags _flags = file_flags::none)`` + +[heading Parameters] + +[table +[[Type] [Concept] [Name] [Description] ] +[[class T] [The type of path to use. ] [ - ] [Must be specified]] +[[] [] [ - ] [Must be specified]] +[[T] [] [_path] [The filing system path to use. ]] +[[file_flags] [] [_flags] [The flags to use.]] +] + + +[heading Header] +`#include <boost/afio/v2/afio.hpp>` + +[heading Race Guarantees][raceguarantees +[raceguarantee FreeBSD, Linux, OS X, Windows..No guarantees.] + ] +[heading Complexity]Amortised O(1) to dispatch. Amortised O(1) to complete if directory deletion is constant time. +[heading Exception Model]Propagates the exception of any input precondition with an errored state at the point of dispatch, and throws a `std::invalid_argument` if any inputs have values which could not possibly be correct. Note that error code returning functions may still throw exceptions e.g. failure to allocate memory. +[heading Example][filedir_example] + + +'''<?dbhtml-include href="disqus_comments.html"?>''' +[endsect] + +[section:rmdir_4_relative_non_throwing rmdir (relative non throwing)] +'''<?dbhtml-include href="disqus_identifiers/rmdir_4_relative_non_throwing.html"?>''' + +'''<indexterm><primary>rmdir</primary></indexterm>''' +Synchronous directory deletion after an optional precondition. + +[heading Description] +Make sure you read the docs for [^`__afio_handle__::unlink()`] for important caveats. Note that on operating systems with an unstable [^`__afio_handle__::path(true)`] you need to be cautious of deleting files by handle as any hard link to that file may be deleted instead of the one you intended. To work around this, portable code should delete by directory handle as the precondition and known leafname. Related types: [^`__afio_path_req__`] Be aware that on Windows AFIO operates exclusively in the NT kernel namespace, NOT the Win32 namespace, and therefore paths you supply are converted by [^`afio::path`] in NT kernel namespace paths. [^`normalise_path()`] can convert an afio path back to a Filesystem TS path for you, but note that this may not be the path that was supplied originally. NT kernel namespace paths have a 32,767 character limit and an almost POSIX like lack of restrictions on naming or historical behaviour quirks, but as a result AFIO does not support DOS short names or any of the other historical Win32 filing system baggage. + +[heading Synopsis] +``template<class T> +void rmdir(error_code & _ec, future<> _precondition, T _path = path(), + file_flags _flags = file_flags::none)`` + +[heading Parameters] + +[table +[[Type] [Concept] [Name] [Description] ] +[[class T] [The type of path to use. ] [ - ] [Must be specified]] +[[error_code &] [] [_ec] [Error code to set. ]] +[[future<>] [] [_precondition] [The precondition to use. ]] +[[T] [] [_path] [The filing system path to use. ]] +[[file_flags] [] [_flags] [The flags to use.]] +] + + +[heading Header] +`#include <boost/afio/v2/afio.hpp>` + +[heading Race Guarantees][raceguarantees +[raceguarantee FreeBSD, Linux..Race free up to the containing directory.] +[raceguarantee Windows..Race free if handle open, else up to the containing directory.] +[raceguarantee OS X..No guarantees.] + ] +[heading Complexity]Amortised O(1) to dispatch. Amortised O(1) to complete if directory deletion is constant time. +[heading Exception Model]Propagates the exception of any input precondition with an errored state at the point of dispatch, and throws a `std::invalid_argument` if any inputs have values which could not possibly be correct. Note that error code returning functions may still throw exceptions e.g. failure to allocate memory. +[heading Example][filedir_example] + + +'''<?dbhtml-include href="disqus_comments.html"?>''' +[endsect] + +[section:rmdir_3_absolute_non_throwing rmdir (absolute non throwing)] +'''<?dbhtml-include href="disqus_identifiers/rmdir_3_absolute_non_throwing.html"?>''' + +'''<indexterm><primary>rmdir</primary></indexterm>''' +Synchronous directory deletion after an optional precondition. + +[heading Description] +Make sure you read the docs for [^`__afio_handle__::unlink()`] for important caveats. Note that on operating systems with an unstable [^`__afio_handle__::path(true)`] you need to be cautious of deleting files by handle as any hard link to that file may be deleted instead of the one you intended. To work around this, portable code should delete by directory handle as the precondition and known leafname. Related types: [^`__afio_path_req__`] Be aware that on Windows AFIO operates exclusively in the NT kernel namespace, NOT the Win32 namespace, and therefore paths you supply are converted by [^`afio::path`] in NT kernel namespace paths. [^`normalise_path()`] can convert an afio path back to a Filesystem TS path for you, but note that this may not be the path that was supplied originally. NT kernel namespace paths have a 32,767 character limit and an almost POSIX like lack of restrictions on naming or historical behaviour quirks, but as a result AFIO does not support DOS short names or any of the other historical Win32 filing system baggage. + +[heading Synopsis] +``template<class T, typename> +void rmdir(error_code & _ec, T _path, file_flags _flags = file_flags::none)`` + +[heading Parameters] + +[table +[[Type] [Concept] [Name] [Description] ] +[[class T] [The type of path to use. ] [ - ] [Must be specified]] +[[] [] [ - ] [Must be specified]] +[[error_code &] [] [_ec] [Error code to set. ]] +[[T] [] [_path] [The filing system path to use. ]] +[[file_flags] [] [_flags] [The flags to use.]] +] + + +[heading Header] +`#include <boost/afio/v2/afio.hpp>` + +[heading Race Guarantees][raceguarantees +[raceguarantee FreeBSD, Linux, OS X, Windows..No guarantees.] + ] +[heading Complexity]Amortised O(1) to dispatch. Amortised O(1) to complete if directory deletion is constant time. +[heading Exception Model]Propagates the exception of any input precondition with an errored state at the point of dispatch, and throws a `std::invalid_argument` if any inputs have values which could not possibly be correct. Note that error code returning functions may still throw exceptions e.g. failure to allocate memory. +[heading Example][filedir_example] + + +'''<?dbhtml-include href="disqus_comments.html"?>''' +[endsect] + diff --git a/attic/doc/generated/group_rmfile.qbk b/attic/doc/generated/group_rmfile.qbk new file mode 100644 index 00000000..1abcd92e --- /dev/null +++ b/attic/doc/generated/group_rmfile.qbk @@ -0,0 +1,293 @@ +[/============================================================================ + Boost.AFIO + + Use, modification and distribution is subject to the Boost Software License, + Version 1.0. (See accompanying file LICENSE_1_0.txt or copy at + http://www.boost.org/LICENSE_1_0.txt) +=============================================================================/] + + +[/ Generated by doxygen_xml2qbk 1.1.1, don't change, will be overwritten automatically] +[/ Generated from doxy/doxygen_output/xml\group__rmfile.xml] +[section:rmfile_1_batch rmfile (batch)] +'''<?dbhtml-include href="disqus_identifiers/rmfile_1_batch.html"?>''' + +'''<indexterm><primary>rmfile</primary></indexterm>''' +Schedule a batch of asynchronous file deletions after optional preconditions. + +[heading Description] +Note that you can delete files before they are closed on Windows just as with POSIX if and only if all open handles to that file were opened with permission for the file to be deleted (AFIO always sets this). The actual file data will be deleted when the last handle is closed on the system. Make sure you read the docs for [^`__afio_handle__::unlink()`] for important caveats. Note that on operating systems with an unstable [^`__afio_handle__::path(true)`] you need to be cautious of deleting files by handle as any hard link to that file may be deleted instead of the one you intended. To work around this, portable code should delete by directory handle as the precondition and known leafname. Related types: [^`__afio_path_req__`] Be aware that on Windows AFIO operates exclusively in the NT kernel namespace, NOT the Win32 namespace, and therefore paths you supply are converted by [^`afio::path`] in NT kernel namespace paths. [^`normalise_path()`] can convert an afio path back to a Filesystem TS path for you, but note that this may not be the path that was supplied originally. NT kernel namespace paths have a 32,767 character limit and an almost POSIX like lack of restrictions on naming or historical behaviour quirks, but as a result AFIO does not support DOS short names or any of the other historical Win32 filing system baggage. + +[heading Synopsis] +``future dispatcher::rmfile(const std::vector< path_req > & reqs)`` + +[heading Parameters] + +[table +[[Type] [Concept] [Name] [Description] ] +[[const std::vector< path_req > &] [] [reqs] [A batch of [^`path_req`] structures.]] +] + + +[heading Returns] +A batch of op handles. + +[heading Header] +`#include <boost/afio/v2/afio.hpp>` + +[heading Race Guarantees][raceguarantees +[raceguarantee FreeBSD, Linux..Race free up to the containing directory.] +[raceguarantee Windows..Race free if handle open, else up to the containing directory.] +[raceguarantee OS X..No guarantees.] + ] +[heading Complexity]Amortised O(N) to dispatch. Amortised O(N/threadpool) to complete if file deletion is constant time. +[heading Exception Model]Propagates exceptions of any input preconditions with an errored state at the point of dispatch, and throws a `std::invalid_argument` if any inputs have values which could not possibly be correct. Once a batch of input ops has been verified at the point of entry as not errored, you are guaranteed that the batch is atomically scheduled as a whole, unless a failure to allocate memory occurs. +[heading Example][filedir_example] + + +'''<?dbhtml-include href="disqus_comments.html"?>''' +[endsect] + +[section:async_rmfile_3_relative async_rmfile (relative)] +'''<?dbhtml-include href="disqus_identifiers/async_rmfile_3_relative.html"?>''' + +'''<indexterm><primary>async_rmfile</primary></indexterm>''' +Asynchronous file deletion after an optional precondition. + +[heading Description] +Note that you can delete files before they are closed on Windows just as with POSIX if and only if all open handles to that file were opened with permission for the file to be deleted (AFIO always sets this). The actual file data will be deleted when the last handle is closed on the system. Make sure you read the docs for [^`__afio_handle__::unlink()`] for important caveats. Note that on operating systems with an unstable [^`__afio_handle__::path(true)`] you need to be cautious of deleting files by handle as any hard link to that file may be deleted instead of the one you intended. To work around this, portable code should delete by directory handle as the precondition and known leafname. Related types: [^`__afio_path_req__`] Be aware that on Windows AFIO operates exclusively in the NT kernel namespace, NOT the Win32 namespace, and therefore paths you supply are converted by [^`afio::path`] in NT kernel namespace paths. [^`normalise_path()`] can convert an afio path back to a Filesystem TS path for you, but note that this may not be the path that was supplied originally. NT kernel namespace paths have a 32,767 character limit and an almost POSIX like lack of restrictions on naming or historical behaviour quirks, but as a result AFIO does not support DOS short names or any of the other historical Win32 filing system baggage. + +[heading Synopsis] +``template<class T> +future async_rmfile(future<> _precondition, T _path = path(), file_flags _flags = file_flags::none)`` + +[heading Parameters] + +[table +[[Type] [Concept] [Name] [Description] ] +[[class T] [The type of path to be used. ] [ - ] [Must be specified]] +[[future<>] [] [_precondition] [The precondition to use. ]] +[[T] [] [_path] [The filing system path to be used. ]] +[[file_flags] [] [_flags] [The flags to be used.]] +] + + +[heading Returns] +A future<void> + +[heading Header] +`#include <boost/afio/v2/afio.hpp>` + +[heading Race Guarantees][raceguarantees +[raceguarantee FreeBSD, Linux..Race free up to the containing directory.] +[raceguarantee Windows..Race free if handle open, else up to the containing directory.] +[raceguarantee OS X..No guarantees.] + ] +[heading Complexity]Amortised O(1) to dispatch. Amortised O(1) to complete if file deletion is constant time. +[heading Exception Model]Propagates the exception of any input precondition with an errored state at the point of dispatch, and throws a `std::invalid_argument` if any inputs have values which could not possibly be correct. Note that error code returning functions may still throw exceptions e.g. failure to allocate memory. +[heading Example][filedir_example] + + +'''<?dbhtml-include href="disqus_comments.html"?>''' +[endsect] + +[section:async_rmfile_2_absolute async_rmfile (absolute)] +'''<?dbhtml-include href="disqus_identifiers/async_rmfile_2_absolute.html"?>''' + +'''<indexterm><primary>async_rmfile</primary></indexterm>''' +Asynchronous file deletion after an optional precondition. + +[heading Description] +Note that you can delete files before they are closed on Windows just as with POSIX if and only if all open handles to that file were opened with permission for the file to be deleted (AFIO always sets this). The actual file data will be deleted when the last handle is closed on the system. Make sure you read the docs for [^`__afio_handle__::unlink()`] for important caveats. Note that on operating systems with an unstable [^`__afio_handle__::path(true)`] you need to be cautious of deleting files by handle as any hard link to that file may be deleted instead of the one you intended. To work around this, portable code should delete by directory handle as the precondition and known leafname. Related types: [^`__afio_path_req__`] Be aware that on Windows AFIO operates exclusively in the NT kernel namespace, NOT the Win32 namespace, and therefore paths you supply are converted by [^`afio::path`] in NT kernel namespace paths. [^`normalise_path()`] can convert an afio path back to a Filesystem TS path for you, but note that this may not be the path that was supplied originally. NT kernel namespace paths have a 32,767 character limit and an almost POSIX like lack of restrictions on naming or historical behaviour quirks, but as a result AFIO does not support DOS short names or any of the other historical Win32 filing system baggage. + +[heading Synopsis] +``template<class T, typename> +future async_rmfile(T _path, file_flags _flags = file_flags::none)`` + +[heading Parameters] + +[table +[[Type] [Concept] [Name] [Description] ] +[[class T] [The type of path to be used. ] [ - ] [Must be specified]] +[[] [] [ - ] [Must be specified]] +[[T] [] [_path] [The filing system path to be used. ]] +[[file_flags] [] [_flags] [The flags to be used.]] +] + + +[heading Returns] +A future<void> + +[heading Header] +`#include <boost/afio/v2/afio.hpp>` + +[heading Race Guarantees][raceguarantees +[raceguarantee FreeBSD, Linux, OS X, Windows..No guarantees.] + ] +[heading Complexity]Amortised O(1) to dispatch. Amortised O(1) to complete if file deletion is constant time. +[heading Exception Model]Propagates the exception of any input precondition with an errored state at the point of dispatch, and throws a `std::invalid_argument` if any inputs have values which could not possibly be correct. Note that error code returning functions may still throw exceptions e.g. failure to allocate memory. +[heading Example][filedir_example] + + +'''<?dbhtml-include href="disqus_comments.html"?>''' +[endsect] + +[section:rmfile_3_relative_throwing rmfile (relative throwing)] +'''<?dbhtml-include href="disqus_identifiers/rmfile_3_relative_throwing.html"?>''' + +'''<indexterm><primary>rmfile</primary></indexterm>''' +Synchronous file deletion after an optional precondition. + +[heading Description] +Note that you can delete files before they are closed on Windows just as with POSIX if and only if all open handles to that file were opened with permission for the file to be deleted (AFIO always sets this). The actual file data will be deleted when the last handle is closed on the system. Make sure you read the docs for [^`__afio_handle__::unlink()`] for important caveats. Note that on operating systems with an unstable [^`__afio_handle__::path(true)`] you need to be cautious of deleting files by handle as any hard link to that file may be deleted instead of the one you intended. To work around this, portable code should delete by directory handle as the precondition and known leafname. Related types: [^`__afio_path_req__`] Be aware that on Windows AFIO operates exclusively in the NT kernel namespace, NOT the Win32 namespace, and therefore paths you supply are converted by [^`afio::path`] in NT kernel namespace paths. [^`normalise_path()`] can convert an afio path back to a Filesystem TS path for you, but note that this may not be the path that was supplied originally. NT kernel namespace paths have a 32,767 character limit and an almost POSIX like lack of restrictions on naming or historical behaviour quirks, but as a result AFIO does not support DOS short names or any of the other historical Win32 filing system baggage. + +[heading Synopsis] +``template<class T> +void rmfile(future<> _precondition, T _path = path(), file_flags _flags = file_flags::none)`` + +[heading Parameters] + +[table +[[Type] [Concept] [Name] [Description] ] +[[class T] [The type of path to be used. ] [ - ] [Must be specified]] +[[future<>] [] [_precondition] [The precondition to use. ]] +[[T] [] [_path] [The filing system path to be used. ]] +[[file_flags] [] [_flags] [The flags to be used.]] +] + + +[heading Header] +`#include <boost/afio/v2/afio.hpp>` + +[heading Race Guarantees][raceguarantees +[raceguarantee FreeBSD, Linux..Race free up to the containing directory.] +[raceguarantee Windows..Race free if handle open, else up to the containing directory.] +[raceguarantee OS X..No guarantees.] + ] +[heading Complexity]Amortised O(1) to dispatch. Amortised O(1) to complete if file deletion is constant time. +[heading Exception Model]Propagates the exception of any input precondition with an errored state at the point of dispatch, and throws a `std::invalid_argument` if any inputs have values which could not possibly be correct. Note that error code returning functions may still throw exceptions e.g. failure to allocate memory. +[heading Example][filedir_example] + + +'''<?dbhtml-include href="disqus_comments.html"?>''' +[endsect] + +[section:rmfile_2_absolute_throwing rmfile (absolute throwing)] +'''<?dbhtml-include href="disqus_identifiers/rmfile_2_absolute_throwing.html"?>''' + +'''<indexterm><primary>rmfile</primary></indexterm>''' +Synchronous file deletion after an optional precondition. + +[heading Description] +Note that you can delete files before they are closed on Windows just as with POSIX if and only if all open handles to that file were opened with permission for the file to be deleted (AFIO always sets this). The actual file data will be deleted when the last handle is closed on the system. Make sure you read the docs for [^`__afio_handle__::unlink()`] for important caveats. Note that on operating systems with an unstable [^`__afio_handle__::path(true)`] you need to be cautious of deleting files by handle as any hard link to that file may be deleted instead of the one you intended. To work around this, portable code should delete by directory handle as the precondition and known leafname. Related types: [^`__afio_path_req__`] Be aware that on Windows AFIO operates exclusively in the NT kernel namespace, NOT the Win32 namespace, and therefore paths you supply are converted by [^`afio::path`] in NT kernel namespace paths. [^`normalise_path()`] can convert an afio path back to a Filesystem TS path for you, but note that this may not be the path that was supplied originally. NT kernel namespace paths have a 32,767 character limit and an almost POSIX like lack of restrictions on naming or historical behaviour quirks, but as a result AFIO does not support DOS short names or any of the other historical Win32 filing system baggage. + +[heading Synopsis] +``template<class T, typename> +void rmfile(T _path, file_flags _flags = file_flags::none)`` + +[heading Parameters] + +[table +[[Type] [Concept] [Name] [Description] ] +[[class T] [The type of path to be used. ] [ - ] [Must be specified]] +[[] [] [ - ] [Must be specified]] +[[T] [] [_path] [The filing system path to be used. ]] +[[file_flags] [] [_flags] [The flags to be used.]] +] + + +[heading Header] +`#include <boost/afio/v2/afio.hpp>` + +[heading Race Guarantees][raceguarantees +[raceguarantee FreeBSD, Linux, OS X, Windows..No guarantees.] + ] +[heading Complexity]Amortised O(1) to dispatch. Amortised O(1) to complete if file deletion is constant time. +[heading Exception Model]Propagates the exception of any input precondition with an errored state at the point of dispatch, and throws a `std::invalid_argument` if any inputs have values which could not possibly be correct. Note that error code returning functions may still throw exceptions e.g. failure to allocate memory. +[heading Example][filedir_example] + + +'''<?dbhtml-include href="disqus_comments.html"?>''' +[endsect] + +[section:rmfile_4_relative_non_throwing rmfile (relative non throwing)] +'''<?dbhtml-include href="disqus_identifiers/rmfile_4_relative_non_throwing.html"?>''' + +'''<indexterm><primary>rmfile</primary></indexterm>''' +Synchronous file deletion after an optional precondition. + +[heading Description] +Note that you can delete files before they are closed on Windows just as with POSIX if and only if all open handles to that file were opened with permission for the file to be deleted (AFIO always sets this). The actual file data will be deleted when the last handle is closed on the system. Make sure you read the docs for [^`__afio_handle__::unlink()`] for important caveats. Note that on operating systems with an unstable [^`__afio_handle__::path(true)`] you need to be cautious of deleting files by handle as any hard link to that file may be deleted instead of the one you intended. To work around this, portable code should delete by directory handle as the precondition and known leafname. Related types: [^`__afio_path_req__`] Be aware that on Windows AFIO operates exclusively in the NT kernel namespace, NOT the Win32 namespace, and therefore paths you supply are converted by [^`afio::path`] in NT kernel namespace paths. [^`normalise_path()`] can convert an afio path back to a Filesystem TS path for you, but note that this may not be the path that was supplied originally. NT kernel namespace paths have a 32,767 character limit and an almost POSIX like lack of restrictions on naming or historical behaviour quirks, but as a result AFIO does not support DOS short names or any of the other historical Win32 filing system baggage. + +[heading Synopsis] +``template<class T> +void rmfile(error_code & _ec, future<> _precondition, T _path = path(), + file_flags _flags = file_flags::none)`` + +[heading Parameters] + +[table +[[Type] [Concept] [Name] [Description] ] +[[class T] [The type of path to be used. ] [ - ] [Must be specified]] +[[error_code &] [] [_ec] [Error code to set. ]] +[[future<>] [] [_precondition] [The precondition to use. ]] +[[T] [] [_path] [The filing system path to be used. ]] +[[file_flags] [] [_flags] [The flags to be used.]] +] + + +[heading Header] +`#include <boost/afio/v2/afio.hpp>` + +[heading Race Guarantees][raceguarantees +[raceguarantee FreeBSD, Linux..Race free up to the containing directory.] +[raceguarantee Windows..Race free if handle open, else up to the containing directory.] +[raceguarantee OS X..No guarantees.] + ] +[heading Complexity]Amortised O(1) to dispatch. Amortised O(1) to complete if file deletion is constant time. +[heading Exception Model]Propagates the exception of any input precondition with an errored state at the point of dispatch, and throws a `std::invalid_argument` if any inputs have values which could not possibly be correct. Note that error code returning functions may still throw exceptions e.g. failure to allocate memory. +[heading Example][filedir_example] + + +'''<?dbhtml-include href="disqus_comments.html"?>''' +[endsect] + +[section:rmfile_3_absolute_non_throwing rmfile (absolute non throwing)] +'''<?dbhtml-include href="disqus_identifiers/rmfile_3_absolute_non_throwing.html"?>''' + +'''<indexterm><primary>rmfile</primary></indexterm>''' +Synchronous file deletion after an optional precondition. + +[heading Description] +Note that you can delete files before they are closed on Windows just as with POSIX if and only if all open handles to that file were opened with permission for the file to be deleted (AFIO always sets this). The actual file data will be deleted when the last handle is closed on the system. Make sure you read the docs for [^`__afio_handle__::unlink()`] for important caveats. Note that on operating systems with an unstable [^`__afio_handle__::path(true)`] you need to be cautious of deleting files by handle as any hard link to that file may be deleted instead of the one you intended. To work around this, portable code should delete by directory handle as the precondition and known leafname. Related types: [^`__afio_path_req__`] Be aware that on Windows AFIO operates exclusively in the NT kernel namespace, NOT the Win32 namespace, and therefore paths you supply are converted by [^`afio::path`] in NT kernel namespace paths. [^`normalise_path()`] can convert an afio path back to a Filesystem TS path for you, but note that this may not be the path that was supplied originally. NT kernel namespace paths have a 32,767 character limit and an almost POSIX like lack of restrictions on naming or historical behaviour quirks, but as a result AFIO does not support DOS short names or any of the other historical Win32 filing system baggage. + +[heading Synopsis] +``template<class T, typename> +void rmfile(error_code & _ec, T _path, file_flags _flags = file_flags::none)`` + +[heading Parameters] + +[table +[[Type] [Concept] [Name] [Description] ] +[[class T] [The type of path to be used. ] [ - ] [Must be specified]] +[[] [] [ - ] [Must be specified]] +[[error_code &] [] [_ec] [Error code to set. ]] +[[T] [] [_path] [The filing system path to be used. ]] +[[file_flags] [] [_flags] [The flags to be used.]] +] + + +[heading Header] +`#include <boost/afio/v2/afio.hpp>` + +[heading Race Guarantees][raceguarantees +[raceguarantee FreeBSD, Linux, OS X, Windows..No guarantees.] + ] +[heading Complexity]Amortised O(1) to dispatch. Amortised O(1) to complete if file deletion is constant time. +[heading Exception Model]Propagates the exception of any input precondition with an errored state at the point of dispatch, and throws a `std::invalid_argument` if any inputs have values which could not possibly be correct. Note that error code returning functions may still throw exceptions e.g. failure to allocate memory. +[heading Example][filedir_example] + + +'''<?dbhtml-include href="disqus_comments.html"?>''' +[endsect] + diff --git a/attic/doc/generated/group_rmsymlink.qbk b/attic/doc/generated/group_rmsymlink.qbk new file mode 100644 index 00000000..496a106a --- /dev/null +++ b/attic/doc/generated/group_rmsymlink.qbk @@ -0,0 +1,293 @@ +[/============================================================================ + Boost.AFIO + + Use, modification and distribution is subject to the Boost Software License, + Version 1.0. (See accompanying file LICENSE_1_0.txt or copy at + http://www.boost.org/LICENSE_1_0.txt) +=============================================================================/] + + +[/ Generated by doxygen_xml2qbk 1.1.1, don't change, will be overwritten automatically] +[/ Generated from doxy/doxygen_output/xml\group__rmsymlink.xml] +[section:rmsymlink_1_batch rmsymlink (batch)] +'''<?dbhtml-include href="disqus_identifiers/rmsymlink_1_batch.html"?>''' + +'''<indexterm><primary>rmsymlink</primary></indexterm>''' +Schedule a batch of asynchronous symlink deletions after optional preconditions. + +[heading Description] +Make sure you read the docs for [^`__afio_handle__::unlink()`] for important caveats. Note that on operating systems with an unstable [^`__afio_handle__::path(true)`] you need to be cautious of deleting files by handle as any hard link to that file may be deleted instead of the one you intended. To work around this, portable code should delete by directory handle as the precondition and known leafname. Related types: [^`__afio_path_req__`] + +[heading Synopsis] +``future dispatcher::rmsymlink(const std::vector< path_req > & reqs)`` + +[heading Parameters] + +[table +[[Type] [Concept] [Name] [Description] ] +[[const std::vector< path_req > &] [] [reqs] [A batch of [^`path_req`] structures.]] +] + + +[heading Returns] +A batch of op handles. + +[heading Header] +`#include <boost/afio/v2/afio.hpp>` + +[heading Race Guarantees][raceguarantees +[raceguarantee FreeBSD, Linux..Race free up to the containing directory.] +[raceguarantee Windows..Race free if handle open, else up to the containing directory.] +[raceguarantee OS X..No guarantees.] + ] +[heading Complexity]Amortised O(N) to dispatch. Amortised O(N/threadpool) to complete if symlink deletion is constant time. +[heading Exception Model]Propagates exceptions of any input preconditions with an errored state at the point of dispatch, and throws a `std::invalid_argument` if any inputs have values which could not possibly be correct. Once a batch of input ops has been verified at the point of entry as not errored, you are guaranteed that the batch is atomically scheduled as a whole, unless a failure to allocate memory occurs. +[heading Example][filedir_example] + + +'''<?dbhtml-include href="disqus_comments.html"?>''' +[endsect] + +[section:async_rmsymlink_3_relative async_rmsymlink (relative)] +'''<?dbhtml-include href="disqus_identifiers/async_rmsymlink_3_relative.html"?>''' + +'''<indexterm><primary>async_rmsymlink</primary></indexterm>''' +Asynchronous symlink deletion after an optional precondition. + +[heading Description] +Make sure you read the docs for [^`__afio_handle__::unlink()`] for important caveats. Note that on operating systems with an unstable [^`__afio_handle__::path(true)`] you need to be cautious of deleting files by handle as any hard link to that file may be deleted instead of the one you intended. To work around this, portable code should delete by directory handle as the precondition and known leafname. Related types: [^`__afio_path_req__`] Be aware that on Windows AFIO operates exclusively in the NT kernel namespace, NOT the Win32 namespace, and therefore paths you supply are converted by [^`afio::path`] in NT kernel namespace paths. [^`normalise_path()`] can convert an afio path back to a Filesystem TS path for you, but note that this may not be the path that was supplied originally. NT kernel namespace paths have a 32,767 character limit and an almost POSIX like lack of restrictions on naming or historical behaviour quirks, but as a result AFIO does not support DOS short names or any of the other historical Win32 filing system baggage. + +[heading Synopsis] +``template<class T> +future async_rmsymlink(future<> _precondition, T _path = path(), file_flags _flags = file_flags::none)`` + +[heading Parameters] + +[table +[[Type] [Concept] [Name] [Description] ] +[[class T] [The type of path to be used. ] [ - ] [Must be specified]] +[[future<>] [] [_precondition] [The precondition to use. ]] +[[T] [] [_path] [The filing system path to be used. ]] +[[file_flags] [] [_flags] [The flags to be used.]] +] + + +[heading Returns] +A future<void> + +[heading Header] +`#include <boost/afio/v2/afio.hpp>` + +[heading Race Guarantees][raceguarantees +[raceguarantee FreeBSD, Linux..Race free up to the containing directory.] +[raceguarantee Windows..Race free if handle open, else up to the containing directory.] +[raceguarantee OS X..No guarantees.] + ] +[heading Complexity]Amortised O(1) to dispatch. Amortised O(1) to complete if symlink deletion is constant time. +[heading Exception Model]Propagates the exception of any input precondition with an errored state at the point of dispatch, and throws a `std::invalid_argument` if any inputs have values which could not possibly be correct. Note that error code returning functions may still throw exceptions e.g. failure to allocate memory. +[heading Example][filedir_example] + + +'''<?dbhtml-include href="disqus_comments.html"?>''' +[endsect] + +[section:async_rmsymlink_2_absolute async_rmsymlink (absolute)] +'''<?dbhtml-include href="disqus_identifiers/async_rmsymlink_2_absolute.html"?>''' + +'''<indexterm><primary>async_rmsymlink</primary></indexterm>''' +Asynchronous symlink deletion after an optional precondition. + +[heading Description] +Make sure you read the docs for [^`__afio_handle__::unlink()`] for important caveats. Note that on operating systems with an unstable [^`__afio_handle__::path(true)`] you need to be cautious of deleting files by handle as any hard link to that file may be deleted instead of the one you intended. To work around this, portable code should delete by directory handle as the precondition and known leafname. Related types: [^`__afio_path_req__`] Be aware that on Windows AFIO operates exclusively in the NT kernel namespace, NOT the Win32 namespace, and therefore paths you supply are converted by [^`afio::path`] in NT kernel namespace paths. [^`normalise_path()`] can convert an afio path back to a Filesystem TS path for you, but note that this may not be the path that was supplied originally. NT kernel namespace paths have a 32,767 character limit and an almost POSIX like lack of restrictions on naming or historical behaviour quirks, but as a result AFIO does not support DOS short names or any of the other historical Win32 filing system baggage. + +[heading Synopsis] +``template<class T, typename> +future async_rmsymlink(T _path, file_flags _flags = file_flags::none)`` + +[heading Parameters] + +[table +[[Type] [Concept] [Name] [Description] ] +[[class T] [The type of path to be used. ] [ - ] [Must be specified]] +[[] [] [ - ] [Must be specified]] +[[T] [] [_path] [The filing system path to be used. ]] +[[file_flags] [] [_flags] [The flags to be used.]] +] + + +[heading Returns] +A future<void> + +[heading Header] +`#include <boost/afio/v2/afio.hpp>` + +[heading Race Guarantees][raceguarantees +[raceguarantee FreeBSD, Linux, OS X, Windows..No guarantees.] + ] +[heading Complexity]Amortised O(1) to dispatch. Amortised O(1) to complete if symlink deletion is constant time. +[heading Exception Model]Propagates the exception of any input precondition with an errored state at the point of dispatch, and throws a `std::invalid_argument` if any inputs have values which could not possibly be correct. Note that error code returning functions may still throw exceptions e.g. failure to allocate memory. +[heading Example][filedir_example] + + +'''<?dbhtml-include href="disqus_comments.html"?>''' +[endsect] + +[section:rmsymlink_3_relative_throwing rmsymlink (relative throwing)] +'''<?dbhtml-include href="disqus_identifiers/rmsymlink_3_relative_throwing.html"?>''' + +'''<indexterm><primary>rmsymlink</primary></indexterm>''' +Synchronous symlink deletion after an optional precondition. + +[heading Description] +Make sure you read the docs for [^`__afio_handle__::unlink()`] for important caveats. Note that on operating systems with an unstable [^`__afio_handle__::path(true)`] you need to be cautious of deleting files by handle as any hard link to that file may be deleted instead of the one you intended. To work around this, portable code should delete by directory handle as the precondition and known leafname. Related types: [^`__afio_path_req__`] Be aware that on Windows AFIO operates exclusively in the NT kernel namespace, NOT the Win32 namespace, and therefore paths you supply are converted by [^`afio::path`] in NT kernel namespace paths. [^`normalise_path()`] can convert an afio path back to a Filesystem TS path for you, but note that this may not be the path that was supplied originally. NT kernel namespace paths have a 32,767 character limit and an almost POSIX like lack of restrictions on naming or historical behaviour quirks, but as a result AFIO does not support DOS short names or any of the other historical Win32 filing system baggage. + +[heading Synopsis] +``template<class T> +void rmsymlink(future<> _precondition, T _path = path(), file_flags _flags = file_flags::none)`` + +[heading Parameters] + +[table +[[Type] [Concept] [Name] [Description] ] +[[class T] [The type of path to be used. ] [ - ] [Must be specified]] +[[future<>] [] [_precondition] [The precondition to use. ]] +[[T] [] [_path] [The filing system path to be used. ]] +[[file_flags] [] [_flags] [The flags to be used.]] +] + + +[heading Header] +`#include <boost/afio/v2/afio.hpp>` + +[heading Race Guarantees][raceguarantees +[raceguarantee FreeBSD, Linux..Race free up to the containing directory.] +[raceguarantee Windows..Race free if handle open, else up to the containing directory.] +[raceguarantee OS X..No guarantees.] + ] +[heading Complexity]Amortised O(1) to dispatch. Amortised O(1) to complete if symlink deletion is constant time. +[heading Exception Model]Propagates the exception of any input precondition with an errored state at the point of dispatch, and throws a `std::invalid_argument` if any inputs have values which could not possibly be correct. Note that error code returning functions may still throw exceptions e.g. failure to allocate memory. +[heading Example][filedir_example] + + +'''<?dbhtml-include href="disqus_comments.html"?>''' +[endsect] + +[section:rmsymlink_2_absolute_throwing rmsymlink (absolute throwing)] +'''<?dbhtml-include href="disqus_identifiers/rmsymlink_2_absolute_throwing.html"?>''' + +'''<indexterm><primary>rmsymlink</primary></indexterm>''' +Synchronous symlink deletion after an optional precondition. + +[heading Description] +Make sure you read the docs for [^`__afio_handle__::unlink()`] for important caveats. Note that on operating systems with an unstable [^`__afio_handle__::path(true)`] you need to be cautious of deleting files by handle as any hard link to that file may be deleted instead of the one you intended. To work around this, portable code should delete by directory handle as the precondition and known leafname. Related types: [^`__afio_path_req__`] Be aware that on Windows AFIO operates exclusively in the NT kernel namespace, NOT the Win32 namespace, and therefore paths you supply are converted by [^`afio::path`] in NT kernel namespace paths. [^`normalise_path()`] can convert an afio path back to a Filesystem TS path for you, but note that this may not be the path that was supplied originally. NT kernel namespace paths have a 32,767 character limit and an almost POSIX like lack of restrictions on naming or historical behaviour quirks, but as a result AFIO does not support DOS short names or any of the other historical Win32 filing system baggage. + +[heading Synopsis] +``template<class T, typename> +void rmsymlink(T _path, file_flags _flags = file_flags::none)`` + +[heading Parameters] + +[table +[[Type] [Concept] [Name] [Description] ] +[[class T] [The type of path to be used. ] [ - ] [Must be specified]] +[[] [] [ - ] [Must be specified]] +[[T] [] [_path] [The filing system path to be used. ]] +[[file_flags] [] [_flags] [The flags to be used.]] +] + + +[heading Header] +`#include <boost/afio/v2/afio.hpp>` + +[heading Race Guarantees][raceguarantees +[raceguarantee FreeBSD, Linux, OS X, Windows..No guarantees.] + ] +[heading Complexity]Amortised O(1) to dispatch. Amortised O(1) to complete if symlink deletion is constant time. +[heading Exception Model]Propagates the exception of any input precondition with an errored state at the point of dispatch, and throws a `std::invalid_argument` if any inputs have values which could not possibly be correct. Note that error code returning functions may still throw exceptions e.g. failure to allocate memory. +[heading Example][filedir_example] + + +'''<?dbhtml-include href="disqus_comments.html"?>''' +[endsect] + +[section:rmsymlink_4_relative_non_throwing rmsymlink (relative non throwing)] +'''<?dbhtml-include href="disqus_identifiers/rmsymlink_4_relative_non_throwing.html"?>''' + +'''<indexterm><primary>rmsymlink</primary></indexterm>''' +Synchronous symlink deletion after an optional precondition. + +[heading Description] +Make sure you read the docs for [^`__afio_handle__::unlink()`] for important caveats. Note that on operating systems with an unstable [^`__afio_handle__::path(true)`] you need to be cautious of deleting files by handle as any hard link to that file may be deleted instead of the one you intended. To work around this, portable code should delete by directory handle as the precondition and known leafname. Related types: [^`__afio_path_req__`] Be aware that on Windows AFIO operates exclusively in the NT kernel namespace, NOT the Win32 namespace, and therefore paths you supply are converted by [^`afio::path`] in NT kernel namespace paths. [^`normalise_path()`] can convert an afio path back to a Filesystem TS path for you, but note that this may not be the path that was supplied originally. NT kernel namespace paths have a 32,767 character limit and an almost POSIX like lack of restrictions on naming or historical behaviour quirks, but as a result AFIO does not support DOS short names or any of the other historical Win32 filing system baggage. + +[heading Synopsis] +``template<class T> +void rmsymlink(error_code & _ec, future<> _precondition, T _path = path(), + file_flags _flags = file_flags::none)`` + +[heading Parameters] + +[table +[[Type] [Concept] [Name] [Description] ] +[[class T] [The type of path to be used. ] [ - ] [Must be specified]] +[[error_code &] [] [_ec] [Error code to set. ]] +[[future<>] [] [_precondition] [The precondition to use. ]] +[[T] [] [_path] [The filing system path to be used. ]] +[[file_flags] [] [_flags] [The flags to be used.]] +] + + +[heading Header] +`#include <boost/afio/v2/afio.hpp>` + +[heading Race Guarantees][raceguarantees +[raceguarantee FreeBSD, Linux..Race free up to the containing directory.] +[raceguarantee Windows..Race free if handle open, else up to the containing directory.] +[raceguarantee OS X..No guarantees.] + ] +[heading Complexity]Amortised O(1) to dispatch. Amortised O(1) to complete if symlink deletion is constant time. +[heading Exception Model]Propagates the exception of any input precondition with an errored state at the point of dispatch, and throws a `std::invalid_argument` if any inputs have values which could not possibly be correct. Note that error code returning functions may still throw exceptions e.g. failure to allocate memory. +[heading Example][filedir_example] + + +'''<?dbhtml-include href="disqus_comments.html"?>''' +[endsect] + +[section:rmsymlink_3_absolute_non_throwing rmsymlink (absolute non throwing)] +'''<?dbhtml-include href="disqus_identifiers/rmsymlink_3_absolute_non_throwing.html"?>''' + +'''<indexterm><primary>rmsymlink</primary></indexterm>''' +Synchronous symlink deletion after an optional precondition. + +[heading Description] +Make sure you read the docs for [^`__afio_handle__::unlink()`] for important caveats. Note that on operating systems with an unstable [^`__afio_handle__::path(true)`] you need to be cautious of deleting files by handle as any hard link to that file may be deleted instead of the one you intended. To work around this, portable code should delete by directory handle as the precondition and known leafname. Related types: [^`__afio_path_req__`] Be aware that on Windows AFIO operates exclusively in the NT kernel namespace, NOT the Win32 namespace, and therefore paths you supply are converted by [^`afio::path`] in NT kernel namespace paths. [^`normalise_path()`] can convert an afio path back to a Filesystem TS path for you, but note that this may not be the path that was supplied originally. NT kernel namespace paths have a 32,767 character limit and an almost POSIX like lack of restrictions on naming or historical behaviour quirks, but as a result AFIO does not support DOS short names or any of the other historical Win32 filing system baggage. + +[heading Synopsis] +``template<class T, typename> +void rmsymlink(error_code & _ec, T _path, file_flags _flags = file_flags::none)`` + +[heading Parameters] + +[table +[[Type] [Concept] [Name] [Description] ] +[[class T] [The type of path to be used. ] [ - ] [Must be specified]] +[[] [] [ - ] [Must be specified]] +[[error_code &] [] [_ec] [Error code to set. ]] +[[T] [] [_path] [The filing system path to be used. ]] +[[file_flags] [] [_flags] [The flags to be used.]] +] + + +[heading Header] +`#include <boost/afio/v2/afio.hpp>` + +[heading Race Guarantees][raceguarantees +[raceguarantee FreeBSD, Linux, OS X, Windows..No guarantees.] + ] +[heading Complexity]Amortised O(1) to dispatch. Amortised O(1) to complete if symlink deletion is constant time. +[heading Exception Model]Propagates the exception of any input precondition with an errored state at the point of dispatch, and throws a `std::invalid_argument` if any inputs have values which could not possibly be correct. Note that error code returning functions may still throw exceptions e.g. failure to allocate memory. +[heading Example][filedir_example] + + +'''<?dbhtml-include href="disqus_comments.html"?>''' +[endsect] + diff --git a/attic/doc/generated/group_statfs.qbk b/attic/doc/generated/group_statfs.qbk new file mode 100644 index 00000000..5ca3ce46 --- /dev/null +++ b/attic/doc/generated/group_statfs.qbk @@ -0,0 +1,180 @@ +[/============================================================================ + Boost.AFIO + + Use, modification and distribution is subject to the Boost Software License, + Version 1.0. (See accompanying file LICENSE_1_0.txt or copy at + http://www.boost.org/LICENSE_1_0.txt) +=============================================================================/] + + +[/ Generated by doxygen_xml2qbk 1.1.1, don't change, will be overwritten automatically] +[/ Generated from doxy/doxygen_output/xml\group__statfs.xml] +[section:statfs_2_batch statfs (batch)] +'''<?dbhtml-include href="disqus_identifiers/statfs_2_batch.html"?>''' + +'''<indexterm><primary>statfs</primary></indexterm>''' +Schedule a batch of asynchronous volume enumerations after preceding operations. + +[heading Description] +Related types: [^`__afio_statfs_t__`] + +[heading Synopsis] +``future< statfs_t > dispatcher::statfs(const std::vector< future<>> & ops, const std::vector< fs_metadata_flags > & reqs)`` + +[heading Parameters] + +[table +[[Type] [Concept] [Name] [Description] ] +[[const std::vector< future<>> &] [] [ops] [A batch of op handles. ]] +[[const std::vector< fs_metadata_flags > &] [] [reqs] [A batch of metadata requests.]] +] + + +[heading Returns] +A batch of stl\u005ffuture volume metadatas. + +[heading Header] +`#include <boost/afio/v2/afio.hpp>` + +[heading Race Guarantees][raceguarantees +[raceguarantee FreeBSD, OS X..Race free.] +[raceguarantee Linux..The following items are fetched in a single snapshot: bsize, iosize, blocks, bfree, bavail, files, ffree, namemax, fsid, +flags.rdonly, flags.noexec, flags.nosuid.] +[raceguarantee Windows..The following snapshot categories apply: (i) flags, namemax, fstypename (ii) bsize, blocks, bfree, bavail. Everything else +is fetched separately.] + ] +[heading Complexity]Amortised O(N) to dispatch. Amortised O(N/threadpool*M) to complete where M is the average number of entries in each directory. +[heading Exception Model]Propagates exceptions of any input preconditions with an errored state at the point of dispatch, and throws a `std::invalid_argument` if any inputs have values which could not possibly be correct. Once a batch of input ops has been verified at the point of entry as not errored, you are guaranteed that the batch is atomically scheduled as a whole, unless a failure to allocate memory occurs. +[heading Example][statfs_example] + + +'''<?dbhtml-include href="disqus_comments.html"?>''' +[endsect] + +[section:async_statfs async_statfs] +'''<?dbhtml-include href="disqus_identifiers/async_statfs.html"?>''' + +'''<indexterm><primary>async_statfs</primary></indexterm>''' +Asynchronous volume enumeration after a preceding operation. + +[heading Description] +Related types: [^`__afio_statfs_t__`] + +[heading Synopsis] +``future<statfs_t> async_statfs(future<> _precondition, fs_metadata_flags req)`` + +[heading Parameters] + +[table +[[Type] [Concept] [Name] [Description] ] +[[future<>] [] [_precondition] [The precondition to use. ]] +[[fs_metadata_flags] [] [req] [A metadata request.]] +] + + +[heading Returns] +A [^`future<``statfs_t``>`] + +[heading Header] +`#include <boost/afio/v2/afio.hpp>` + +[heading Race Guarantees][raceguarantees +[raceguarantee FreeBSD, OS X..Race free.] +[raceguarantee Linux..The following items are fetched in a single snapshot: bsize, iosize, blocks, bfree, bavail, files, ffree, namemax, fsid, +flags.rdonly, flags.noexec, flags.nosuid.] +[raceguarantee Windows..The following snapshot categories apply: (i) flags, namemax, fstypename (ii) bsize, blocks, bfree, bavail. Everything else +is fetched separately.] + ] +[heading Complexity]Amortised O(1) to dispatch. Amortised O(1) to complete. +[heading Exception Model]Propagates the exception of any input precondition with an errored state at the point of dispatch, and throws a `std::invalid_argument` if any inputs have values which could not possibly be correct. Note that error code returning functions may still throw exceptions e.g. failure to allocate memory. +[heading Example][statfs_example] + + +'''<?dbhtml-include href="disqus_comments.html"?>''' +[endsect] + +[section:statfs_2_throwing statfs (throwing)] +'''<?dbhtml-include href="disqus_identifiers/statfs_2_throwing.html"?>''' + +'''<indexterm><primary>statfs</primary></indexterm>''' +Synchronous volume enumeration after a preceding operation. + +[heading Description] +Related types: [^`__afio_statfs_t__`] + +[heading Synopsis] +``statfs_t statfs(future<> _precondition, fs_metadata_flags req)`` + +[heading Parameters] + +[table +[[Type] [Concept] [Name] [Description] ] +[[future<>] [] [_precondition] [The precondition to use. ]] +[[fs_metadata_flags] [] [req] [A metadata request.]] +] + + +[heading Returns] +The volume metadata requested. + +[heading Header] +`#include <boost/afio/v2/afio.hpp>` + +[heading Race Guarantees][raceguarantees +[raceguarantee FreeBSD, OS X..Race free.] +[raceguarantee Linux..The following items are fetched in a single snapshot: bsize, iosize, blocks, bfree, bavail, files, ffree, namemax, fsid, +flags.rdonly, flags.noexec, flags.nosuid.] +[raceguarantee Windows..The following snapshot categories apply: (i) flags, namemax, fstypename (ii) bsize, blocks, bfree, bavail. Everything else +is fetched separately.] + ] +[heading Complexity]Amortised O(1) to dispatch. Amortised O(1) to complete. +[heading Exception Model]Propagates the exception of any input precondition with an errored state at the point of dispatch, and throws a `std::invalid_argument` if any inputs have values which could not possibly be correct. Note that error code returning functions may still throw exceptions e.g. failure to allocate memory. +[heading Example][statfs_example] + + +'''<?dbhtml-include href="disqus_comments.html"?>''' +[endsect] + +[section:statfs_3_nonthrowing statfs (nonthrowing)] +'''<?dbhtml-include href="disqus_identifiers/statfs_3_nonthrowing.html"?>''' + +'''<indexterm><primary>statfs</primary></indexterm>''' +Synchronous volume enumeration after a preceding operation. + +[heading Description] +Related types: [^`__afio_statfs_t__`] + +[heading Synopsis] +``statfs_t statfs(error_code & _ec, future<> _precondition, fs_metadata_flags req)`` + +[heading Parameters] + +[table +[[Type] [Concept] [Name] [Description] ] +[[error_code &] [] [_ec] [Error code to set. ]] +[[future<>] [] [_precondition] [The precondition to use. ]] +[[fs_metadata_flags] [] [req] [A metadata request.]] +] + + +[heading Returns] +The volume metadata requested. + +[heading Header] +`#include <boost/afio/v2/afio.hpp>` + +[heading Race Guarantees][raceguarantees +[raceguarantee FreeBSD, OS X..Race free.] +[raceguarantee Linux..The following items are fetched in a single snapshot: bsize, iosize, blocks, bfree, bavail, files, ffree, namemax, fsid, +flags.rdonly, flags.noexec, flags.nosuid.] +[raceguarantee Windows..The following snapshot categories apply: (i) flags, namemax, fstypename (ii) bsize, blocks, bfree, bavail. Everything else +is fetched separately.] + ] +[heading Complexity]Amortised O(1) to dispatch. Amortised O(1) to complete. +[heading Exception Model]Propagates the exception of any input precondition with an errored state at the point of dispatch, and throws a `std::invalid_argument` if any inputs have values which could not possibly be correct. Note that error code returning functions may still throw exceptions e.g. failure to allocate memory. +[heading Example][statfs_example] + + +'''<?dbhtml-include href="disqus_comments.html"?>''' +[endsect] + diff --git a/attic/doc/generated/group_symlink.qbk b/attic/doc/generated/group_symlink.qbk new file mode 100644 index 00000000..20120d2e --- /dev/null +++ b/attic/doc/generated/group_symlink.qbk @@ -0,0 +1,311 @@ +[/============================================================================ + Boost.AFIO + + Use, modification and distribution is subject to the Boost Software License, + Version 1.0. (See accompanying file LICENSE_1_0.txt or copy at + http://www.boost.org/LICENSE_1_0.txt) +=============================================================================/] + + +[/ Generated by doxygen_xml2qbk 1.1.1, don't change, will be overwritten automatically] +[/ Generated from doxy/doxygen_output/xml\group__symlink.xml] +[section:symlink_2_batch symlink (batch)] +'''<?dbhtml-include href="disqus_identifiers/symlink_2_batch.html"?>''' + +'''<indexterm><primary>symlink</primary></indexterm>''' +Schedule a batch of asynchronous symlink creations and opens after a precondition. + +[heading Description] +Note that if creating and you don't specify a target, the target for the symlink is the precondition. On Windows directories are symlinked using a reparse point instead of a symlink due to the default lack of the [^`SeCreateSymbolicLinkPrivilege`] for non-Administrative users. On Windows you can open symlinks as a file and so a valid handle is output, whereas on POSIX except for Linux you cannot do this and an invalid handle is output. Related types: [^`__afio_path_req__`] Be aware that on Windows AFIO operates exclusively in the NT kernel namespace, NOT the Win32 namespace, and therefore paths you supply are converted by [^`afio::path`] in NT kernel namespace paths. [^`normalise_path()`] can convert an afio path back to a Filesystem TS path for you, but note that this may not be the path that was supplied originally. NT kernel namespace paths have a 32,767 character limit and an almost POSIX like lack of restrictions on naming or historical behaviour quirks, but as a result AFIO does not support DOS short names or any of the other historical Win32 filing system baggage. + +[heading Synopsis] +``future dispatcher::symlink(const std::vector< path_req > & reqs, const std::vector< future<>> & targets = std::vector< future<>>())`` + +[heading Parameters] + +[table +[[Type] [Concept] [Name] [Description] ] +[[const std::vector< path_req > &] [] [reqs] [A batch of [^`path_req`] structures. ]] +[[const std::vector< future<>> &] [] [targets] [An optional batch of targets if creating symlinks.]] +] + + +[heading Returns] +A batch of op handles. + +[heading Header] +`#include <boost/afio/v2/afio.hpp>` + +[heading Race Guarantees][raceguarantees +[raceguarantee FreeBSD, Linux, Windows..Link creation is race free up to the containing directory. Destination is unavoidably racy.] +[raceguarantee OS X..No guarantees.] + ] +[heading Complexity]Amortised O(N) to dispatch. Amortised O(N/threadpool) to complete if symlink creation is constant time. +[heading Exception Model]Propagates exceptions of any input preconditions with an errored state at the point of dispatch, and throws a `std::invalid_argument` if any inputs have values which could not possibly be correct. Once a batch of input ops has been verified at the point of entry as not errored, you are guaranteed that the batch is atomically scheduled as a whole, unless a failure to allocate memory occurs. +[heading Example][filedir_example] + + +'''<?dbhtml-include href="disqus_comments.html"?>''' +[endsect] + +[section:async_symlink_4_relative async_symlink (relative)] +'''<?dbhtml-include href="disqus_identifiers/async_symlink_4_relative.html"?>''' + +'''<indexterm><primary>async_symlink</primary></indexterm>''' +Asynchronous symlink creation and open after a precondition. + +[heading Description] +Note that if creating and you don't specify a target, the target for the symlink is the precondition. On Windows directories are symlinked using a reparse point instead of a symlink due to the default lack of the [^`SeCreateSymbolicLinkPrivilege`] for non-Administrative users. On Windows you can open symlinks as a file and so a valid handle is output, whereas on POSIX except for Linux you cannot do this and an invalid handle is output. Related types: [^`__afio_path_req__`] Be aware that on Windows AFIO operates exclusively in the NT kernel namespace, NOT the Win32 namespace, and therefore paths you supply are converted by [^`afio::path`] in NT kernel namespace paths. [^`normalise_path()`] can convert an afio path back to a Filesystem TS path for you, but note that this may not be the path that was supplied originally. NT kernel namespace paths have a 32,767 character limit and an almost POSIX like lack of restrictions on naming or historical behaviour quirks, but as a result AFIO does not support DOS short names or any of the other historical Win32 filing system baggage. + +[heading Synopsis] +``template<class T> +future async_symlink(future<> _precondition, T _path, future<> _target = future<>(), + file_flags _flags = file_flags::none)`` + +[heading Parameters] + +[table +[[Type] [Concept] [Name] [Description] ] +[[class T] [The type of path to use. ] [ - ] [Must be specified]] +[[future<>] [] [_precondition] [The precondition to use. ]] +[[T] [] [_path] [The filing system path to use. ]] +[[future<>] [] [_target] [The item to link to if creating. ]] +[[file_flags] [] [_flags] [The flags to use.]] +] + + +[heading Returns] +A future<void> + +[heading Header] +`#include <boost/afio/v2/afio.hpp>` + +[heading Race Guarantees][raceguarantees +[raceguarantee FreeBSD, Linux, Windows..Link creation is race free up to the containing directory. Destination is unavoidably racy.] +[raceguarantee OS X..No guarantees.] + ] +[heading Complexity]Amortised O(1) to dispatch. Amortised O(1) to complete if symlink creation is constant time. +[heading Exception Model]Propagates the exception of any input precondition with an errored state at the point of dispatch, and throws a `std::invalid_argument` if any inputs have values which could not possibly be correct. Note that error code returning functions may still throw exceptions e.g. failure to allocate memory. +[heading Example][filedir_example] + + +'''<?dbhtml-include href="disqus_comments.html"?>''' +[endsect] + +[section:async_symlink_3_absolute async_symlink (absolute)] +'''<?dbhtml-include href="disqus_identifiers/async_symlink_3_absolute.html"?>''' + +'''<indexterm><primary>async_symlink</primary></indexterm>''' +Asynchronous symlink creation and open after a precondition. + +[heading Description] +Note that if creating and you don't specify a target, the target for the symlink is the precondition. On Windows directories are symlinked using a reparse point instead of a symlink due to the default lack of the [^`SeCreateSymbolicLinkPrivilege`] for non-Administrative users. On Windows you can open symlinks as a file and so a valid handle is output, whereas on POSIX except for Linux you cannot do this and an invalid handle is output. Related types: [^`__afio_path_req__`] Be aware that on Windows AFIO operates exclusively in the NT kernel namespace, NOT the Win32 namespace, and therefore paths you supply are converted by [^`afio::path`] in NT kernel namespace paths. [^`normalise_path()`] can convert an afio path back to a Filesystem TS path for you, but note that this may not be the path that was supplied originally. NT kernel namespace paths have a 32,767 character limit and an almost POSIX like lack of restrictions on naming or historical behaviour quirks, but as a result AFIO does not support DOS short names or any of the other historical Win32 filing system baggage. + +[heading Synopsis] +``template<class T, typename> +future async_symlink(T _path, future<> _target = future<>(), file_flags _flags = file_flags::none)`` + +[heading Parameters] + +[table +[[Type] [Concept] [Name] [Description] ] +[[class T] [The type of path to use. ] [ - ] [Must be specified]] +[[] [] [ - ] [Must be specified]] +[[T] [] [_path] [The filing system path to use. ]] +[[future<>] [] [_target] [The item to link to if creating. ]] +[[file_flags] [] [_flags] [The flags to use.]] +] + + +[heading Returns] +A future<void> + +[heading Header] +`#include <boost/afio/v2/afio.hpp>` + +[heading Race Guarantees][raceguarantees +[raceguarantee FreeBSD, Linux, OS X, Windows..No guarantees.] + ] +[heading Complexity]Amortised O(1) to dispatch. Amortised O(1) to complete if symlink creation is constant time. +[heading Exception Model]Propagates the exception of any input precondition with an errored state at the point of dispatch, and throws a `std::invalid_argument` if any inputs have values which could not possibly be correct. Note that error code returning functions may still throw exceptions e.g. failure to allocate memory. +[heading Example][filedir_example] + + +'''<?dbhtml-include href="disqus_comments.html"?>''' +[endsect] + +[section:symlink_4_relative_throwing symlink (relative throwing)] +'''<?dbhtml-include href="disqus_identifiers/symlink_4_relative_throwing.html"?>''' + +'''<indexterm><primary>symlink</primary></indexterm>''' +Synchronous symlink creation and open after a precondition.. + +[heading Description] +Note that if creating and you don't specify a target, the target for the symlink is the precondition. On Windows directories are symlinked using a reparse point instead of a symlink due to the default lack of the [^`SeCreateSymbolicLinkPrivilege`] for non-Administrative users. On Windows you can open symlinks as a file and so a valid handle is output, whereas on POSIX except for Linux you cannot do this and an invalid handle is output. Related types: [^`__afio_path_req__`] Be aware that on Windows AFIO operates exclusively in the NT kernel namespace, NOT the Win32 namespace, and therefore paths you supply are converted by [^`afio::path`] in NT kernel namespace paths. [^`normalise_path()`] can convert an afio path back to a Filesystem TS path for you, but note that this may not be the path that was supplied originally. NT kernel namespace paths have a 32,767 character limit and an almost POSIX like lack of restrictions on naming or historical behaviour quirks, but as a result AFIO does not support DOS short names or any of the other historical Win32 filing system baggage. + +[heading Synopsis] +``template<class T> +handle_ptr symlink(future<> _precondition, T _path, future<> _target = future<>(), + file_flags _flags = file_flags::none)`` + +[heading Parameters] + +[table +[[Type] [Concept] [Name] [Description] ] +[[class T] [The type of path to use. ] [ - ] [Must be specified]] +[[future<>] [] [_precondition] [The precondition to use. ]] +[[T] [] [_path] [The filing system path to use. ]] +[[future<>] [] [_target] [The item to link to if creating. ]] +[[file_flags] [] [_flags] [The flags to use.]] +] + + +[heading Returns] +A handle to the symlink. + +[heading Header] +`#include <boost/afio/v2/afio.hpp>` + +[heading Race Guarantees][raceguarantees +[raceguarantee FreeBSD, Linux, Windows..Link creation is race free up to the containing directory. Destination is unavoidably racy.] +[raceguarantee OS X..No guarantees.] + ] +[heading Complexity]Amortised O(1) to dispatch. Amortised O(1) to complete if symlink creation is constant time. +[heading Exception Model]Propagates the exception of any input precondition with an errored state at the point of dispatch, and throws a `std::invalid_argument` if any inputs have values which could not possibly be correct. Note that error code returning functions may still throw exceptions e.g. failure to allocate memory. +[heading Example][filedir_example] + + +'''<?dbhtml-include href="disqus_comments.html"?>''' +[endsect] + +[section:symlink_3_absolute_throwing symlink (absolute throwing)] +'''<?dbhtml-include href="disqus_identifiers/symlink_3_absolute_throwing.html"?>''' + +'''<indexterm><primary>symlink</primary></indexterm>''' +Synchronous symlink creation and open after a precondition. + +[heading Description] +Note that if creating and you don't specify a target, the target for the symlink is the precondition. On Windows directories are symlinked using a reparse point instead of a symlink due to the default lack of the [^`SeCreateSymbolicLinkPrivilege`] for non-Administrative users. On Windows you can open symlinks as a file and so a valid handle is output, whereas on POSIX except for Linux you cannot do this and an invalid handle is output. Related types: [^`__afio_path_req__`] Be aware that on Windows AFIO operates exclusively in the NT kernel namespace, NOT the Win32 namespace, and therefore paths you supply are converted by [^`afio::path`] in NT kernel namespace paths. [^`normalise_path()`] can convert an afio path back to a Filesystem TS path for you, but note that this may not be the path that was supplied originally. NT kernel namespace paths have a 32,767 character limit and an almost POSIX like lack of restrictions on naming or historical behaviour quirks, but as a result AFIO does not support DOS short names or any of the other historical Win32 filing system baggage. + +[heading Synopsis] +``template<class T, typename> +handle_ptr symlink(T _path, future<> _target = future<>(), file_flags _flags = file_flags::none)`` + +[heading Parameters] + +[table +[[Type] [Concept] [Name] [Description] ] +[[class T] [The type of path to use. ] [ - ] [Must be specified]] +[[] [] [ - ] [Must be specified]] +[[T] [] [_path] [The filing system path to use. ]] +[[future<>] [] [_target] [The item to link to if creating. ]] +[[file_flags] [] [_flags] [The flags to use.]] +] + + +[heading Returns] +A handle to the symlink. + +[heading Header] +`#include <boost/afio/v2/afio.hpp>` + +[heading Race Guarantees][raceguarantees +[raceguarantee FreeBSD, Linux, OS X, Windows..No guarantees.] + ] +[heading Complexity]Amortised O(1) to dispatch. Amortised O(1) to complete if symlink creation is constant time. +[heading Exception Model]Propagates the exception of any input precondition with an errored state at the point of dispatch, and throws a `std::invalid_argument` if any inputs have values which could not possibly be correct. Note that error code returning functions may still throw exceptions e.g. failure to allocate memory. +[heading Example][filedir_example] + + +'''<?dbhtml-include href="disqus_comments.html"?>''' +[endsect] + +[section:symlink_5_relative_non_throwing symlink (relative non throwing)] +'''<?dbhtml-include href="disqus_identifiers/symlink_5_relative_non_throwing.html"?>''' + +'''<indexterm><primary>symlink</primary></indexterm>''' +Synchronous symlink creation and open after a precondition. + +[heading Description] +Note that if creating and you don't specify a target, the target for the symlink is the precondition. On Windows directories are symlinked using a reparse point instead of a symlink due to the default lack of the [^`SeCreateSymbolicLinkPrivilege`] for non-Administrative users. On Windows you can open symlinks as a file and so a valid handle is output, whereas on POSIX except for Linux you cannot do this and an invalid handle is output. Related types: [^`__afio_path_req__`] Be aware that on Windows AFIO operates exclusively in the NT kernel namespace, NOT the Win32 namespace, and therefore paths you supply are converted by [^`afio::path`] in NT kernel namespace paths. [^`normalise_path()`] can convert an afio path back to a Filesystem TS path for you, but note that this may not be the path that was supplied originally. NT kernel namespace paths have a 32,767 character limit and an almost POSIX like lack of restrictions on naming or historical behaviour quirks, but as a result AFIO does not support DOS short names or any of the other historical Win32 filing system baggage. + +[heading Synopsis] +``template<class T> +handle_ptr symlink(error_code & _ec, future<> _precondition, T _path, + future<> _target = future<>(), file_flags _flags = file_flags::none)`` + +[heading Parameters] + +[table +[[Type] [Concept] [Name] [Description] ] +[[class T] [The type of path to use. ] [ - ] [Must be specified]] +[[error_code &] [] [_ec] [Error code to set. ]] +[[future<>] [] [_precondition] [The precondition to use. ]] +[[T] [] [_path] [The filing system path to use. ]] +[[future<>] [] [_target] [The item to link to if creating. ]] +[[file_flags] [] [_flags] [The flags to use.]] +] + + +[heading Returns] +A handle to the symlink. + +[heading Header] +`#include <boost/afio/v2/afio.hpp>` + +[heading Race Guarantees][raceguarantees +[raceguarantee FreeBSD, Linux, Windows..Link creation is race free up to the containing directory. Destination is unavoidably racy.] +[raceguarantee OS X..No guarantees.] + ] +[heading Complexity]Amortised O(1) to dispatch. Amortised O(1) to complete if symlink creation is constant time. +[heading Exception Model]Propagates the exception of any input precondition with an errored state at the point of dispatch, and throws a `std::invalid_argument` if any inputs have values which could not possibly be correct. Note that error code returning functions may still throw exceptions e.g. failure to allocate memory. +[heading Example][filedir_example] + + +'''<?dbhtml-include href="disqus_comments.html"?>''' +[endsect] + +[section:symlink_4_absolute_non_throwing symlink (absolute non throwing)] +'''<?dbhtml-include href="disqus_identifiers/symlink_4_absolute_non_throwing.html"?>''' + +'''<indexterm><primary>symlink</primary></indexterm>''' +Synchronous symlink creation and open after a precondition. + +[heading Description] +Note that if creating and you don't specify a target, the target for the symlink is the precondition. On Windows directories are symlinked using a reparse point instead of a symlink due to the default lack of the [^`SeCreateSymbolicLinkPrivilege`] for non-Administrative users. On Windows you can open symlinks as a file and so a valid handle is output, whereas on POSIX except for Linux you cannot do this and an invalid handle is output. Related types: [^`__afio_path_req__`] Be aware that on Windows AFIO operates exclusively in the NT kernel namespace, NOT the Win32 namespace, and therefore paths you supply are converted by [^`afio::path`] in NT kernel namespace paths. [^`normalise_path()`] can convert an afio path back to a Filesystem TS path for you, but note that this may not be the path that was supplied originally. NT kernel namespace paths have a 32,767 character limit and an almost POSIX like lack of restrictions on naming or historical behaviour quirks, but as a result AFIO does not support DOS short names or any of the other historical Win32 filing system baggage. + +[heading Synopsis] +``template<class T, typename> +handle_ptr symlink(error_code & _ec, T _path, future<> _target = future<>(), + file_flags _flags = file_flags::none)`` + +[heading Parameters] + +[table +[[Type] [Concept] [Name] [Description] ] +[[class T] [The type of path to use. ] [ - ] [Must be specified]] +[[] [] [ - ] [Must be specified]] +[[error_code &] [] [_ec] [Error code to set. ]] +[[T] [] [_path] [The filing system path to use. ]] +[[future<>] [] [_target] [The item to link to if creating. ]] +[[file_flags] [] [_flags] [The flags to use.]] +] + + +[heading Returns] +A handle to the symlink. + +[heading Header] +`#include <boost/afio/v2/afio.hpp>` + +[heading Race Guarantees][raceguarantees +[raceguarantee FreeBSD, Linux, OS X, Windows..No guarantees.] + ] +[heading Complexity]Amortised O(1) to dispatch. Amortised O(1) to complete if symlink creation is constant time. +[heading Exception Model]Propagates the exception of any input precondition with an errored state at the point of dispatch, and throws a `std::invalid_argument` if any inputs have values which could not possibly be correct. Note that error code returning functions may still throw exceptions e.g. failure to allocate memory. +[heading Example][filedir_example] + + +'''<?dbhtml-include href="disqus_comments.html"?>''' +[endsect] + diff --git a/attic/doc/generated/group_sync.qbk b/attic/doc/generated/group_sync.qbk new file mode 100644 index 00000000..3c48febf --- /dev/null +++ b/attic/doc/generated/group_sync.qbk @@ -0,0 +1,142 @@ +[/============================================================================ + Boost.AFIO + + Use, modification and distribution is subject to the Boost Software License, + Version 1.0. (See accompanying file LICENSE_1_0.txt or copy at + http://www.boost.org/LICENSE_1_0.txt) +=============================================================================/] + + +[/ Generated by doxygen_xml2qbk 1.1.1, don't change, will be overwritten automatically] +[/ Generated from doxy/doxygen_output/xml\group__sync.xml] +[section:sync_1_batch sync (batch)] +'''<?dbhtml-include href="disqus_identifiers/sync_1_batch.html"?>''' + +'''<indexterm><primary>sync</primary></indexterm>''' +Schedule a batch of asynchronous content synchronisations with physical storage after preceding operations. + +[heading Description] +It goes without saying that this call can take very significant amounts of time to complete! + +[heading Synopsis] +``future dispatcher::sync(const std::vector< future<>> & ops)`` + +[heading Parameters] + +[table +[[Type] [Concept] [Name] [Description] ] +[[const std::vector< future<>> &] [] [ops] [A batch of op handles.]] +] + + +[heading Returns] +A batch of op handles. + +[heading Header] +`#include <boost/afio/v2/afio.hpp>` + +[heading Complexity]Amortised O(N) to dispatch. Amortised O(N/threadpool) to complete if content synchronisation is constant time (which is extremely unlikely). +[heading Exception Model]Propagates exceptions of any input preconditions with an errored state at the point of dispatch, and throws a `std::invalid_argument` if any inputs have values which could not possibly be correct. Once a batch of input ops has been verified at the point of entry as not errored, you are guaranteed that the batch is atomically scheduled as a whole, unless a failure to allocate memory occurs. +[heading Example][readwrite_example] + + +'''<?dbhtml-include href="disqus_comments.html"?>''' +[endsect] + +[section:async_sync async_sync] +'''<?dbhtml-include href="disqus_identifiers/async_sync.html"?>''' + +'''<indexterm><primary>async_sync</primary></indexterm>''' +Asynchronous content synchronisation with physical storage after a preceding operation. + +[heading Description] +It goes without saying that this call can take very significant amounts of time to complete! + +[heading Synopsis] +``future async_sync(future<> _precondition)`` + +[heading Parameters] + +[table +[[Type] [Concept] [Name] [Description] ] +[[future<>] [] [_precondition] [The precondition to use.]] +] + + +[heading Returns] +A future<void> + +[heading Header] +`#include <boost/afio/v2/afio.hpp>` + +[heading Complexity]Amortised O(1) to dispatch. Amortised O(1) to complete if content synchronisation is constant time (which is extremely unlikely). +[heading Exception Model]Propagates the exception of any input precondition with an errored state at the point of dispatch, and throws a `std::invalid_argument` if any inputs have values which could not possibly be correct. Note that error code returning functions may still throw exceptions e.g. failure to allocate memory. +[heading Example][readwrite_example] + + +'''<?dbhtml-include href="disqus_comments.html"?>''' +[endsect] + +[section:sync_1_throwing sync (throwing)] +'''<?dbhtml-include href="disqus_identifiers/sync_1_throwing.html"?>''' + +'''<indexterm><primary>sync</primary></indexterm>''' +Synchronous content synchronisation with physical storage after a preceding operation. + +[heading Description] +It goes without saying that this call can take very significant amounts of time to complete! + +[heading Synopsis] +``void sync(future<> _precondition)`` + +[heading Parameters] + +[table +[[Type] [Concept] [Name] [Description] ] +[[future<>] [] [_precondition] [The precondition to use.]] +] + + +[heading Header] +`#include <boost/afio/v2/afio.hpp>` + +[heading Complexity]Amortised O(1) to dispatch. Amortised O(1) to complete if content synchronisation is constant time (which is extremely unlikely). +[heading Exception Model]Propagates the exception of any input precondition with an errored state at the point of dispatch, and throws a `std::invalid_argument` if any inputs have values which could not possibly be correct. Note that error code returning functions may still throw exceptions e.g. failure to allocate memory. +[heading Example][readwrite_example] + + +'''<?dbhtml-include href="disqus_comments.html"?>''' +[endsect] + +[section:sync_2_non_throwing sync (non throwing)] +'''<?dbhtml-include href="disqus_identifiers/sync_2_non_throwing.html"?>''' + +'''<indexterm><primary>sync</primary></indexterm>''' +Synchronous content synchronisation with physical storage after a preceding operation. + +[heading Description] +It goes without saying that this call can take very significant amounts of time to complete! + +[heading Synopsis] +``void sync(error_code & _ec, future<> _precondition)`` + +[heading Parameters] + +[table +[[Type] [Concept] [Name] [Description] ] +[[error_code &] [] [_ec] [Error code to set. ]] +[[future<>] [] [_precondition] [The precondition to use.]] +] + + +[heading Header] +`#include <boost/afio/v2/afio.hpp>` + +[heading Complexity]Amortised O(1) to dispatch. Amortised O(1) to complete if content synchronisation is constant time (which is extremely unlikely). +[heading Exception Model]Propagates the exception of any input precondition with an errored state at the point of dispatch, and throws a `std::invalid_argument` if any inputs have values which could not possibly be correct. Note that error code returning functions may still throw exceptions e.g. failure to allocate memory. +[heading Example][readwrite_example] + + +'''<?dbhtml-include href="disqus_comments.html"?>''' +[endsect] + diff --git a/attic/doc/generated/group_to_asio_buffers.qbk b/attic/doc/generated/group_to_asio_buffers.qbk new file mode 100644 index 00000000..5016e54d --- /dev/null +++ b/attic/doc/generated/group_to_asio_buffers.qbk @@ -0,0 +1,305 @@ +[/============================================================================ + Boost.AFIO + + Use, modification and distribution is subject to the Boost Software License, + Version 1.0. (See accompanying file LICENSE_1_0.txt or copy at + http://www.boost.org/LICENSE_1_0.txt) +=============================================================================/] + + +[/ Generated by doxygen_xml2qbk 1.1.1, don't change, will be overwritten automatically] +[/ Generated from doxy/doxygen_output/xml\group__to__asio__buffers.xml] +[section:to_asio_buffers_1_asio_mutable_buffer to_asio_buffers (asio mutable_buffer)] +'''<?dbhtml-include href="disqus_identifiers/to_asio_buffers_1_asio_mutable_buffer.html"?>''' + +'''<indexterm><primary>to_asio_buffers</primary></indexterm>''' +Passing through asio::mutable\u005fbuffer. + +[heading Synopsis] +``std::vector<asio::mutable_buffer> to_asio_buffers(asio::mutable_buffer & v)`` + +[heading Parameters] + +[table +[[Type] [Concept] [Name] [Description] ] +[[asio::mutable_buffer &] [] [v] []] +] + + +[heading Returns] +A vector of ASIO buffers + +[heading Header] +`#include <boost/afio/v2/afio.hpp>` + + +'''<?dbhtml-include href="disqus_comments.html"?>''' +[endsect] + +[section:to_asio_buffers_1_asio_const_buffer to_asio_buffers (asio const_buffer)] +'''<?dbhtml-include href="disqus_identifiers/to_asio_buffers_1_asio_const_buffer.html"?>''' + +'''<indexterm><primary>to_asio_buffers</primary></indexterm>''' +Passing through asio::const\u005fbuffer. + +[heading Synopsis] +``std::vector<asio::const_buffer> to_asio_buffers(asio::const_buffer & v)`` + +[heading Parameters] + +[table +[[Type] [Concept] [Name] [Description] ] +[[asio::const_buffer &] [] [v] []] +] + + +[heading Returns] +A vector of ASIO buffers + +[heading Header] +`#include <boost/afio/v2/afio.hpp>` + + +'''<?dbhtml-include href="disqus_comments.html"?>''' +[endsect] + +[section:to_asio_buffers_2_buffer_of_t to_asio_buffers (buffer of T)] +'''<?dbhtml-include href="disqus_identifiers/to_asio_buffers_2_buffer_of_t.html"?>''' + +'''<indexterm><primary>to_asio_buffers</primary></indexterm>''' +A buffer at v sized length*sizeof(T) + +[heading Synopsis] +``template<class T> +std::vector<asio::mutable_buffer> to_asio_buffers(T * v, size_t length)`` + +[heading Parameters] + +[table +[[Type] [Concept] [Name] [Description] ] +[[class T] [Any trivial type T ] [ - ] [Must be specified]] +[[T *] [] [v] []] +[[size_t] [] [length] []] +] + + +[heading Returns] +A vector of ASIO buffers + +[heading Header] +`#include <boost/afio/v2/afio.hpp>` + + +'''<?dbhtml-include href="disqus_comments.html"?>''' +[endsect] + +[section:to_asio_buffers_2_const_buffer_of_t to_asio_buffers (const buffer of T)] +'''<?dbhtml-include href="disqus_identifiers/to_asio_buffers_2_const_buffer_of_t.html"?>''' + +'''<indexterm><primary>to_asio_buffers</primary></indexterm>''' +A buffer at v sized length*sizeof(T) + +[heading Synopsis] +``template<class T> +std::vector<asio::const_buffer> to_asio_buffers(const T * v, size_t length)`` + +[heading Parameters] + +[table +[[Type] [Concept] [Name] [Description] ] +[[class T] [Any trivial type T ] [ - ] [Must be specified]] +[[const T *] [] [v] []] +[[size_t] [] [length] []] +] + + +[heading Returns] +A vector of ASIO buffers + +[heading Header] +`#include <boost/afio/v2/afio.hpp>` + + +'''<?dbhtml-include href="disqus_comments.html"?>''' +[endsect] + +[section:to_asio_buffers_2_buffer to_asio_buffers (buffer)] +'''<?dbhtml-include href="disqus_identifiers/to_asio_buffers_2_buffer.html"?>''' + +'''<indexterm><primary>to_asio_buffers</primary></indexterm>''' +A buffer at v sized length. + +[heading Synopsis] +``std::vector<asio::mutable_buffer> to_asio_buffers(void * v, size_t length)`` + +[heading Parameters] + +[table +[[Type] [Concept] [Name] [Description] ] +[[void *] [] [v] []] +[[size_t] [] [length] []] +] + + +[heading Returns] +A vector of ASIO buffers + +[heading Header] +`#include <boost/afio/v2/afio.hpp>` + + +'''<?dbhtml-include href="disqus_comments.html"?>''' +[endsect] + +[section:to_asio_buffers_2_const_buffer_of_t to_asio_buffers (const buffer of T)] +'''<?dbhtml-include href="disqus_identifiers/to_asio_buffers_2_const_buffer_of_t.html"?>''' + +'''<indexterm><primary>to_asio_buffers</primary></indexterm>''' +A buffer at v sized length. + +[heading Synopsis] +``std::vector<asio::const_buffer> to_asio_buffers(const void * v, size_t length)`` + +[heading Parameters] + +[table +[[Type] [Concept] [Name] [Description] ] +[[const void *] [] [v] []] +[[size_t] [] [length] []] +] + + +[heading Returns] +A vector of ASIO buffers + +[heading Header] +`#include <boost/afio/v2/afio.hpp>` + + +'''<?dbhtml-include href="disqus_comments.html"?>''' +[endsect] + +[section:to_asio_buffers_1_trivial_and_container_types to_asio_buffers (trivial and container types)] +'''<?dbhtml-include href="disqus_identifiers/to_asio_buffers_1_trivial_and_container_types.html"?>''' + +'''<indexterm><primary>to_asio_buffers</primary></indexterm>''' +Any trivial type T or STL container. + +[heading Description] +Trivial types turn into a buffer of &v sized sizeof(T). Container types have their value type deduced and to\u005fasio\u005fbuffers() called on that value\u005ftype. Additional specialisations are provided for string, vector and array to collapse the scatter gather buffers into a single one for contiguous storage. + +[heading Synopsis] +``template<class T> +std::vector< asio::mutable_buffer > to_asio_buffers(T & v)`` + +[heading Parameters] + +[table +[[Type] [Concept] [Name] [Description] ] +[[class T] [Any trivial type T or STL container ] [ - ] [Must be specified]] +[[T &] [] [v] []] +] + + +[heading Returns] +A vector of ASIO buffers + +[heading Header] +`#include <boost/afio/v2/afio.hpp>` + + +'''<?dbhtml-include href="disqus_comments.html"?>''' +[endsect] + +[section:to_asio_buffers_1_const_trivial_and_container_types to_asio_buffers (const trivial and container types)] +'''<?dbhtml-include href="disqus_identifiers/to_asio_buffers_1_const_trivial_and_container_types.html"?>''' + +'''<indexterm><primary>to_asio_buffers</primary></indexterm>''' +Any trivial type T or STL container. + +[heading Description] +Trivial types turn into a buffer of &v sized sizeof(T). Container types have their value type deduced and to\u005fasio\u005fbuffers() called on that value\u005ftype. Additional specialisations are provided for string, vector and array to collapse the scatter gather buffers into a single one for contiguous storage. + +[heading Synopsis] +``template<class T> +std::vector< asio::const_buffer > to_asio_buffers(const T & v)`` + +[heading Parameters] + +[table +[[Type] [Concept] [Name] [Description] ] +[[class T] [Any trivial type T or STL container ] [ - ] [Must be specified]] +[[const T &] [] [v] []] +] + + +[heading Returns] +A vector of ASIO buffers + +[heading Header] +`#include <boost/afio/v2/afio.hpp>` + + +'''<?dbhtml-include href="disqus_comments.html"?>''' +[endsect] + +[section:to_asio_buffers_1_c_arrays to_asio_buffers (C arrays)] +'''<?dbhtml-include href="disqus_identifiers/to_asio_buffers_1_c_arrays.html"?>''' + +'''<indexterm><primary>to_asio_buffers</primary></indexterm>''' +A buffer at v sized N*sizeof(T) + +[heading Synopsis] +``template<class T, size_t N> +std::vector< asio::mutable_buffer > to_asio_buffers(T(&) v)`` + +[heading Parameters] + +[table +[[Type] [Concept] [Name] [Description] ] +[[class T] [Any trivial type T ] [ - ] [Must be specified]] +[[N] [] [ - ] [Must be specified]] +[[T(&)] [] [v] []] +] + + +[heading Returns] +A vector of ASIO buffers + +[heading Header] +`#include <boost/afio/v2/afio.hpp>` + + +'''<?dbhtml-include href="disqus_comments.html"?>''' +[endsect] + +[section:to_asio_buffers_1_const_c_arrays to_asio_buffers (const C arrays)] +'''<?dbhtml-include href="disqus_identifiers/to_asio_buffers_1_const_c_arrays.html"?>''' + +'''<indexterm><primary>to_asio_buffers</primary></indexterm>''' +A buffer at v sized N*sizeof(T) + +[heading Synopsis] +``template<class T, size_t N> +std::vector< asio::const_buffer > to_asio_buffers(const T(&) v)`` + +[heading Parameters] + +[table +[[Type] [Concept] [Name] [Description] ] +[[class T] [Any trivial type T ] [ - ] [Must be specified]] +[[N] [] [ - ] [Must be specified]] +[[const T(&)] [] [v] []] +] + + +[heading Returns] +A vector of ASIO buffers + +[heading Header] +`#include <boost/afio/v2/afio.hpp>` + + +'''<?dbhtml-include href="disqus_comments.html"?>''' +[endsect] + diff --git a/attic/doc/generated/group_truncate.qbk b/attic/doc/generated/group_truncate.qbk new file mode 100644 index 00000000..3ee9840f --- /dev/null +++ b/attic/doc/generated/group_truncate.qbk @@ -0,0 +1,134 @@ +[/============================================================================ + Boost.AFIO + + Use, modification and distribution is subject to the Boost Software License, + Version 1.0. (See accompanying file LICENSE_1_0.txt or copy at + http://www.boost.org/LICENSE_1_0.txt) +=============================================================================/] + + +[/ Generated by doxygen_xml2qbk 1.1.1, don't change, will be overwritten automatically] +[/ Generated from doxy/doxygen_output/xml\group__truncate.xml] +[section:truncate_2_batch truncate (batch)] +'''<?dbhtml-include href="disqus_identifiers/truncate_2_batch.html"?>''' + +'''<indexterm><primary>truncate</primary></indexterm>''' +Schedule a batch of asynchronous file length truncations after preceding operations. + +[heading Synopsis] +``future dispatcher::truncate(const std::vector< future<>> & ops, const std::vector< off_t > & sizes)`` + +[heading Parameters] + +[table +[[Type] [Concept] [Name] [Description] ] +[[const std::vector< future<>> &] [] [ops] [A batch of op handles. ]] +[[const std::vector< off_t > &] [] [sizes] [A batch of new lengths.]] +] + + +[heading Returns] +A batch of op handles. + +[heading Header] +`#include <boost/afio/v2/afio.hpp>` + +[heading Complexity]Amortised O(N) to dispatch. Amortised O(N/threadpool) to complete if truncating file lengths is constant time. +[heading Exception Model]Propagates exceptions of any input preconditions with an errored state at the point of dispatch, and throws a `std::invalid_argument` if any inputs have values which could not possibly be correct. Once a batch of input ops has been verified at the point of entry as not errored, you are guaranteed that the batch is atomically scheduled as a whole, unless a failure to allocate memory occurs. +[heading Example][readwrite_example] + + +'''<?dbhtml-include href="disqus_comments.html"?>''' +[endsect] + +[section:async_truncate async_truncate] +'''<?dbhtml-include href="disqus_identifiers/async_truncate.html"?>''' + +'''<indexterm><primary>async_truncate</primary></indexterm>''' +Asynchronous file length truncation after a preceding operation. + +[heading Synopsis] +``future async_truncate(future<> _precondition, off_t newsize)`` + +[heading Parameters] + +[table +[[Type] [Concept] [Name] [Description] ] +[[future<>] [] [_precondition] [The precondition to use. ]] +[[off_t] [] [newsize] [The new size for the file.]] +] + + +[heading Returns] +A future<void> + +[heading Header] +`#include <boost/afio/v2/afio.hpp>` + +[heading Complexity]Amortised O(1) to dispatch. Amortised O(1) to complete if truncating file lengths is constant time. +[heading Exception Model]Propagates the exception of any input precondition with an errored state at the point of dispatch, and throws a `std::invalid_argument` if any inputs have values which could not possibly be correct. Note that error code returning functions may still throw exceptions e.g. failure to allocate memory. +[heading Example][readwrite_example] + + +'''<?dbhtml-include href="disqus_comments.html"?>''' +[endsect] + +[section:truncate_2_throwing truncate (throwing)] +'''<?dbhtml-include href="disqus_identifiers/truncate_2_throwing.html"?>''' + +'''<indexterm><primary>truncate</primary></indexterm>''' +Synchronous file length truncation after a preceding operation. + +[heading Synopsis] +``void truncate(future<> _precondition, off_t newsize)`` + +[heading Parameters] + +[table +[[Type] [Concept] [Name] [Description] ] +[[future<>] [] [_precondition] [The precondition to use. ]] +[[off_t] [] [newsize] [The new size for the file.]] +] + + +[heading Header] +`#include <boost/afio/v2/afio.hpp>` + +[heading Complexity]Amortised O(1) to dispatch. Amortised O(1) to complete if truncating file lengths is constant time. +[heading Exception Model]Propagates the exception of any input precondition with an errored state at the point of dispatch, and throws a `std::invalid_argument` if any inputs have values which could not possibly be correct. Note that error code returning functions may still throw exceptions e.g. failure to allocate memory. +[heading Example][readwrite_example] + + +'''<?dbhtml-include href="disqus_comments.html"?>''' +[endsect] + +[section:truncate_3_non_throwing truncate (non throwing)] +'''<?dbhtml-include href="disqus_identifiers/truncate_3_non_throwing.html"?>''' + +'''<indexterm><primary>truncate</primary></indexterm>''' +Synchronous file length truncation after a preceding operation. + +[heading Synopsis] +``void truncate(error_code & _ec, future<> _precondition, off_t newsize)`` + +[heading Parameters] + +[table +[[Type] [Concept] [Name] [Description] ] +[[error_code &] [] [_ec] [Error code to set. ]] +[[future<>] [] [_precondition] [The precondition to use. ]] +[[off_t] [] [newsize] [The new size for the file.]] +] + + +[heading Header] +`#include <boost/afio/v2/afio.hpp>` + +[heading Complexity]Amortised O(1) to dispatch. Amortised O(1) to complete if truncating file lengths is constant time. +[heading Exception Model]Propagates the exception of any input precondition with an errored state at the point of dispatch, and throws a `std::invalid_argument` if any inputs have values which could not possibly be correct. Note that error code returning functions may still throw exceptions e.g. failure to allocate memory. +[heading Example][readwrite_example] + + +'''<?dbhtml-include href="disqus_comments.html"?>''' +[endsect] + diff --git a/attic/doc/generated/group_utils.qbk b/attic/doc/generated/group_utils.qbk new file mode 100644 index 00000000..31fa7fa9 --- /dev/null +++ b/attic/doc/generated/group_utils.qbk @@ -0,0 +1,200 @@ +[/============================================================================ + Boost.AFIO + + Use, modification and distribution is subject to the Boost Software License, + Version 1.0. (See accompanying file LICENSE_1_0.txt or copy at + http://www.boost.org/LICENSE_1_0.txt) +=============================================================================/] + + +[/ Generated by doxygen_xml2qbk 1.1.1, don't change, will be overwritten automatically] +[/ Generated from doxy/doxygen_output/xml\group__utils.xml] +[section:page_sizes page_sizes] +'''<?dbhtml-include href="disqus_identifiers/page_sizes.html"?>''' + +'''<indexterm><primary>page_sizes</primary></indexterm>''' +Returns the page sizes of this architecture which is useful for calculating direct i/o multiples. + +[heading Synopsis] +``BOOST_AFIO_DECL std::vector<size_t> utils::page_sizes(bool only_actually_available = true)`` + +[heading Parameters] + +[table +[[Type] [Concept] [Name] [Description] ] +[[bool] [] [only_actually_available] [Only return page sizes actually available to the user running this process ]] +] + + +[heading Returns] +The page sizes of this architecture. + +[heading Header] +`#include <boost/afio/v2/afio.hpp>` + +[heading Complexity]Whatever the system API takes (one would hope constant time). +[heading Exception Model]Any error from the operating system or std::bad_alloc. + + +'''<?dbhtml-include href="disqus_comments.html"?>''' +[endsect] + +[section:file_buffer_default_size file_buffer_default_size] +'''<?dbhtml-include href="disqus_identifiers/file_buffer_default_size.html"?>''' + +'''<indexterm><primary>file_buffer_default_size</primary></indexterm>''' +Returns a reasonable default size for page\u005fallocator, typically the closest page size from page\u005fsizes() to 1Mb. + +[heading Synopsis] +``size_t utils::file_buffer_default_size()`` + +[heading Parameters] + +[table +[[Type] [Concept] [Name] [Description] ] +] + + +[heading Returns] +A value of a TLB large page size close to 1Mb. + +[heading Header] +`#include <boost/afio/v2/afio.hpp>` + +[heading Complexity]Whatever the system API takes (one would hope constant time). +[heading Exception Model]Any error from the operating system or std::bad_alloc. + + +'''<?dbhtml-include href="disqus_comments.html"?>''' +[endsect] + +[section:random_fill random_fill] +'''<?dbhtml-include href="disqus_identifiers/random_fill.html"?>''' + +'''<indexterm><primary>random_fill</primary></indexterm>''' +Fills the buffer supplied with cryptographically strong randomness. Uses the OS kernel API. + +[heading Synopsis] +``BOOST_AFIO_DECL void utils::random_fill(char * buffer, size_t bytes)`` + +[heading Parameters] + +[table +[[Type] [Concept] [Name] [Description] ] +[[char *] [] [buffer] [A buffer to fill ]] +[[size_t] [] [bytes] [How many bytes to fill]] +] + + +[heading Header] +`#include <boost/afio/v2/afio.hpp>` + +[heading Complexity]Whatever the system API takes. +[heading Exception Model]Any error from the operating system. + + +'''<?dbhtml-include href="disqus_comments.html"?>''' +[endsect] + +[section:to_hex_string to_hex_string] +'''<?dbhtml-include href="disqus_identifiers/to_hex_string.html"?>''' + +'''<indexterm><primary>to_hex_string</primary></indexterm>''' +Converts a number to a hex string. Out buffer can be same as in buffer. + +[heading Description] +Note that the character range used is a 16 item table of: + +0123456789abcdef + +This lets one pack one byte of input into two bytes of output. + +[heading Synopsis] +``size_t utils::to_hex_string(char * out, size_t outlen, const char * _in, + size_t inlen)`` + +[heading Parameters] + +[table +[[Type] [Concept] [Name] [Description] ] +[[char *] [] [out] []] +[[size_t] [] [outlen] []] +[[const char *] [] [_in] []] +[[size_t] [] [inlen] []] +] + + +[heading Header] +`#include <boost/afio/v2/afio.hpp>` + +[heading Complexity]O(N) where N is the length of the number. +[heading Exception Model]Throws exception if output buffer is too small for input. + + +'''<?dbhtml-include href="disqus_comments.html"?>''' +[endsect] + +[section:from_hex_string from_hex_string] +'''<?dbhtml-include href="disqus_identifiers/from_hex_string.html"?>''' + +'''<indexterm><primary>from_hex_string</primary></indexterm>''' +Converts a hex string to a number. Out buffer can be same as in buffer. + +[heading Description] +Note that this routine is about 43% slower than to\u005fhex\u005fstring(), half of which is due to input validation. + +[heading Synopsis] +``size_t utils::from_hex_string(char * out, size_t outlen, const char * in, + size_t inlen)`` + +[heading Parameters] + +[table +[[Type] [Concept] [Name] [Description] ] +[[char *] [] [out] []] +[[size_t] [] [outlen] []] +[[const char *] [] [in] []] +[[size_t] [] [inlen] []] +] + + +[heading Header] +`#include <boost/afio/v2/afio.hpp>` + +[heading Complexity]O(N) where N is the length of the string. +[heading Exception Model]Throws exception if output buffer is too small for input or input size is not multiple of two. + + +'''<?dbhtml-include href="disqus_comments.html"?>''' +[endsect] + +[section:random_string random_string] +'''<?dbhtml-include href="disqus_identifiers/random_string.html"?>''' + +'''<indexterm><primary>random_string</primary></indexterm>''' +Returns a cryptographically random string capable of being used as a filename. Essentially random\u005ffill() + to\u005fhex\u005fstring(). + +[heading Synopsis] +``std::string utils::random_string(size_t randomlen)`` + +[heading Parameters] + +[table +[[Type] [Concept] [Name] [Description] ] +[[size_t] [] [randomlen] [The number of bytes of randomness to use for the string. ]] +] + + +[heading Returns] +A string representing the randomness at a 2x ratio, so if 32 bytes were requested, this string would be 64 bytes long. + +[heading Header] +`#include <boost/afio/v2/afio.hpp>` + +[heading Complexity]Whatever the system API takes. +[heading Exception Model]Any error from the operating system. + + +'''<?dbhtml-include href="disqus_comments.html"?>''' +[endsect] + diff --git a/attic/doc/generated/group_when_all_futures.qbk b/attic/doc/generated/group_when_all_futures.qbk new file mode 100644 index 00000000..eb9229c5 --- /dev/null +++ b/attic/doc/generated/group_when_all_futures.qbk @@ -0,0 +1,11 @@ +[/============================================================================ + Boost.AFIO + + Use, modification and distribution is subject to the Boost Software License, + Version 1.0. (See accompanying file LICENSE_1_0.txt or copy at + http://www.boost.org/LICENSE_1_0.txt) +=============================================================================/] + + +[/ Generated by doxygen_xml2qbk 1.1.1, don't change, will be overwritten automatically] +[/ Generated from doxy/doxygen_output/xml\group__when__all__futures.xml] diff --git a/attic/doc/generated/group_write.qbk b/attic/doc/generated/group_write.qbk new file mode 100644 index 00000000..1da621c4 --- /dev/null +++ b/attic/doc/generated/group_write.qbk @@ -0,0 +1,272 @@ +[/============================================================================ + Boost.AFIO + + Use, modification and distribution is subject to the Boost Software License, + Version 1.0. (See accompanying file LICENSE_1_0.txt or copy at + http://www.boost.org/LICENSE_1_0.txt) +=============================================================================/] + + +[/ Generated by doxygen_xml2qbk 1.1.1, don't change, will be overwritten automatically] +[/ Generated from doxy/doxygen_output/xml\group__write.xml] +[section:write_1_batch write (batch)] +'''<?dbhtml-include href="disqus_identifiers/write_1_batch.html"?>''' + +'''<indexterm><primary>write</primary></indexterm>''' +Schedule a batch of asynchronous data writes after preceding operations, where offset and total data written must not exceed the present file size. + +[heading Description] +Related types: [^`__afio_io_req__`] Note that on Windows this call issues a separate async file operation for each buffer supplied, thus making scatter/gather i/o no more efficient than making separate calls. The big exception to this is when doing unbuffered page aligned i/o for which Windows provides special scatter/gather i/o functions. You should therefore assume that only each buffer is atomically read or written rather than the full sequence of buffers at once (this also applies to POSIX systems without the preadv()/pwritev() operations). + +[heading Synopsis] +``template<class T> +virtual std::vector<future<> > dispatcher::write(const std::vector< io_req< const T >> & ops)`` + +[heading Parameters] + +[table +[[Type] [Concept] [Name] [Description] ] +[[class T] [Any type. ] [ - ] [Must be specified]] +[[const std::vector< io_req< const T >> &] [] [ops] [A batch of io_req<const T> structures.]] +] + + +[heading Returns] +A batch of op handles. + +[heading Header] +`#include <boost/afio/v2/afio.hpp>` + +[heading Complexity]Amortised O(N) to dispatch. Amortised O(N/threadpool) to complete if writing data is constant time. +[heading Exception Model]Propagates exceptions of any input preconditions with an errored state at the point of dispatch, and throws a `std::invalid_argument` if any inputs have values which could not possibly be correct. Once a batch of input ops has been verified at the point of entry as not errored, you are guaranteed that the batch is atomically scheduled as a whole, unless a failure to allocate memory occurs. +[heading Example][readwrite_example] + + +'''<?dbhtml-include href="disqus_comments.html"?>''' +[endsect] + +[section:async_write_3_length_deducing async_write (length deducing)] +'''<?dbhtml-include href="disqus_identifiers/async_write_3_length_deducing.html"?>''' + +'''<indexterm><primary>async_write</primary></indexterm>''' +Asynchronous data write after a preceding operation, where offset and total data written must not exceed the present file size. + +[heading Description] +Related types: [^`__afio_io_req__`] Note that on Windows this call issues a separate async file operation for each buffer supplied, thus making scatter/gather i/o no more efficient than making separate calls. The big exception to this is when doing unbuffered page aligned i/o for which Windows provides special scatter/gather i/o functions. You should therefore assume that only each buffer is atomically read or written rather than the full sequence of buffers at once (this also applies to POSIX systems without the preadv()/pwritev() operations). + +[heading Synopsis] +``template<class T> +future async_write(future<> _precondition, T && v, off_t _where)`` + +[heading Parameters] + +[table +[[Type] [Concept] [Name] [Description] ] +[[class T] [Any type. ] [ - ] [Must be specified]] +[[future<>] [] [_precondition] [The precondition to use. ]] +[[T &&] [] [v] [Some item understood by [^`to_asio_buffers()`]]] +[[off_t] [] [_where] [The file offset to do the i/o]] +] + + +[heading Returns] +A future<void> + +[heading Header] +`#include <boost/afio/v2/afio.hpp>` + +[heading Complexity]Amortised O(1) to dispatch. Amortised O(1) to complete if writing data is constant time. +[heading Exception Model]Propagates the exception of any input precondition with an errored state at the point of dispatch, and throws a `std::invalid_argument` if any inputs have values which could not possibly be correct. Note that error code returning functions may still throw exceptions e.g. failure to allocate memory. +[heading Example][readwrite_example] + + +'''<?dbhtml-include href="disqus_comments.html"?>''' +[endsect] + +[section:async_write_4_length_specifying async_write (length specifying)] +'''<?dbhtml-include href="disqus_identifiers/async_write_4_length_specifying.html"?>''' + +'''<indexterm><primary>async_write</primary></indexterm>''' +Asynchronous data write after a preceding operation, where offset and total data written must not exceed the present file size. + +[heading Description] +Related types: [^`__afio_io_req__`] Note that on Windows this call issues a separate async file operation for each buffer supplied, thus making scatter/gather i/o no more efficient than making separate calls. The big exception to this is when doing unbuffered page aligned i/o for which Windows provides special scatter/gather i/o functions. You should therefore assume that only each buffer is atomically read or written rather than the full sequence of buffers at once (this also applies to POSIX systems without the preadv()/pwritev() operations). + +[heading Synopsis] +``template<class T> +future async_write(future<> _precondition, T && v, size_t _length, + off_t _where)`` + +[heading Parameters] + +[table +[[Type] [Concept] [Name] [Description] ] +[[class T] [Any type. ] [ - ] [Must be specified]] +[[future<>] [] [_precondition] [The precondition to use. ]] +[[T &&] [] [v] [Some item understood by [^`to_asio_buffers()`]]] +[[size_t] [] [_length] [The length of the item ]] +[[off_t] [] [_where] [The file offset to do the i/o]] +] + + +[heading Returns] +A future<void> + +[heading Header] +`#include <boost/afio/v2/afio.hpp>` + +[heading Complexity]Amortised O(1) to dispatch. Amortised O(1) to complete if writing data is constant time. +[heading Exception Model]Propagates the exception of any input precondition with an errored state at the point of dispatch, and throws a `std::invalid_argument` if any inputs have values which could not possibly be correct. Note that error code returning functions may still throw exceptions e.g. failure to allocate memory. +[heading Example][readwrite_example] + + +'''<?dbhtml-include href="disqus_comments.html"?>''' +[endsect] + +[section:write_3_length_deducing_throwing write (length deducing throwing)] +'''<?dbhtml-include href="disqus_identifiers/write_3_length_deducing_throwing.html"?>''' + +'''<indexterm><primary>write</primary></indexterm>''' +Synchronous data write after a preceding operation, where offset and total data written must not exceed the present file size. + +[heading Description] +Related types: [^`__afio_io_req__`] Note that on Windows this call issues a separate async file operation for each buffer supplied, thus making scatter/gather i/o no more efficient than making separate calls. The big exception to this is when doing unbuffered page aligned i/o for which Windows provides special scatter/gather i/o functions. You should therefore assume that only each buffer is atomically read or written rather than the full sequence of buffers at once (this also applies to POSIX systems without the preadv()/pwritev() operations). + +[heading Synopsis] +``template<class T> +void write(future<> _precondition, T && v, off_t _where)`` + +[heading Parameters] + +[table +[[Type] [Concept] [Name] [Description] ] +[[class T] [Any type. ] [ - ] [Must be specified]] +[[future<>] [] [_precondition] [The precondition to use. ]] +[[T &&] [] [v] [Some item understood by [^`to_asio_buffers()`]]] +[[off_t] [] [_where] [The file offset to do the i/o]] +] + + +[heading Header] +`#include <boost/afio/v2/afio.hpp>` + +[heading Complexity]Amortised O(1) to dispatch. Amortised O(1) to complete if writing data is constant time. +[heading Exception Model]Propagates the exception of any input precondition with an errored state at the point of dispatch, and throws a `std::invalid_argument` if any inputs have values which could not possibly be correct. Note that error code returning functions may still throw exceptions e.g. failure to allocate memory. +[heading Example][readwrite_example] + + +'''<?dbhtml-include href="disqus_comments.html"?>''' +[endsect] + +[section:write_4_length_specifying_throwing write (length specifying throwing)] +'''<?dbhtml-include href="disqus_identifiers/write_4_length_specifying_throwing.html"?>''' + +'''<indexterm><primary>write</primary></indexterm>''' +Synchronous data write after a preceding operation, where offset and total data written must not exceed the present file size. + +[heading Description] +Related types: [^`__afio_io_req__`] Note that on Windows this call issues a separate async file operation for each buffer supplied, thus making scatter/gather i/o no more efficient than making separate calls. The big exception to this is when doing unbuffered page aligned i/o for which Windows provides special scatter/gather i/o functions. You should therefore assume that only each buffer is atomically read or written rather than the full sequence of buffers at once (this also applies to POSIX systems without the preadv()/pwritev() operations). + +[heading Synopsis] +``template<class T> +void write(future<> _precondition, T && v, size_t _length, + off_t _where)`` + +[heading Parameters] + +[table +[[Type] [Concept] [Name] [Description] ] +[[class T] [Any type. ] [ - ] [Must be specified]] +[[future<>] [] [_precondition] [The precondition to use. ]] +[[T &&] [] [v] [Some item understood by [^`to_asio_buffers()`]]] +[[size_t] [] [_length] [The length of the item ]] +[[off_t] [] [_where] [The file offset to do the i/o]] +] + + +[heading Header] +`#include <boost/afio/v2/afio.hpp>` + +[heading Complexity]Amortised O(1) to dispatch. Amortised O(1) to complete if writing data is constant time. +[heading Exception Model]Propagates the exception of any input precondition with an errored state at the point of dispatch, and throws a `std::invalid_argument` if any inputs have values which could not possibly be correct. Note that error code returning functions may still throw exceptions e.g. failure to allocate memory. +[heading Example][readwrite_example] + + +'''<?dbhtml-include href="disqus_comments.html"?>''' +[endsect] + +[section:write_4_length_deducing_non_throwing write (length deducing non throwing)] +'''<?dbhtml-include href="disqus_identifiers/write_4_length_deducing_non_throwing.html"?>''' + +'''<indexterm><primary>write</primary></indexterm>''' +Synchronous data write after a preceding operation, where offset and total data written must not exceed the present file size. + +[heading Description] +Related types: [^`__afio_io_req__`] Note that on Windows this call issues a separate async file operation for each buffer supplied, thus making scatter/gather i/o no more efficient than making separate calls. The big exception to this is when doing unbuffered page aligned i/o for which Windows provides special scatter/gather i/o functions. You should therefore assume that only each buffer is atomically read or written rather than the full sequence of buffers at once (this also applies to POSIX systems without the preadv()/pwritev() operations). + +[heading Synopsis] +``template<class T> +void write(error_code & _ec, future<> _precondition, T && v, + off_t _where)`` + +[heading Parameters] + +[table +[[Type] [Concept] [Name] [Description] ] +[[class T] [Any type. ] [ - ] [Must be specified]] +[[error_code &] [] [_ec] [Error code to set. ]] +[[future<>] [] [_precondition] [The precondition to use. ]] +[[T &&] [] [v] [Some item understood by [^`to_asio_buffers()`]]] +[[off_t] [] [_where] [The file offset to do the i/o]] +] + + +[heading Header] +`#include <boost/afio/v2/afio.hpp>` + +[heading Complexity]Amortised O(1) to dispatch. Amortised O(1) to complete if writing data is constant time. +[heading Exception Model]Propagates the exception of any input precondition with an errored state at the point of dispatch, and throws a `std::invalid_argument` if any inputs have values which could not possibly be correct. Note that error code returning functions may still throw exceptions e.g. failure to allocate memory. +[heading Example][readwrite_example] + + +'''<?dbhtml-include href="disqus_comments.html"?>''' +[endsect] + +[section:write_5_length_specifying_non_throwing write (length specifying non throwing)] +'''<?dbhtml-include href="disqus_identifiers/write_5_length_specifying_non_throwing.html"?>''' + +'''<indexterm><primary>write</primary></indexterm>''' +Synchronous data write after a preceding operation, where offset and total data written must not exceed the present file size. + +[heading Description] +Related types: [^`__afio_io_req__`] Note that on Windows this call issues a separate async file operation for each buffer supplied, thus making scatter/gather i/o no more efficient than making separate calls. The big exception to this is when doing unbuffered page aligned i/o for which Windows provides special scatter/gather i/o functions. You should therefore assume that only each buffer is atomically read or written rather than the full sequence of buffers at once (this also applies to POSIX systems without the preadv()/pwritev() operations). + +[heading Synopsis] +``template<class T> +void write(error_code & _ec, future<> _precondition, T && v, + size_t _length, off_t _where)`` + +[heading Parameters] + +[table +[[Type] [Concept] [Name] [Description] ] +[[class T] [Any type. ] [ - ] [Must be specified]] +[[error_code &] [] [_ec] [Error code to set. ]] +[[future<>] [] [_precondition] [The precondition to use. ]] +[[T &&] [] [v] [Some item understood by [^`to_asio_buffers()`]]] +[[size_t] [] [_length] [The length of the item ]] +[[off_t] [] [_where] [The file offset to do the i/o]] +] + + +[heading Header] +`#include <boost/afio/v2/afio.hpp>` + +[heading Complexity]Amortised O(1) to dispatch. Amortised O(1) to complete if writing data is constant time. +[heading Exception Model]Propagates the exception of any input precondition with an errored state at the point of dispatch, and throws a `std::invalid_argument` if any inputs have values which could not possibly be correct. Note that error code returning functions may still throw exceptions e.g. failure to allocate memory. +[heading Example][readwrite_example] + + +'''<?dbhtml-include href="disqus_comments.html"?>''' +[endsect] + diff --git a/attic/doc/generated/group_zero.qbk b/attic/doc/generated/group_zero.qbk new file mode 100644 index 00000000..49c2d3b0 --- /dev/null +++ b/attic/doc/generated/group_zero.qbk @@ -0,0 +1,146 @@ +[/============================================================================ + Boost.AFIO + + Use, modification and distribution is subject to the Boost Software License, + Version 1.0. (See accompanying file LICENSE_1_0.txt or copy at + http://www.boost.org/LICENSE_1_0.txt) +=============================================================================/] + + +[/ Generated by doxygen_xml2qbk 1.1.1, don't change, will be overwritten automatically] +[/ Generated from doxy/doxygen_output/xml\group__zero.xml] +[section:zero_2_batch zero (batch)] +'''<?dbhtml-include href="disqus_identifiers/zero_2_batch.html"?>''' + +'''<indexterm><primary>zero</primary></indexterm>''' +Schedule a batch of asynchronous zeroing and deallocations of physical storage ("hole punching") after preceding operations. + +[heading Description] +Most extent based filing systems provide an optimised way of zeroing parts of a file by deallocating the storage backing those regions, and marking those regions as unwritten instead of actually writing zero bytes to storage. They appear as zeroes to anything reading those ranges, and have the big advantage of not consuming any actual physical storage. On Windows, extent deallocation writes zeros for ordinary files and only actually deallocates physical storage if the file is sparse or compressed (note that AFIO by default creates sparse files where possible, and converts any file opened for writing to a sparse file). For your information, deallocation on NTFS is on a 64Kb granularity, but the zeros are written at a byte granularity. On Linux, an attempt is made to use FALLOC\u005fFL\u005fPUNCH\u005fHOLE which if it fails then a write of zeros corresponding to the same ranges is made instead. On FreeBSD, long runs of zeros are automatically detected and eliminated on physical storage, and so zeros are simply written. On OS X, there is no formal hole punching API that we are aware of, and so zeros are simply written. + +[heading Synopsis] +``future dispatcher::zero(const std::vector< future<>> & ops, const std::vector< std::vector< std::pair< off_t, off_t >>> & ranges)`` + +[heading Parameters] + +[table +[[Type] [Concept] [Name] [Description] ] +[[const std::vector< future<>> &] [] [ops] [A batch of op handles. ]] +[[const std::vector< std::vector< std::pair< off_t, off_t >>> &] [] [ranges] [A batch of vectors of extents to zero and deallocate.]] +] + + +[heading Returns] +A batch of op handles. + +[heading Header] +`#include <boost/afio/v2/afio.hpp>` + +[heading Complexity]Amortised O(N) to dispatch. Amortised O(N/threadpool) to complete if deallocation is constant time. +[heading Exception Model]Propagates exceptions of any input preconditions with an errored state at the point of dispatch, and throws a `std::invalid_argument` if any inputs have values which could not possibly be correct. Once a batch of input ops has been verified at the point of entry as not errored, you are guaranteed that the batch is atomically scheduled as a whole, unless a failure to allocate memory occurs. +[heading Example][extents_example] + + +'''<?dbhtml-include href="disqus_comments.html"?>''' +[endsect] + +[section:async_zero async_zero] +'''<?dbhtml-include href="disqus_identifiers/async_zero.html"?>''' + +'''<indexterm><primary>async_zero</primary></indexterm>''' +Asynchronous zeroing and deallocation of physical storage ("hole punching") after a preceding operation. + +[heading Description] +Most extent based filing systems provide an optimised way of zeroing parts of a file by deallocating the storage backing those regions, and marking those regions as unwritten instead of actually writing zero bytes to storage. They appear as zeroes to anything reading those ranges, and have the big advantage of not consuming any actual physical storage. On Windows, extent deallocation writes zeros for ordinary files and only actually deallocates physical storage if the file is sparse or compressed (note that AFIO by default creates sparse files where possible, and converts any file opened for writing to a sparse file). For your information, deallocation on NTFS is on a 64Kb granularity, but the zeros are written at a byte granularity. On Linux, an attempt is made to use FALLOC\u005fFL\u005fPUNCH\u005fHOLE which if it fails then a write of zeros corresponding to the same ranges is made instead. On FreeBSD, long runs of zeros are automatically detected and eliminated on physical storage, and so zeros are simply written. On OS X, there is no formal hole punching API that we are aware of, and so zeros are simply written. + +[heading Synopsis] +``future async_zero(future<> _precondition, std::vector< std::pair< off_t, off_t >> ranges)`` + +[heading Parameters] + +[table +[[Type] [Concept] [Name] [Description] ] +[[future<>] [] [_precondition] [The precondition to use. ]] +[[std::vector< std::pair< off_t, off_t >>] [] [ranges] [A sequence of extents to zero and deallocate]] +] + + +[heading Returns] +A future<void> + +[heading Header] +`#include <boost/afio/v2/afio.hpp>` + +[heading Complexity]Amortised O(1) to dispatch. Amortised O(1) to complete if deallocation is constant time. +[heading Exception Model]Propagates the exception of any input precondition with an errored state at the point of dispatch, and throws a `std::invalid_argument` if any inputs have values which could not possibly be correct. Note that error code returning functions may still throw exceptions e.g. failure to allocate memory. +[heading Example][extents_example] + + +'''<?dbhtml-include href="disqus_comments.html"?>''' +[endsect] + +[section:zero_2_throwing zero (throwing)] +'''<?dbhtml-include href="disqus_identifiers/zero_2_throwing.html"?>''' + +'''<indexterm><primary>zero</primary></indexterm>''' +Synchronous zeroing and deallocation of physical storage ("hole punching") after a preceding operation. + +[heading Description] +Most extent based filing systems provide an optimised way of zeroing parts of a file by deallocating the storage backing those regions, and marking those regions as unwritten instead of actually writing zero bytes to storage. They appear as zeroes to anything reading those ranges, and have the big advantage of not consuming any actual physical storage. On Windows, extent deallocation writes zeros for ordinary files and only actually deallocates physical storage if the file is sparse or compressed (note that AFIO by default creates sparse files where possible, and converts any file opened for writing to a sparse file). For your information, deallocation on NTFS is on a 64Kb granularity, but the zeros are written at a byte granularity. On Linux, an attempt is made to use FALLOC\u005fFL\u005fPUNCH\u005fHOLE which if it fails then a write of zeros corresponding to the same ranges is made instead. On FreeBSD, long runs of zeros are automatically detected and eliminated on physical storage, and so zeros are simply written. On OS X, there is no formal hole punching API that we are aware of, and so zeros are simply written. + +[heading Synopsis] +``void zero(future<> _precondition, std::vector< std::pair< off_t, off_t >> ranges)`` + +[heading Parameters] + +[table +[[Type] [Concept] [Name] [Description] ] +[[future<>] [] [_precondition] [The precondition to use. ]] +[[std::vector< std::pair< off_t, off_t >>] [] [ranges] [A sequence of extents to zero and deallocate]] +] + + +[heading Header] +`#include <boost/afio/v2/afio.hpp>` + +[heading Complexity]Amortised O(1) to dispatch. Amortised O(1) to complete if deallocation is constant time. +[heading Exception Model]Propagates the exception of any input precondition with an errored state at the point of dispatch, and throws a `std::invalid_argument` if any inputs have values which could not possibly be correct. Note that error code returning functions may still throw exceptions e.g. failure to allocate memory. +[heading Example][extents_example] + + +'''<?dbhtml-include href="disqus_comments.html"?>''' +[endsect] + +[section:zero_3_non_throwing zero (non throwing)] +'''<?dbhtml-include href="disqus_identifiers/zero_3_non_throwing.html"?>''' + +'''<indexterm><primary>zero</primary></indexterm>''' +Synchronous zeroing and deallocation of physical storage ("hole punching") after a preceding operation. + +[heading Description] +Most extent based filing systems provide an optimised way of zeroing parts of a file by deallocating the storage backing those regions, and marking those regions as unwritten instead of actually writing zero bytes to storage. They appear as zeroes to anything reading those ranges, and have the big advantage of not consuming any actual physical storage. On Windows, extent deallocation writes zeros for ordinary files and only actually deallocates physical storage if the file is sparse or compressed (note that AFIO by default creates sparse files where possible, and converts any file opened for writing to a sparse file). For your information, deallocation on NTFS is on a 64Kb granularity, but the zeros are written at a byte granularity. On Linux, an attempt is made to use FALLOC\u005fFL\u005fPUNCH\u005fHOLE which if it fails then a write of zeros corresponding to the same ranges is made instead. On FreeBSD, long runs of zeros are automatically detected and eliminated on physical storage, and so zeros are simply written. On OS X, there is no formal hole punching API that we are aware of, and so zeros are simply written. + +[heading Synopsis] +``void zero(error_code & _ec, future<> _precondition, std::vector< std::pair< off_t, off_t >> ranges)`` + +[heading Parameters] + +[table +[[Type] [Concept] [Name] [Description] ] +[[error_code &] [] [_ec] [Error code to set. ]] +[[future<>] [] [_precondition] [The precondition to use. ]] +[[std::vector< std::pair< off_t, off_t >>] [] [ranges] [A sequence of extents to zero and deallocate]] +] + + +[heading Header] +`#include <boost/afio/v2/afio.hpp>` + +[heading Complexity]Amortised O(1) to dispatch. Amortised O(1) to complete if deallocation is constant time. +[heading Exception Model]Propagates the exception of any input precondition with an errored state at the point of dispatch, and throws a `std::invalid_argument` if any inputs have values which could not possibly be correct. Note that error code returning functions may still throw exceptions e.g. failure to allocate memory. +[heading Example][extents_example] + + +'''<?dbhtml-include href="disqus_comments.html"?>''' +[endsect] + diff --git a/attic/doc/generated/struct_directory_entry_hash.qbk b/attic/doc/generated/struct_directory_entry_hash.qbk new file mode 100644 index 00000000..e5376aa6 --- /dev/null +++ b/attic/doc/generated/struct_directory_entry_hash.qbk @@ -0,0 +1,45 @@ +[/============================================================================ + Boost.AFIO + + Use, modification and distribution is subject to the Boost Software License, + Version 1.0. (See accompanying file LICENSE_1_0.txt or copy at + http://www.boost.org/LICENSE_1_0.txt) +=============================================================================/] + + +[/ Generated by doxygen_xml2qbk 1.1.1, don't change, will be overwritten automatically] +[/ Generated from doxy/doxygen_output/xml\structboost_1_1afio_1_1directory__entry__hash.xml] +[section:directory_entry_hash directory_entry_hash] +'''<?dbhtml-include href="disqus_identifiers/directory_entry_hash.html"?>''' + +'''<indexterm><primary>directory_entry_hash</primary></indexterm>''' +A hasher for directory_entry, hashing inode and birth time (if available on this platform). + +[heading Synopsis] +``struct directory_entry_hash +{ + // ... +}; +`` + +[heading Member Function(s)] +[table +[[Function] [Description] [Parameters] [Returns]] +[[``size_t operator()(const directory_entry & p)`` + +] [] [[* const directory_entry &]: ['p]: + + + +][ + +] +] +] + +[heading Header] +`#include <boost/afio/v2/afio.hpp>` + +'''<?dbhtml-include href="disqus_comments.html"?>''' +[endsect] + diff --git a/attic/doc/generated/struct_enumerate_req.qbk b/attic/doc/generated/struct_enumerate_req.qbk new file mode 100644 index 00000000..b520807b --- /dev/null +++ b/attic/doc/generated/struct_enumerate_req.qbk @@ -0,0 +1,146 @@ +[/============================================================================ + Boost.AFIO + + Use, modification and distribution is subject to the Boost Software License, + Version 1.0. (See accompanying file LICENSE_1_0.txt or copy at + http://www.boost.org/LICENSE_1_0.txt) +=============================================================================/] + + +[/ Generated by doxygen_xml2qbk 1.1.1, don't change, will be overwritten automatically] +[/ Generated from doxy/doxygen_output/xml\structboost_1_1afio_1_1enumerate__req.xml] +[section:enumerate_req enumerate_req] +'''<?dbhtml-include href="disqus_identifiers/enumerate_req.html"?>''' +[section:filter filter] +'''<?dbhtml-include href="disqus_identifiers/filter.html"?>''' + +'''<indexterm><primary>filter</primary></indexterm>''' +'''<indexterm><primary>none</primary></indexterm>''' +'''<indexterm><primary>fastdeleted</primary></indexterm>''' +How to do deleted file elimination on Windows. + +[heading Synopsis] +``enum filter {none, fastdeleted};`` + +[heading Values] + +[table +[[Value] [Description] ] +[[none] [Do no filtering at all. ]] +[[fastdeleted] [Filter out AFIO deleted files based on their filename (fast and fairly reliable) ]] +] + + +[heading Header] +`#include <boost/afio/v2/afio.hpp>` + + +'''<?dbhtml-include href="disqus_comments.html"?>''' +[endsect] + + +'''<indexterm><primary>enumerate_req</primary></indexterm>''' +A convenience bundle of precondition, number of items to enumerate, item pattern match and metadata to prefetch. + +[heading Description] +You should note that shell globs must use a restricted form for portability: + +Microsoft Windows NT oddly does not specify what wildcards are permitted, but I think the documentation for the kernel function FsRtlIsNameInExpression() is probably sound: * means zero or more characters, ? means any one character. Do not use <, > or " as these have special MS-DOS compatibility inducing consequences. Do not use ^ as this is the Windows wildcard escape character. + +POSIX further extends NT's wildcards with \[seq\] which is a subset of characters and \[!seq\] which is not any subset of characters. Here a \ is the wildcard escape character. + +[heading Synopsis] +``struct enumerate_req +{ + future precondition; // A precondition for this operation. + size_t maxitems; // The maximum number of items to return in this request. Note that setting to one will often invoke two syscalls. + bool restart; // Restarts the enumeration for this open directory handle. + path glob; // An optional shell glob by which to filter the items returned. Done kernel side on Windows, user side on POSIX. + metadata_flags metadata; // The metadata to prefetch for each item enumerated. AFIO may fetch more metadata than requested if it is cost free. + filter filtering; // Any filtering you want AFIO to do for you. +}; +`` + +[heading Constructor(s)] +[table +[[Function] [Description] [Parameters] ] +[[``enumerate_req()`` + +] [Default constructor. ] [ + +]] +[[``enumerate_req(future<> _precondition, size_t _maxitems = 2, bool _restart = true, + path _glob = path(), metadata_flags _metadata = metadata_flags::None, filter _filtering = filter::fastdeleted)`` + +] [Constructs an instance. ] [[* future<>]: ['_precondition]: The precondition for this operation. + +[* size_t]: ['_maxitems]: The maximum number of items to return in this request. Note that setting to one will often invoke two syscalls. + +[* bool]: ['_restart]: Restarts the enumeration for this open directory handle. + +[* path]: ['_glob]: An optional shell glob by which to filter the items returned. Done kernel side on Windows, user side on POSIX. + +[* metadata_flags]: ['_metadata]: The metadata to prefetch for each item enumerated. AFIO may fetch more metadata than requested if it is cost free. + +[* filter]: ['_filtering]: Any filtering you want AFIO to do for you. + + + +]] +[[``enumerate_req(future<> _precondition, path _glob, size_t _maxitems = 2, + bool _restart = true, metadata_flags _metadata = metadata_flags::None, filter _filtering = filter::fastdeleted)`` + +] [Constructs an instance. ] [[* future<>]: ['_precondition]: The precondition for this operation. + +[* path]: ['_glob]: A shell glob by which to filter the items returned. Done kernel side on Windows, user side on POSIX. + +[* size_t]: ['_maxitems]: The maximum number of items to return in this request. Note that setting to one will often invoke two syscalls. + +[* bool]: ['_restart]: Restarts the enumeration for this open directory handle. + +[* metadata_flags]: ['_metadata]: The metadata to prefetch for each item enumerated. AFIO may fetch more metadata than requested if it is cost free. + +[* filter]: ['_filtering]: Any filtering you want AFIO to do for you. + + + +]] +[[``enumerate_req(future<> _precondition, metadata_flags _metadata, size_t _maxitems = 2, + bool _restart = true, path _glob = path(), filter _filtering = filter::fastdeleted)`` + +] [Constructs an instance. ] [[* future<>]: ['_precondition]: The precondition for this operation. + +[* metadata_flags]: ['_metadata]: The metadata to prefetch for each item enumerated. AFIO may fetch more metadata than requested if it is cost free. + +[* size_t]: ['_maxitems]: The maximum number of items to return in this request. Note that setting to one will often invoke two syscalls. + +[* bool]: ['_restart]: Restarts the enumeration for this open directory handle. + +[* path]: ['_glob]: An optional shell glob by which to filter the items returned. Done kernel side on Windows, user side on POSIX. + +[* filter]: ['_filtering]: Any filtering you want AFIO to do for you. + + + +]] +] + +[heading Member Function(s)] +[table +[[Function] [Description] [Parameters] [Returns]] +[[``bool validate()`` + +] [Validates contents. ] [ + +][ + +] +] +] + +[heading Header] +`#include <boost/afio/v2/afio.hpp>` + +'''<?dbhtml-include href="disqus_comments.html"?>''' +[endsect] + diff --git a/attic/doc/generated/struct_handle_1_1mapped_file.qbk b/attic/doc/generated/struct_handle_1_1mapped_file.qbk new file mode 100644 index 00000000..d1f6eff3 --- /dev/null +++ b/attic/doc/generated/struct_handle_1_1mapped_file.qbk @@ -0,0 +1,96 @@ +[/============================================================================ + Boost.AFIO + + Use, modification and distribution is subject to the Boost Software License, + Version 1.0. (See accompanying file LICENSE_1_0.txt or copy at + http://www.boost.org/LICENSE_1_0.txt) +=============================================================================/] + + +[/ Generated by doxygen_xml2qbk 1.1.1, don't change, will be overwritten automatically] +[/ Generated from doxy/doxygen_output/xml\structboost_1_1afio_1_1handle_1_1mapped__file.xml] +[section:handle_mapped_file handle::mapped_file] +'''<?dbhtml-include href="disqus_identifiers/handle_mapped_file.html"?>''' + +'''<indexterm><primary>handle</primary></indexterm><indexterm><primary>mapped_file</primary></indexterm>''' +A holder of a mapped file. + +[heading Synopsis] +``struct handle::mapped_file +{ + handle_ptr h; // The file being mapped. + void * addr; // The address in memory of the map. + size_t length; // The length of the map. + off_t offset; // The offset of the map into the file. +}; +`` + +[heading Constructor(s)] +[table +[[Function] [Description] [Parameters] ] +[[``mapped_file(const mapped_file & )`` + +] [] [[* const mapped_file &]: [']: + + + +]] +[[``mapped_file(mapped_file && )`` + +] [] [[* mapped_file &&]: [']: + + + +]] +[[``mapped_file(handle_ptr _h, void * _addr, size_t _length, + off_t _offset)`` + +] [] [[* handle_ptr]: ['_h]: + +[* void *]: ['_addr]: + +[* size_t]: ['_length]: + +[* off_t]: ['_offset]: + + + +]] +[[``~mapped_file()`` + +] [] [ + +]] +] + +[heading Member Function(s)] +[table +[[Function] [Description] [Parameters] [Returns]] +[[``mapped_file & operator=(const mapped_file & )`` + +] [] [[* const mapped_file &]: [']: + + + +][ + +] +] +[[``mapped_file & operator=(mapped_file && )`` + +] [] [[* mapped_file &&]: [']: + + + +][ + +] +] +] + +[heading Header] +`#include <boost/afio/v2/afio.hpp>` + +'''<?dbhtml-include href="disqus_comments.html"?>''' +[endsect] + diff --git a/attic/doc/generated/struct_io_req.qbk b/attic/doc/generated/struct_io_req.qbk new file mode 100644 index 00000000..e56000cb --- /dev/null +++ b/attic/doc/generated/struct_io_req.qbk @@ -0,0 +1,136 @@ +[/============================================================================ + Boost.AFIO + + Use, modification and distribution is subject to the Boost Software License, + Version 1.0. (See accompanying file LICENSE_1_0.txt or copy at + http://www.boost.org/LICENSE_1_0.txt) +=============================================================================/] + + +[/ Generated by doxygen_xml2qbk 1.1.1, don't change, will be overwritten automatically] +[/ Generated from doxy/doxygen_output/xml\structboost_1_1afio_1_1io__req.xml] +[section:io_req io_req] +'''<?dbhtml-include href="disqus_identifiers/io_req.html"?>''' + +'''<indexterm><primary>io_req</primary></indexterm>''' +A convenience bundle of precondition, data and where for reading into a T as specified by its to_asio_buffers() overload. Data [*MUST] stay around until the operation completes. + +[heading Synopsis] +``template<class T> +struct io_req + : public detail::io_req_impl< false > +{ + future precondition; // A precondition containing an open file handle for this operation. + std::vector< asio::mutable_buffer > buffers; // A sequence of mutable Boost.ASIO buffers to read into. + off_t where; // The offset from which to read. +}; +`` + +[heading Template parameter(s)] +[table +[[Parameter] [Description]] +[[class T] [Any readable (if const) or writable (if non-const) type T as specified by its to_asio_buffers() overload. ]] +] + +[heading Constructor(s)] +[table +[[Function] [Description] [Parameters] ] +[[``io_req()`` + +] [Default constructor. ] [ + +]] +[[``io_req(const io_req & o)`` + +] [Copy constructor. ] [[* const io_req &]: ['o]: + + + +]] +[[``io_req(io_req && o)`` + +] [Move constructor. ] [[* io_req &&]: ['o]: + + + +]] +[[``io_req(future<> _precondition, T * v, size_t _length, + off_t _where)`` + +] [Constructs an instance. ] [[* future<>]: ['_precondition]: An optional precondition for this operation + +[* T *]: ['v]: A pointer to memory or reference to object into which to read or write + +[* size_t]: ['_length]: The number of items to transfer + +[* off_t]: ['_where]: The offset at which to transfer + + + +]] +[[``template<class U> +io_req(future<> _precondition, U & v, off_t _where)`` + +] [Constructs an instance. ] [[* future<>]: ['_precondition]: An optional precondition for this operation + +[* U &]: ['v]: A pointer to memory or reference to object into which to read or write + +[* off_t]: ['_where]: The offset at which to transfer + + + +]] +[[``template<class U, size_t N> +io_req(future<> _precondition, U(&) v, off_t _where)`` + +] [Constructs an instance. ] [[* future<>]: ['_precondition]: An optional precondition for this operation + +[* U(&)]: ['v]: A pointer to memory or reference to object into which to read or write + +[* off_t]: ['_where]: The offset at which to transfer + + + +]] +] + +[heading Member Function(s)] +[table +[[Function] [Description] [Parameters] [Returns]] +[[``bool validate()`` + +] [Validates contents for correctness. ] [ + +][ +True if contents are correct + +] +] +[[``io_req & operator=(const io_req & o)`` + +] [Copy assignment. ] [[* const io_req &]: ['o]: + + + +][ + +] +] +[[``io_req & operator=(io_req && o)`` + +] [Move assignment. ] [[* io_req &&]: ['o]: + + + +][ + +] +] +] + +[heading Header] +`#include <boost/afio/v2/afio.hpp>` + +'''<?dbhtml-include href="disqus_comments.html"?>''' +[endsect] + diff --git a/attic/doc/generated/struct_io_req_3_01const_01_t_01_4.qbk b/attic/doc/generated/struct_io_req_3_01const_01_t_01_4.qbk new file mode 100644 index 00000000..1ab76f93 --- /dev/null +++ b/attic/doc/generated/struct_io_req_3_01const_01_t_01_4.qbk @@ -0,0 +1,169 @@ +[/============================================================================ + Boost.AFIO + + Use, modification and distribution is subject to the Boost Software License, + Version 1.0. (See accompanying file LICENSE_1_0.txt or copy at + http://www.boost.org/LICENSE_1_0.txt) +=============================================================================/] + + +[/ Generated by doxygen_xml2qbk 1.1.1, don't change, will be overwritten automatically] +[/ Generated from doxy/doxygen_output/xml\structboost_1_1afio_1_1io__req_3_01const_01_t_01_4.xml] +[section:io_req_constt_ io_req< const T >] +'''<?dbhtml-include href="disqus_identifiers/io_req_constt_.html"?>''' + +'''<indexterm><primary>io_req< const T ></primary></indexterm>''' +A convenience bundle of precondition, data and where for reading into a T as specified by its to_asio_buffers() overload. Data [*MUST] stay around until the operation completes. + +[heading Synopsis] +``template<class T> +struct io_req< const T > + : public detail::io_req_impl< true > +{ + future precondition; // A precondition containing an open file handle for this operation. + std::vector< asio::const_buffer > buffers; // A sequence of const Boost.ASIO buffers to write from. + off_t where; // The offset at which to write. +}; +`` + +[heading Template parameter(s)] +[table +[[Parameter] [Description]] +[[class T] [Any readable (if const) or writable (if non-const) type T as specified by its to_asio_buffers() overload. ]] +] + +[heading Member Function(s)] +[table +[[Function] [Description] [Parameters] [Returns]] +[[``bool validate()`` + +] [Validates contents for correctness. ] [ + +][ +True if contents are correct + +] +] +[[`` io_req()`` + +] [Default constructor. ] [ + +][ + +] +] +[[`` io_req(const io_req & o)`` + +] [Copy constructor. ] [[* const io_req &]: ['o]: + + + +][ + +] +] +[[`` io_req(io_req && o)`` + +] [Move constructor. ] [[* io_req &&]: ['o]: + + + +][ + +] +] +[[`` io_req(const io_req< T > & o)`` + +] [Copy constructor. ] [[* const io_req< T > &]: ['o]: + + + +][ + +] +] +[[`` io_req(io_req< T > && o)`` + +] [Move constructor. ] [[* io_req< T > &&]: ['o]: + + + +][ + +] +] +[[``io_req & operator=(const io_req & o)`` + +] [Copy assignment. ] [[* const io_req &]: ['o]: + + + +][ + +] +] +[[``io_req & operator=(io_req && o)`` + +] [Move assignment. ] [[* io_req &&]: ['o]: + + + +][ + +] +] +[[`` io_req(future<> _precondition, const T * v, size_t _length, + off_t _where)`` + +] [Constructs an instance. ] [[* future<>]: ['_precondition]: An optional precondition for this operation + +[* const T *]: ['v]: A pointer to memory or reference to object into which to read or write + +[* size_t]: ['_length]: The number of items to transfer + +[* off_t]: ['_where]: The offset at which to transfer + + + +][ + +] +] +[[``template<class U> + io_req(future<> _precondition, const U & v, off_t _where)`` + +] [Constructs an instance. ] [[* future<>]: ['_precondition]: An optional precondition for this operation + +[* const U &]: ['v]: A pointer to memory or reference to object into which to read or write + +[* off_t]: ['_where]: The offset at which to transfer + + + +][ + +] +] +[[``template<class U, size_t N> + io_req(future<> _precondition, const U(&) v, off_t _where)`` + +] [Constructs an instance. ] [[* future<>]: ['_precondition]: An optional precondition for this operation + +[* const U(&)]: ['v]: A pointer to memory or reference to object into which to read or write + +[* off_t]: ['_where]: The offset at which to transfer + + + +][ + +] +] +] + +[heading Header] +`#include <boost/afio/v2/afio.hpp>` + +'''<?dbhtml-include href="disqus_comments.html"?>''' +[endsect] + diff --git a/attic/doc/generated/struct_io_req_3_01const_01void_01_4.qbk b/attic/doc/generated/struct_io_req_3_01const_01void_01_4.qbk new file mode 100644 index 00000000..2cf1cff9 --- /dev/null +++ b/attic/doc/generated/struct_io_req_3_01const_01void_01_4.qbk @@ -0,0 +1,132 @@ +[/============================================================================ + Boost.AFIO + + Use, modification and distribution is subject to the Boost Software License, + Version 1.0. (See accompanying file LICENSE_1_0.txt or copy at + http://www.boost.org/LICENSE_1_0.txt) +=============================================================================/] + + +[/ Generated by doxygen_xml2qbk 1.1.1, don't change, will be overwritten automatically] +[/ Generated from doxy/doxygen_output/xml\structboost_1_1afio_1_1io__req_3_01const_01void_01_4.xml] +[section:io_req_constvoid_ io_req< const void >] +'''<?dbhtml-include href="disqus_identifiers/io_req_constvoid_.html"?>''' + +'''<indexterm><primary>io_req< const void ></primary></indexterm>''' +A convenience bundle of precondition, data and where for reading into a T as specified by its to_asio_buffers() overload. Data [*MUST] stay around until the operation completes. + +[heading Synopsis] +``struct io_req< const void > + : public detail::io_req_impl< true > +{ + future precondition; // A precondition containing an open file handle for this operation. + std::vector< asio::const_buffer > buffers; // A sequence of const Boost.ASIO buffers to write from. + off_t where; // The offset at which to write. +}; +`` + +[heading Member Function(s)] +[table +[[Function] [Description] [Parameters] [Returns]] +[[``bool validate()`` + +] [Validates contents for correctness. ] [ + +][ +True if contents are correct + +] +] +[[`` io_req()`` + +] [Default constructor. ] [ + +][ + +] +] +[[`` io_req(const io_req & o)`` + +] [Copy constructor. ] [[* const io_req &]: ['o]: + + + +][ + +] +] +[[`` io_req(io_req && o)`` + +] [Move constructor. ] [[* io_req &&]: ['o]: + + + +][ + +] +] +[[`` io_req(const io_req< void > & o)`` + +] [Copy constructor. ] [[* const io_req< void > &]: ['o]: + + + +][ + +] +] +[[`` io_req(io_req< void > && o)`` + +] [Move constructor. ] [[* io_req< void > &&]: ['o]: + + + +][ + +] +] +[[``io_req & operator=(const io_req & o)`` + +] [Copy assignment. ] [[* const io_req &]: ['o]: + + + +][ + +] +] +[[``io_req & operator=(io_req && o)`` + +] [Move assignment. ] [[* io_req &&]: ['o]: + + + +][ + +] +] +[[`` io_req(future<> _precondition, const void * v, size_t _length, + off_t _where)`` + +] [Constructs an instance. ] [[* future<>]: ['_precondition]: An optional precondition for this operation + +[* const void *]: ['v]: A pointer to memory or reference to object into which to read or write + +[* size_t]: ['_length]: The number of items to transfer + +[* off_t]: ['_where]: The offset at which to transfer + + + +][ + +] +] +] + +[heading Header] +`#include <boost/afio/v2/afio.hpp>` + +'''<?dbhtml-include href="disqus_comments.html"?>''' +[endsect] + diff --git a/attic/doc/generated/struct_io_req_3_01void_01_4.qbk b/attic/doc/generated/struct_io_req_3_01void_01_4.qbk new file mode 100644 index 00000000..ff414503 --- /dev/null +++ b/attic/doc/generated/struct_io_req_3_01void_01_4.qbk @@ -0,0 +1,112 @@ +[/============================================================================ + Boost.AFIO + + Use, modification and distribution is subject to the Boost Software License, + Version 1.0. (See accompanying file LICENSE_1_0.txt or copy at + http://www.boost.org/LICENSE_1_0.txt) +=============================================================================/] + + +[/ Generated by doxygen_xml2qbk 1.1.1, don't change, will be overwritten automatically] +[/ Generated from doxy/doxygen_output/xml\structboost_1_1afio_1_1io__req_3_01void_01_4.xml] +[section:io_req_void_ io_req< void >] +'''<?dbhtml-include href="disqus_identifiers/io_req_void_.html"?>''' + +'''<indexterm><primary>io_req< void ></primary></indexterm>''' +A convenience bundle of precondition, data and where for reading into a T as specified by its to_asio_buffers() overload. Data [*MUST] stay around until the operation completes. + +[heading Synopsis] +``struct io_req< void > + : public detail::io_req_impl< false > +{ + future precondition; // A precondition containing an open file handle for this operation. + std::vector< asio::mutable_buffer > buffers; // A sequence of mutable Boost.ASIO buffers to read into. + off_t where; // The offset from which to read. +}; +`` + +[heading Member Function(s)] +[table +[[Function] [Description] [Parameters] [Returns]] +[[``bool validate()`` + +] [Validates contents for correctness. ] [ + +][ +True if contents are correct + +] +] +[[`` io_req()`` + +] [Default constructor. ] [ + +][ + +] +] +[[`` io_req(const io_req & o)`` + +] [Copy constructor. ] [[* const io_req &]: ['o]: + + + +][ + +] +] +[[`` io_req(io_req && o)`` + +] [Move constructor. ] [[* io_req &&]: ['o]: + + + +][ + +] +] +[[``io_req & operator=(const io_req & o)`` + +] [Copy assignment. ] [[* const io_req &]: ['o]: + + + +][ + +] +] +[[``io_req & operator=(io_req && o)`` + +] [Move assignment. ] [[* io_req &&]: ['o]: + + + +][ + +] +] +[[`` io_req(future<> _precondition, void * v, size_t _length, + off_t _where)`` + +] [Constructs an instance. ] [[* future<>]: ['_precondition]: An optional precondition for this operation + +[* void *]: ['v]: A pointer to memory or reference to object into which to read or write + +[* size_t]: ['_length]: The number of items to transfer + +[* off_t]: ['_where]: The offset at which to transfer + + + +][ + +] +] +] + +[heading Header] +`#include <boost/afio/v2/afio.hpp>` + +'''<?dbhtml-include href="disqus_comments.html"?>''' +[endsect] + diff --git a/attic/doc/generated/struct_is_future.qbk b/attic/doc/generated/struct_is_future.qbk new file mode 100644 index 00000000..236dca99 --- /dev/null +++ b/attic/doc/generated/struct_is_future.qbk @@ -0,0 +1,38 @@ +[/============================================================================ + Boost.AFIO + + Use, modification and distribution is subject to the Boost Software License, + Version 1.0. (See accompanying file LICENSE_1_0.txt or copy at + http://www.boost.org/LICENSE_1_0.txt) +=============================================================================/] + + +[/ Generated by doxygen_xml2qbk 1.1.1, don't change, will be overwritten automatically] +[/ Generated from doxy/doxygen_output/xml\structboost_1_1afio_1_1is__future.xml] +[section:is_future is_future] +'''<?dbhtml-include href="disqus_identifiers/is_future.html"?>''' + +'''<indexterm><primary>is_future</primary></indexterm>''' +Trait for determining if a type is an afio::future<T> + +[heading Synopsis] +``template<class T> +struct is_future + : public false_type +{ + // ... +}; +`` + +[heading Template parameter(s)] +[table +[[Parameter] [Description]] +[[class T] []] +] + +[heading Header] +`#include <boost/afio/v2/afio.hpp>` + +'''<?dbhtml-include href="disqus_comments.html"?>''' +[endsect] + diff --git a/attic/doc/generated/struct_is_future_3_01future_3_01_t_01_4_01_4.qbk b/attic/doc/generated/struct_is_future_3_01future_3_01_t_01_4_01_4.qbk new file mode 100644 index 00000000..c4a3b479 --- /dev/null +++ b/attic/doc/generated/struct_is_future_3_01future_3_01_t_01_4_01_4.qbk @@ -0,0 +1,38 @@ +[/============================================================================ + Boost.AFIO + + Use, modification and distribution is subject to the Boost Software License, + Version 1.0. (See accompanying file LICENSE_1_0.txt or copy at + http://www.boost.org/LICENSE_1_0.txt) +=============================================================================/] + + +[/ Generated by doxygen_xml2qbk 1.1.1, don't change, will be overwritten automatically] +[/ Generated from doxy/doxygen_output/xml\structboost_1_1afio_1_1is__future_3_01future_3_01_t_01_4_01_4.xml] +[section:is_future< future< t > > is_future< future< T > >] +'''<?dbhtml-include href="disqus_identifiers/is_future_-future_-t-_.html"?>''' + +'''<indexterm><primary>is_future< future< T > ></primary></indexterm>''' + + +[heading Synopsis] +``template<class T> +struct is_future< future< T > > + : public true_type +{ + // ... +}; +`` + +[heading Template parameter(s)] +[table +[[Parameter] [Description]] +[[class T] []] +] + +[heading Header] +`#include <boost/afio/v2/afio.hpp>` + +'''<?dbhtml-include href="disqus_comments.html"?>''' +[endsect] + diff --git a/attic/doc/generated/struct_lock_req.qbk b/attic/doc/generated/struct_lock_req.qbk new file mode 100644 index 00000000..1dbdaede --- /dev/null +++ b/attic/doc/generated/struct_lock_req.qbk @@ -0,0 +1,133 @@ +[/============================================================================ + Boost.AFIO + + Use, modification and distribution is subject to the Boost Software License, + Version 1.0. (See accompanying file LICENSE_1_0.txt or copy at + http://www.boost.org/LICENSE_1_0.txt) +=============================================================================/] + + +[/ Generated by doxygen_xml2qbk 1.1.1, don't change, will be overwritten automatically] +[/ Generated from doxy/doxygen_output/xml\structboost_1_1afio_1_1lock__req.xml] +[section:lock_req lock_req] +'''<?dbhtml-include href="disqus_identifiers/lock_req.html"?>''' +[section:type Type] +'''<?dbhtml-include href="disqus_identifiers/type.html"?>''' + +'''<indexterm><primary>Type</primary></indexterm>''' +'''<indexterm><primary>unknown</primary></indexterm>''' +'''<indexterm><primary>read_lock</primary></indexterm>''' +'''<indexterm><primary>write_lock</primary></indexterm>''' +'''<indexterm><primary>unlock</primary></indexterm>''' + + +[heading Synopsis] +``enum Type {unknown, read_lock, write_lock, unlock};`` + +[heading Values] + +[table +[[Value] [Description] ] +[[unknown] []] +[[read_lock] []] +[[write_lock] []] +[[unlock] []] +] + + +[heading Header] +`#include <boost/afio/v2/afio.hpp>` + + +'''<?dbhtml-include href="disqus_comments.html"?>''' +[endsect] + + +'''<indexterm><primary>lock_req</primary></indexterm>''' + + +[heading Synopsis] +``struct lock_req +{ + future precondition; + enum boost::afio::lock_req::Type type; + off_t offset; + off_t length; +}; +`` + +[heading Constructor(s)] +[table +[[Function] [Description] [Parameters] ] +[[``lock_req()`` + +] [] [ + +]] +[[``lock_req(future<> _precondition, Type _type = Type::write_lock)`` + +] [] [[* future<>]: ['_precondition]: + +[* Type]: ['_type]: + + + +]] +[[``lock_req(future<> _precondition, std::nullptr_t )`` + +] [] [[* future<>]: ['_precondition]: + +[* std::nullptr_t]: [']: + + + +]] +[[``lock_req(future<> _precondition, Type _type, off_t _offset, + off_t _length)`` + +] [] [[* future<>]: ['_precondition]: + +[* Type]: ['_type]: + +[* off_t]: ['_offset]: + +[* off_t]: ['_length]: + + + +]] +[[``lock_req(future<> _precondition, off_t _offset, off_t _length, + Type _type = Type::write_lock)`` + +] [] [[* future<>]: ['_precondition]: + +[* off_t]: ['_offset]: + +[* off_t]: ['_length]: + +[* Type]: ['_type]: + + + +]] +] + +[heading Member Function(s)] +[table +[[Function] [Description] [Parameters] [Returns]] +[[``bool validate()`` + +] [Validates contents. ] [ + +][ + +] +] +] + +[heading Header] +`#include <boost/afio/v2/afio.hpp>` + +'''<?dbhtml-include href="disqus_comments.html"?>''' +[endsect] + diff --git a/attic/doc/generated/struct_path_1_1direct.qbk b/attic/doc/generated/struct_path_1_1direct.qbk new file mode 100644 index 00000000..a8ccce4d --- /dev/null +++ b/attic/doc/generated/struct_path_1_1direct.qbk @@ -0,0 +1,30 @@ +[/============================================================================ + Boost.AFIO + + Use, modification and distribution is subject to the Boost Software License, + Version 1.0. (See accompanying file LICENSE_1_0.txt or copy at + http://www.boost.org/LICENSE_1_0.txt) +=============================================================================/] + + +[/ Generated by doxygen_xml2qbk 1.1.1, don't change, will be overwritten automatically] +[/ Generated from doxy/doxygen_output/xml\structboost_1_1afio_1_1path_1_1direct.xml] +[section:path_direct path::direct] +'''<?dbhtml-include href="disqus_identifiers/path_direct.html"?>''' + +'''<indexterm><primary>path</primary></indexterm><indexterm><primary>direct</primary></indexterm>''' + + +[heading Synopsis] +``struct path::direct +{ + // ... +}; +`` + +[heading Header] +`#include <boost/afio/v2/afio.hpp>` + +'''<?dbhtml-include href="disqus_comments.html"?>''' +[endsect] + diff --git a/attic/doc/generated/struct_path_1_1make_absolute.qbk b/attic/doc/generated/struct_path_1_1make_absolute.qbk new file mode 100644 index 00000000..198deed6 --- /dev/null +++ b/attic/doc/generated/struct_path_1_1make_absolute.qbk @@ -0,0 +1,321 @@ +[/============================================================================ + Boost.AFIO + + Use, modification and distribution is subject to the Boost Software License, + Version 1.0. (See accompanying file LICENSE_1_0.txt or copy at + http://www.boost.org/LICENSE_1_0.txt) +=============================================================================/] + + +[/ Generated by doxygen_xml2qbk 1.1.1, don't change, will be overwritten automatically] +[/ Generated from doxy/doxygen_output/xml\structboost_1_1afio_1_1path_1_1make__absolute.xml] +[section:path_make_absolute path::make_absolute] +'''<?dbhtml-include href="disqus_identifiers/path_make_absolute.html"?>''' + +'''<indexterm><primary>path</primary></indexterm><indexterm><primary>make_absolute</primary></indexterm>''' +Makes a path absolute according to the current working directory. + +[heading Synopsis] +``struct path::make_absolute + : public path +{ + // ... +}; +`` + +[heading Constructor(s)] +[table +[[Function] [Description] [Parameters] ] +[[``make_absolute(const path & p)`` + +] [] [[* const path &]: ['p]: + + + +]] +[[``make_absolute(path && p)`` + +] [] [[* path &&]: ['p]: + + + +]] +[[``template<class T, typename> +make_absolute(T && p)`` + +] [] [[* T &&]: ['p]: + + + +]] +] + +[heading Member Function(s)] +[table +[[Function] [Description] [Parameters] [Returns]] +[[``template<class Source> +path & assign(Source const & source)`` + +] [Converts source to AFIO path format. ] [[* Source const &]: ['source]: + + + +][ + +] +] +[[``template<class InputIterator> +path & assign(InputIterator begin, InputIterator end)`` + +] [] [[* InputIterator]: ['begin]: + +[* InputIterator]: ['end]: + + + +][ + +] +] +[[``path & operator/=(const path & p)`` + +] [] [[* const path &]: ['p]: + + + +][ + +] +] +[[``template<class Source> +path & operator/=(Source const & source)`` + +] [] [[* Source const &]: ['source]: + + + +][ + +] +] +[[``template<class Source> +path & append(Source const & source)`` + +] [] [[* Source const &]: ['source]: + + + +][ + +] +] +[[``template<class InputIterator> +path & append(InputIterator begin, InputIterator end)`` + +] [] [[* InputIterator]: ['begin]: + +[* InputIterator]: ['end]: + + + +][ + +] +] +[[``path & operator+=(const path & x)`` + +] [] [[* const path &]: ['x]: + + + +][ + +] +] +[[``path & operator+=(const string_type & x)`` + +] [] [[* const string_type &]: ['x]: + + + +][ + +] +] +[[``path & operator+=(const value_type * x)`` + +] [] [[* const value_type *]: ['x]: + + + +][ + +] +] +[[``path & operator+=(value_type x)`` + +] [] [[* value_type]: ['x]: + + + +][ + +] +] +[[``template<class Source> +path & operator+=(Source const & x)`` + +] [] [[* Source const &]: ['x]: + + + +][ + +] +] +[[``template<class Source> +path & concat(Source const & x)`` + +] [] [[* Source const &]: ['x]: + + + +][ + +] +] +[[``template<class InputIterator> +path & concat(InputIterator begin, InputIterator end)`` + +] [] [[* InputIterator]: ['begin]: + +[* InputIterator]: ['end]: + + + +][ + +] +] +[[``path & make_preferred()`` + +] [] [ + +][ + +] +] +[[``path & remove_filename()`` + +] [] [ + +][ + +] +] +[[``path & replace_extension(const path & new_extension = path())`` + +] [] [[* const path &]: ['new_extension]: + + + +][ + +] +] +[[``path root_name()`` + +] [] [ + +][ + +] +] +[[``path root_directory()`` + +] [] [ + +][ + +] +] +[[``path root_path()`` + +] [] [ + +][ + +] +] +[[``path relative_path()`` + +] [] [ + +][ + +] +] +[[``path parent_path()`` + +] [] [ + +][ + +] +] +[[``path filename()`` + +] [] [ + +][ + +] +] +[[``path stem()`` + +] [] [ + +][ + +] +] +[[``path extension()`` + +] [] [ + +][ + +] +] +[[``iterator begin()`` + +] [] [ + +][ + +] +] +[[``iterator end()`` + +] [] [ + +][ + +] +] +[[``filesystem::path filesystem_path()`` + +] [Return a normalised filesystem::path from an AFIO path. ] [ + +][ + +] +] +] + +[heading Header] +`#include <boost/afio/v2/afio.hpp>` + +'''<?dbhtml-include href="disqus_comments.html"?>''' +[endsect] + diff --git a/attic/doc/generated/struct_path_hash.qbk b/attic/doc/generated/struct_path_hash.qbk new file mode 100644 index 00000000..c8eed842 --- /dev/null +++ b/attic/doc/generated/struct_path_hash.qbk @@ -0,0 +1,45 @@ +[/============================================================================ + Boost.AFIO + + Use, modification and distribution is subject to the Boost Software License, + Version 1.0. (See accompanying file LICENSE_1_0.txt or copy at + http://www.boost.org/LICENSE_1_0.txt) +=============================================================================/] + + +[/ Generated by doxygen_xml2qbk 1.1.1, don't change, will be overwritten automatically] +[/ Generated from doxy/doxygen_output/xml\structboost_1_1afio_1_1path__hash.xml] +[section:path_hash path_hash] +'''<?dbhtml-include href="disqus_identifiers/path_hash.html"?>''' + +'''<indexterm><primary>path_hash</primary></indexterm>''' +A hasher for path. + +[heading Synopsis] +``struct path_hash +{ + std::hash< path::string_type > hasher; +}; +`` + +[heading Member Function(s)] +[table +[[Function] [Description] [Parameters] [Returns]] +[[``size_t operator()(const path & p)`` + +] [] [[* const path &]: ['p]: + + + +][ + +] +] +] + +[heading Header] +`#include <boost/afio/v2/afio.hpp>` + +'''<?dbhtml-include href="disqus_comments.html"?>''' +[endsect] + diff --git a/attic/doc/generated/struct_path_req.qbk b/attic/doc/generated/struct_path_req.qbk new file mode 100644 index 00000000..00e722b9 --- /dev/null +++ b/attic/doc/generated/struct_path_req.qbk @@ -0,0 +1,135 @@ +[/============================================================================ + Boost.AFIO + + Use, modification and distribution is subject to the Boost Software License, + Version 1.0. (See accompanying file LICENSE_1_0.txt or copy at + http://www.boost.org/LICENSE_1_0.txt) +=============================================================================/] + + +[/ Generated by doxygen_xml2qbk 1.1.1, don't change, will be overwritten automatically] +[/ Generated from doxy/doxygen_output/xml\structboost_1_1afio_1_1path__req.xml] +[section:path_req path_req] +'''<?dbhtml-include href="disqus_identifiers/path_req.html"?>''' + +'''<indexterm><primary>path_req</primary></indexterm>''' +A convenience bundle of path and flags, with optional precondition. Paths may be a path fragment (relative to the precondition) or absolute, in which case if necessary they are made canonical and absolute in the constructor according to the current working directory. + +[heading Synopsis] +``struct path_req +{ + bool is_relative; // Whether the precondition is also where this path begins. + boost::afio::path path; // The filing system path to be used for this operation. + file_flags flags; // The flags to be used for this operation (note they can be overriden by flags passed during dispatcher construction). + future precondition; // An optional precondition for this operation +}; +`` + +[heading Constructor(s)] +[table +[[Function] [Description] [Parameters] ] +[[``path_req()`` + +] [Default constructor. ] [ + +]] +[[``path_req(const path_req & o)`` + +] [Copy constructor. ] [[* const path_req &]: ['o]: + + + +]] +[[``path_req(path_req && o)`` + +] [Move constructor. ] [[* path_req &&]: ['o]: + + + +]] +[[``path_req(absolute && o)`` + +] [Move constructor. ] [[* absolute &&]: ['o]: + + + +]] +[[``path_req(relative && o)`` + +] [Move constructor. ] [[* relative &&]: ['o]: + + + +]] +[[``template<class T, typename> +path_req(T && _path, file_flags _flags = file_flags::none)`` + +] [Constructs an instance. ] [[* T &&]: ['_path]: The filing system path to be used. + +[* file_flags]: ['_flags]: The flags to be used. + + + +]] +[[``template<class T, typename> +path_req(bool _is_relative, future<> _precondition, T && _path, + file_flags _flags = file_flags::none)`` + +] [Constructs an instance. ] [[* bool]: ['_is_relative]: Whether the precondition is where the path begins + +[* future<>]: ['_precondition]: The precondition for this operation. + +[* T &&]: ['_path]: The filing system path to be used. + +[* file_flags]: ['_flags]: The flags to be used. + + + +]] +[[``path_req(bool _is_relative, future<> _precondition, boost::afio::path _path, + file_flags _flags = file_flags::none)`` + +] [] [[* bool]: ['_is_relative]: + +[* future<>]: ['_precondition]: + +[* boost::afio::path]: ['_path]: + +[* file_flags]: ['_flags]: + + + +]] +[[``path_req(future<> _precondition, file_flags _flags = file_flags::none)`` + +] [Constructs an instance. ] [[* future<>]: ['_precondition]: The precondition for this operation (used as the path). + +[* file_flags]: ['_flags]: The flags to be used. + + + +]] +] + +[heading Member Function(s)] +[table +[[Function] [Description] [Parameters] [Returns]] +[[``bool validate()`` + +] [Validates contents. ] [ + +][ + +] +] +] + +[heading Header] +`#include <boost/afio/v2/afio.hpp>` + +[include generated/struct_path_req_1_1absolute.qbk] +[include generated/struct_path_req_1_1relative.qbk] + +'''<?dbhtml-include href="disqus_comments.html"?>''' +[endsect] + diff --git a/attic/doc/generated/struct_path_req_1_1absolute.qbk b/attic/doc/generated/struct_path_req_1_1absolute.qbk new file mode 100644 index 00000000..178c94da --- /dev/null +++ b/attic/doc/generated/struct_path_req_1_1absolute.qbk @@ -0,0 +1,64 @@ +[/============================================================================ + Boost.AFIO + + Use, modification and distribution is subject to the Boost Software License, + Version 1.0. (See accompanying file LICENSE_1_0.txt or copy at + http://www.boost.org/LICENSE_1_0.txt) +=============================================================================/] + + +[/ Generated by doxygen_xml2qbk 1.1.1, don't change, will be overwritten automatically] +[/ Generated from doxy/doxygen_output/xml\structboost_1_1afio_1_1path__req_1_1absolute.xml] +[section:path_req_absolute path_req::absolute] +'''<?dbhtml-include href="disqus_identifiers/path_req_absolute.html"?>''' + +'''<indexterm><primary>path_req</primary></indexterm><indexterm><primary>absolute</primary></indexterm>''' +Convenience tag type constructing an absolute path path_req. + +[heading Synopsis] +``struct path_req::absolute + : public path_req +{ + bool is_relative; // Whether the precondition is also where this path begins. + boost::afio::path path; // The filing system path to be used for this operation. + file_flags flags; // The flags to be used for this operation (note they can be overriden by flags passed during dispatcher construction). + future precondition; // An optional precondition for this operation +}; +`` + +[heading Constructor(s)] +[table +[[Function] [Description] [Parameters] ] +[[``template<class T> +absolute(future<> _precondition, T && _path, file_flags _flags = file_flags::none)`` + +] [Constructs an instance. ] [[* future<>]: ['_precondition]: The precondition for this operation. + +[* T &&]: ['_path]: The filing system path to be used. + +[* file_flags]: ['_flags]: The flags to be used. + + + +]] +] + +[heading Member Function(s)] +[table +[[Function] [Description] [Parameters] [Returns]] +[[``bool validate()`` + +] [Validates contents. ] [ + +][ + +] +] +] + +[heading Header] +`#include <boost/afio/v2/afio.hpp>` + +'''<?dbhtml-include href="disqus_comments.html"?>''' +[endsect] + diff --git a/attic/doc/generated/struct_path_req_1_1relative.qbk b/attic/doc/generated/struct_path_req_1_1relative.qbk new file mode 100644 index 00000000..79d962f4 --- /dev/null +++ b/attic/doc/generated/struct_path_req_1_1relative.qbk @@ -0,0 +1,73 @@ +[/============================================================================ + Boost.AFIO + + Use, modification and distribution is subject to the Boost Software License, + Version 1.0. (See accompanying file LICENSE_1_0.txt or copy at + http://www.boost.org/LICENSE_1_0.txt) +=============================================================================/] + + +[/ Generated by doxygen_xml2qbk 1.1.1, don't change, will be overwritten automatically] +[/ Generated from doxy/doxygen_output/xml\structboost_1_1afio_1_1path__req_1_1relative.xml] +[section:path_req_relative path_req::relative] +'''<?dbhtml-include href="disqus_identifiers/path_req_relative.html"?>''' + +'''<indexterm><primary>path_req</primary></indexterm><indexterm><primary>relative</primary></indexterm>''' +Convenience tag type constructing a relative path path_req. + +[heading Synopsis] +``struct path_req::relative + : public path_req +{ + bool is_relative; // Whether the precondition is also where this path begins. + boost::afio::path path; // The filing system path to be used for this operation. + file_flags flags; // The flags to be used for this operation (note they can be overriden by flags passed during dispatcher construction). + future precondition; // An optional precondition for this operation +}; +`` + +[heading Constructor(s)] +[table +[[Function] [Description] [Parameters] ] +[[``template<class T> +relative(future<> _precondition, T && _path, file_flags _flags = file_flags::none)`` + +] [Constructs an instance. ] [[* future<>]: ['_precondition]: The precondition for this operation. + +[* T &&]: ['_path]: The filing system path to be used. + +[* file_flags]: ['_flags]: The flags to be used. + + + +]] +[[``relative(future<> _precondition, file_flags _flags = file_flags::none)`` + +] [Constructs an instance. ] [[* future<>]: ['_precondition]: The precondition for this operation. + +[* file_flags]: ['_flags]: The flags to be used. + + + +]] +] + +[heading Member Function(s)] +[table +[[Function] [Description] [Parameters] [Returns]] +[[``bool validate()`` + +] [Validates contents. ] [ + +][ + +] +] +] + +[heading Header] +`#include <boost/afio/v2/afio.hpp>` + +'''<?dbhtml-include href="disqus_comments.html"?>''' +[endsect] + diff --git a/attic/doc/generated/struct_stat_t.qbk b/attic/doc/generated/struct_stat_t.qbk new file mode 100644 index 00000000..32d3e4d5 --- /dev/null +++ b/attic/doc/generated/struct_stat_t.qbk @@ -0,0 +1,79 @@ +[/============================================================================ + Boost.AFIO + + Use, modification and distribution is subject to the Boost Software License, + Version 1.0. (See accompanying file LICENSE_1_0.txt or copy at + http://www.boost.org/LICENSE_1_0.txt) +=============================================================================/] + + +[/ Generated by doxygen_xml2qbk 1.1.1, don't change, will be overwritten automatically] +[/ Generated from doxy/doxygen_output/xml\structboost_1_1afio_1_1stat__t.xml] +[section:stat_t stat_t] +'''<?dbhtml-include href="disqus_identifiers/stat_t.html"?>''' + +'''<indexterm><primary>stat_t</primary></indexterm>''' +Metadata about a directory entry. + +[heading Description] +This structure looks somewhat like a [^`struct stat`], and indeed it was derived from BSD's [^`struct stat`]. However there are a number of changes to better interoperate with modern practice, specifically: + +* inode value containers are forced to 64 bits. +* Timestamps use C++11's [^`std::chrono::system_clock::time_point`] or Boost equivalent. The resolution of these may or may not equal what a [^`struct timespec`] can do depending on your STL. +* The type of a file, which is available on Windows and on POSIX without needing an additional syscall, is provided by [^`st_type`] which is one of the values from [^`filesystem::file_type`]. +* As type is now separate from permissions, there is no longer a [^`st_mode`], instead being a [^`st_perms`] which is solely the permissions bits. If you want to test permission bits in [^`st_perms`] but don't want to include platform specific headers, note that [^`filesystem::perms`] contains definitions of the POSIX permissions flags. +* The st\u005fsparse and st\u005fcompressed flags indicate if your file is sparse and/or compressed, or if the directory will compress newly created files by default. Note that on POSIX, a file is sparse if and only if st\u005fallocated < st\u005fsize which can include compressed files if that filing system is mounted with compression enabled (e.g. ZFS with ZLE compression which elides runs of zeros). +* The st\u005freparse\u005fpoint is a Windows only flag and is never set on POSIX, even on a NTFS volume. + + + +[heading Synopsis] +``struct stat_t +{ + uint64_t st_dev; // inode of device containing file (POSIX only) + uint64_t st_ino; // inode of file (Windows, POSIX) + filesystem::file_type st_type; // type of file (Windows, POSIX) + filesystem::perms st_perms; // uint16_t bitfield perms of file (POSIX only) + int16_t st_nlink; // number of hard links (Windows, POSIX) + int16_t st_uid; // user ID of the file (POSIX only) + int16_t st_gid; // group ID of the file (POSIX only) + dev_t st_rdev; // id of file if special (POSIX only) + chrono::system_clock::time_point st_atim; // time of last access (Windows, POSIX) + chrono::system_clock::time_point st_mtim; // time of last data modification (Windows, POSIX) + chrono::system_clock::time_point st_ctim; // time of last status change (Windows, POSIX) + off_t st_size; // file size, in bytes (Windows, POSIX) + off_t st_allocated; // bytes allocated for file (Windows, POSIX) + off_t st_blocks; // number of blocks allocated (Windows, POSIX) + uint16_t st_blksize; // block size used by this device (Windows, POSIX) + uint32_t st_flags; // user defined flags for file (FreeBSD, OS X, zero otherwise) + uint32_t st_gen; // file generation number (FreeBSD, OS X, zero otherwise) + chrono::system_clock::time_point st_birthtim; // time of file creation (Windows, FreeBSD, OS X, zero otherwise) + unsigned st_sparse; // if this file is sparse, or this directory capable of sparse files (Windows, POSIX) + unsigned st_compressed; // if this file is compressed, or this directory capable of compressed files (Windows) + unsigned st_reparse_point; // if this file or directory is a reparse point (Windows) +}; +`` + +[heading Constructor(s)] +[table +[[Function] [Description] [Parameters] ] +[[``stat_t()`` + +] [Constructs a UNINITIALIZED instance i.e. full of random garbage. ] [ + +]] +[[``stat_t(std::nullptr_t )`` + +] [Constructs a zeroed instance. ] [[* std::nullptr_t]: [']: + + + +]] +] + +[heading Header] +`#include <boost/afio/v2/afio.hpp>` + +'''<?dbhtml-include href="disqus_comments.html"?>''' +[endsect] + diff --git a/attic/doc/generated/struct_statfs_t.qbk b/attic/doc/generated/struct_statfs_t.qbk new file mode 100644 index 00000000..35a38edf --- /dev/null +++ b/attic/doc/generated/struct_statfs_t.qbk @@ -0,0 +1,55 @@ +[/============================================================================ + Boost.AFIO + + Use, modification and distribution is subject to the Boost Software License, + Version 1.0. (See accompanying file LICENSE_1_0.txt or copy at + http://www.boost.org/LICENSE_1_0.txt) +=============================================================================/] + + +[/ Generated by doxygen_xml2qbk 1.1.1, don't change, will be overwritten automatically] +[/ Generated from doxy/doxygen_output/xml\structboost_1_1afio_1_1statfs__t.xml] +[section:statfs_t statfs_t] +'''<?dbhtml-include href="disqus_identifiers/statfs_t.html"?>''' + +'''<indexterm><primary>statfs_t</primary></indexterm>''' +Metadata about a filing system. Unsupported entries are -1. + +[heading Synopsis] +``struct statfs_t +{ + struct boost::afio::statfs_t::f_flags_t f_flags; // copy of mount exported flags (Windows, POSIX) + uint64_t f_bsize; // fundamental filesystem block size (Windows, POSIX) + uint64_t f_iosize; // optimal transfer block size (Windows, POSIX) + uint64_t f_blocks; // total data blocks in filesystem (Windows, POSIX) + uint64_t f_bfree; // free blocks in filesystem (Windows, POSIX) + uint64_t f_bavail; // free blocks avail to non-superuser (Windows, POSIX) + uint64_t f_files; // total file nodes in filesystem (POSIX) + uint64_t f_ffree; // free nodes avail to non-superuser (POSIX) + uint32_t f_namemax; // maximum filename length (Windows, POSIX) + int16_t f_owner; // user that mounted the filesystem (BSD, OS X) + uint64_t f_fsid; // filesystem id (Windows, POSIX) + std::string f_fstypename; // filesystem type name (Windows, POSIX) + std::string f_mntfromname; // mounted filesystem (Windows, POSIX) + path f_mntonname; // directory on which mounted (Windows, POSIX) +}; +`` + +[heading Constructor(s)] +[table +[[Function] [Description] [Parameters] ] +[[``statfs_t()`` + +] [] [ + +]] +] + +[heading Header] +`#include <boost/afio/v2/afio.hpp>` + +[include generated/struct_statfs_t_1_1f_flags_t.qbk] + +'''<?dbhtml-include href="disqus_comments.html"?>''' +[endsect] + diff --git a/attic/doc/generated/struct_statfs_t_1_1f_flags_t.qbk b/attic/doc/generated/struct_statfs_t_1_1f_flags_t.qbk new file mode 100644 index 00000000..2839e82f --- /dev/null +++ b/attic/doc/generated/struct_statfs_t_1_1f_flags_t.qbk @@ -0,0 +1,37 @@ +[/============================================================================ + Boost.AFIO + + Use, modification and distribution is subject to the Boost Software License, + Version 1.0. (See accompanying file LICENSE_1_0.txt or copy at + http://www.boost.org/LICENSE_1_0.txt) +=============================================================================/] + + +[/ Generated by doxygen_xml2qbk 1.1.1, don't change, will be overwritten automatically] +[/ Generated from doxy/doxygen_output/xml\structboost_1_1afio_1_1statfs__t_1_1f__flags__t.xml] +[section:statfs_t_f_flags_t statfs_t::f_flags_t] +'''<?dbhtml-include href="disqus_identifiers/statfs_t_f_flags_t.html"?>''' + +'''<indexterm><primary>statfs_t</primary></indexterm><indexterm><primary>f_flags_t</primary></indexterm>''' + + +[heading Synopsis] +``struct statfs_t::f_flags_t +{ + uint32_t rdonly; // Filing system is read only (Windows, POSIX) + uint32_t noexec; // Filing system cannot execute programs (POSIX) + uint32_t nosuid; // Filing system cannot superuser (POSIX) + uint32_t acls; // Filing system provides ACLs (Windows, POSIX) + uint32_t xattr; // Filing system provides extended attributes (Windows, POSIX) + uint32_t compression; // Filing system provides whole volume compression (Windows, POSIX) + uint32_t extents; // Filing system provides extent based file storage (sparse files) (Windows, POSIX) + uint32_t filecompression; // Filing system provides per-file selectable compression (Windows) +}; +`` + +[heading Header] +`#include <boost/afio/v2/afio.hpp>` + +'''<?dbhtml-include href="disqus_comments.html"?>''' +[endsect] + diff --git a/attic/doc/generated/struct_utils_1_1page_allocator_1_1rebind.qbk b/attic/doc/generated/struct_utils_1_1page_allocator_1_1rebind.qbk new file mode 100644 index 00000000..9fff58bf --- /dev/null +++ b/attic/doc/generated/struct_utils_1_1page_allocator_1_1rebind.qbk @@ -0,0 +1,37 @@ +[/============================================================================ + Boost.AFIO + + Use, modification and distribution is subject to the Boost Software License, + Version 1.0. (See accompanying file LICENSE_1_0.txt or copy at + http://www.boost.org/LICENSE_1_0.txt) +=============================================================================/] + + +[/ Generated by doxygen_xml2qbk 1.1.1, don't change, will be overwritten automatically] +[/ Generated from doxy/doxygen_output/xml\structboost_1_1afio_1_1utils_1_1page__allocator_1_1rebind.xml] +[section:utils_page_allocator_rebind utils::page_allocator::rebind] +'''<?dbhtml-include href="disqus_identifiers/utils_page_allocator_rebind.html"?>''' + +'''<indexterm><primary>utils</primary></indexterm><indexterm><primary>page_allocator</primary></indexterm><indexterm><primary>rebind</primary></indexterm>''' + + +[heading Synopsis] +``template<class U> +struct utils::page_allocator::rebind +{ + // ... +}; +`` + +[heading Template parameter(s)] +[table +[[Parameter] [Description]] +[[class U] []] +] + +[heading Header] +`#include <boost/afio/v2/afio.hpp>` + +'''<?dbhtml-include href="disqus_comments.html"?>''' +[endsect] + diff --git a/attic/doc/generated/struct_utils_1_1page_allocator_3_01void_01_4_1_1rebind.qbk b/attic/doc/generated/struct_utils_1_1page_allocator_3_01void_01_4_1_1rebind.qbk new file mode 100644 index 00000000..29a52216 --- /dev/null +++ b/attic/doc/generated/struct_utils_1_1page_allocator_3_01void_01_4_1_1rebind.qbk @@ -0,0 +1,37 @@ +[/============================================================================ + Boost.AFIO + + Use, modification and distribution is subject to the Boost Software License, + Version 1.0. (See accompanying file LICENSE_1_0.txt or copy at + http://www.boost.org/LICENSE_1_0.txt) +=============================================================================/] + + +[/ Generated by doxygen_xml2qbk 1.1.1, don't change, will be overwritten automatically] +[/ Generated from doxy/doxygen_output/xml\structboost_1_1afio_1_1utils_1_1page__allocator_3_01void_01_4_1_1rebind.xml] +[section:utils_page_allocator< void >_rebind utils::page_allocator< void >::rebind] +'''<?dbhtml-include href="disqus_identifiers/utils_page_allocator_-void-_.html"?>''' + +'''<indexterm><primary>utils</primary></indexterm><indexterm><primary>page_allocator< void ></primary></indexterm><indexterm><primary>rebind</primary></indexterm>''' + + +[heading Synopsis] +``template<class U> +struct utils::page_allocator< void >::rebind +{ + // ... +}; +`` + +[heading Template parameter(s)] +[table +[[Parameter] [Description]] +[[class U] []] +] + +[heading Header] +`#include <boost/afio/v2/afio.hpp>` + +'''<?dbhtml-include href="disqus_comments.html"?>''' +[endsect] + diff --git a/attic/doc/html/myboostbook.css b/attic/doc/html/myboostbook.css new file mode 100644 index 00000000..21591724 --- /dev/null +++ b/attic/doc/html/myboostbook.css @@ -0,0 +1,723 @@ +/*============================================================================= + Copyright (c) 2004 Joel de Guzman + http://spirit.sourceforge.net/ + + Distributed under the Boost Software License, Version 1.0. (See accompany- + ing file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) +=============================================================================*/ + +/*============================================================================= + Body defaults +=============================================================================*/ + + body + { + margin: 1em; + font-family: sans-serif; + } + +/*============================================================================= + Paragraphs +=============================================================================*/ + + p + { + text-align: left; + font-size: 10pt; + line-height: 1.15; + } + +/*============================================================================= + Program listings +=============================================================================*/ + + /* Code on paragraphs */ + p tt.computeroutput + { + font-size: 9pt; + } + + pre.synopsis + { + font-size: 9pt; + margin: 1pc 4% 0pc 4%; + padding: 0.5pc 0.5pc 0.5pc 0.5pc; + } + + .programlisting, + .screen + { + font-size: 9pt; + display: block; + margin: 1pc 4% 0pc 4%; + padding: 0.5pc 0.5pc 0.5pc 0.5pc; + } + + /* Program listings in tables don't get borders */ + td .programlisting, + td .screen + { + margin: 0pc 0pc 0pc 0pc; + padding: 0pc 0pc 0pc 0pc; + } + +/*============================================================================= + Headings +=============================================================================*/ + + h1, h2, h3, h4, h5, h6 + { + text-align: left; + margin: 1em 0em 0.5em 0em; + font-weight: bold; + } + + h1 { font-size: 140%; } + h2 { font-weight: bold; font-size: 140%; } + h3 { font-weight: bold; font-size: 130%; } + h4 { font-weight: bold; font-size: 120%; } + h5 { font-weight: normal; font-style: italic; font-size: 110%; } + h6 { font-weight: normal; font-style: italic; font-size: 100%; } + + /* Top page titles */ + title, + h1.title, + h2.title + h3.title, + h4.title, + h5.title, + h6.title, + .refentrytitle + { + font-weight: bold; + margin-bottom: 1pc; + } + + h1.title { font-size: 140% } + h2.title { font-size: 140% } + h3.title { font-size: 130% } + h4.title { font-size: 120% } + h5.title { font-size: 110% } + h6.title { font-size: 100% } + + .section h1 + { + margin: 0em 0em 0.5em 0em; + font-size: 140%; + } + + .section h2 { font-size: 140% } + .section h3 { font-size: 130% } + .section h4 { font-size: 120% } + .section h5 { font-size: 110% } + .section h6 { font-size: 100% } + + /* Code on titles */ + h1 tt.computeroutput { font-size: 140% } + h2 tt.computeroutput { font-size: 140% } + h3 tt.computeroutput { font-size: 130% } + h4 tt.computeroutput { font-size: 130% } + h5 tt.computeroutput { font-size: 130% } + h6 tt.computeroutput { font-size: 130% } + + +/*============================================================================= + Author +=============================================================================*/ + + h3.author + { + font-size: 100% + } + +/*============================================================================= + Lists +=============================================================================*/ + + li + { + font-size: 10pt; + line-height: 1.3; + } + + /* Unordered lists */ + ul + { + text-align: left; + } + + /* Ordered lists */ + ol + { + text-align: left; + } + +/*============================================================================= + Links +=============================================================================*/ + + a + { + text-decoration: none; /* no underline */ + } + + a:hover + { + text-decoration: underline; + } + +/*============================================================================= + Spirit style navigation +=============================================================================*/ + + .spirit-nav + { + text-align: right; + } + + .spirit-nav a + { + color: white; + padding-left: 0.5em; + } + + .spirit-nav img + { + border-width: 0px; + } + +/*============================================================================= + Copyright footer +=============================================================================*/ + .copyright-footer + { + text-align: right; + font-size: 70%; + } + + .copyright-footer p + { + text-align: right; + font-size: 80%; + } + +/*============================================================================= + Table of contents +=============================================================================*/ + + div.toc + { + margin: 1pc 4% 0pc 4%; + padding: 0.1pc 1pc 0.1pc 1pc; + font-size: 80%; + line-height: 1.15; + } + + .boost-toc + { + float: right; + padding: 0.5pc; + } + + /* Code on toc */ + .toc .computeroutput { font-size: 120% } + + /* No margin on nested menus */ + + .toc dl dl { margin: 0; } + +/*============================================================================= + Tables +=============================================================================*/ + + .table-title, + div.table p.title + { + margin-left: 4%; + padding-right: 0.5em; + padding-left: 0.5em; + } + + .informaltable table, + .table table + { + width: 92%; + margin-left: 4%; + margin-right: 4%; + } + + div.informaltable table, + div.table table + { + padding: 4px; + } + + /* Table Cells */ + div.informaltable table tr td, + div.table table tr td + { + padding: 0.5em; + text-align: left; + font-size: 9pt; + } + + div.informaltable table tr th, + div.table table tr th + { + padding: 0.5em 0.5em 0.5em 0.5em; + border: 1pt solid white; + font-size: 80%; + } + + table.simplelist + { + width: auto !important; + margin: 0em !important; + padding: 0em !important; + border: none !important; + } + table.simplelist td + { + margin: 0em !important; + padding: 0em !important; + text-align: left !important; + font-size: 9pt !important; + border: none !important; + } + +/*============================================================================= + Blurbs +=============================================================================*/ + + div.note, + div.tip, + div.important, + div.caution, + div.warning, + p.blurb + { + font-size: 9pt; /* A little bit smaller than the main text */ + line-height: 1.2; + display: block; + margin: 1pc 4% 0pc 4%; + padding: 0.5pc 0.5pc 0.5pc 0.5pc; + } + + p.blurb img + { + padding: 1pt; + } + +/*============================================================================= + Variable Lists +=============================================================================*/ + + div.variablelist + { + margin: 1em 0; + } + + /* Make the terms in definition lists bold */ + div.variablelist dl dt, + span.term + { + font-weight: bold; + font-size: 10pt; + } + + div.variablelist table tbody tr td + { + text-align: left; + vertical-align: top; + padding: 0em 2em 0em 0em; + font-size: 10pt; + margin: 0em 0em 0.5em 0em; + line-height: 1; + } + + div.variablelist dl dt + { + margin-bottom: 0.2em; + } + + div.variablelist dl dd + { + margin: 0em 0em 0.5em 2em; + font-size: 10pt; + } + + div.variablelist table tbody tr td p, + div.variablelist dl dd p + { + margin: 0em 0em 0.5em 0em; + line-height: 1; + } + +/*============================================================================= + Misc +=============================================================================*/ + + /* Title of books and articles in bibliographies */ + span.title + { + font-style: italic; + } + + span.underline + { + text-decoration: underline; + } + + span.strikethrough + { + text-decoration: line-through; + } + + /* Copyright, Legal Notice */ + div div.legalnotice p + { + text-align: left + } + +/*============================================================================= + Colors +=============================================================================*/ + + @media screen + { + body { + background-color: #FFFFFF; + color: #000000; + } + + /* Syntax Highlighting */ + .keyword { color: #0000AA; } + .identifier { color: #000000; } + .special { color: #707070; } + .preprocessor { color: #402080; } + .char { color: teal; } + .comment { color: #800000; } + .string { color: teal; } + .number { color: teal; } + .white_bkd { background-color: #FFFFFF; } + .dk_grey_bkd { background-color: #999999; } + + /* Links */ + a, a .keyword, a .identifier, a .special, a .preprocessor + a .char, a .comment, a .string, a .number + { + color: #005a9c; + } + + a:visited, a:visited .keyword, a:visited .identifier, + a:visited .special, a:visited .preprocessor a:visited .char, + a:visited .comment, a:visited .string, a:visited .number + { + color: #9c5a9c; + } + + h1 a, h2 a, h3 a, h4 a, h5 a, h6 a, + h1 a:hover, h2 a:hover, h3 a:hover, h4 a:hover, h5 a:hover, h6 a:hover, + h1 a:visited, h2 a:visited, h3 a:visited, h4 a:visited, h5 a:visited, h6 a:visited + { + text-decoration: none; /* no underline */ + color: #000000; + } + + /* Copyright, Legal Notice */ + .copyright + { + color: #666666; + font-size: small; + } + + div div.legalnotice p + { + color: #666666; + } + + /* Program listing */ + pre.synopsis + { + border: 1px solid #DCDCDC; + } + + .programlisting, + .screen + { + border: 1px solid #DCDCDC; + } + + td .programlisting, + td .screen + { + border: 0px solid #DCDCDC; + } + + /* Blurbs */ + div.note, + div.tip, + div.important, + div.caution, + div.warning, + p.blurb + { + border: 1px solid #DCDCDC; + } + + /* Table of contents */ + div.toc + { + border: 1px solid #DCDCDC; + } + + /* Tables */ + div.informaltable table tr td, + div.table table tr td + { + border: 1px solid #DCDCDC; + } + + div.informaltable table tr th, + div.table table tr th + { + background-color: #F0F0F0; + border: 1px solid #DCDCDC; + } + + .copyright-footer + { + color: #8F8F8F; + } + + /* Misc */ + span.highlight + { + color: #00A000; + } + } + + @media print + { + /* Links */ + a + { + color: black; + } + + a:visited + { + color: black; + } + + .spirit-nav + { + display: none; + } + + /* Program listing */ + pre.synopsis + { + border: 1px solid gray; + } + + .programlisting, + .screen + { + border: 1px solid gray; + } + + td .programlisting, + td .screen + { + border: 0px solid #DCDCDC; + } + + /* Table of contents */ + div.toc + { + border: 1px solid gray; + } + + .informaltable table, + .table table + { + border: 1px solid gray; + border-collapse: collapse; + } + + /* Tables */ + div.informaltable table tr td, + div.table table tr td + { + border: 1px solid gray; + } + + div.informaltable table tr th, + div.table table tr th + { + border: 1px solid gray; + } + + table.simplelist tr td + { + border: none !important; + } + + /* Misc */ + span.highlight + { + font-weight: bold; + } + } + +/*============================================================================= + Images +=============================================================================*/ + + span.inlinemediaobject img + { + vertical-align: middle; + } + +/*============================================================================== + Super and Subscript: style so that line spacing isn't effected, see + http://www.adobe.com/cfusion/communityengine/index.cfm?event=showdetails&productId=1&postId=5341 +==============================================================================*/ + +sup, +sub { + height: 0; + line-height: 1; + vertical-align: baseline; + position: relative; + +} + +/* For internet explorer: */ + +* html sup, +* html sub { + vertical-align: bottom; +} + +sup { + bottom: 1ex; +} + +sub { + top: .5ex; +} + +/*============================================================================== + Indexes: pretty much the same as the TOC. +==============================================================================*/ + + .index + { + font-size: 80%; + padding-top: 0px; + padding-bottom: 0px; + margin-top: 0px; + margin-bottom: 0px; + margin-left: 0px; + } + + .index ul + { + padding-left: 3em; + } + + .index p + { + padding: 2px; + margin: 2px; + } + + .index-entry-level-0 + { + font-weight: bold; + } + + .index em + { + font-weight: bold; + } + + + + + + + + + + + + + + +/* Make TOC subsections multi-column */ +body div.chapter div.toc dl dd dl dd dl dd dl, body div.section div.toc dl dd dl dd dl { + -moz-column-count:auto; + -webkit-column-count:auto; + column-count:auto; + -moz-column-width: 30em; + -webkit-column-width: 30em; + column-width: 30em; +} + +/* Stop APIs consuming all the horizontal space */ +div.informaltable table tbody tr td pre.table-programlisting { + white-space: pre-wrap; + padding-left: 4em; + text-indent: -4em; +} +pre.programlisting { + white-space: pre-wrap; +} + +/* Put some spacing between list items */ +div.orderedlist ol.orderedlist li.listitem, div.itemizedlist ul.itemizedlist li.listitem { + padding-top: 0.25em; + padding-bottom: 0.25em; +} + +/* Add text alignment and text colours */ +span.aligncenter { display: inline-block; width: 100%; text-align: center; } +span.alignright { display: inline-block; width: 100%; text-align: right; } +span.alignjustify { display: inline-block; width: 100%; text-align: justify; } +span.red { color: red; } +span.green { color: green; } + +/* Have Disqus comment counts be small */ +span.disqus-comment-count { font-size: x-small; margin-left: 1em; } + +/* Try it now online button */ +div.spirit-nav form { display: inline; float: left; height: 0px; } +input.tryitnowbtn { + background: #3498db; + background-image: -webkit-linear-gradient(top, #3498db, #17425c); + background-image: -moz-linear-gradient(top, #3498db, #17425c); + background-image: -ms-linear-gradient(top, #3498db, #17425c); + background-image: -o-linear-gradient(top, #3498db, #17425c); + background-image: linear-gradient(to bottom, #3498db, #17425c); + -webkit-border-radius: 28; + -moz-border-radius: 28; + border-radius: 28px; + text-shadow: 2px 2px 3px #001040; + font-family: Arial; + color: #ffffff; + font-size: 12px; + padding: 2px 8px 2px 8px; + text-decoration: none; +} +input.tryitnowbtn:hover { + background: #46fc3c; + background-image: -webkit-linear-gradient(top, #46fc3c, #218a21); + background-image: -moz-linear-gradient(top, #46fc3c, #218a21); + background-image: -ms-linear-gradient(top, #46fc3c, #218a21); + background-image: -o-linear-gradient(top, #46fc3c, #218a21); + background-image: linear-gradient(to bottom, #46fc3c, #218a21); + text-decoration: none; +} diff --git a/attic/doc/latencies.xlsx b/attic/doc/latencies.xlsx Binary files differnew file mode 100644 index 00000000..2eef61ff --- /dev/null +++ b/attic/doc/latencies.xlsx diff --git a/attic/doc/make_qbk.py b/attic/doc/make_qbk.py new file mode 100755 index 00000000..0f1a3c00 --- /dev/null +++ b/attic/doc/make_qbk.py @@ -0,0 +1,245 @@ +#! /usr/bin/env python +# -*- coding: utf-8 -*- +# =========================================================================== +# Use, modification and distribution is subject to the Boost Software License, +# Version 1.0. (See accompanying file LICENSE_1_0.txt or copy at +# http://www.boost.org/LICENSE_1_0.txt) +# ============================================================================ + +import os, sys, glob, shutil + +os.chdir(os.path.dirname(sys.argv[0])) + +if 'DOXYGEN' in os.environ: + doxygen_cmd = os.environ['DOXYGEN'] +else: + doxygen_cmd = 'doxygen' + +if 'DOXYGEN_XML2QBK' in os.environ: + doxygen_xml2qbk_cmd = os.environ['DOXYGEN_XML2QBK'] +else: + doxygen_xml2qbk_cmd = 'doxygen_xml2qbk' + +if os.path.exists("generated"): + shutil.rmtree("generated", True) +if os.path.exists("disqus_identifiers"): + shutil.rmtree("disqus_identifiers", True) +if os.path.exists("html/afio"): + shutil.rmtree("html/afio", True) +if os.path.exists("doxy/doxygen_output"): + shutil.rmtree("doxy/doxygen_output", True) +os.mkdir("generated") +os.mkdir("disqus_identifiers") +os.mkdir("doxy/doxygen_output") + +cmd = doxygen_xml2qbk_cmd +cmd = cmd + " --xml %s" +cmd = cmd + " --start_include boost/afio/" +cmd = cmd + " --convenience_header_path ../../include/boost/afio/" +cmd = cmd + " --convenience_headers afio.hpp" +cmd = cmd + " --skip_namespace boost::afio::" +cmd = cmd + " --copyright copyright_block.qbk" +#cmd = cmd + " --output_style alt +cmd = cmd + ' --output_member_variables ""' +cmd = cmd + " > generated/%s.qbk" + +def call_doxygen(): + os.chdir("doxy"); + os.system(doxygen_cmd) + os.chdir("..") + +def path2identifier(prefix, i): + i=i[len(prefix):-4] + return i.replace('__', '_') + +call_doxygen() + +# Add all classes +for i in glob.glob("doxy/doxygen_output/xml/classboost_1_1afio_1_1*.xml"): + if "detail_1_1" not in i: + os.system(cmd % (i, "class_"+path2identifier("doxy/doxygen_output/xml/classboost_1_1afio_1_1", i))); +# Add all structs +for i in glob.glob("doxy/doxygen_output/xml/structboost_1_1afio_1_1*.xml"): + if "detail_1_1" not in i: + os.system(cmd % (i, "struct_"+path2identifier("doxy/doxygen_output/xml/structboost_1_1afio_1_1", i))); +# Add all namespaces +#for i in glob.glob("doxy/doxygen_output/xml/namespaceboost_1_1afio_1_1*.xml"): +# if "detail" not in i: +# os.system(cmd % (i, "namespace_"+path2identifier("doxy/doxygen_output/xml/namespaceboost_1_1afio_1_1", i))); +# Add all groups +for i in glob.glob("doxy/doxygen_output/xml/group__*.xml"): + if "detail_1_1" not in i: + os.system(cmd % (i, "group_"+path2identifier("doxy/doxygen_output/xml/group__", i))); + +# Patch broken index term generation +for i in glob.glob("generated/struct_io_req_3_01*.qbk"): + with open(i, "r+b") as ih: + t=ih.read(); + # Fix erroneous expansions of nested types + t=t.replace("</primary></indexterm><indexterm><primary>", "::") + # Fix failure to escape < and > + it1=t.find("<indexterm><primary>")+20 + it2=t.find("</primary></indexterm>", it1) + indexterm=t[it1:it2] + indexterm=indexterm.replace("<", "<") + indexterm=indexterm.replace(">", ">") + t=t[:it1]+indexterm+t[it2:] + # Fix failure to collapse section ids + si1=t.find("[section:io_req<") + if si1!=-1: + si1+=15; + si2=si1+1 + count=1 + while count>0: + if t[si2]=='<': count+=1 + elif t[si2]=='>': count-=1 + si2+=1 + postfix=t[si1:si2] + postfix=postfix.replace("<", "_") + postfix=postfix.replace(">", "_") + postfix=postfix.replace(",", "_") + postfix=postfix.replace(" ", "") + t=t[:si1]+postfix+t[si2:] + ih.seek(0) + ih.truncate(0) + ih.write(t) +for i in glob.glob("generated/class_enqueued_task*.qbk"): + with open(i, "r+b") as ih: + t=ih.read(); + # Fix failure to escape < and > + it1=t.find("<indexterm><primary>")+20 + it2=t.find("</primary></indexterm>", it1) + indexterm=t[it1:it2] + indexterm=indexterm.replace("<", "<") + indexterm=indexterm.replace(">", ">") + t=t[:it1]+indexterm+t[it2:] + # Fix failure to collapse section ids + si1=t.find("[section:enqueued_task<") + if si1!=-1: + si1+=22; + si2=si1+1 + count=1 + while count>0: + if t[si2]=='<': count+=1 + elif t[si2]=='>': count-=1 + si2+=1 + postfix=t[si1:si2] + postfix=postfix.replace("<", "_") + postfix=postfix.replace(">", "_") + postfix=postfix.replace("(", "_") + postfix=postfix.replace(")", "_") + postfix=postfix.replace(",", "_") + postfix=postfix.replace(" ", "") + t=t[:si1]+postfix+t[si2:] + ih.seek(0) + ih.truncate(0) + ih.write(t) +for i in glob.glob("generated/class_future*.qbk"): + with open(i, "r+b") as ih: + t=ih.read(); + # Fix failure to escape < and > + it1=t.find("<indexterm><primary>")+20 + it2=t.find("</primary></indexterm>", it1) + indexterm=t[it1:it2] + indexterm=indexterm.replace("<", "<") + indexterm=indexterm.replace(">", ">") + t=t[:it1]+indexterm+t[it2:] + # Fix failure to collapse section ids + si1=t.find("[section:future<") + if si1!=-1: + si1+=15; + si2=si1+1 + count=1 + while count>0: + if t[si2]=='<': count+=1 + elif t[si2]=='>': count-=1 + si2+=1 + postfix=t[si1:si2] + postfix=postfix.replace("<", "_") + postfix=postfix.replace(">", "_") + postfix=postfix.replace("(", "_") + postfix=postfix.replace(")", "_") + postfix=postfix.replace(",", "_") + postfix=postfix.replace(" ", "") + t=t[:si1]+postfix+t[si2:] + ih.seek(0) + ih.truncate(0) + ih.write(t) + +# Patch failure to put in-class enums in the right section +for i in glob.glob("generated/class_*.qbk")+glob.glob("generated/struct_*.qbk"): + with open(i, "r+b") as ih: + t=ih.readlines() + sections=[] + stack=[] + n=-1 + for line in t: + n+=1 + if line[:9]=="[section:": + stack.append(n) + elif line[:9]=="[endsect]": + if len(stack)==1: + sections.append((stack[0], n)) + stack.pop() + if len(sections)>2: + print("There are more than two standalone sections in "+i+". This is bad.") + elif len(sections)>1: + print("In "+i+" relocating "+t[sections[0][0]]+" into "+t[sections[1][0]]) + t.insert(sections[0][0], t.pop(sections[1][0])) + with open(i, "w+b") as ih: + ih.writelines(t) + +def write_disqus_fragment(name, title): + with open("disqus_identifiers/"+name+".html", "wt") as identh: + identh.write("""<script type="text/javascript"> +var disqus_identifier = '"""+name+"""'; +var disqus_title = 'Boost.AFIO """+title+"""'; +</script> +""") + +# Patch all reference sections with Disqus commenting +for i in glob.glob("generated/*.qbk"): + with open(i, "r+b") as ih: + t=ih.readlines() + n=-1 + skip=0 + for line in t: + n+=1 + if skip: + skip=skip-1 + continue + if line[:9]=="[section:": + name=line[9:-2]; + if name[-1]==']': name=name[:-1] + firstspace=name.find(' ') + if name[firstspace-1]=='<': + firstspace=name.find('>', firstspace)+1 + title=name[firstspace+1:].replace('<', '<').replace('>', '>') + name=name[:firstspace].replace('<', '_').replace('>', '_').replace(' ', '-') + write_disqus_fragment(name, title) + t.insert(n+1, """'''<?dbhtml-include href="disqus_identifiers/"""+name+""".html"?>''' +""") + elif line[:9]=="[endsect]": + t.insert(n, """'''<?dbhtml-include href="disqus_comments.html"?>''' +""") + skip=2 + with open(i, "w+b") as ih: + ih.writelines(t) + +# Generate disqus html fragments for these sections +disqus_sections=[ + ("introduction", "Introduction"), + ("design_rationale", "Design Introduction and Rationale"), + ("overview", "Single page cheat sheet"), + ("compilation", "Compilation"), + ("hello_world", "Hello World, asynchronously!"), + ("file_concat", "Concatenating files"), + ("atomic_logging", "Achieving atomicity on the filing system"), + ("filesystem_races", "Handling races on the filing system"), + ("so_what", "What benefit does asynchronous file i/o bring me? A demonstration of AFIO's power") +] +for name, title in disqus_sections: + write_disqus_fragment(name, title) + +# Use either bjam or b2 or ../../../b2 (the last should be done on Release branch) +#os.system("..\\..\\b2.exe") diff --git a/attic/doc/power_loss_safety_table.qbk b/attic/doc/power_loss_safety_table.qbk new file mode 100644 index 00000000..ee58033e --- /dev/null +++ b/attic/doc/power_loss_safety_table.qbk @@ -0,0 +1,17 @@ +[table:power_loss_safety Power loss safety matrix: What non-trivially reconstructible data can you lose if power is suddenly lost? [*Any help which can be supplied in filling in the unknowns in this table would be hugely appreciated]. + [[][[role aligncenter Newly created file content corruptable after close]][[role aligncenter File data content rewrite corruptable after close]][[role aligncenter Cosmic ray bitrot corruptable]][[role aligncenter Can punch holes into physical storage of files[footnote This is where a filing system permits you to deallocate the physical storage of a region of a file, so a file claiming to occupy 8Mb could be reduced to 1Mb of actual storage consumption. This may sound like sparse file support, but transparent compression support also counts as it would reduce a region written with all zeros to nearly zero physical storage]]][[role aligncenter Default max seconds of writes reordered without using `fsync()`]]] + [[[role alignright FAT32]][__itick__][__itick__][__itick__][__cross__][[role aligncenter ?]]] + [[[role alignright ext2]][__itick__][__itick__][__itick__][__cross__][[role aligncenter 35]]] + [ + [[role alignright ext3/4 `data=writeback`]][__itick__][__itick__][__itick__][[role aligncenter [role green ext4 only]]] + [[role aligncenter 35[footnote This is the `commit` mount setting added to the `/proc/sys/vm/dirty_expire_centiseconds` value. Sources: [@https://www.kernel.org/doc/Documentation/filesystems/ext4.txt] and [@http://www.westnet.com/~gsmith/content/linux-pdflush.htm]]]] + ] + [[[role alignright ext3/4 `data=ordered` (default)]][__icross__][__itick__][__itick__][[role aligncenter [role green ext4 only]]][[role aligncenter 35]]] + [[[role alignright UFS + soft updates[footnote Source: [@http://www.freebsd.org/cgi/man.cgi?query=syncer]]]][__icross__][__itick__][__itick__][__tick__[footnote BSD automatically detects extended regions of all bits zero, and eliminates their physical representation on storage.]][[role aligncenter 30]]] + [[[role alignright HFS+]][__icross__][__itick__][__itick__][__tick__][[role aligncenter ?]]] + [[[role alignright NTFS[footnote Source: [@http://technet.microsoft.com/en-us/library/bb742613.aspx]]]][__icross__][__itick__][__itick__][__tick__][[role aligncenter Until idle or write limit]]] + [[[role alignright ext3/4 `data=journal`]][__icross__][__icross__][__itick__][[role aligncenter [role green ext4 only]]][[role aligncenter 5]]] + [[[role alignright BTRFS[footnote Source: [@https://wiki.archlinux.org/index.php/Btrfs]]]][__icross__][__icross__][__icross__][__tick__][[role aligncenter 30]]] + [[[role alignright ReFS]][__icross__][[role aligncenter [role green not if integrity streams enabled]]][[role aligncenter [role green not if integrity streams enabled]]][__tick__][[role aligncenter Until idle or write limit]]] + [[[role alignright ZFS]][__icross__][__icross__][__icross__][__tick__][[role aligncenter 30]]] +] diff --git a/attic/doc/quickstart.qbk b/attic/doc/quickstart.qbk new file mode 100644 index 00000000..ebf9b0bc --- /dev/null +++ b/attic/doc/quickstart.qbk @@ -0,0 +1,1261 @@ +[/============================================================================ + Boost.AFIO + + Use, modification and distribution is subject to the Boost Software License, + Version 1.0. (See accompanying file LICENSE_1_0.txt or copy at + http://www.boost.org/LICENSE_1_0.txt) +=============================================================================/] + +[section:quickstart Quick Start Tutorial] + +So why bother with __boost_afio__? What's wrong with the STL iostreams and Filesystem? + +The answer is that there is nothing wrong with either for 95% of use cases. Performance +of both is pretty good in fact most of the time __dash__ which actually isn't that +surprising as C++ is a pay-for-what-you-use systems language, and you'll see how well +STL iostreams does later on in this tutorial. + +However a surprising amount of production code out there is highly unreliable when used on a filing +system experiencing rapid change, or even just a filing system mounted on a network. In many +ways it is when your code needs to ["grow up] from assuming a never changing static filesystem +into a more realistic model is when you ought to reach AFIO which has hopefully abstracted away +all those tedious platform specific and filing system specific quirks for you. + +The quick start tutorial is broken into two sections: + +# A step by step workshop in building an AFIO program which can concurrently read/write an indexed +blobstore. This workshop was presented at CppCon 2015 and the slides and materials can be found +at <TBD LINK>. Issues covered: + * Files being renamed, created or deleted by others when you are using them. + * Directories being renamed, created or deleted by others when you are using them. + * Windows only: how to correctly delete a directory tree on Windows, and why almost every +implementation of directory tree deletion for Windows is unreliable. + * Techniques for avoiding filing system races: + * Inode checking + * Lock files + * Atomic renames + * Never use absolute paths +# Real world sample mini-programs written using AFIO which show various filing system algorithms +and strategies in action. + * Hello world + * Concatenating files + * Atomicity on the filing system + * Races on the filing system + * Find regular expression in files in directory tree + +[section:workshop Step by step workshop building an AFIO-based key-value store] + +[section:naive 1. World's simplest named blob store in STL iostreams] + +Let us imagine your application needs to persist some state across executions, and that that state +is merely a collection of key-value items e.g. + +* "dog" => "I am a dog" +* "cat" => "I am a cat" +* "horse" => "I am a horse" +* ... + +Let us imagine that you write the following low level public interface for this key-value store: + +[workshop_naive_interface] + +The macros for the monad and afio namespaces are to enforce a ['hard] version dependency. By aliasing +into the `BOOST_AFIO_V2_NAMESPACE`, you are creating a specific dependency on v2 of the AFIO ABI. AFIO +ships some still supported previously used ABI versions of itself in every version, so by pinning yourself +to v2 you mean v2 and nothing but v2. If you just wanted the current AFIO, simply alias into namespace +`boost::afio` as with other libraries, this picks up whatever the current configuration and version of +AFIO is. + +The `outcome<>` comes from __boost_outcome__ which is a dependency of __boost_afio__. It has an identical +API to `std::future<>` or more rather `boost::future<>`, so simply treat it as an always ready future. +`outcome<>` here can return a shared pointer to the iostream, or empty (item not found), or an error, or +an exception as you can see in this example use case: + +[workshop_use_naive] + +A perfectly straightforward and simple way of implementing `data_store` using pure C++ STL is this: + +[workshop_naive] + +Note that `outcome<T>` implicitly consumes any `T`, `std::error_code`, `std::exception_ptr` or `empty`, hence +the ability to return any of those directly. + +This very simple solution assumes that the key-value store is a directory in the current path called ["store] and +that each key-value item is simply a file called the same name as the key name. + +[table:conditions This solution will perform pretty well and is perfectly fine under these conditions: +[[][Condition]] +[[__cross__][On Microsoft Windows you don't place the store deep in a directory hierarchy and you use only short key names.]] +[[__cross__][No third party thread or process will rename the location of the store during use.]] +[[__cross__][The size of the values being read and written is small.]] +[[__cross__][Only one thread or process will ever interact with the key-value store at a time.]] +[[__cross__][You don't care what happens if your process unexpectedly exits during a modify.]] +[[__cross__][Maximum performance isn't important to you.]] +[[__cross__][You don't care what happens under power loss.]] +[[__cross__][You don't need to update more than one key-value at once.]] +] + +[endsect] [/ naive] + +[section:naive_afio 2. World's simplest named blob store in AFIO (synchronous)] + +Let's see the same thing as in the last section, but written using AFIO. First, the interface is identical +to before, just with different private member variables: + +[workshop_naive_afio_interface] + +We now have a `dispatcher_ptr` and a `handle_ptr` to the store directory which is created/opened during +construction of `data_store`. Instead of constructing to a filesystem path, we now construct to an AFIO path. +Note that AFIO paths are always either absolute or relative to some open file handle, and therefore in this +situation at the point of construction the current working directory will be fetched and an absolute path +constructed. This differs from filesystem which passes through relative paths and lets the OS resolve from +the current working directory __dash__ AFIO does it this way as the current working directory setting at some +later point of asynchronous execution is inherently unpredictable. As the `data_store` interface is identical, +so is the use case from the previous page. The implementation is rather different however: + +[workshop_naive_afio1] + +This is a good bit longer and looks more complex, however there is already a big if not obvious gain: third party +processes can happily rename and move around the store directory once it has been opened and this implementation +will work perfectly. This is because we open a handle to the store directory in the `data_store` constructor, +and thereafter use that open handle as a base location for all leaf path operations. Except on OS X which currently +doesn't support the POSIX race free filesystem extensions, that makes all data store operations invariant to +store path mutation on all supported platforms. + +Another big gain is we are now using memory mapped files for the lookup which avoids any memory copying, and +there is a hint we are also avoiding memory copies in the write too. + +You will also note that in the constructor, we specify a URI to `make_dispatcher()`. This lets you open +different kinds of filesystem e.g. ZIP archives, HTTP sites etc. AFIO currently doesn't provide backends except +for `file:///` i.e. the local filesystem, however future versions will. Note that a dispatcher can force on or off +`file_flags` for all operations scheduled against that dispatcher __dash__ here we force mask out any attempt to +open anything for writing if we are opening the store read-only. + +Finally, you may wonder why we only use `current_dispatcher_guard` once in the constructor. This is because +if AFIO can deduce the dispatcher to use from any precondition you supply, you need not set the thread local +dispatcher. As the opening of the store directory is done as an absolute path lookup and therefore takes no +inputs specifying a dispatcher, you need to set the current dispatcher in that one situation alone. + +The remaining magic is in the custom iostreams implementations `idirectstream` and `odirectstream`: + +[workshop_naive_afio2] + +These are not hugely conforming iostreams implementations in order to keep them brief for the purposes of this +tutorial. The read stream is very straightforward, we simply have `streambuf` directly use the memory map of +the file. + +The write stream is a bit more complicated: we fill a 4Kb page and ['asynchronously] write it out +using a page stealing friendly algorithm which in the usual case means the kernel simply takes possession of +the 4Kb page as-is with no memory copying at all. At some future point it will be flushed onto storage. The +reason this works is thanks to the special STL allocator `utils::page_allocator<>` which returns whole kernel +page cache pages. Most kernels will mark whole pages scheduled for write with copy-on-write behaviour such that +they can be safely DMAed by the kernel DMA engine as any subsequent write will cause a copy, so because we never write to the page between the write +request and freeing the page, most kernels simply transfer ownership of the page from the user space process +to the file page cache with no further processing. Hence the asynchronous write of the page tends to complete very +quickly __dash__ indeed far faster than copying 4Kb of memory and often quicker than the time to fill another page, and hence we wait for any previous write to +complete before scheduling the next write in order to report any errors which occurred during the write. + +This is the first use of asynchronous i/o in this tutorial. AFIO provides a custom `future<T>` type extending +the lightweight monadic futures framework in __boost_outcome__, so you get all the +[@http://www.drdobbs.com/parallel/improving-futures-and-callbacks-in-c-to/240004255 C++ 1z Concurrency TS extensions], +[@http://blogs.msdn.com/b/vcblog/archive/2014/11/12/resumable-functions-in-c.aspx C++ 1z coroutines support] and +[@http://www.boost.org/doc/html/thread/synchronization.html#thread.synchronization.futures Boost.Thread future extensions] in the AFIO custom `future<>`. There are also many +additional extensions beyond what Boost.Thread or the Concurrency TS provides, including foreign future composable waits. + +[table:conditions This solution will perform reasonably well under these conditions: +[[][Condition]] +[[__tick__] [On Microsoft Windows you can place the store deep in a directory hierarchy and use long key names.]] +[[__tick__] [Third party threads and processes can rename the location of the store during use.]] +[[__tick__] [The size of ['all] the values being read at any given time fits into your virtual address space (which is at least 2Gb on 32 bit, 8Tb on 64 bit).]] +[[__cross__][Only one thread or process will ever interact with the key-value store at a time.]] +[[__cross__][You don't care what happens if your process unexpectedly exits during a modify.]] +[[__cross__][Maximum performance isn't important to you.]] +[[__cross__][You don't care what happens under power loss.]] +[[__cross__][You don't need to update more than one key-value at once.]] +] + +[endsect] [/ naive_afio] + +[section:naive_afio_async 3. World's simplest named blob store in AFIO (asynchronous)] + +Let's see the same exact thing as in the last section, but this time with a fully asynchronous public interface. +Instead of returning `outcome<>`, we now return `shared_future<>`: + +[workshop_naive_async_afio_interface] + +An extension to the Concurrency TS futures is that Boost.Monad futures are also monads, and therefore implicitly +convert from their allowed monadic input types without you needing to write `make_ready_future(T)` as with the +Concurrency TS. + +You may be interested to know that the benchmarking harness code is 100% identical for all three of these +implementations. This is because `outcome<>` is sufficiently API-identical to `future<>` that identical code can drive all +three implementations. + +`write()` is now implemented by scheduling the file to be opened for write access and attaching a continuation +which will propagate any error, and if no error returns via the shared future the shared pointer to the output stream. + +[workshop_naive_async_afio1] + +`lookup()` takes the chaining of continuations one sequence further. It schedules the file to be opened for reading +and attaches a continuation which firstly propagates any error, and then if the file is big enough it memory maps +the file and returns the input stream. If the file is small enough it schedules a read of the entire file, attaching +a second continuation to return the input stream. + +The below pattern is 100% pure soon-to-be-standardised Concurrency TS future continuations which can be easily coroutinised +automatically on a C++ 1z Coroutines supporting compiler (simply insert `await` before any AFIO `async_XXX` function). Apart from the fact that +__boost_outcome__ lightweight futures also provide an `error_code` transport, there is nothing below which wouldn't +work with an upcoming standard C++ library (unless the TS changes substantially, which is very unlikely at this late +stage). + +[note This peer review edition of AFIO v1.40 provides a shim future type standing in for an eventual lightweight future +implementation. C++ 1z coroutine support is not implemented for the shim future type.] + +[workshop_naive_async_afio2] + +The input and output stream implementations are pretty similar to before, but here they are for reference: + +[workshop_naive_async_afio3] + + +[section:naive_racy The problems with this naive design] + +You might be curious as to the performance of this naive key-value blob database. I was, so I performed the +following benchmarks on Win8.1 NTFS and Linux ext4 both on SSD using the code above. Note that the test +uses OpenMP to parallelise the operations, so the below shows AFIO in a worst case light as will be explained +shortly: + +[role aligncenter [$../../../../../libs/afio/doc/src/images/workshop_naive_insertions.png] [$../../../../../libs/afio/doc/src/images/workshop_naive_lookups.png]] + +I don't know about you, but I was more than quite surprised at how good the performance is considering its +naive simplicity. As a reference comparison, with durability disabled these NoSQL key-value databases achieve +the following performance ([@http://www.datastax.com/wp-content/themes/datastax-2014-08/files/NoSQL_Benchmarks_EndPoint.pdf source]): + +[table:nosql Performance for various NoSQL databases with fsync disabled on Linux ext4: +[[][[*Our naive design]][Cassandra][Couchbase][HBase][MongoDB]] +[[Insertion][[*25,576]][53,067][40,063][38,991][18,038]] +[[Lookup][[*64,495]][38,235][14,503][3,955][2,752]] +] + +The naive results were calculated by excluding the highest value and averaging the next three highest values. +Now this is not a fair comparison by any means __dash__ the NoSQL databases are running over a network stack +(which particularly penalises read performance) whereas ours is direct to the OS API more or less, +and our naive benchmark only writes 10 bytes of value per item which is small enough to pack into the inode +on both NTFS and ext4, so the extent allocator is never getting invoked. Still, one is used to thinking of +the filesystem as incredibly slow and to be avoided with fancy database software __dash__ this simple test +shows that ['recent] filesystems are competitive to fancy databases (and indeed even more so with a more +sophisticated design than the one we used, as you will see later). + +[note NTFS has such poor insertion performance because Microsoft Windows performs a sequentially consistent flush of the +containing directory on file handle close, whereas Linux doesn't even flush the containing directory after +you fsync a file and you must explicitly fsync the directory itself. You may find the +`afio::file_flags::temporary_file` flag of use as this hints to Windows that the file is not important, +and it may encourage Windows to not be so careful with sequentially flushing directory changes every single written +file close.] + +As is fairly obvious from the results, AFIO lags far behind iostreams at about one half to one third the performance. +We are using AFIO's synchronous API for the most part, and that is simply a `get()` on the asynchronous API which +introduces an unnecessary thread sleep (the fully asynchronous edition is about 0-5% faster). Much more importantly, +because no platform provides asynchronous file open nor close, AFIO emulates asynchronicity by +executing the file opens and closes in a threadpool which is exactly what the iostreams does via OpenMP, however there +isn't a copy of ASIO and AFIO and all the futures and completion handlers standing in between, so the iostreams +implementation is far faster and will [*always] be faster than AFIO if you do a lot of file opens and closes which +is pretty much this benchmark in a nutshell. + +[note This peer review edition of AFIO v1.40 uses a mocked up v1.40 API based on the v1.3 series engine. Performance +of this mockup will be considerably below the final v1.40 engine written using __boost_outcome__'s lightweight futures.] + +A design which makes better use of AFIO is one which is asynchronous throughout and which avoids file opens and closes +(['tip:] always avoid file opens period if you want fast filesystem performance, they are always very slow due +to the security checking of every single item in the path. File closes are also particularly slow on Microsoft Windows +and Apple OS X). + +Some might think that the flat store of all the keys in a single directory would scale poorly to item count. +This certainly ['used] to be true for the previous generation of filing system, however modern filing +systems usually have between `O(log N)` to `O(1)` lookup complexity and between `O(N)` and `O(1)` insertion +complexity __dash__ this author found excellent lookup performance with 10M items on ext4 and NTFS, +though insertion performance was not great for NTFS (which does a directory flush each file close). + +[*Problem 1 with naive design:] We are doing too many file opens and closes for really good performance. + +[*Problem 2 with naive design:] ['Atomicity]: Writes do not atomically appear fully completed to other readers, so if one thread/process reads a value +currently being written by another thread/process, they will see a partially written value which is a filesystem race. + +[*Problem 3 with naive design:] ['Consistency]: If a writer process fatal exits during a write and therefore does not complete a write, the key value store +is corrupted. + +[*Problem 4 with naive design:] ['Isolation]: There is no concurrency ordering control apart from that provided by the operating system. AFIO exposes +the strong guarantees made by operating systems as to the atomicity of read and write visibility to other readers and writers (see each +API reference documentation page for the guarantees per API per platform), however the STL iostreams wrapper +around AFIO ruins those guarantees (this is why AFIO does not provide iostreams wrappers). + +[*Problem 5 with naive design:] ['Durability]: If power loss occurs during use of the key-value store, you are at the mercy of random chance as to +what data in what order reached physical storage. On many filing systems you aren't even guaranteed +that extent metadata matches contents, so your value may consist of portions of valid data intermixed with +garbage. + +[*Problem 6 with naive design:] Insertion and update complexity may be as poor as `O(N)` on some filesystems. + +[*Problem 7 with naive design:] There is no way of atomically updating two or more key-value items in a transaction. + +Luckily, AFIO exposes exactly the right features to make five of those seven problems go away with very few changes +to the above code. + +[endsect] [/naive_racy] + +[endsect] [/naive_afio_async] + +[section:atomic_updates 4. Second attempt at a key-value store: How to implement atomic value updates and therefore Atomicity, Consistency, Isolation and Durability] + +The naive key-value store simply stored each key in a single flat directory, so: + +* "dog" => `store/dog` +* "cat" => `store/cat` +* "horse" => `store/horse` +* ... + +When inserting or updating an item, it simply opened the filename and wrote out the contents +thus creating races for concurrent users and potentially writing out the entire directory inode +if that filesystem rebalances its directory contents. So how do we implement ACID-ity of updates +with constant time updates? + +It is actually surprisingly simple thanks to AFIO. Firstly, we are going to reorganise the +store's structure with a directory per key name to become this instead: + +* "dog" => `store/dog/0` +* "cat" => `store/cat/0` +* "horse" => `store/horse/0` +* ... + +We are going to change the lookup semantics to this instead: + +# For some key, open the file `store/key/0` for reading. + +The insertion semantics becomes this: + +# For some key, open the file `store/key/tmpXXXXXXXXXXXXXXXX` for writing ['optionally] using `afio::file_flags::always_sync` +(this causes the OS to not report write completion until the write reaches physical storage), +creating any `store/key` directory as necessary, where `XXXXXXXXXXXXXXXX` is a cryptographically strong +128-bit random number. + +# Write the new value using the output stream as normal, keeping the handle open. + +# Atomically rename `store/key/tmpXXXXXXXXXXXXXXXX` to `store/key/0` using AFIO's special `atomic_relink()` +function (which because it acts on an open file handle, is invariant to path relocations of itself). +This function does as it says, and atomically makes visible at `store/key/0` our new value for +the key, unlinking any file previously there[footnote This operation is not possible on Microsoft +Windows using the Win32 API __dash__ nowhere in the Win32 API is this operation made available. +However the NT kernel API does provide this operation, hence AFIO can provide POSIX atomic relink +guarantees on Windows.]. [*Never at any point is there not a complete and finished +value file on physical storage at `store/key/0`][footnote This may not be true on older NFS mounts, +or NFS mounts with the wrong configuration. See the NFS documentation. It is also possible to +configure Samba in a way which breaks the atomicity of atomic renaming, see the Samba documentation.]. +On Linux only we then execute a sync on the directory handle for `store/key` because Linux is +different from other operating systems in that you must explicitly request metadata updates to be sent +to physical storage. + +Not that we'll be implementing this here, but the deletion semantics would be: + +# Atomically rename `store/key` to `store/deadXXXXXXXXXXXXXXXX` where the latter part is another 128-bit +crypto strong random number. Note that Microsoft Windows does not permit you to rename a directory +containing an open file, so you may need to move all the contents of the directory into a newly created +`deadXXXXXXXXXXXXXXXX` directory instead, being careful of races caused by someone setting a new key-value +into the directory you are trying to delete. + +# Recursively delete the dead directory. On Microsoft Windows, AFIO tags the items for later deletion when +the last handle to them is closed. Remember that someone doing a lookup may still have a handle open to +the just deleted version of the handle, but on both POSIX and Windows this is fine __dash__ the physical +storage will be deallocated on last handle close, even (usually) under unexpected power loss. + +What these new semantics achieve: + +# [*Atomicity]: Values always appear to concurrent readers complete and finished. +# [*Consistency]: If a writer fatal exits during a key update, the store is left in a consistent state. +# [*Isolation]: The operating system provides strong ordering guarantees about atomic relinking, +thus creating a sequentially consistent ordering of key-value update visibility. +# [*(Durability)]: If power loss suddenly occurs, the key-value store will [*always] be internally +consistent, even if `afio::file_flags::always_sync` was not specified (see below for why). +It may not have all the key-values in an identical order to how they were written as +this second generation design does not implement transactions, but there will always be a complete +value for a key which at some point was stored to that key. Strictly speaking, this means that +durability is not fulfilled __dash__ durability means when you are told a write completes, it is +durably stored, however for full durability simply add `afio::file_flags::always_sync`. +# [*Much improved update complexity]: New key insertion may still be as poor as `O(N)` complexity, but +updates of existing keys is now no worse than lookup complexity, which is a big improvement over +the naive design. If your filing system has `O(N)` insert complexity, you could use prefix directories to +form a binary tree, thus reducing insert complexity to `O(log N)`. + +Many readers will be wondering why `afio::file_flags::always_sync` is not necessary for consistency +even under power loss, and the answer is because of journalled filing systems combined with how we are +modifying data. If you examine [link afio.design.acid_write_ordering.write_ordering_data.power_loss_safety the table of power loss +safety guarantees in the design rationale], you will note that journalled file systems (with write barriers +enabled) make strong guarantees about newly created file content but not about rewritten file content: +if a newly created file appears in the filing system, it is guaranteed to have correct contents because +['journalled filing systems do not write an updated directory pointing to the new file until the file +contents are on physical storage]. Our naive design of creating a brand new file per key-value update +exploits this guarantee, so the sequentially consistent ordering of writes to physical storage, even +without `afio::file_flags::always_sync`, is this: + +# Allocate extents for new file content. Write journal. +# Write new file content to physical storage. Write journal. +# Write new copy of directory containing atomic rename of randomly named file with deallocation +of extents of previous file. Write journal. + +If power is lost at any point, during journal replay on power restore a journalled filing system will +throw away any extents allocated for content not referenced by a directory on physical storage. The +filing system on power restore therefore refers to a previously consistent filing system i.e. how it +was just before power was lost. This is why the store will be consistent even under power loss[footnote +This is as yet untested by empirical testing, however AFIO does no magic tricks, it just thinly wraps +the operating system APIs.], though without `afio::file_flags::always_sync` you may lose up to 5-35 +seconds of updates and there may be reordering of updates by up to 5-35 seconds. Here is the table +from the design rationale once again, for your convenience: + +[include power_loss_safety_table.qbk] + +It goes, of course, without saying that if you are [*not] on a journalled filing system then you absolutely +need `afio::file_flags::always_sync` and on Linux you had best sync the directories containing newly written +files too. + +So let's look at the code: you will be surprised at how few changes there are compared to the earlier +asynchronous AFIO implementation. Firstly, the interface is unchanged from before: + +[workshop_atomic_updates_afio_interface] + +`lookup()` is almost identical to before, now it simply opens `key/0` instead. + +[workshop_atomic_updates_afio1] + +`write()` is a bit different. We now open the key directory, and while that is happening asynchronously +we generate a crypto strong random name which tends to be slow. We then schedule creating that temporary +file with the extra flag `afio::file_flags::hold_parent_open` (which incidentally can dramatically increase AFIO +filesystem performance because a number of fast code paths can be taken e.g. fetching most metadata +about a file on Windows will actually do a single glob directory enumeration on its parent directory when available +which is about 20x faster. The reason it is not enabled by default is because of process file descriptor limits +on POSIX, especially the severely low default limit on Apple OS X). In this particular case, we just want +our temporary file to retain knowledge of its parent because we will fetch that parent later. + +[workshop_atomic_updates_afio2] + +Finally the input and output streams. The input stream is unchanged, whilst the output stream +destructor now simply atomically renames the temp file to "0" using the parent directory handle +as the base for the rename target in order to ensure race freedom. + +[workshop_atomic_updates_afio3] + +Obviously enough we don't have any garbage collection in here for failed or aborted writes. Thanks +to the unique naming of those files, these are very easy to spot during a GC pass and if they had a +last modified date several days ago they would ideal for purging. Implementing one of those is easy +using __afio_enumerate__, and is left as an exercise for the reader. + +[table:conditions This second generation solution will perform reasonably well under these conditions: +[[][Condition]] +[[__tick__] [On Microsoft Windows you can place the store deep in a directory hierarchy and use long key names.]] +[[__tick__] [Third party threads and processes can rename the location of the store during use.]] +[[__tick__] [The size of ['all] the values being read at any given time fits into your virtual address space (which is at least 2Gb on 32 bit, 8Tb on 64 bit).]] +[[__tick__] [As many processes and threads may read and write to the store concurrently as you like, +including any mix of CIFS and NFS clients.]] +[[__tick__] [Processes may unexpectedly exit during modifies with no consequence on consistency.]] +[[__cross__][Maximum performance isn't important to you.]] +[[__tick__] [Sudden power loss may not maintain original write ordering across multiple key-value +updates, however each key will have some complete value which it had at some point in history.]] +[[__cross__][You don't need to update more than one key-value at once.]] +] + +[section:atomic_updates_problems The performance of and problems with this second generation design] + +Let's see how this second generation ACI(D) design benchmarks compared to the first AFIO implementation +where the dotted lines are the previous generation design: + +[role aligncenter [$../../../../../libs/afio/doc/src/images/workshop_atomic_updates_insertions.png] [$../../../../../libs/afio/doc/src/images/workshop_atomic_updates_lookups.png]] + +Lookups are actually not better __dash__ we are comparing the synchronous naive design to an asynchronous +design, so the asynchronous design pulls ahead a bit on Microsoft Windows. Note, though, that the extra +directory indirection costs you a noticeable amount of performance on ext4 __dash__ perhaps as much as 15% +once you include the 10% bump from the asynchronous API. + +Insertions are however diametrically slower: about four times slower on both NTFS and ext4. This is +because atomic renames appear to not parallelise well __dash__ both filing systems are gating hard at about +four parallel atomic renames (the number of cores on my test CPU), and if you throttle the parallelism +by hand you'll find performance is really only half that of the first generation design which is logical +as we are committing twice the new items to before. This is a good example of where Intel's Hyperthreading +can really penalise overall performance sometimes: filing systems tend to parallelise linearly to real +CPU core count only. + +This second generation design is actually quite solid, and assuming that the design rationale is correct +about the sequential consistency of journalling file systems then this key-value store design is likely production code +useful, especially if you are storing large blobs which you might like to individually memory map. What you don't have +though is the ability to update key-values as a transaction, and insertion performance is already heading +downwards towards less than 1000 items/second which bodes poorly for adding transaction support. + +Out of curiosity, how might we add transaction support to this design? One's first thought is a lock file +of some sort, perhaps even a lock file for the entire store. AFIO v1.3 can push about 3000 exclusive lock files +per second (see the mini-programs on atomicity following this section) so you might imagine holding a global lock +file during reads and during a sequence of multiple atomic renames which make up committing a transaction. + +Unfortunately, while that strategy would work well most of the time, it falls down spectacularly in the +situation of power loss. The problem you have is that you have no way at all of forcing the order of +key-value updates to reach physical storage. You might think that calling `fsync()` or using `O_SYNC` +and then writing each item sequentially might work, but imagine if power is lost in the middle of +that sequence: how do you know if the store you are now looking at was in the middle of a transaction, +and if so what needs to be rolled back? + +If you think this through, you realise that you need some form of write log from which an interrupted +sequence of operations can be reconstituted and either completed or discarded to return a store to +a consistent state. This write log is called a journal by journalling file systems, and is called +various things by databases ([@https://www.sqlite.org/wal.html write ahead logging, rollback journal etc]). +It has the special property that it is always moving forwards in time and what it records is the +sequentially consistent history of the database. + +You have probably guessed what the final part of this workshop tutorial does: and indeed it is +implementing a transactional write log. + +[endsect] [/atomic_updates_problems] + +[endsect] [/atomic_updates] + + +[section:extents_theory 5. Third attempt at a key-value store: Thinking like a filing system] + +You should prepare yourself to now think outside your normal comfort zone, and like a filing system engineer. + +Modern filing systems are ['extents] based, which means that instead of your file content being stored +as the program sees it when reading it, physical storage allocation is [*lazy]. In other words, only when +you write first into an extent is physical storage actually allocated, and if you never write into an +extent then no physical storage is consumed, despite that that region of the file reads as all bits zero. + +You can test this for yourself by the following shell command on an extents-based filing system (e.g. +ZFS, UFS, HFS+, ext4): + +``` +ned@kate:~$ truncate -s 2T sparse.img +ned@kate:~$ ls -ls sparse.img +0 -rw-rw-r-- 1 ned ned 2199023255552 Aug 19 16:13 sparse.img +``` + +The first zero shows the allocated size of the file, which is zero. The maximum allocation of the file, +which is reported as the size, is 2Tb. Let's try writing a single byte onto the end of the file: + +``` +ned@kate:~$ echo '0' >> sparse.img +ned@kate:~$ ls -ls sparse.img +4 -rw-rw-r-- 1 ned ned 2199023255554 Aug 19 16:17 sparse.img +``` + +The maximum allocation has increased by two bytes as you would expect. However, the actual real +allocation is now in fact four bytes! If you were not on an extents-based filing system the +echo append command would take a very long time to execute and you would in fact get a 2Tb +sized file almost entirely made of zeroes! + +Different filing systems have different granularities of extent. ext4, for example, usually +has a 4Kb extent granularity unless it is a partial final extent. ZFS usually has a 128Kb +granularity, while NTFS usually has a 64Kb granularity. The key thing to remember here is +that the granularity is usually quite chunky, so storing a single byte every 256Kb offset +is going to be extremely wasteful of physical storage. AFIO provides enumeration of the +allocated extents of a file using __afio_extents__. + +Just as you can lazily allocate physical storage for file content using extents, so too +can you deallocate extents by ["punching holes] in a file's content storage. This simply +eliminates the physical storage for a region, and therefore subsequent reads from that +region will now return all bits zero. AFIO's API for doing this deallocation is +__afio_zero__, and just to remind you of which filing systems provide extents and APIs +to manage them, here is that power loss safety table once again: + +[include power_loss_safety_table.qbk] + +[heading Visibility of concurrent writes to concurrent readers in file i/o] + +The final piece of the puzzle is [*atomicity of writes]. Many people do not realise that POSIX operating +systems are supposed to provide some strong POSIX-mandated guarantees about the visibility of file i/o to concurrent +readers and writers, and these guarantees AFIO goes out of its way not to interfere with. These are: + +# The ['visibility] of a write to a file is to be atomic to all readers of the same file, including +gather writes (note gather writes on Microsoft Windows are not atomic, but single buffer writes may be, +see below). The POSIX-2008 wording is this: + + [:['["If a `read()` of file data can be proven (by any means) to occur after a `write()` of the data, it +must reflect that `write()`, even if the calls are made by different processes. A similar requirement +applies to multiple write operations to the same file position. This is needed to guarantee the +propagation of data from `write()` calls to subsequent `read()` calls.]] ([@http://pubs.opengroup.org/onlinepubs/9699919799/functions/write.html POSIX-2008])] + + If you try to implement this wording, you quickly realise there is an implied mutex on each file in the +kernel, and every read to and write from that file across the system involves holding that mutex during +the read or write. Whether that is actually the case is unimportant, POSIX requires that it must appear +to file i/o readers and writers that this is as if so. + + In actual implementations however, the reality is somewhat different. The first obvious difficulty +is with networked filing systems where performance would be awful if an implied mutex had to be claimed +for every single read and write, so networked filing systems don't do that. The second big deviation +is with memory mapped files as reading and writing raw memory does not synchronise on +the implied per-file mutex and therefore you may see a partially written write during a read. All the +major operating systems do just happen to synchronise i/o between memory maps and normal +read/write so long as nobody is using `afio::file_flags::os_direct` i.e. `msync(MS_INVALIDATE)` +is a noop on any recent major operating system, however memory map i/o still races on itself and +on normal i/o operations. This, incidentally, is why AFIO does not provide much memory map support currently. + + An additional problem beyond these is that Linux is simply non-conforming to POSIX-2008 here, +and has unfortunately been so for a very long time. Linux does lock on a per-page granularity, +so per 4Kb page it locks and nothing past that. This implies that if your read unfortunately +straddles a 4Kb boundary, you have a race. XFS has implemented additional locking to solve this +problem, but ext4 has not. You can see more detail +[@http://jeffr-tech.livejournal.com/20707.html here] and [@http://permalink.gmane.org/gmane.comp.file-systems.ext4/27225 here]. + + Finally, Microsoft Windows makes no public guarantees about the atomic visibility of writes except +that nothing is guaranteed past a sector size, and by that they are referring to the atomicity +of a write reaching storage rather than anything about visibility to concurrent reader writers. +From how the NT kernel IRP queue works whereby reads and writes both enter the same serialised queue, +it seems to me that the POSIX visibility guarantees are met which would be expected as the NT kernel +is explicitly designed to be POSIX compliant, however one should be cautious here. I note from a +review of portable databases that none makes strong assumptions about read-write visibility ordering, and +I assume that is for a reason __dash__ though that reason could simply be ["Linux]. + + [*If] you are willing to restrict your end use cases to: + + * Any of the BSDs (these conform to POSIX). + * Linux with XFS (XFS implements special workarounds to conform with POSIX). + * Microsoft Windows with NTFS (it is thought to conform to POSIX). + + ... then you may be able to dispense with explicit locks. You may find the __afio_statfs__ API useful +as it can return the name of the filing system providing an open file handle. + +# By extension of the above, POSIX requires that the visibility of a write to a file opened for append-only access is also +atomic to all readers and writers of the same file. Or put more succinctly, appending to +an append-only file is atomic per syscall, so concurrent appenders are guaranteed each of +their writes will appear to be appended in full before another appender's write. Here is +the POSIX-2008 wording: + + [:['["If the `O_APPEND` flag of the file status flags is set, the file offset shall be set to the end +of the file prior to each write and no intervening file modification operation shall occur between +changing the file offset and the write operation.]] ([@http://pubs.opengroup.org/onlinepubs/9699919799/functions/write.html POSIX-2008])] + + You will be glad to know that this is a much better supported feature in implementations. +The atomicity of file append even works on CIFS/Samba network shares in the usual configuration, albeit +with a severe performance penalty (NFS network shares unfortunately do not preserve +append atomicity because the protocol is incapable of expressing such an operation). Because +memory maps are for a given file extent, file appends don't affect them, and because the requirement +is merely for the atomicity of the increment of the file size, the atomicity of the visibility of the content +appended is a separate problem to ['where] the content is appended whose increment is guaranteed +to be atomic except on NFS. + +[heading The relevance of all this filing system theory to the final key-value BLOB store] + +Why all this matters is because you need to understand all this theory to understand why the third generation +key-value BLOB store presented next is designed exactly the way it is. Unintuitively, it is going to +be a set of always-growing atomically-appended sparse files. We take advantage of hole punching +to deallocate the parts of the files no longer needed so physically consumed storage does not grow +past what is needed, but their apparent sizes grow forever and the atomicity of the atomic append operation +is used as the concurrency control mechanism for implementing transactional updates as effectively copy-on-write, plus as the mechanism +for marking time to the filing system such that extents which have exceeded their maximum age and must be +flushed to storage are always exactly those at an offset earlier in the file. Because we never open +nor close files, we avoid the costs of security checking during path lookup, and therefore maximise performance. +While the next example does not make use of memory maps as that would severely complicate the code, the +on-disk file format is capable of being used directly from a memory map which would allow high performance +scaling to hundreds of millions of key-value pairs without blinking. The only real pessimism in the +following design is that it doesn't scale well to modifies with worse than +`O(N^2)` complexity to concurrency of writers and worse than `O(N)` complexity to key count. + +We do have to take some care however. As on Linux writes are not atomic with respect to reads across +4Kb boundaries, we are going to need some mechanism of checking if some given append is valid or not, which usefully +can be reused to check a store for validity after a sudden power loss (just because reads and +writes may have sequential consistency of visibility to processes has no bearing whatsoever on what order writes are flushed +to physical storage). Any writes we make within a 4Kb boundary is probably safe e.g. to the very front +of the store file, so long as it does not exceed 4Kb. + +And just to be extra special careful, we will never do a ['rewrite] of existing content exceeding +a sector size which we'll assume is 512 bytes on a 512 byte boundary as that is publicly documented +as guaranteed for all the major operating systems. For that reason, as you will note in the implementation +next section, everything is aligned to a 32 byte boundary and we never rewrite more than 32 bytes which +guarantees we will never rewrite across a 512 byte boundary, and therefore risk atomicity. + +[section:extents The final named blob store design] + +[caution This section was not finished in time for the beginning of the Boost peer review due a hard +drive failure induced by the testing of AFIO-based key-value stores in this workshop tutorial (sigh!), but it will be finished +shortly after I get up and running again on a new hard drive (as I write this, the drive is being cloned in between +periods it hangs and I have to power cycle to get it back for more cloning). The page content is representative of the +final edition, however the source code listed has not been debugged nor tuned for performance yet +and is therefore not listed here. The benchmarks are obviously missing for this solution on the next page.] + +As you might have guessed from the theory on the preceding page, the final design of the key-value store is radically +different to before. Instead of storing each value in its own file, we have this store structure instead: + +* `store/index` + + This always growing file is a simple linear history of snapshot state of the key-value store with a full copy of +all the key-value pairs being written per transaction as a single shot atomic append. The blobs are referred to by +unique integer index into a linked small blob index (see below). The key-value pairs are stored on-disk as a dense hash +map which is very friendly to memory maps, eight bytes per entry, with the key strings stored contiguously after +the hash array. + + Each index record appended to the index is content hashed, and if during later parsing the hash does not match +the contents the record is ignored. If after power loss the end of the index is trashed, the solution +below will replay the history of transactions from the beginning, skipping any deallocated extents, until it finds the most recent complete +undamaged index which does not refer to damaged blobs (see below). + +* `store/large_blob_store` +* `store/large_blob_store.ecc` + + We don't implement the large blob store in the solution below to keep the code brief, however it is intended +to house any blob sized 4Kb or above as memory maps are a much superior way of working with larger values +and keeping large blobs separately makes extent fragmentation from hole punching much less expensive. Unlike the other +files, the large blob store is not necessarily always atomic appended, a deallocated extent might be reallocated +for example. This eliminates the problem of ever exceeding a `2^64` maximum file size. + + Each large blob is [*always] aligned to a 4Kb boundary to allow memory mapping. The large blob store is quite +stupid and contains no metadata at all __dash__ it relies on the small blob store for all metadata. This +stupidity, and the fact it is a separate file, allows you to speculatively allocate new +blob value storage before a new value is written such that one writes directly into the final storage from +the beginning with no unneeded memory copying. One then either commits the new value or throws it away by +punching a hole over it. You will notice below that each blob keeps an age from a monotonically increase count +based on updates, this is used to keep a blob pinned into existence for a period even if it is not in use. + + In short, the large blob file provides a large number of useful optimisations, but is not strictly speaking +necessary. You could just use the small blob file for all blobs, and that is what this simplified implementation +does for brevity. + + You are probably curious about the ECC file. The ECC file is a SECDED 32784,32768 Hamming code, so 16 bits (2 bytes) +of ECC per 4096 bytes. This file allows single bit flips to be healed which can save a blob from being +invalidated due to failing its hash check. We don't bother using this for either the index or the small +blob store as almost all bit flips seen in a computer system stem from non-ECC RAM rather than long term +storage, and the overhead of ECC calculation is probably not worth it except for large BLOBs given the +statistical chance of a bit flip. AFIO provides a very fast SECDED implementation in `afio::utils::secded_ecc<>`. + +* `store/small_blob_store` + + The small blob store is where all the blob values live. To add a new value, one simply constructs +a blob value record and atomically appends it in a single shot. Each blob has a hash of its content, and +if the hash does not match its contents it is considered invalid and pending deallocation via hole punching. + +The operations involved in opening a data store for use become these: + +# Create/open the store directory. +# Create/open for atomic append only the `index` and `small_blob_store` files. +# Open for read write the `index` and `small_blob_store` files into a second open handle. +# If either the `index` or `small_blob_store` files have zero length, atomic append into each their 32 byte header. +This is racy, but safe as spurious additional 32 byte headers are ignored by the parsing code. +# If either the `index` or `small_blob_store` files specify a last known length which is greater than the size +reported by the operating system, or the last good index specified by the header points to a corrupted +index, we consider either or both to be dirty. We firstly replay the +small blob store from the beginning, skipping any deallocated extents, and we atomic append a blob store index (a map of content hashes to +offsets in either the small or large blob store), updating the header to point at the new blob store index. + + We then replay the index from the beginning, skipping any deallocated extents, matching off valid index +records against our most recently generated blob store index. We choose the last uncorrupted index +which does not refer to hashes of unavailable content. + +If two processes concurrently open the same dirty data store and both repair the store, you will note +that the above healing process is invariant to concurrent heals. Again, the parsing code correctly skips +spurious atomic writes. + +The operations involved for reading a key-value: + +# We reload the index and blob store index loaded into memory if it has changed (by simply checking +if the file size for either has grown). +# We look up the blob index mapped by the key. +# We look up the blob store file linked to by the index and get the offset and file for the content. +# We read the value to be delivered using the input stream, similar to the second generation key-value store. + +The operations involved for writing a key-value: + +# We hand out an output stream which records all output to memory. +# On the destruction of the output stream, we build the gather write buffers for writing a blob with this value +(i.e. hashing the contents etc). +# We refresh the blob store index and see if this blob is already stored with an age less than 50. If so, we +update its age to 0 along with all other blobs referred to by the index. If not, we atomic append the new blob +and loop trying to atomic append an updated canonical blob store index until success (we must loop as we must +reconcile with other concurrent writers). On success, we update the header at the front of the small blob store +file to point at the new canonical blob store index with an incremented time count (this being a monotonically +increasing count of successful blob store updates). +# We refresh the index and update or add the key mapping to the map of keys to blob store index item, atomically +appending the new index. If someone else wrote a new index between our starting index and our just written index, +we return a transaction conflict error. On success, we update the header at the front of the +index file to point at the new canonical index. +# Every few thousand new indices we punch a hole earlier in index history by calling __afio_zero__. We always leave +around a few thousand indices for replay after sudden power loss. + +It may now seem that there is a big race condition in between atomic appends of a new canonical index for either +store and the updating of the header at the front of the file. This is correct, but is solved by the following +index parsing algorithm for both store files: + +# Read the header at the front of the file for the hint to the current canonical index. +# Parse each record from the hint onwards until the end of the file. + +In other words, a racily written hint adds a small bit of work to the parser, but nothing important. All we care +is that it is approximately correct. + +We don't implement item deletion as we didn't in either of the previous two generation key-value stores, however if one were +to implement it it would have these operations: + +# For all blobs in the blob store index with an age greater than 100 (this implies that writer concurrency +must never exceed 50), and where their contiguous storage exceeds 4Kb, we remove those entries from the blob +store index and write a new canonical blob store index. +# If entries were removed, we calculate a set of extents to be deallocated and fire and forget a call +to batch __afio_zero__. The extents to be deallocated are calculated by walking the small blob index +and keeping a record of extents not referred to (i.e. the gaps between blobs stored). For each of those containing +an aligned 4Kb quantity or more we rewrite the record header to have any parser skip the deallocated extent, and +deallocate the rest. + +So let's look at our new interface file. It looks pretty similar to before, the only real change is the many new +private member variable `handle_ptr`'s to the store files described above. Another change is that we now return +a `outcome<ostream>` for writing but a `shared_future<istream>` for reading __dash__ this is because as explained +earlier, writes are now fully buffered to memory before being hashed and committed as a transaction, so by explicitly +returning a monad we are saying that this is now a synchronous operation (one could just return an already ready +shared future, but this method makes public API assurances, and because a __boost_outcome__ future is a monad, +your code will likely not even notice). + +[workshop_final_interface] + +More code is to come ... + +[table:conditions This third generation solution will perform excellently under these conditions: +[[][Condition]] +[[__tick__] [On Microsoft Windows you can place the store deep in a directory hierarchy and use long key names.]] +[[__tick__] [Third party threads and processes can rename the location of the store during use.]] +[[__tick__] [The size of ['all] the values being read at any given time fits into your virtual address space (which is at least 2Gb on 32 bit, 8Tb on 64 bit).]] +[[__tick__] [As many processes and threads may read and write to the store concurrently as you like, +including CIFS clients but excluding NFS clients.]] +[[__tick__] [Processes may unexpectedly exit during modifies with no consequence on consistency.]] +[[__tick__ __tick__] [Lookup performance is breathtakingly swift and close to invariant to item count. +Write performance is much slower, but a lot faster than the atomic rename based design.]] +[[__tick__ __tick__] [Sudden power loss will restore the key-value store to some point in history +preserving the exact ordering of updates.]] +[[__tick__] [This design allows the atomic transactional update of as many key-value item at once as you like.]] +] + + +[endsect] [/extents] + +[section:extents_problems The performance of and problems with this third generation design] + +[caution This section was not completed in time for the beginning of the Boost peer review, but +it will be finished shortly.] + +[endsect] [/extents_problems] + +[endsect] [/extents_theory] + +[endsect] [/ workshop] + +[section:mini_programs Example mini-programs written using AFIO] + +[section:hello_world Hello World, asynchronously!] + +'''<?dbhtml-include href="disqus_identifiers/hello_world.html"?>''' + +We might as well jump straight in: on the left is a traditional STL iostreams +implementation with its equivalent in AFIO free functions on the right. + +[table:hello_world Traditional STL iostreams and AFIO side by side + [[[readwrite_example_traditional]][[readwrite_example]]] +] + +AFIO is based on future continuations as will be in the standard C++ library from C++ 1z onwards. +Each continuation enforces an order of execution between the asynchronous operations. + +What this means is straightforward: in the example above `async_file()` outputs on completion +an open file handle which is fed to `async_truncate()` which on completion feeds the same input +handle to `async_write()` and so on. `async_close()` takes in the open file handle, closes it, and +outputs a null file handle on completion to `async_rmfile()` which can still retrieve its last known +path before being closed. + +'''<?dbhtml-include href="disqus_comments.html"?>''' + +[endsect] [/hello_world] + +[section:file_concat A less toy example: Concatenating files] + +'''<?dbhtml-include href="disqus_identifiers/file_concat.html"?>''' + +The Hello World example didn't really demonstrate why using AFIO is any better than using +STL iostreams. The final example in this quick start will give a ["real world] and unfortunately +somewhat overwhelming in complexity example of how +AFIO can run rings around STL iostreams (complete with benchmarks!), so as an intermediate +__dash__ and hopefully not as overwhelming __dash__ +step here is a simple file copy utility which can also concatenate multiple source files +into a destination file[footnote My thanks to Artur Laksberg, Dev Lead of the Microsoft +Visual C++ Parallel Libraries team, for suggesting this as a good demonstration of an +asynchronous file i/o library. I had been until then quite stumped for an intermediate +quick start example between the first and last examples.]. + +[filecopy_example] + +This example consists of a function called `async_concatenate_files()` which will +asynchronously append those file paths in ['sources] into the file path in ['dest], with +the `main()` function simply parsing arguments and printing progress every second. +I won't explain the example hugely __dash__ it's pretty straightforward, it simply +parallel reads all source files in `chunk_size` chunks, writing them to their appropriate +offset into the output file. It +is a very good example, incidentally, of why C++11 is like a whole new language over +C++98 even for simple systems programming tasks like this one. + +You may note that the temporary buffers for each chunk are allocated using a special +`page_allocator`. If your operating system allows it, regions of memory returned +by this allocator have the maximum possible scatter gather DMA efficiency possible. +Even if your operating system doesn't allow it, it does no harm to use this allocator +instead of the system allocator. + +The chances are that this file copying implementation would be little faster than a naive +implementation however (unless the source files are on different physical devices, in which +case you'd see maximum performance). Some might also argue that firing a consumer producer thread per source +file would be just as easy, albeit that output file position management across threads +might be slightly tricky. + +Let us start into where the AFIO implementation starts to deliver real value add: a multiprocess safe log file and +finding which files in a directory tree contain a regular expression. + +'''<?dbhtml-include href="disqus_comments.html"?>''' + +[endsect] [/file_concat] + +[section:atomic_logging Achieving atomicity on the filing system] + +'''<?dbhtml-include href="disqus_identifiers/atomic_logging.html"?>''' + +__triplegit__, the forthcoming reliable graph database store, ideally needs to allow multiple processes to +concurrently read and write the graph store without mutual exclusion where possible. Each collection of hashes which form +the tree which makes up some given version of the graph is itself a hashed object in the content +addressable store, and you can have multiple named graphs in the graph store which may or may not +share nodes. One problem as with all databases is how to efficiently issue an atomic transaction +which updates multiple graphs simultaneously and atomically when there is the potential of concurrent +writers also trying to issue write transactions which may, or may not, cause conflict with other +transactions. + +The really naive solution is to keep a single lock file which is created using O_EXCL i.e. fail +if you didn't create the file for the entire graph store. This serialises +all transactions, and therefore eliminates any problems with updates clashing. This is usefully +well supported by all operating systems, and by NFS and Samba. + +A less naive solution is to keep one lock file per graph, and to +use a multiple lock and backoff strategy to lock the requisite number of graphs for some given +transaction. The big problem with this approach is that you are unfairly penalised for especially large multi-graph transactions over others +with smaller transactions as lock complexity is worse than linear. Nevertheless performance is actually not bad: these are results for my 3.9Ghz i7-3770K workstation +using AFIO to implement the lock file with various numbers of concurrent writers (note that Windows provides magic +flags for telling it about lock files, if not used expect a 40% performance reduction): + +[table:lock_file_performance Lock file performance on various operating systems: + [[writers][lock files][Win8.1 x64 NTFS HD][Win8.1 x64 NTFS SSD][Linux x64 ext4 SSD][FreeBSD 10.1 ZFS SSD]] + [[1][1][2468][2295][3590][9922]] + [[2][1][2507][2385][3583][9903]] + [[4][1][1966][2161][3664][9684]] + [[8][1][1400][1851][3703][6537]] + [[16][1][742][602][3833][1251]] + [] + [[1][8][826][888][1378][2455]] + [[2][8][508][637][576][917]] + [[4][8][67][167][417][63]] + [[8][8][37][117][106][0.55]] + [[16][8][33][77][26][0.5]] +] + +As you can see, Linux does a very good job of O(1) to waiters complexity, but performance on Windows +and FreeBSD collapses once you exceed CPU cores. Also, Windows is sensitive to device block size __dash__ the +hard drive outperforms the SSD because it has 512 byte sectors and the SSD has 4096 byte sectors. +I suspect that internally Windows memcpy()'s in device native sector sizes, or is actually sending +data to physical storage despite us marking this file as temporary. One very striking observation is +how FreeBSD is a full 2.76x the performance of Linux and 4.32x that of Windows. + +A much more intelligent way of solving this problem is to figure out which graphs are common across each +of the transactions currently pending, and to strictly order the transactions in the sequence +which maximises throughput without updates clashing. +One way of many distributed writers constructing a shared graph of dependencies is to append messages +into a shared file, and then one can deploy a distributed mutual exclusion algorithm of which those +by Suzuki and Kasami, Maekawa and Ricart and Agrawala are the most famous. This requires the ability +to atomically append to the shared file, something guaranteed on all operating systems, but unfortunately +not guaranteed by NFS nor Samba (though when combined with advisory file locking those do work as +expected, albeit with poor performance). This means that on an all-Windows setup, or if on POSIX and +not using NFS nor Samba, the atomic append method could be valuable, especially as the cost of locking +multiple actors is pretty much the same as locking a single actor so you get eight graphs locked for +the same cost as locking one. + +[table:atomic_append_performance Atomic append lock performance on various operating systems: + [[writers][lock files][Win8.1 x64 NTFS HD][Win8.1 x64 NTFS SSD][Linux x64 ext4 SSD][FreeBSD 10.1 ZFS SSD]] + [[1][1][2592][2875][1198][29]] + [[2][1][1284][2565][1344][25]] + [[4][1][1420][2384][1327][35]] + [[8][1][1262][1764][1254][55]] + [[16][1][428][520][1260][37]] +] + +Linux once against does a great job of O(1) to waiters complexity, but at the third of the speed of +a simple lock file and up to half the speed of Windows. Windows does better than Linux here especially +on SSDs where it is faster than a simple lock file, but doesn't scale to waiters once they pass CPU core count. +FreeBSD is two orders of magnitude slower which is because ZFS checksums and copy on writes file changes, +so every time we append 16 bytes we are forcing a full copy of the 128Kb extent to be issued. It would +appear that ZFS syncs its internal buffers when a different file descriptor atomic appends to the same file +__dash__ this has the above pathological performance outcome unfortunately. + +This introduces the final potential solution which is that of the quagmire of advisory file locking. +This is an area where Windows and POSIX diverge very significantly, and the interactions between +Windows and POSIX when Windows locks regions in a file on a Samba share on a POSIX machine or when +POSIX does byte range locking at all (there is a very fun stanza in the POSIX standard which basically +releases all your locks on first file descriptor close) are full of quirks, races and other nasties. +For this reason you should avoid the very temporary and experimental code currently in AFIO which +implements Samba and NFS safe file range locking where theoretically both Windows and POSIX code +can safely lock ranges in files concurrently, those APIs are not documented for good reason! +Still, performance with these __dash__ despite the hoop jumping inefficiencies AFIO leaps through +to implement relatively sane semantics __dash__ is impressive. + +[table:advisory_lock_file_performance Advisory lock file performance on various operating systems: + [[writers][lock files][Win8.1 x64 NTFS HD][Win8.1 x64 NTFS SSD][Linux x64 ext4 SSD][FreeBSD 10.1 ZFS SSD]] + [[1][1][5799][5166][3466][21536]] + [[2][1][5788][6656][2215][11654]] + [[4][1][5775][7020][1073][5384]] + [[8][1][5773][6738][518][2584]] + [[16][1][5695][5617][360][1326]] +] + +Fascinatingly the tables suddenly switch here: Windows sees O(1) to waiters complexity, whilst +Linux and FreeBSD sees a mostly O(N) to waiters complexity drop in performance. FreeBSD, as with the +simple lock file performance, blows all others out of the water again in advisory lock performance too. I +should add here that because POSIX advisory locks are per process, the Linux and FreeBSD benchmarks were +generated by running N copies of the benchmark program whereas the NT kernel inherits the really +excellent and well thought through file byte range locking model of DEC VMS and treats locks as +effectively reference counted byte ranges, and therefore works as expected from a single process. +I have yet to add process-local byte range locking to simulate sane range locking for POSIX, so +expect the numbers above to worsen. + +After all of that, we are left with this locking strategy matrix for __triplegit__: + +[table:best_locking_strategy_matrix Fastest file system locking strategy for various operating systems: + [[Operating system][Best locking policy]] + [[Win8.1 x64 NTFS][Advisory locks fastest, then atomic append locks, finally lock files]] + [[Linux x64 ext4][Lock files fastest, then advisory locks, finally atomic append locks]] + [[FreeBSD 10.1 ZFS][Advisory locks fastest, then lock files, avoid atomic append locks at all costs]] +] + +I should [*emphasise] once again that the advisory locking code is riddled with bugs and you should +not use it in your code at this time. Once I have a CI testing all possible combinations of locking +and nothing is erroring out I'll release that code for production use, probably in v1.4. + +All these benchmarks came from this benchmarking program I wrote using AFIO which illustrates how +you might implement the techniques used above: + +[benchmark_atomic_log] + +'''<?dbhtml-include href="disqus_comments.html"?>''' + +[endsect] [/atomic_logging] + +[section:filesystem_races Handling races on the filing system] + +'''<?dbhtml-include href="disqus_identifiers/filesystem_races.html"?>''' + +Filing systems are a shared resource common to all processes on the system and sometimes the network, +and are therefore as a globally shared resource inherently racy. Yet overwhelmingly programs, even often those written +by world expert programmers, singularly assume +the filing system to be a static, constant and unchanging place only modifiable by the current program, +as indeed did until very recently the POSIX API standard which defines the common API for Linux, FreeBSD, +Mac OS X and other Unices. +When bug reports come in of data being lost, even very large professional corporations can make a real +hash of testing that their ["fix] isn't worse at losing data than the previous more naive implementation. +This is because when you program against a mental model of a static, unchanging filesystem you will become +inevitably surprised when it happens to change at exactly the wrong moment __dash__ which of course is +a moment you can never replicate on your developer workstation, thus making finding and fixing these +sorts of bug highly non-trivial. + +In case you don't realise how much user data and productivity is lost each year to filing system races, +just look up ["corrupted Office file] on Google and weep. Even for us programmers, if you try keeping a +Git repository on a Samba drive expect some interesting, and moreover quite strongly associated to specific +combinations of client accessing the repo concurrently, object database corruption from time to time. + +Well, there is some good news: AFIO makes maximum use of host OS filing system race safeguards, so if you +write your code against AFIO and take note of the race guarantees section in each individual per-API +reference documentation page, you should hopefully avoid any possibility of experiencing filing system +races. + +[heading What AFIO provides for managing filing system raciness] + +Firstly, readers will probably be quite surprised to learn that the only operating system capable of providing +completely race free filing system behaviour is Microsoft Windows, or rather the very well designed NT kernel API which AFIO uses directly. +Linux provides robust file descriptor path discovery and the `XXXat()` POSIX APIs, and with those AFIO can provide pretty +good race condition safety on Linux up to the final directory in the path. +Mac OS X provides an unfortunately quite broken file descriptor path discovery, and additionally does not provide the `XXXat()` +POSIX APIs and so AFIO cannot provide race protection, but can throw exceptions sometimes if it detects the filesystem +has suddenly changed and you're about to delete the wrong file (you shouldn't rely on this, it's racy). FreeBSD provides the `XXXat()` POSIX APIs, but its file +descriptor path discovery only works correctly for directory not file handles due to a kernel bug (I've opened +a feature request ticket for this at [@https://bugs.freebsd.org/bugzilla/show_bug.cgi?id=198570 https://bugs.freebsd.org/bugzilla/show_bug.cgi?id=198570]) and therefore AFIO +can provide only race condition safety for directories only on FreeBSD. + +Additionally, working with the filing system in a race safe way on POSIX requires opening a file descriptor to the +containing directory for every operation (some proprietary Linux extensions allow this to be avoided for some operations on +newer Linux kernels). AFIO will keep a global cache of open file handles for containing directories +on request using the `file_flags::hold_parent_open` flag which can be enabled per dispatcher or per individual file handle open, +this very significantly reduces the cost of race condition safety on POSIX ['for file entries only] as directories ignore +the `file_flags::hold_parent_open` flag, though at the cost of increased file descriptor usage, which has low hard limits +especially on OS X which is why it is disabled by default. The alternative if you don't want AFIO to bother with race safety +is to specify the `file_flags::no_race_protection` flag per dispatcher or per individual file handle open, this causes AFIO +to use the same maximum performance code paths as used before the v1.3 engine. + +[heading How to implement filing system race safety on AFIO] + +The essential rule for achieving maximum filing system race safety is to avoid using absolute paths where possible. If +you want your code to also be safe on POSIX, you must additionally only assume race safety up to the final directory in +a path __dash__ thereafter design your node to never behave racily within a single directory. + +The core container type for specifying a location on the filing system to AFIO is __afio_path_req__ which looks like this: + + struct path_req + { + bool is_relative; // Whether the precondition is also where this path begins. + afio::path path; // The filing system path to be used for this operation. + file_flags flags; // The flags to be used for this operation (note they can be overriden by flags passed during dispatcher construction). + future<> precondition; // An optional precondition for this operation. + path_req(T &&); // Converts T to a filesystem::path, makes it absolute, then converts to an afio::path + path_req(bool, T &&); // If the bool is true, converts T to an afio::path fragment. If false, same as above overload (i.e. make absolute). + }; + +For convenience, type markup is provided for the boolean taking constructor, these being `path_req::relative` and +`path_req::absolute`. + +If the path is relative, then the path of the precondition is used as the base from which the relative path fragment +operates. On FreeBSD, Linux and Windows this base extension happens inside the kernel and so the current path of the precondition +really doesn't matter __dash__ it could be changing a thousand times per second and it wouldn't matter. On OS X due +to lack of the `XXXat()` POSIX APIs the path of the precondition is fetched and the extension done by hand. + +An AFIO extension allows you to specify a file as precondition. In this situation, if you specify an empty path +then you mean the precondition itself which is very useful for deleting or renaming an open file handle. If you want +a sibling file, this can be found via a path fragment starting with `../`, though note that this necessarily is racy +to the containing directory +(AFIO opens the containing directory of the file, ensuring the directory contains an inode matching the file, and +then uses that directory handle as a base __dash__ the race here being if the file relocates after matching its +containing directory). + +[heading Gotchas specific to Microsoft Windows] + +Finally, there are some gotchas specific to Microsoft Windows: + +1. You cannot rename a directory which has an open file handle in any process to any item anywhere within itself or its children. + +2. You cannot rename to a destination which has an open file handle with DELETE permissions (`file_flags::write`) +to itself or any of its parent directories in any process. You CAN do this from a source like this, but the destination cannot be +like this (why is this? It is not documented anywhere in Microsoft's documentation, but if I had to guess, I'd suggest that the +atomicity of the rename is implemented by taking an op lock on the destination, an op lock not granted if any handles exist which +could change the path suddenly. I'm not sure if Microsoft are themselves aware of this limitation). + +One might note that much of the utility of race protecting APIs is lost with these restrictions. However, note that one could +emulate POSIX semantics by renaming out all the contents of a directory to be renamed to elsewhere, rename the directory, and then +renaming the contents back in. Given the pathetic slowness of opening handles on Windows, this might seem impossibly inefficient, +however NT provides a little known `FILE_DELETE_CHILD` permission which gives you delete/rename permission on all the children +and subchildren of a directory with just one handle open. I learned about this flag the hard way, by it breaking in many subtle ways +AFIO's functioning on Windows when it was requested by default, something which took several days of head scratching to track down. AFIO doesn't +currently do this trick of renaming out and back in on Windows, but might in the future after a lot more experimentation as to if +it is viable and reliable without surprises. + +On Windows opening a directory with write access requests rename/delete privileges, whereas on POSIX +the write access request is ignored for directories as POSIX doesn't allow it anyway. This allows you to write identical code +which works universally. + +As an example of some programming AFIO safely on an extremely unstable filing system, below is the functional test which verifies AFIO +for filing system race safety. +As you will see, a worker thread is solely dedicated to renaming directories to unique names whilst the main thread creates files +inside those constantly changing directories, and relinks them into another directory which is also constantly changing on POSIX, but +is stable on Windows. This is iterated for a substantial period of time to verify that nothing goes wrong. + +[race_protection_example] + +'''<?dbhtml-include href="disqus_comments.html"?>''' + +[endsect] [/filesystem_races] + + +[section:so_what What performance benefit does asynchronous file i/o bring me? A demonstration] + +'''<?dbhtml-include href="disqus_identifiers/so_what.html"?>''' + +So we can schedule file i/o operations asynchronously with AFIO: what's the benefit of doing that +instead of creating separate threads of execution and executing the file i/o there instead? + +As a quick summary as we're about to prove our case, there are three main benefits to using AFIO +over doing it by hand: + +# You don't have to worry about threading or race conditions or losing error state (as much). AFIO +does all that for you. +# On platforms which provide native asynchronous file i/o support and/or native scatter/gather +file i/o support, AFIO will use that +instead of issuing multiple filing system operations using a thread pool to achieve +concurrency. This can very significantly reduce the number of threads needed to keep your +storage device fully occupied __dash__ remember that ['queue depth] i.e. that metric you see all +over storage device benchmarks is the number of operations in flight at once, which implies +the number of threads needed. Most storage devices are IOPS limited due to SATA or SAS +connection latencies without introducing queue depth __dash__ in particular, modern SSDs cannot +achieve tens of thousands of IOPS range without substantial queue depths, which without +using a native asynchronous file i/o API means lots of threads. +# It's very, very easy to have AFIO turn off file system caching, readahead or buffering +on a case by case basis which makes writing scalable random synchronous file i/o applications +much easier. + +What these three items mean is that writing scalable high-performance filing system code is much easier. +Let us take a real world comparative example, this being a simple STL iostreams, Boost Filesystem and OpenMP +based find regular expression in files implementation: + +[find_in_files_iostreams] + +This implementation is fairly straightforward: enumerate all files in all directories below +the current directory into a vector, fire off N threads to open each file, read it entirely +into memory, regex it for the pattern and if found print the file's path. + +Let's now look at the AFIO implementation, and you should prepare yourself because it is far +more mind bendy due to the many nestings of callbacks needed (it may remind you of WinRT or .NET +code, everything is asynchronous callback): + +[warning In the v1.4 engine we ought to gain C++ 1z stackful coroutine support which will let me rewrite +the below to be vastly simpler and without the multitude of nested callback handlers.] + +[find_in_files_afio] + +Here the `find_in_files` class is used to carry state across the callbacks __dash__ one could just +as equally bind the state into each callback's parameters instead via some sort of pointer to +a struct. But the difference in complexity is noticeable __dash__ you're probably now asking, why +choose this hideous complexity over the much clearer OpenMP and iostreams implementation[footnote +Indeed many ask the same when programming WinRT apps __dash__ Microsoft's insistance on never allowing +any call to block can make simple designs explode with complexities of nested callbacks.]? + +Well, that's simple: do you want maximum file i/o performance? Here is a search for ["Niall] in a +Boost working directory which contained about 7Gb of data across ~35k files[footnote Test machine +was a 3.5Ghz Intel i7-3770K Microsoft Windows 8 x64 machine with Seagate ST3320620AS 7200rpm hard +drive. Note that AFIO has a native WinIOCP backend which leverages host asynchronous file i/o support.]: + +[table:find_in_files_performance Find in files performance for traditional vs AFIO implementations + [[][iostreams, single threaded][iostreams, OpenMP][Boost.AFIO][Boost.AFIO `file_flags::os_direct`][Boost.AFIO `file_flags::os_mmap`[footnote The superiority of memory maps on Windows is because all buffered file i/o is done via memory copying to/from memory maps on Windows anyway, so eliminating that memory copy is huge.]]] + [[Warm cache][812 Mb/sec][1810 Mb/sec][2663 Mb/sec][N/A][6512 Mb/sec]] + [[][+0%][+123%][+228%][][+702%]] + [[Cold cache[footnote File cache reset using [@http://technet.microsoft.com/en-us/sysinternals/ff700229.aspx]]][16 Mb/sec][[*8 Mb/sec]][15 Mb/sec][13.14 Mb/sec][24 Mb/sec]] + [[][+0%][[*-50%]][-6%][-18%][+50%]] +] + +Note how AFIO outperforms the OpenMP iostreams implementation by about 50% for a warm cache, with only +a 6% penalty for a cold cache over a single threaded implementation. Note the [*50%] penalty the OpenMP +iostreams implementation suffers for a cold cache __dash__ a naive multithreaded implementation causes +a lot of disc seeks. If you map a file into memory using `file_flags::os_mmap`, AFIO will `memcpy()` from +that map instead of reading __dash__ or of course you can use the map directly using the pointer returned +by `try_mapfile()`. + +The eagle eyed amongst you will have noticed that the AFIO implementation looks hand tuned with a +special depth first algorithm balancing concurrency with seek locality __dash__ that's because I invested +two days into achieving maximum possible performance as a demonstration of AFIO's power (and to find +and fix some bottlenecks). Some might argue that this is therefore not a fair comparison to the OpenMP iostreams +implementation. + +There are two parts to answering this argument. The first is that yes, the OpenMP iostreams search +algorithm is fairly stupid and simply tries to read as many files as there are CPUs, and those files could +be stored anywhere on the spinning disc. Because AFIO +can issue far more concurrent file open and read requests than OpenMP, it gives a lot more scope to +the filing system to optimise hard drive seeks and satisfy as many requests as is feasible __dash__ +sufficiently so that with a cold cache, AFIO is a little slower than a single threaded iostreams +implementation where the filing system can spot the access pattern and prefetch quite effectively. +A completely valid solution to the OpenMP performance deficit would be to increase thread count dramatically. + +The second part of answering that argument is this: AFIO's very flexible op chaining structure lets you +very easily twiddle with the execution dependency graph to achieve maximum possible performance by +balancing concurrency (too much or too little is slower, what you need is just the right balance) +and disc seeks (enumerations are best not done in parallel, it defeats any prefetching algorithm), +unlike the naive OpenMP implementation which is much harder to play around with. Don't get me wrong: +if you have plenty of time on your hands, you can implement a hand written and tuned find in files +implementation that is faster than AFIO's implementation, but it will have taken you a lot longer, +and the code will neither be as portable nor as maintainable. + +'''<?dbhtml-include href="disqus_comments.html"?>''' + +[endsect] [/so_what] + +[endsect] [/ mini_programs] + +[endsect] [/quickstart] diff --git a/attic/doc/reference.qbk b/attic/doc/reference.qbk new file mode 100644 index 00000000..0e0dd56f --- /dev/null +++ b/attic/doc/reference.qbk @@ -0,0 +1,110 @@ +[/============================================================================ + Boost.AFIO + + Use, modification and distribution is subject to the Boost Software License, + Version 1.0. (See accompanying file LICENSE_1_0.txt or copy at + http://www.boost.org/LICENSE_1_0.txt) +=============================================================================/] + +[section:reference Reference] + +[section:macros_flags Macros and Flags] +[include generated/group_macros.qbk] +[include generated/group_file_flags.qbk] +[include generated/group_fs_metadata_flags.qbk] +[include generated/group_metadata_flags.qbk] +[endsect] + +[section:structs Structures] +[include generated/struct_enumerate_req.qbk] +[section:io_req io_req] +[include generated/struct_io_req.qbk] +[include generated/struct_io_req_3_01const_01_t_01_4.qbk] +[include generated/struct_io_req_3_01void_01_4.qbk] +[include generated/struct_io_req_3_01const_01void_01_4.qbk] +[endsect] +[include generated/struct_path_req.qbk] +[include generated/struct_stat_t.qbk] +[include generated/struct_statfs_t.qbk] +[endsect] +[section:classes Classes] +[include generated/class_current_dispatcher_guard.qbk] +[include generated/class_directory_entry.qbk] +[include generated/class_dispatcher.qbk] +[include generated/class_enqueued_task_3_01_r_07_08_4.qbk] +[include generated/class_future.qbk] +[include generated/class_future_3_01void_01_4.qbk] +[include generated/class_handle.qbk] +[include generated/class_path.qbk] +[include generated/class_thread_source.qbk] +[include generated/class_std_thread_pool.qbk] +[endsect] + +[section:functions Functions] +[include generated/group_async_file_io_dispatcher.qbk] +[include generated/group_make_io_req.qbk] +[include generated/group_process_threadpool.qbk] + +[section:dir Functions for opening/creating directories] +[include generated/group_dir.qbk] +[endsect] +[section:rmdir Functions for deleting directories] +[include generated/group_rmdir.qbk] +[endsect] +[section:file Functions for opening/creating files] +[include generated/group_file.qbk] +[endsect] +[section:rmfile Functions for deleting files] +[include generated/group_rmfile.qbk] +[endsect] +[section:symlink Functions for opening/creating symlinks] +[include generated/group_symlink.qbk] +[endsect] +[section:rmsymlink Functions for deleting symlinks] +[include generated/group_rmsymlink.qbk] +[endsect] +[section:sync Functions for synchronising changes to physical storage] +[include generated/group_sync.qbk] +[endsect] +[section:zero Functions for deallocating/zeroing physical storage] +[include generated/group_zero.qbk] +[endsect] +[section:close Functions for closing open handles] +[include generated/group_close.qbk] +[endsect] +[section:read Functions for scatter reading file contents] +[include generated/group_read.qbk] +[endsect] +[section:write Functions for gather writing file contents] +[include generated/group_write.qbk] +[endsect] +[section:truncate Functions for setting maximum file extent] +[include generated/group_truncate.qbk] +[endsect] +[section:enumerate Functions for enumerating directory contents and fetching file metadata] +[include generated/group_enumerate.qbk] +[endsect] +[section:extents Functions for enumerating file physical storage extents] +[include generated/group_extents.qbk] +[endsect] +[section:statfs Functions for fetching storage volume metadata] +[include generated/group_statfs.qbk] +[endsect] + +[section:to_asio_buffers Specialisations for how types should be parsed into ASIO scatter/gather buffers] +[include generated/group_to_asio_buffers.qbk] +[endsect] + +[endsect] + +[section:utilities Utilities] +[section:classes Classes] +[include generated/class_utils_1_1page_allocator.qbk] +[include generated/class_utils_1_1secded_ecc.qbk] +[endsect] +[section:function Functions in namespace utils] +[include generated/group_utils.qbk] +[endsect] +[endsect] + +[endsect] [/reference] diff --git a/attic/doc/release_notes.qbk b/attic/doc/release_notes.qbk new file mode 100644 index 00000000..6dc10a80 --- /dev/null +++ b/attic/doc/release_notes.qbk @@ -0,0 +1,833 @@ +[/============================================================================ + Boost.AFIO + + Use, modification and distribution is subject to the Boost Software License, + Version 1.0. (See accompanying file LICENSE_1_0.txt or copy at + http://www.boost.org/LICENSE_1_0.txt) +=============================================================================/] + +[section:release_notes Release Notes] + +[/=================] +[heading Known deviations in this version being presented for Boost peer review from +version to enter Boost if accepted] +[/=================] + +This peer review edition of AFIO v1.4 has been ["mocked up] with an API which should very closely +resemble the eventual API in the v1.4 engine which will be rewritten to use the just written +lightweight future-promise factory toolkit in forthcoming __boost_outcome__. It is, however, +still in fact the mature v1.3 engine with a faked wrapper API simulating the v1.4 engine. +Known deviations from the eventual v1.4 release: + +* AFIO's `future` is a shim type standing in for the eventual custom Boost.Monad based future. +Continuations work, but are horribly hacked together __dash__ if your continuation returns +a Boost.Monad future, it shims in a one way conversion to lightweight futures. If your continuation +returns anything else, including an AFIO future, it stays within AFIO < v1.4's fairly broken future +semantics (AFIO was first written back in 2012 when the Concurrency TS looked very different +indeed, and AFIO has not kept up). + +[warning AFIO's future shim type can't do continuations on anything but `future<void>`. For +any `future<T>` it actually executes the continuation immediately which will usually just +happen to work through fortune as the continuation usually does a `get()`.] + +* Relatedly, because AFIO < v1.4 implemented future continuations atop STL and Boost futures +using an internal hash table to look up the associated extra operation metadata per future, +these APIs will also be vanishing: + + * `async_io_dispatcher_base::completion()` - replaced with future.then() + * `async_io_dispatcher_base::call()` - replaced with future.then() + * `async_io_dispatcher_base::barrier()` - replaced with when_all(). + +* Lightweight future-promise also enables C++ 1z coroutines, and therefore the code examples +in the documentation can then be rewritten to use C++ 1z coroutines where appropriate. This +should particularly aid the find regex in files tutorial example which is currently very messy. + +[/=================] +[heading Anticipated forthcoming features in future versions] +[/=================] + +* The v1.4 engine will be rewritten yet again to use a new custom future +implementation whereby async_io_op shall become afio::future<T>. This should +let the API no longer return two sets of futures when returning results +(async_io_op therefore matches afio::future<void>), plus make best use of the +proposed concurrent_unordered_map by finally actually processing batches of +operations as a batch, instead of one at a time. + +* The v1.4 engine afio::future<T> ought to transparently support Boost.Fiber, +this should let you program against AFIO using awaitable resumable functions +which is much cleaner. The v1.3 engine already reduced latency by 50% over +the v1.2 engine, but with Fibers we finally ought to eliminate the O(waiters) +scaling for op completions in favour of O(1) to waiters. + +* AFIO v1.5 will abstract out all the OS specific code into a C (not C++) +abstraction layer. This makes it far easier to reuse the same code for a later +AFIO based Filesystem TS implementation. It also eliminates the use of C++ +exceptions at the OS specific layer. Note I may still use lambdas in the C +abstraction layer, if compiled as C these appear as C callbacks but if compiled +as C++ they are some callable type. + +* It is hoped that the v1.5 engine will have two additional bindings, one +for Microsoft COM thanks to John Bandela's CppComponents (https://github.com/jbandela/cppcomponents) +and another with plain C bindings (which actually wrap the COM object). Both +these bindings have no requirement for anything Microsoft, and work as expected +on POSIX. + +* The v1.5 engine will finally make use of the API support for alternative async_io_dispatcher +implementations, adding at least one for temp file support with special temp +file semantics, and maybe others with transparent hashing and bit flip healing +(see below). The temp file support will allow anonymous and named temp files +which can be device volume matched to some path, thus allowing file move to be +done without copying. Anonymous temp files can use Linux specific facilities +for those. + +* Finally, making good use of the new coroutine support the v1.5 engine should +have an async fast batch hash engine which provides transparent hashing of all +async reads and writes with optional SECDEC ECC calculation. Hashes will probably +be initially limited to Blake2b (crypto strong and very fast, even on ARM) and SpookyHash +(not crypto strong, but superbly fast and for small blocks), though I may dust off +my 4-SHA SSE2/NEON SHA256 engine for Intel and ARM for the giggle. In addition +to fast batch hashing, the coroutine support should make filing system tree +algorithms enormously easier to write, so expect an optimally fast race free +directory tree visitor, deleter, mover and copier which is the find in files +tutorial made generic. + + +[h5 In some later version, in order:] + +* When ignoring the close of a cached directory handle, kick out its weak_ptr from +the central directory cache if its reference count is 1. + +* Individual file change monitoring. This would be very useful for implementing +distributed mutual exclusion algorithms to avoid spinning on file updates. + +* Related to the preceding item, formal async lock file support with deadline +timeouts. + +* Portable fast file byte range advisory locking which works across network shares, +but can still utilise shared memory when possible. + +* Related to locking files, the ability to copy files (unwritten destination locked until +complete) using a variety of algorithms (including cheap copies on btrfs [cp --reflink=auto]) +with progress notification via the file change monitoring. Extend rename file and delete file +with lock file options. + +* Also related to locking files, DeleteOnClose should use advisory locks to have the +last handle close do the file delete on POSIX. + +* Right now specifying an empty path with precondition to mean same as precondition is +inefficient and racy: it opens the containing directory and uses the containing +directory as the base with its leafname. What it should do is to duplicate the handle +and use fnctl() etc to reopen the handle with the desired access and flags. + +* Extended attributes support. TripleGit could use this to avoid a second file +handle open of metadata per graph object read. Unsure if NTFS is any faster +opening EA though, need to test. + +* AFIO's stable DLL ABI is intentionally C compatible, so all one needs is a libclang +tool for generating C wrappers for the DLL ABI which massage C arrays into pseudo std::vector +const lvalue refs. Such C bindings would be all batch and have none of the friendliness of +programming AFIO in C++, but they ought to work quite well. + +* Kernel side file <=> socket data copying via sendfile and splice on Linux. Integrating +splice as async with ASIO is unfortunately painful :( + +* async_io_dispatcher_base::read_partial() to read as much of a single buffer as +possible, rather than only complete buffers. + +* Fast, scalable portable directory contents change monitoring. It should be able +to monitor a 1M entry directory experiencing 1% entry changes per second without +using a shocking amount of RAM. + +* ACL support + +* Asynchronous file handle closing in ~async_io_handle() (currently if not +explicitly closed, the async_io_handle destructor must synchronously close) + + +[/=================] +[heading Boost 1.59 AFIO v1.40 beta] +[/=================] + +* Unit tests were not trapping exception throws from normalise_path(path_normalise::guid_all), +link() or file(file_flags::create_compressed). This caused test failure on FAT32 and ReFS +volumes on Windows as those operations are not supported. + +* Rename file_buffer_allocator to page_allocator. Fixes issue #95 from review. + +* Replace all use of std::cerr with BOOST_AFIO_LOG_FATAL_EXIT(). Fixes issue #104 from review. + +* All synchronous free functions not returning anything now return a void. Fixes issue #107 from review. + +* ASIO_STANDALONE is now detected using #ifdef not #if. Fixes issue #113 from review. + +[/=================] +[heading Boost 1.59 AFIO v1.40 alpha 21st August 2015 Boost peer review 1 edition] +[/=================] + +* Removed VS2013 support as lightweight future-promise will require VS2015: + * Replaced all BOOST_NOEXCEPT and BOOST_NOEXCEPT_OR_NOTHROW with noexcept + * Replaced all BOOST_CONSTEXPR with constexpr + +* Replaced camel cased items in file_flags with Boost compliant forms. + +* Replaced all async_io_op with afio::future<void>. async_io_op::get() is now called +future<>::get_handle(), plus the former structure members are now member function +accessors. + +* Replaced all functions returning pairs of futures with afio::future<T> instead. + +* Docs now contain commenting facility per reference page plus on some of the essay pages. + +* Online docs now include a "Try AFIO now in online compiler" button every page. + +* Implemented multi-version compatibility, and backported that patch to the v1.3 branch. +The v1.3 branch is now included in the v1.4 branch as v1. + +* Implemented free functions for future continuation for all AFIO operations. + +* async_io_handle is now handle. Instead of explicit std::shared_ptr<async_io_handle> +we now have handle_ptr. + +* async_file_io_dispatcher_base is now dispatcher. Instead of explicit std::shared_ptr<async_file_io_dispatcher_base> +we now have dispatcher_ptr. make_async_io_dispatcher() is now make_dispatcher(). + +* make_dispatcher() now takes a URI and returns a monad. + +* Fixed issue #84 Symlinks were never being followed on Windows. + +* Fixed issue #83 Fix failure to handle Dedup reparse point types. + +* async_data_op_req is now io_req, similarly for make_async_data_op_req. + +* async_enumerate_op_req is now enumerate_req. + +* async_path_op_req is now path_req. + +* Added optional additional target parameter to symlink(). + +* Added reparse_point flag to stat_t. + +* Verified as working with Boost 1.59 release. + +* `handle::try_mapfile()` is no more, we now have `handle::map_file()` which can also +map writeable files now plus map offsets. + + +Still to do in this release: + +* ADD URI REGEX REGISTRATION SYSTEM (need priorities? Need to do some research. Make sure +it's DLL unload safe). + +* Add unit test for multi-version use within the same translation unit. + +[/=================] +[heading Boost 1.58 AFIO v1.31 18th April 2015] +[/=================] + +* Added Appveyor CI support which complements the Travis CI support. + +* Verified as working with Boost 1.58 release. + +[/=================] +[heading Boost 1.57 AFIO v1.30 18th March 2015] +[/=================] + +AFIO is now a Boost.BindLib based library. This has resulted in an enormous change set +which is only barely summarised here: + +* AFIO is now capable of: + * Being used standalone, or as a Boost module, or if you have inline namespace support in your + compiler then both simultaneously in the same translation unit or in the same binary, including + any combination of the following library dependency configurations (config macro and its default + is shown): + * Using Boost.Atomic, Boost.Chrono and Boost.Thread OR the C++ 11 STL (BOOST_AFIO_USE_BOOST_THREAD=0). + * Using Boost.Filesystem OR the C++ 1z Filesystem TS (BOOST_AFIO_USE_BOOST_FILESYSTEM=1, except on + VS2015 which provides Filesystem). + * Using Boost.ASIO OR standalone ASIO (ASIO_STANDALONE=1) + + That makes eight different potential configurations, and all eight can coexist in the same translation unit, + though you will find compilation time becomes enormous. + +* AFIO's unit test suite no longer requires Boost.Test, and can now alternatively use CATCH C++ +(BOOST_AFIO_USE_BOOST_UNIT_TEST=0) via BindLib. + +* Dropped support for these compiler versions due to insufficient C++ 11 support: + * Anything before GCC 4.7, as these lack template alias support. + * Anything before VS2013, as these lack template alias support. I took the opportunity to clean out + the VS2010 special code paths and all the variadic template emulation. + +* symlink() now can create file symbolic links on Windows (it'll probably error out due to lack of +privileges held by the user, but it can now at least try). + +* Added the TemporaryFile and DeleteOnClose file_flags. These improve lock file performance on Windows +by about 60%. + +* Added sparse file support. AFIO now always creates sparse file where possible, and converts any +files it opens for writing into a sparse file where possible. You can disable that behaviour using +the NoSparse flag. + +* stat_t now contains member flags indicating if a file entry is sparse and/or compressed. + +* Added a new api zero() which can very efficiently zero ranges in a file by deallocating them on +physical storage (["hole punching]). + +* Added a new api extents() which lets you query which ranges in a file contain valid data. + +* Added a new api statfs() which returns a statfs_t which lets you query the volume on which a file +or directory lives. Again, thanks to using the NT kernel API directly the structure on Windows is +almost as complete as on POSIX. + +* Improved unit testing, especially unit testing of error handling, and indeed found that on Windows +an invalid handle object generated by a failed open or an explicit close caused the next dependant +operation to segfault. Also on Windows any errors generated during read() and write() were being lost +and the dispatcher hanged instead of being reported (oops!). + +* Added an extra section to the tutorial on how to implement an atomic log file using the new +features in AFIO. + +* Completely rewrote the async_data_op_req metaprogramming which assembles ASIO scatter gather buffers +from types and containers supplied to read() and write(). The old system which had to work on VS2010 +was basically a set of repetitive hardcoded template specialisation overloads for void *, T *, +std::array, std::vector and std::basic_string. The new much more sophisticated metaprogramming (with +an unfortunate corresponding increase in compilation times) now understands any STL like container +(detected using SFINAE std::begin() and std::end()), including nested STL like containers, and will +correctly generate ASIO scatter gather buffers from say something like a std::list<std::list<std::string>> +but also correctly coalesce buffers for trivial types such as std::vector<std::array<trivial type, N>> where it spots that +only one ASIO scatter gather buffer is needed. Const types were supported before in that only +an asio::const_buffer could be constructed from the limited list of supported input types, but now the +metaprogramming asks STL like containers if their values are const (e.g. unordered_set), and if so +it will always generate an asio::const_buffer, which of course means that such STL like containers can +only be used for writing only and not reading. + +* Fixed memory corruption in async_file_io_dispatcher destructor which only occurred when there were extant ops +during destruction. + +* Use rename to random name before deletion pattern in rmfile() to work around Windows refusing new file +creation with the same name as a recently deleted file. enumerate() now filters out such zombied pending +delete files automatically. This makes AFIO rmfile() work on Windows with POSIX semantics. + +* Fixed bug where direntry() was using lstat() instead of fstat() on POSIX and therefore failing if the +file handle had been deleted. + +* symlink() no longer opens target file on POSIX, and instead returns a closed handle. The previous +behaviour was throwing exceptions when the symlink was broken. + +* Made async_io_handle::path() virtual and now capable of asking for the current path of the file handle +even after the file has been renamed or deleted. Doing this required a refactoring of the error generation +code which previously consumed a const filesystem::path &, now it consumes a lambda which generates the path +on demand. + +* File handles now refresh their path() to their true path on open, and again at various points during execution. +A careful audit was undertaken to spot all instances where a fresh path is really needed versus a stale path, +nevertheless some instances may have been missed. Nevertheless, this now means that AFIO can work with files +whose names and locations change throughout the time that AFIO holds a path open to them, though +note that inevitably this support will be racy if the filename changes between AFIO's refresh and the operation. + +* Replaced all use of filesystem::path with afio::path which on Windows enforces NT kernel path naming and +ensures that multiple conversions from win32 path to NT paths are no longer done. Support is also now provided +for converting the NT kernel paths AFIO uses to traditional DOS ones. + +* directory_entry::name() is now a string instead of a path. + +* Thanks to Travis CI adding Mac OS X as a CI target, added OS X support to AFIO. This involved writing an +expect-based lldb automator to get stack backtraces of failures, which was tedious. + +* Added APIs random_fill() and random_string() useful for generating crypto strong random file names. + +* page_size() has become page_sizes(), and now can return large/huge page sizes. A file_buffer_default_size() +new API will return the closest page size to 1Mb. + +* Added page_allocator, a STL allocator suitable for allocating efficient large file buffers. + +* stat_t flags, gen and birthtime weren't being set on FreeBSD. Sorry. + +* Made big changes to how async_path_op_req works and is used. Instead of hard coded overloads, +async_path_op_req now takes a template parameter for the path and has metaprogramming for converting that into +an afio::path. You can also now supply absolute and relative-to-the-precondition paths via +`async_path_op_req::absolute` and `async_path_op_req::relative`, plus you can supply a bare precondition +which finally allows rmfile() et al to directly delete inputs by op handle. Also added a depends() API +which lets you return one op handle only when another op handle completes. + +* Made AFIO provide [*much] stronger filing system race condition protection. This comes with a performance +cost, so a new file_flags::no_race_protection can disable the new semantics. Renamed file_flags::fast_directory_enumeration +to file_flags::hold_parent_open as enabling HoldParentOpen will make most of the performance cost of race +protection disappear. + +* Implemented WillBeSequentiallyAccessed and WillBeRandomlyAccessed for POSIX. + +* Added is_open() to async_io_handle. Made pseudo deleted file filtering optional in enumerate(). + +* Stack backtraces are now retained per exception throw as well as per op schedule if BOOST_AFIO_OP_STACKBACKTRACEDEPTH +is defined (defaults to yes if NDEBUG is not defined). Also added MSVC and FreeBSD support, and exceptions returned by the future +handle now provide stack backtraces. + +* Added virtual member functions link(), unlink() and atomic_relink() to async_io_handle, plus adjusted the engine to +always call these instead of performing those operations unilaterally. + +* Added a race protection unit test. + + + +[/=================] +[heading Boost 1.57 AFIO v1.22 stable branch tagged] +[/=================] + +Fixed buffer underflow when decoding Win32 error codes to strings. Thanks to ariccio +for reporting this. + +Relocated docs from ci.nedprod.com to http://boostgsoc13.github.io/boost.afio/ + +Updated the stale CI test dashboard copy in the DocBook edition. + + +[/=================] +[heading Boost 1.56 AFIO v1.21 10th Aug 2014] +[/=================] + +Finished getting a ThreadSanitizer (tsan) + UndefinedBehaviorSanitizer (ubsan) pass +running per-commit on Travis CI (>= v1.2 was tsan clean, I just hadn't bothered getting +a CI to verify it to be so per commit). + +Fixed bug where --lto wasn't turning on the optimiser for LTO output. Sorry. + +Added a benchmark testing for latency under concurrency loads. + +Added a new FAQ entry on AFIO execution latencies. + +Reorganised source code structure to fit modular Boost. AFIO is now a Boost v1.56 +module just like any other. Obviously this will break source code compatibility +with all preceding Boosts. + +[/=================] +[heading Boost 1.55 AFIO v1.21 23rd Mar 2014] +[/=================] + +Fixed a bug in the custom unit testing framework which was throwing away any exceptions +being thrown by the tests (thanks to Paul Kirth for finding this and reporting it). +Fixing this bug revealed that enumerate() with a glob on Windows has never worked +properly and the exception thrown by MSVC's checked iterators was hiding the problem, +so fixed that bug too. + +Added async_io_dispatcher_base::post_op_filter() and async_io_dispatcher_base::post_readwrite_filter(), +including documentation examples and integrating filters into the unit testing. +post_readwrite_filter() ought to be particularly useful to those seeking deep ASIO +integration. Thanks to Bjorn Reese for the long discussions leading up to this +choice of improved ASIO support. + +During updating the benchmarks below now I have regained access to my developer +workstation, discovered a severe performance regression in the v1.2 engine of +around 27% over the v1.1 engine. Steps taken: + +1. The shared state in every async_io_op was a shared_ptr, now it is the +underlying shared_future. Eliminated copies of shared_ptr, now we always +use the shared_future in enqueued_task directly. This reduced regression to 18%. + +2. Removed more code from inside the TSX locks. This reduced regression to 16%. + +3. Removed the second TSX lock from complete_async_op(). This eliminated the +regression and actually added 2% to the v1.1 engine. + +4. Removed the second TSX lock from chain_async_op(). This added a further 10% +over the v1.1 engine, so we are now 12% faster which is about right given +the v1.2 engine removed 15% of code. + +Added nested TSX transaction support. + +The CI shows that clang 3.1 now produces segfaulting binaries with this release, +so rather than debug clang, I simply dropped clang 3.1 support. AFIO now requires +clang 3.2 or better. + +[/=================] +[heading Boost 1.55 AFIO v1.20 5th Feb 2014] +[/=================] + +This is a major refactor of AFIO's core op dispatch engine to trim it down by +about 15%. Key breaking differences from the v1.1 series of AFIO are as follows: + +* Replaced all use of packaged_task with enqueued_task, a custom implementation +which makes possible many performance improvements throughout the engine. +* thread_source::enqueue() now can take a preprepared enqueued_task. +* thread_source::enqueue() now always returns a shared_future instead of a future. +This has had knock on effects throughout AFIO, so many futures are now shared_future. +* Completion handler spec has changed from: + + pair<bool, shared_ptr<async_io_handle>> (*)(size_t id, shared_ptr<async_io_handle> h, exception_ptr *e) + + to: + + pair<bool, shared_ptr<async_io_handle>> (*)(size_t id, async_io_op preceding) + + This substantially improves performance, simplifies the implementation, and lets + completion handlers more readily retrieve the error state of preceding operations + and react appropriately. +* All restrictions on immediate completions have been removed. You can now do anything +in an immediate completion that you can do in a normal completion. +* async_io_op::h now always refers to a correct future i.e. the future is no longer +lazily allocated. +* Now that op futures are always correct, when_all(ops) has been drastically simplified +to an implementation which literally assembles the futures into a list and passes +them to boost::wait_for_all(). +* Added when_any(ops). + +[/=================] +[heading Boost 1.55 AFIO v1.11] +[/=================] + +Added --fast-build to test Jamfile to preserve my sanity attempting to work with +AFIO on an Intel Atom 220 netbook. + +Fixed failure to auto-const an async_data_op_req<boost::asio::mutable_buffer> +when used for writing. Thanks to Bjorn Reese for reporting this. + +Replaced use of std::runtime_error with std::invalid_argument where that makes +sense. Thanks to Bjorn Reese for reporting this. + +Replaced throwing of std::ios_base::failure with std::system_error. Thanks to +Bjorn Reese for suggesting and submitting a patch for this. + +async_io_dispatcher_base::enumerate() did not take a metadata_flags, and it +was supposed to. Thanks to Bjorn Reese for reporting this. + +Added a unit compilation test to ensure that implicit construction from a +single arg to the op convenience classes works as intended. + +Significantly optimised build system and added in precompiled headers support. +Combined with --fast-build this provides an 8x build time improvement. + +boost::afio::stat_t::st_type() is now a boost::filesystem::file_type instead +of replicating the POSIX file type codes. Thanks to Bjorn Reese for suggesting +this. + +boost::afio::stat_t::st_mode() is now st_perms(). Also disabled unused fields in +stat_t on Windows. Thanks to Bjorn Reese for suggesting this. + +[/=================] +[heading Boost 1.55 AFIO v1.1 1st Nov 2013] +[/=================] + +Immediate completions no longer hold the opslock, which meant the opslock could be +changed from a recursive mutex to a spinlock. The new, more parallelised, behaviour +illuminated a number of new race conditions in when_all() which have been fixed. + +Completely gutted dispatch engine and replaced with a new, almost entirely wait +free implementation based on throwing atomics at the problem. If it weren't for the spin lock around the +central ops hash table, AFIO would now be an entirely wait free design. + +In order to do something about that spin lock, replaced all locking in AFIO (apart +from the directory file handle cache) with memory transactions instead. This +does CPUID at runtime and will use Intel's TSX-NI memory transaction implementation +if available, if not it falls back to a spin lock based emulation. On memory +transaction capable CPUs, AFIO is now almost entirely wait free, apart from when +it has to fetch memory from the kernel. + +Made AFIO usable as headers only. + +[/=================] +[heading Boost 1.55 AFIO v1.0 27th Sep 2013] +[/=================] + +First release for end of Google Summer of Code 2013. + +[endsect] + + + + +[section:FAQ Frequently Asked Questions] + +[section:closure_performance What is the maximum throughput of AFIO's closure execution engine aka +how many IOPS can I push with AFIO?] + +For v1.3 of the engine, maximum ops [*dispatch] throughput is approximately as follows, where the values for `call()` might be for +use as a closure engine whereas the values for `completion()` might be for max filing system IOPS[footnote The phrase +["might be] is important: a null closure benchmark will always have dispatch rate problems i.e. the closures being executed +take less time to execute than the time to dispatch them, so these figures are best read as maximum dispatch rate, not +maximum IOPS.]: + +[table:throughput Maximum null closure dispatch rate on a 3.5Ghz Intel Core i7 3770K for AFIO v1.3[footnote Benchmarks compiled using `address-model=64 link=static --lto release -j 4`.] +[[Operating system][`call()` unchained][`call()` chained][`completion()` unchained][`completion()` chained][Raw ASIO]] +[[Microsoft Windows 8 x64 with Visual Studio 2013][[role alignright 1148070]][[role alignright 704051]][[role alignright 1850090]][[role alignright 877899]][[role alignright 2750088]]] +[[['Relative to ASIO]][[role alignright 42%]][[role alignright 26%]][[role alignright 67%]][[role alignright 32%]][[role alignright 100%]]] +[[['Relative to AFIO v1.21]][[role alignright +1%]][[role alignright +16%]][[role alignright +14%]][[role alignright +36%]][]] +[[['Relative to AFIO v1.1]][[role alignright +26%]][[role alignright +18%]][[role alignright +19%]][[role alignright +20%]][]] + +[[][][][][][]] + +[[Ubuntu 14.04 LTS Linux x64 with GCC 4.9.2][[role alignright 1149470]][[role alignright 1100650]][[role alignright 1629110]][[role alignright 1308240]][[role alignright 1927300]]] +[[['Relative to ASIO]][[role alignright 60%]][[role alignright 57%]][[role alignright 85%]][[role alignright 68%]][[role alignright 100%]]] +[[['Relative to AFIO v1.21]][[role alignright -11%]][[role alignright +8%]][[role alignright +10%]][[role alignright +9%]][]] +[[['Relative to AFIO v1.1]][[role alignright +5%]][[role alignright +39%]][[role alignright +14%]][[role alignright +20%]][]] +[[][][][][][]] + +] + +We hope that ~600k min IOPS surely ought to be enough to max out any SATA III SSD __dash__ it should even max out any mid range +PCIe based SSD too, and if paired with a CPU with more cores, AFIO's almost wait free design ought to scale out fairly +well too such that it may be able to max out even top end PCIe SSDs, some of which can push 10m IOPS now. + +[endsect] [/closure_performance] + +[section:closure_latency What is the latency of AFIO's closure execution engine aka +how quickly can I push a single op with AFIO?] + +For v1.3 of the engine on a quad core hyperthreading 3.5Ghz Intel Core i7 3770K, I found +the following latency graph which is in CPU cycles: + +[role aligncenter [$afio_latencies.png]] + +The solid lines represent average dispatch to execution and execution finish to completion +notification latencies and are cumulative on the left scale, whilst the dotted lines represent +minimum latencies and are cumulative on the right scale. As one can see, one can expect a +minimum of around 6,000 CPU cycles between dispatch and the operation beginning, and a minimum +of around 4,000 cycles between the operation completing and its op reference becoming signalled, +thus making total minimum latency per op around 10,000 CPU cycles, or around 2.5 microseconds. + +Average latency is rather worse of course, but if you don't exceed CPU cores you can expect a +60,000 CPU cycle total latency with a 95% confidence +interval of plus/minus 600 CPU cycles, which is 15 microseconds plus/minus 0.15 microseconds. +Given that a filing system on a PCIe SSD might have a 80 microsecond latency, AFIO could be adding +20% to that, however do bear in mind that a thread sleep and wake costs 52 microseconds so +we are operating pretty close to hardware limits here. + +[endsect] [/closure_latency] + +[section:stuck_ops I'm seeing ["WARNING: `~async_file_dispatcher_base()` detects stuck `async_io_op` in total of X ops] during +process close. What does this mean?] + +This means that you scheduled ops with a dispatcher which did not complete in a timely fashion before you tried to destroy +that dispatcher. This generally indicates a bug in your code, which can include: + +# An op is still running in some thread pool and you didn't use __afio_when_all__ or `get()` to wait for it to complete before trying +to destroy the dispatcher. +# An op's precondition never completed and therefore the op was never started. + +Tracking down the cause of the latter in particular is very similar to tracking down race conditions i.e. it's hard, and we +as the authors of __boost_afio__ know just how hard! Try recompiling AFIO with the macro +`BOOST_AFIO_OP_STACKBACKTRACEDEPTH` set to a reasonable depth like 8 will have AFIO take a stack backtrace for every op +allocated which it then will print during the stuck ops warnings. This can be helpful to identify which ops exactly are +stuck, and then you can figure out which preconditions of theirs are the cause. + +Note that `BOOST_AFIO_OP_STACKBACKTRACEDEPTH` has two implementations on POSIX, one based on glibc `backtrace()` and the other based +on libunwind. The latter is more portable, but requires explicit linking with libunwind, so we have defaulted to the former. + +[endsect] [/stuck_ops] + +[section:vector_use Why did you use `std::vector<>` as the ops batch container instead of a generic iterator range?] + +# `std::vector<async_io_op>` is the closest thing to a variable length array in C++[footnote Ok, there is also +the oft-forgotten `std::valarray<>` too, but its use as a generic container isn't recommended.], at least until C++ 14 where we +will gain `std::dynarray<>` and dynamic array sizing. +# `std::vector<async_io_op>` is well understood, particularly its performance during by-value copies and during +`push_back()` which is by far the most common operation you do when preparing a batch. +# `std::vector<async_io_op>` is very amenable to splitting the batch across threads (not that AFIO currently does this). +# `std::vector<async_io_op>` is easily transportable through an ABI, whereas arbitrary container iterators would need type +erasing (i.e. slow). As AFIO was developed initially as not header-only, this made a lot of sense initially. + +We are not opposed to the use of generic iterator ranges in an AFIO v2 if there is user demand for such a thing. + +[endsect] [/vector_use] + +[section:foreign_fd How do I configure my own file descriptor or HANDLE in AFIO?] + +Sometimes you receive a file descriptor or HANDLE from a third party piece of code and you need to insert it as-in +into AFIO for use. The solution to this is very simple: + +# Subclass __afio_handle__ with a custom implementation for your file descriptor type. In particular, you probably +will have custom close semantics (e.g. don't close, or invoke third party code to implement close). +# Instantiate your custom handle implementation, and pass it into `async_file_io_dispatcher_base::adopt()`. This +will immediately convert your custom handle type into an `async_io_op` suitable for supplying to `read()`, `write()` +etc. +# That's it, there is no more to it. + +[endsect] [/foreign_fd] + +[section:slow_compile Using AFIO really slows down my compile times. Can't you do something about that?] + +You'll find a huge amount depends on your compiler. Here are some build time benchmarks for my developer workstation: + +[table:build_time Single thread build times for AFIO v1.3 for various compilers and options on a 3.5Ghz Intel Core i7 3770K +[[Build flags][Microsoft Windows 8.1 x64 with Visual Studio 2013][Ubuntu 14.04 LTS Linux x64 with GCC 4.9 and gold linker][Ubuntu 14.04 LTS Linux x64 with clang 3.4 and gold linker]] +[ [`--link-test --fast-build debug`][[role green 0m55s]][3m53s][asio failure]] +[ [`--link-test debug`][2m10s][10m26s][5m46s]] +[ [`--link-test --lto debug`][5m37s][GCC ICE][5m42s]] +[ [`--link-test pch=off debug`][7m17s][[role red 12m0s]][5m45s]] +[[`--link-test --fast-build release`][1m10s][3m22s][asio failure]] +[ [`--link-test release`][2m58s][9m57s][8m10s]] +[ [`--link-test --lto release`][7m30s][[role red 13m0s]][8m11s]] +[ [standalone alltests release][0m20s][0m51s][0m42s]] +[[standalone multiabi alltests release][0m39s][1m34s][1m13s]] +] + +[table:build_time Single thread build times for AFIO v1.2 for various compilers and options on a 3.5Ghz Intel Core i7 3770K +[[Build flags][Microsoft Windows 8 x64 with Visual Studio 2013][Ubuntu 12.04 LTS Linux x64 with GCC 4.8 and gold linker][Ubuntu 12.04 LTS Linux x64 with clang 3.4 and gold linker]] +[ [`--link-test --fast-build debug`][01m43s][03m31s[footnote ASIO has a link error without `link=static`]][fails]] +[ [`--link-test debug`][02m40s][06m15s][04m24s]] +[ [`--link-test --lto debug`][[role red 09m36s]][06m23s][04m32s]] +[ [`--link-test pch=off debug`][06m12s][08m01s][04m26s]] +[[`--link-test --fast-build release`][02m01s][03m15s[footnote ASIO has a link error without `link=static`]][fails]] +[ [`--link-test release`][03m09s][06m28s][06m06s]] +[ [`--link-test --lto release`][10m24s][07m08s][06m14s]] +] + +You'll note that v1.3 is substantially faster than v1.2 to build on MSVC for some odd reason, despite considerably +more metaprogramming, code, and tests. The rises in times like with GCC and clang make more sense. + +The benefit of `--fast-build` grows exponentially the less powerful the CPU: on my Intel Atom 220 +netbook `--fast-build` gets total build times under five minutes which is impressive compared to +the twenty or so minutes without that flag. + +`--fast-build` works by defining `BOOST_AFIO_HEADERS_ONLY` to 0 for each compiland, and +linking to the AFIO shared library instead. It also does the same for ASIO by defining `BOOST_ASIO_SEPARATE_COMPILATION` +and `BOOST_ASIO_DYN_LINK` for each compiland, and links to the ASIO +shared library instead (which is built via `boost/asio/impl/src.hpp`, see ASIO's docs). + +[endsect] [/slow_compile] + +[section:fatal_error_read Why do I get a fatal application exit with `FATAL EXCEPTION: Failed to read all buffers` when I read a file?] + +This is actually a safety checkpoint for your code: in complex, multi-process concurrent reading and writing of +the same file, it is extremely difficult to coordinate changing file lengths with i/o in a way which +doesn't introduce race conditions OR unacceptably low performance. AFIO therefore doesn't even +try[footnote AFIO [*will] try to provide a synchronised, accurate file extent after fast portable +file locking support has been added, but until then no.] +and simply requires you the programmer to ALWAYS do i/o, whether reading or writing, within the extent +of a file. In other words, if you're going to read 100 bytes from offset 100 in a file, that file +better be at least 200 bytes long or it's going to fail with a fatal application exit. + +This will probably seem harsh to anyone using AFIO for the first time, because the following +naive code will fatal exit the application if foo.txt is not 1024 bytes or longer: + +[readallof_example_bad] + +With synchronous i/o a read of 1024 bytes will read ['up to] 1024 bytes, returning the amount +actually read via some mechanism. With AFIO, either you +read [*all] 1024 bytes or you read nothing, in which case a normal exception is thrown with +whatever error the operating system returned. If a ['partial] read happens, then AFIO fatal +exits the application with the above message as it is probably a logic error in your code. + +You may now wonder how to easily not exceed file extents during i/o: for writing, see +__afio_truncate__ to ensure a file's size before writing, or else open a file for append-only +in which case all writes atomically occur at the end of the file. For reading, the following code +is suggested: + +[readallof_example_single] + +If you're going to read many files from the same directory, it is far faster to open a +handle to the containing directory and using enumerate to fetch the metadata asynchronously +instead of using `direntry()` which is synchronous: + +[readallof_example_many] + +[endsect] [/fatal_error_read] + +[section:async_metadata `async_io_handle::direntry()` and `async_io_handle::lstat()` are +both synchronous functions which block. How then can I get metadata about files and +directories asynchronously?] + +This is easy, if not terribly obvious: call __afio_enumerate__ on the containing +directory of the file you want metadata for with a shell glob exactly matching the +file name and with the minimum metadata you are looking for. AFIO will then +asynchronously fetch that metadata for you, returning it in the future `directory_entry` +returned by `enumerate()`. + +[endsect] [/async_metadata] + +[section:deleting_open_files I thought on Windows it is impossible to delete a file which +is still open for use. How does AFIO achieve this?] + +On POSIX you are allowed to call `unlink()` on a file which is open for use __dash__ indeed +this is a very convenient way of creating an anonymous private temporary file whose storage will be +deallocated on the last file handle close. Ordinarily Windows does not permit deletion or renaming of +files still in use, but if all open handles to that file were opened with `FILE_SHARE_DELETE` then +it ['can] permit renames and deletions of open files. + +There are however some gotchas with this, and it is worth listing them here. Firstly, Windows +never allows you to really delete an open file, rather it is flagged as delete pending and its entry +in its directory remains visible (though no new file handles may be opened to it) and when +the very last open handle to the file in the system is closed, only then is it truly deleted. Well, +actually only ['sort of truly deleted], because Windows only ['appears] to remove the file entry from the directory, but +in fact that entry is merely hidden and actually still exists and attempting to create a file with the +same name will return an access denied error. How long it silently exists for depends on a range +of factors, but put it this way: if your code loops creating and deleting the same file name as you +might when operating a lock file, you're going to see lots of random spurious access denied errors and +truly dismal lock file performance compared to POSIX. + +Note that this lazy file deletion is different from ["file tunnelling] whereby a file created with +the same name as a recently deleted file silently inherits its creation time and other metadata. I +mention this because this feature also gets in the way of POSIX file semantics, but for other reasons. + +AFIO works around these un-POSIX file semantics by taking a dual step to deleting files. Firstly, it renames the file to a 128 +bit cryptographically strong random name prefixed by [".afiod] into as high up the directory hierarchy +as it is able to, and only then does it request the deletion of the file. As AFIO always +opens files with `FILE_SHARE_DELETE` permission enabled, with that flag Windows permits renaming +and deletion, and because the name was changed to a very random name somewhere not in its origin +directory before deletion, you don't see those unexpected and random errors when creating files +with the same name as a recently deleted file as you do anywhere else on Windows. Because the file +is probably not in its original containing directory any more, deletions of that directory will +not fail with ["directory not empty] as they otherwise normally would and indeed do in most Windows +programs. Handy eh? + +Unfortunately, there are additional problems with deleting directories caused by AFIO's caching +of directory handles in a central table __dash__ this happens by default for all directories opened +without write permissions and without the `file_flags::unique_directory_handle` flag. Explicit close +handle requests for these cached directories are ignored by AFIO, and therefore AFIO may hold into existence +a directory longer than might otherwise be anticipated with the only way of forcing actual deletion +being the destruction of any reference to that directory, something difficult to achieve in larger +more complex codebases. Nevertheless, as it is the system which does the deletion, you are guaranteed +by Windows that the directory will eventually be cleaned up some day, possibly in weeks or months +on a long lived system. If you don't want this, open directories with write permissions or the +unique directory handle flag. + +[endsect] [/deleting_open_files] + +[section:multi_abi How do I reconfigure AFIO within the same translation unit to use a different ABI?] + +Here is how the unit test does it: + +``` +// Reduce unit testing +#define BOOST_AFIO_RUNNING_IN_CI 1 +// Use the Boost.Test emulation in Boost.BindLib as Boost.Test isn't multi ABI capable. +#define BOOST_AFIO_USE_BOOST_UNIT_TEST 0 + +#define STRINGIZE2(a) #a +#define STRINGIZE(a, b) STRINGIZE2(a ## b) + +// Make unit test names be different +#define BOOST_CATCH_AUTO_TEST_CASE_NAME(name) STRINGIZE(1_, name) + +// A copy of AFIO + unit tests completely standalone apart from Boost.Filesystem +#define BOOST_AFIO_USE_BOOST_THREAD 0 +#define BOOST_AFIO_USE_BOOST_FILESYSTEM 1 +#define ASIO_STANDALONE 1 +#include "test_all.cpp" +#undef BOOST_AFIO_USE_BOOST_THREAD +#undef BOOST_AFIO_USE_BOOST_FILESYSTEM +#undef ASIO_STANDALONE + +// Force unit test utilities to be reincluded +#undef BOOST_AFIO_TEST_FUNCTIONS_HPP +#undef BOOST_CATCH_AUTO_TEST_CASE_NAME +#define BOOST_CATCH_AUTO_TEST_CASE_NAME(name) STRINGIZE(2_, name) + +// A copy of AFIO + unit tests using Boost.Thread, Boost.Filesystem and Boost.ASIO +#define BOOST_AFIO_USE_BOOST_THREAD 1 +#define BOOST_AFIO_USE_BOOST_FILESYSTEM 1 +// ASIO_STANDALONE undefined +#include "test_all.cpp" +``` + +So, simply `#undef` and re-`#define` the configuration macros you want and reinclude `afio.hpp`. You +can do this every time you switch between configuration in a translation unit, so you can return to +a previously included translation BUT note that you cannot later include a new header not previously +included during that configuration's previous existence. In other words, include all the headers you +are ever going to use in that translation unit just after the first time you configure that configuration. + +The situation is very similar for including hard version dependencies. You cannot include a newer version +of AFIO after including a previous version as some version of AFIO must be the most recent version in order +for something to live at `boost::afio`. Just always include the newest version first. + +[endsect] [/multi_abi] + + +[endsect] [/FAQ] diff --git a/attic/doc/src/images/afio_latencies.pdf b/attic/doc/src/images/afio_latencies.pdf Binary files differnew file mode 100644 index 00000000..95cce932 --- /dev/null +++ b/attic/doc/src/images/afio_latencies.pdf diff --git a/attic/doc/src/images/afio_latencies.png b/attic/doc/src/images/afio_latencies.png Binary files differnew file mode 100644 index 00000000..e52606b8 --- /dev/null +++ b/attic/doc/src/images/afio_latencies.png diff --git a/attic/doc/src/images/afio_latencies_1.2.pdf b/attic/doc/src/images/afio_latencies_1.2.pdf Binary files differnew file mode 100644 index 00000000..f02821de --- /dev/null +++ b/attic/doc/src/images/afio_latencies_1.2.pdf diff --git a/attic/doc/src/images/afio_latencies_1.2.png b/attic/doc/src/images/afio_latencies_1.2.png Binary files differnew file mode 100644 index 00000000..56046543 --- /dev/null +++ b/attic/doc/src/images/afio_latencies_1.2.png diff --git a/attic/doc/src/images/afio_latencies_1.3.pdf b/attic/doc/src/images/afio_latencies_1.3.pdf Binary files differnew file mode 100644 index 00000000..95cce932 --- /dev/null +++ b/attic/doc/src/images/afio_latencies_1.3.pdf diff --git a/attic/doc/src/images/afio_latencies_1.3.png b/attic/doc/src/images/afio_latencies_1.3.png Binary files differnew file mode 100644 index 00000000..e52606b8 --- /dev/null +++ b/attic/doc/src/images/afio_latencies_1.3.png diff --git a/attic/doc/src/images/boost.png b/attic/doc/src/images/boost.png Binary files differnew file mode 100644 index 00000000..0714ca20 --- /dev/null +++ b/attic/doc/src/images/boost.png diff --git a/attic/doc/src/images/boost_full.png b/attic/doc/src/images/boost_full.png Binary files differnew file mode 100644 index 00000000..b4d51fcd --- /dev/null +++ b/attic/doc/src/images/boost_full.png diff --git a/attic/doc/src/images/boost_proposed.png b/attic/doc/src/images/boost_proposed.png Binary files differnew file mode 100644 index 00000000..0714ca20 --- /dev/null +++ b/attic/doc/src/images/boost_proposed.png diff --git a/attic/doc/src/images/boost_proposed.svg b/attic/doc/src/images/boost_proposed.svg new file mode 100644 index 00000000..10fbdd9c --- /dev/null +++ b/attic/doc/src/images/boost_proposed.svg @@ -0,0 +1,449 @@ +<?xml version="1.0" encoding="UTF-8" standalone="no"?> +<!-- Generator: Adobe Illustrator 12.0.0, SVG Export Plug-In . SVG Version: 6.00 Build 51448) --> +<svg + xmlns:dc="http://purl.org/dc/elements/1.1/" + xmlns:cc="http://creativecommons.org/ns#" + xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#" + xmlns:svg="http://www.w3.org/2000/svg" + xmlns="http://www.w3.org/2000/svg" + xmlns:xlink="http://www.w3.org/1999/xlink" + xmlns:sodipodi="http://sodipodi.sourceforge.net/DTD/sodipodi-0.dtd" + xmlns:inkscape="http://www.inkscape.org/namespaces/inkscape" + version="1.1" + id="Layer_1" + width="444.1889" + height="146.81453" + viewBox="0 0 444.1889 146.81453" + overflow="visible" + enable-background="new 0 0 517 500" + xml:space="preserve" + inkscape:version="0.46" + sodipodi:docname="Proposed for Boost.svg" + inkscape:export-filename="C:\Users\Paul\Desktop\Proposed for Boost.png" + inkscape:export-xdpi="59.369999" + inkscape:export-ydpi="59.369999" + style="display:inline;overflow:visible" + sodipodi:version="0.32" + inkscape:output_extension="org.inkscape.output.svg.inkscape"><sodipodi:namedview + pagecolor="#ffffff" + bordercolor="#666666" + borderopacity="1" + objecttolerance="10" + gridtolerance="10" + guidetolerance="10" + inkscape:pageopacity="0" + inkscape:pageshadow="2" + inkscape:window-width="1440" + inkscape:window-height="845" + id="namedview11418" + showgrid="false" + showguides="true" + inkscape:guide-bbox="true" + inkscape:zoom="1.3350176" + inkscape:cx="148.34277" + inkscape:cy="59.740325" + inkscape:window-x="2320" + inkscape:window-y="37" + inkscape:window-maximized="1" + inkscape:current-layer="layer7"><sodipodi:guide + id="guide11439" + position="-36.703636,107.11469" + orientation="0,1" /></sodipodi:namedview><metadata + id="metadata11422"><rdf:RDF><cc:Work + rdf:about=""><dc:format>image/svg+xml</dc:format><dc:type + rdf:resource="http://purl.org/dc/dcmitype/StillImage" /><dc:title /></cc:Work></rdf:RDF></metadata><defs + id="defs11420"><linearGradient + id="linearGradient3816" + inkscape:collect="always"><stop + id="stop3818" + offset="0" + style="stop-color:#000000;stop-opacity:1;" /><stop + id="stop3820" + offset="1" + style="stop-color:#000000;stop-opacity:0;" /></linearGradient><inkscape:perspective + id="perspective11424" + inkscape:persp3d-origin="258.5 : 166.66667 : 1" + inkscape:vp_z="517 : 250 : 1" + inkscape:vp_y="0 : 1000 : 0" + inkscape:vp_x="0 : 250 : 1" + sodipodi:type="inkscape:persp3d" /><radialGradient + r="58.375" + cy="246.375" + cx="63.75" + gradientUnits="userSpaceOnUse" + id="radialGradient11812" + xlink:href="#XMLID_5_" + inkscape:collect="always" /><linearGradient + y2="242.22659" + x2="110.314" + y1="242.22659" + x1="66.6689" + gradientUnits="userSpaceOnUse" + id="linearGradient11814" + xlink:href="#XMLID_7_" + inkscape:collect="always" /><linearGradient + y2="222.79201" + x2="78.625504" + y1="222.79201" + x1="39.3022" + gradientUnits="userSpaceOnUse" + id="linearGradient11816" + xlink:href="#XMLID_8_" + inkscape:collect="always" /><linearGradient + y2="262.375" + x2="72.826698" + y1="262.375" + x1="28.6553" + gradientUnits="userSpaceOnUse" + id="linearGradient11818" + xlink:href="#XMLID_6_" + inkscape:collect="always" /><radialGradient + gradientUnits="userSpaceOnUse" + r="58.375" + fy="246.375" + fx="63.75" + cy="246.375" + cx="63.75" + id="radialGradient3822" + xlink:href="#linearGradient3816" + inkscape:collect="always" /><radialGradient + r="58.375" + fy="246.375" + fx="63.75" + cy="246.375" + cx="63.75" + gradientUnits="userSpaceOnUse" + id="radialGradient3826" + xlink:href="#linearGradient3816" + inkscape:collect="always" /></defs> + +<g + transform="translate(3.5916937e-8,-170.41634)" + id="boost"> + +</g> + + + + +<g + style="display:none" + inkscape:label="Alpha Background" + id="layer12" + inkscape:groupmode="layer"><rect + style="fill:none;stroke:none;display:inline;overflow:visible" + id="rect11821" + width="444.1889" + height="146.81453" + x="-3.5916937e-08" + y="170.41634" + transform="translate(2.8192073e-6,-170.41634)" /></g><g + transform="translate(3.5916937e-8,-170.41634)" + style="display:inline" + inkscape:label="White Background" + id="layer11" + inkscape:groupmode="layer"><rect + y="171.16539" + x="16.479183" + height="146.81453" + width="444.1889" + id="rect11810" + style="fill:#ffffff;fill-opacity:1;fill-rule:evenodd;stroke:none" /></g><g + transform="translate(3.5916937e-8,-170.41634)" + style="display:inline" + inkscape:label="Boost Logo" + id="layer7" + inkscape:groupmode="layer"><text + style="font-size:101.1230011px;fill:#4a6484;display:inline;overflow:visible;font-family:Denmark" + id="text11381" + font-size="101.123" + transform="matrix(0.9848,0,-0.1736,0.9848,128.1865,269.8252)">boost</text> + + + + + + + + + +<g + transform="matrix(0.98716824,0,0,0.93584122,0.8180256,15.55239)" + style="fill:url(#radialGradient3822);fill-opacity:1;display:inline;overflow:visible" + id="g3792"> + <radialGradient + id="radialGradient3794" + cx="63.75" + cy="246.375" + r="58.375" + gradientUnits="userSpaceOnUse"> + <stop + offset="0" + style="stop-color:#000000;fill-opacity:1;fill:url(#radialGradient3822)" + id="stop3796" /> + <stop + offset="0.0641" + style="stop-color:#191919;fill-opacity:1;fill:url(#radialGradient3822)" + id="stop3798" /> + <stop + offset="0.2539" + style="stop-color:#5E5E5E;fill-opacity:1;fill:url(#radialGradient3822)" + id="stop3800" /> + <stop + offset="0.4336" + style="stop-color:#979797;fill-opacity:1;fill:url(#radialGradient3822)" + id="stop3802" /> + <stop + offset="0.5979" + style="stop-color:#C4C4C4;fill-opacity:1;fill:url(#radialGradient3822)" + id="stop3804" /> + <stop + offset="0.7439" + style="stop-color:#E4E4E4;fill-opacity:1;fill:url(#radialGradient3822)" + id="stop3806" /> + <stop + offset="0.866" + style="stop-color:#F8F8F8;fill-opacity:1;fill:url(#radialGradient3822)" + id="stop3808" /> + <stop + offset="0.9494" + style="stop-color:#FFFFFF;fill-opacity:1;fill:url(#radialGradient3822)" + id="stop3810" /> + </radialGradient> + <circle + cx="63.75" + cy="246.375" + r="58.375" + id="circle3812" + sodipodi:cx="63.75" + sodipodi:cy="246.375" + sodipodi:rx="58.375" + sodipodi:ry="58.375" + style="opacity:0.3;fill:url(#radialGradient3826);fill-opacity:1" + d="m 122.125,246.375 c 0,32.23962 -26.135378,58.375 -58.375,58.375 C 31.510378,304.75 5.375,278.61462 5.375,246.375 5.375,214.13538 31.510378,188 63.75,188 c 32.239622,0 58.375,26.13538 58.375,58.375 z" /> +</g><g + id="right-center" + style="display:inline;overflow:visible"> + <linearGradient + y2="242.22659" + x2="110.314" + y1="242.22659" + x1="66.6689" + gradientUnits="userSpaceOnUse" + id="XMLID_7_"> + <stop + id="stop11400" + style="stop-color:#B1D2EC" + offset="0.0056" /> + <stop + id="stop11402" + style="stop-color:#C8E6F6" + offset="1" /> + </linearGradient> + <polygon + style="fill:url(#linearGradient11814)" + id="polygon11404" + points="77.164,223.15 66.669,241.262 78.307,261.304 99.112,261.21 110.314,242.047 99.106,223.15 " /> + <path + style="fill:#ffffff" + id="path11406" + d="M 99.675,222.15 H 98.536 77.739 76.586 l -0.578,0.997 -9.914,17.112 -0.581,1.004 0.582,1.003 11.056,19.039 0.582,1.001 1.157,-0.005 19.655,-0.088 1.142,-0.005 0.576,-0.986 10.617,-18.162 0.594,-1.016 -0.601,-1.013 -10.617,-17.901 -0.581,-0.98 0,0 z m -31.85,19.112 9.914,-17.112 h 20.797 l 10.617,17.901 0,0 0,0 -10.617,18.162 -19.655,0.088 -11.056,-19.039 0,0 0,0 z" /> +</g><g + id="left-up" + style="display:inline;overflow:visible"> + <linearGradient + y2="222.79201" + x2="78.625504" + y1="222.79201" + x1="39.3022" + gradientUnits="userSpaceOnUse" + id="XMLID_8_"> + <stop + id="stop11410" + style="stop-color:#B1D2EC" + offset="0.0056" /> + <stop + id="stop11412" + style="stop-color:#C8E6F6" + offset="1" /> + </linearGradient> + <path + style="fill:url(#linearGradient11816)" + id="path11414" + d="m 50.211,207.025 -10.909,19.045 6.912,12.442 16.451,0.047 c 0,0 11.104,-18.828 11.656,-19.763 0.766,0 4.304,0 4.304,0 l -6.704,-11.771 h -21.71 z" /> + <path + style="fill:#ffffff" + id="path11416" + d="M 72.503,206.025 H 71.34 50.79 49.631 l -0.576,1.006 -10.34,18.053 -0.561,0.979 0.548,0.986 6.353,11.436 0.569,1.026 1.173,0.003 15.292,0.044 1.146,0.003 0.583,-0.987 11.075,-18.778 h 2.012 3.441 l -1.703,-2.99 -5.565,-9.771 -0.575,-1.01 0,0 z M 40.45,226.078 50.79,208.025 h 20.55 l 5.565,9.771 0,0 0,0 H 73.75 l -11.655,19.762 -15.292,-0.044 -6.353,-11.436 0,0 0,0 z" /> +</g><g + id="left-down" + style="display:inline;overflow:visible"> + <linearGradient + y2="262.375" + x2="72.826698" + y1="262.375" + x1="28.6553" + gradientUnits="userSpaceOnUse" + id="XMLID_6_"> + <stop + id="stop11390" + style="stop-color:#8AACD6" + offset="0" /> + <stop + id="stop11392" + style="stop-color:#A7C7E6" + offset="1" /> + </linearGradient> + <polygon + style="fill:url(#linearGradient11818)" + id="polygon11394" + points="39.721,281.375 61.665,281.375 72.827,262.465 61.668,243.375 39.724,243.375 28.655,262.286 " /> + <path + style="fill:#ffffff" + id="path11396" + d="M 62.242,242.375 H 61.094 40.297 39.15 l -0.579,0.99 -10.485,17.914 -0.589,1.005 0.585,1.008 10.485,18.086 0.578,0.997 h 1.152 20.797 1.142 l 0.58,-0.983 10.572,-17.913 0.597,-1.012 -0.592,-1.014 -10.572,-18.087 -0.579,-0.991 0,0 z m -32.43,19.914 10.485,-17.914 h 20.797 l 10.572,18.087 0,0 0,0 -10.572,17.913 H 40.297 l -10.485,-18.086 0,0 0,0 z" /> +</g><g + id="c_x2B__x2B__libs" + style="display:inline;overflow:visible"> + <g + id="g11384"> + + <text + style="font-size:14.2159996px;letter-spacing:13.40499973;fill:#4a6484;font-family:Denmark" + id="text11386" + letter-spacing="13.405" + font-size="14.216" + transform="matrix(0.9698,0,-0.1736,0.9848,129.4995,290.7246)">C++ LIBRARIES</text> + + + + + + + + + + + </g> +</g><text + sodipodi:linespacing="100%" + id="text2453" + y="210.11618" + x="158.79939" + style="font-size:36px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:start;line-height:100%;writing-mode:lr-tb;text-anchor:start;fill:#ff0000;fill-opacity:1;stroke:none;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1;font-family:Arial;-inkscape-font-specification:Arial" + xml:space="preserve"><tspan + sodipodi:role="line" + id="tspan2450" + x="158.79939" + y="210.11618">Proposed for</tspan></text> + + + +</g><g + style="display:none" + inkscape:label="Proposed For" + id="layer10" + inkscape:groupmode="layer"><g + id="g2932" + style="display:inline;overflow:visible" + transform="translate(2.7832904e-6,0)"><g + id="g2925"><g + id="g2914" + style="display:inline;overflow:visible" + transform="translate(2.7832904e-6,0)"><g + id="g2897"><g + id="g2911" + style="display:inline;overflow:visible" + transform="translate(2.8192073e-6,-170.41634)"><text + xml:space="preserve" + style="font-size:14.34384632px;font-style:italic;font-variant:normal;font-weight:normal;font-stretch:normal;fill:#000000;fill-opacity:1;stroke:none;font-family:Denmark;-inkscape-font-specification:Bitstream Vera Sans" + x="175.09654" + y="220.46455" + id="text11435" + transform="scale(1.0495629,0.95277758)"><tspan + sodipodi:role="line" + id="tspan11437" + x="175.09654" + y="220.46455" + style="font-style:italic;font-weight:normal;letter-spacing:6.09533262;fill:#ff0000;-inkscape-font-specification:Bitstream Vera Sans Oblique">PROPOSED FOR</tspan></text> + + + + + + + +</g></g></g></g></g></g><g + style="display:inline" + inkscape:label="Unofficial Extension" + id="layer2" + inkscape:groupmode="layer"><g + id="g3016" + style="display:inline;overflow:visible" + transform="translate(2.7832904e-6,0)"><g + id="g3018" + style="display:inline;overflow:visible" + transform="translate(137.07948,-18.749054)"><g + id="g3020" + style="display:inline;overflow:visible" + transform="translate(2.8192073e-6,-170.41634)"> + + + +</g></g></g></g><g + style="display:none" + inkscape:label="For Use With" + id="layer1" + inkscape:groupmode="layer"><g + id="g3010"><g + transform="translate(2.7832904e-6,0)" + style="display:inline;overflow:visible" + id="g2902"><g + transform="translate(2.8192073e-6,-170.41634)" + style="display:inline;overflow:visible" + id="g2904"><text + transform="scale(1.0495629,0.95277758)" + id="text2906" + y="220.46455" + x="182.23338" + style="font-size:14.34384632px;font-style:italic;font-variant:normal;font-weight:normal;font-stretch:normal;fill:#000000;fill-opacity:1;stroke:none;font-family:Denmark;-inkscape-font-specification:Bitstream Vera Sans" + xml:space="preserve"><tspan + style="font-style:italic;font-weight:normal;letter-spacing:6.09533262;fill:#ff0000;-inkscape-font-specification:Bitstream Vera Sans Oblique" + y="220.46455" + x="182.23338" + id="tspan2908" + sodipodi:role="line">FOR USE WITH</tspan></text> + + + + + + + +</g></g></g></g><g + transform="translate(3.5916937e-8,-170.41634)" + style="display:none" + inkscape:label="Powered By" + id="layer6" + inkscape:groupmode="layer"><text + transform="scale(1.0495629,0.95277758)" + id="text11497" + y="220.46455" + x="203.05875" + style="font-size:14.34384632px;font-style:italic;font-variant:normal;font-weight:normal;font-stretch:normal;fill:#4a6484;fill-opacity:1;stroke:none;display:inline;font-family:Denmark;-inkscape-font-specification:Bitstream Vera Sans" + xml:space="preserve"><tspan + style="font-style:italic;font-weight:normal;letter-spacing:6.09533262;fill:#4a6484;fill-opacity:1;-inkscape-font-specification:Bitstream Vera Sans Oblique" + y="220.46455" + x="203.05875" + id="tspan11499" + sodipodi:role="line">POWERED BY</tspan></text> + + + + + + + + + +</g></svg>
\ No newline at end of file diff --git a/attic/doc/src/images/workshop_atomic_updates_insertions.png b/attic/doc/src/images/workshop_atomic_updates_insertions.png Binary files differnew file mode 100644 index 00000000..47e941b0 --- /dev/null +++ b/attic/doc/src/images/workshop_atomic_updates_insertions.png diff --git a/attic/doc/src/images/workshop_atomic_updates_insertions_1.3.png b/attic/doc/src/images/workshop_atomic_updates_insertions_1.3.png Binary files differnew file mode 100644 index 00000000..47e941b0 --- /dev/null +++ b/attic/doc/src/images/workshop_atomic_updates_insertions_1.3.png diff --git a/attic/doc/src/images/workshop_atomic_updates_lookups.png b/attic/doc/src/images/workshop_atomic_updates_lookups.png Binary files differnew file mode 100644 index 00000000..7e528192 --- /dev/null +++ b/attic/doc/src/images/workshop_atomic_updates_lookups.png diff --git a/attic/doc/src/images/workshop_atomic_updates_lookups_1.3.png b/attic/doc/src/images/workshop_atomic_updates_lookups_1.3.png Binary files differnew file mode 100644 index 00000000..7e528192 --- /dev/null +++ b/attic/doc/src/images/workshop_atomic_updates_lookups_1.3.png diff --git a/attic/doc/src/images/workshop_naive_insertions.png b/attic/doc/src/images/workshop_naive_insertions.png Binary files differnew file mode 100644 index 00000000..7bf03f44 --- /dev/null +++ b/attic/doc/src/images/workshop_naive_insertions.png diff --git a/attic/doc/src/images/workshop_naive_insertions_1.3.png b/attic/doc/src/images/workshop_naive_insertions_1.3.png Binary files differnew file mode 100644 index 00000000..7bf03f44 --- /dev/null +++ b/attic/doc/src/images/workshop_naive_insertions_1.3.png diff --git a/attic/doc/src/images/workshop_naive_lookups.png b/attic/doc/src/images/workshop_naive_lookups.png Binary files differnew file mode 100644 index 00000000..e01cf39d --- /dev/null +++ b/attic/doc/src/images/workshop_naive_lookups.png diff --git a/attic/doc/src/images/workshop_naive_lookups_1.3.png b/attic/doc/src/images/workshop_naive_lookups_1.3.png Binary files differnew file mode 100644 index 00000000..e01cf39d --- /dev/null +++ b/attic/doc/src/images/workshop_naive_lookups_1.3.png diff --git a/attic/doc/workshop.xlsx b/attic/doc/workshop.xlsx Binary files differnew file mode 100644 index 00000000..f29d1003 --- /dev/null +++ b/attic/doc/workshop.xlsx |
