mirror of
https://github.com/Naios/continuable.git
synced 2025-12-07 01:06:44 +08:00
Finish the documentation
This commit is contained in:
Denis Blank
parent
936a09dac2
commit
2d1fda228f
147
doc/changelog.dox
Normal file
147
doc/changelog.dox
Normal file
@ -0,0 +1,147 @@
|
||||
/*
|
||||
Copyright(c) 2015 - 2018 Denis Blank <denis.blank at outlook dot com>
|
||||
|
||||
Permission is hereby granted, free of charge, to any person obtaining a copy
|
||||
of this software and associated documentation files(the "Software"), to deal
|
||||
in the Software without restriction, including without limitation the rights
|
||||
to use, copy, modify, merge, publish, distribute, sublicense, and / or sell
|
||||
copies of the Software, and to permit persons to whom the Software is
|
||||
furnished to do so, subject to the following conditions :
|
||||
|
||||
The above copyright notice and this permission notice shall be included in
|
||||
all copies or substantial portions of the Software.
|
||||
|
||||
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
||||
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
||||
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.IN NO EVENT SHALL THE
|
||||
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
||||
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
||||
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
||||
SOFTWARE.
|
||||
*/
|
||||
|
||||
namespace cti {
|
||||
/** \page changelog Changelog
|
||||
\brief A description of the changes made to continuable.
|
||||
|
||||
\section changelog-versions Versions
|
||||
|
||||
Following versions were released:
|
||||
|
||||
\subsection changelog-versions-3-0-0 3.0.0
|
||||
|
||||
\subsection changelog-versions-2-0-0 2.0.0
|
||||
|
||||
<B>Error handling</B>
|
||||
|
||||
Usually it is inconvenient to handle error codes and exceptions in an
|
||||
asynchronous context, as we all know `std::future` supports error handling
|
||||
through exceptions already. We now introduce this capability to the
|
||||
continuable library while allowing error codes to be used as well.
|
||||
|
||||
Consider the function `cti::continuable<> get_bad_continuable()`
|
||||
which always resolves through an error, then you may handle the error code
|
||||
or exception as following:
|
||||
|
||||
\code{.cpp}
|
||||
get_bad_continuable()
|
||||
.then([] {
|
||||
// ... never invoked
|
||||
})
|
||||
.then([] {
|
||||
// ... never invoked as well
|
||||
})
|
||||
.fail([] (std::exception_ptr e) {
|
||||
try {
|
||||
std::rethrow_exception(e);
|
||||
} catch(std::exception const& e) {
|
||||
// Handle the exception here
|
||||
}
|
||||
});
|
||||
\endcode
|
||||
|
||||
|
||||
<B>Abstracting callbacks as promises</B>
|
||||
|
||||
Since a callback may be called through an error or result the cri::promise
|
||||
class was added in order ro provide a similar interface to std::promise:
|
||||
|
||||
|
||||
\code{.cpp}
|
||||
auto http_request(std::string url) {
|
||||
return cti::make_continuable<std::string>(
|
||||
[url = std::move(url)](cti::promise<std::string> promise) {
|
||||
// Perform the actual request through a different library,
|
||||
// resolve the promise upon completion of the task.
|
||||
promise.set_value("<html> ... </html>");
|
||||
// ...or promise.set_exception(...);
|
||||
});
|
||||
}
|
||||
\endcode
|
||||
|
||||
<B>`co_await` support</B>
|
||||
|
||||
Experimental coroutine (`co_await` and `co_return`) support was added,
|
||||
this is available on MSVC 2017 and Clang 5.0.
|
||||
|
||||
\code{.cpp}
|
||||
int i = co_await cti::make_continuable<int>([](auto&& promise) {
|
||||
promise.set_value(0);
|
||||
});
|
||||
\endcode
|
||||
|
||||
<B>Minor improvements</B>
|
||||
|
||||
The library was improved in other ways:
|
||||
|
||||
- `constexpr` and `noexcept` improvements
|
||||
- Compile-time improvements
|
||||
- Documentation improvements
|
||||
|
||||
<B>Header split</B>
|
||||
|
||||
Since the overall library size was increased the headers were split into smaller chunks.
|
||||
|
||||
\subsection changelog-versions-1-0-0 1.0.0
|
||||
|
||||
- Documentation and readme changes
|
||||
- Change the assertion type of some GTest macros from expected to assertion.
|
||||
|
||||
\subsection changelog-versions-0-8-0 0.8.0 (unstable)
|
||||
|
||||
- Fixes a major issue with handling the ownership for consumed continuables
|
||||
which led to unintended invocations.
|
||||
- Adds partial application support which makes it possible to chain callbacks
|
||||
which accept less arguments then the curret signature.
|
||||
\code{.cpp}
|
||||
http_request("github.com")
|
||||
.then([] {
|
||||
// ...
|
||||
});
|
||||
\endcode
|
||||
- Adds Support for sequential invocation:
|
||||
\code{.cpp}
|
||||
http_request("github.com") >> http_request("atom.io")
|
||||
.then([] (std::string github, std::string atom) {
|
||||
// ...
|
||||
});
|
||||
\endcode
|
||||
|
||||
\subsection changelog-versions-0-7-0 0.7.0 (unstable)
|
||||
|
||||
- Continuation syntactic sugar
|
||||
- Executor support
|
||||
- Connection support
|
||||
|
||||
\section changelog-semver Semantic versioning and stability
|
||||
|
||||
Continuable strictly follows the rules of
|
||||
[semantic versioning](http://semver.org/), the API is kept stable
|
||||
across minor versions.
|
||||
|
||||
The CI driven unit-tests are observed through the Clang sanitizers
|
||||
(asan, ubsan and lsan - when compiling with Clang) or
|
||||
Valgrind (when compiling with GCC) in order to prevent regressions.
|
||||
|
||||
*/
|
||||
}
|
||||
@ -54,6 +54,9 @@ The \ref installation and \ref configuration are explained in its own chapter.
|
||||
The \ref tutorial is everything you need in order to get to know the libraries
|
||||
API. Beside of this, there is a detailed in-source documentation provided.
|
||||
|
||||
Continuable follows the semantic versioning schema and changes are listed
|
||||
in the \ref changelog.
|
||||
|
||||
\section mainpage-contact Contributing and Questions
|
||||
|
||||
Through the [Github issue tracker](https://github.com/Naios/continuable/issues)
|
||||
|
||||
@ -26,76 +26,121 @@ namespace cti {
|
||||
|
||||
\tableofcontents
|
||||
|
||||
\section installation-requirements Requirements
|
||||
|
||||
## Installation
|
||||
Continuable requires a fairly new toolchain and was verified to work with
|
||||
following compilers:
|
||||
|
||||
### How-to use
|
||||
- Visual Studio 2017+ Update 2
|
||||
- Clang 5.0+
|
||||
- GCC 6.0+
|
||||
|
||||
As mentioned earlier the library is header-only. There is a cmake project provided for simple setup:
|
||||
Although the build is observed with the listed compilers earlier
|
||||
versions might work.
|
||||
|
||||
#### As git submodule
|
||||
\section installation-dependencies Dependencies
|
||||
|
||||
\endcodesh
|
||||
# Shell:
|
||||
git submodule add https://github.com/Naios/continuable.git
|
||||
\endcode
|
||||
Continuable is a header-only library with one required header-only dependency:
|
||||
|
||||
\endcodecmake
|
||||
# CMake file:
|
||||
- [Naios/function2](https://github.com/Naios/function2) is used as type
|
||||
erasure wrapper to convert a \ref continuable_base into a \ref continuable.
|
||||
|
||||
Additionally GTest is required as optional dependency for the asynchronous
|
||||
unit testing macros defined in `continuable/continuable-testing.hpp`
|
||||
if those are used:
|
||||
|
||||
- [google/googletest](https://github.com/google/googletest) is used as
|
||||
unit testing framework and to provide asynchronous testing macros.
|
||||
|
||||
For the examples and unit tests there might be more dependencies used,
|
||||
which are fetched through git submodules.
|
||||
|
||||
\note The library only depends on the standard library when following
|
||||
headers are used:
|
||||
- `continuable/continuable-base.hpp`
|
||||
- `continuable/continuable-promise-base.hpp`
|
||||
- `continuable/continuable-connections.hpp`
|
||||
- `continuable/continuable-promisify.hpp`
|
||||
- `continuable/continuable-transforms.hpp`
|
||||
|
||||
\section installation-installation Installation
|
||||
|
||||
Making continuable available inside your project is possible through
|
||||
various ways.
|
||||
|
||||
\subsection installation-installation-cmake Through CMake
|
||||
|
||||
The continuable build is driven by CMake and the project exposes CMake
|
||||
interface targets when being used by external projects:
|
||||
|
||||
\code{.cmake}
|
||||
add_subdirectory(continuable)
|
||||
# continuable provides an interface target which makes it's
|
||||
# headers available to all projects using the continuable library.
|
||||
target_link_libraries(my_project continuable)
|
||||
\endcode
|
||||
|
||||
On POSIX platforms you are required to link your application against a corresponding thread library, otherwise `std::future's` won't work properly, this is done automatically by the provided CMake project.
|
||||
When adding the continuable subdirectory as git submodule this should work
|
||||
out of the box.
|
||||
|
||||
#### As CMake library
|
||||
\code{.sh}
|
||||
git submodule add https://github.com/Naios/continuable.git
|
||||
\endcode
|
||||
|
||||
Additionally the project exports a `continuable` target which is importable through CMake when installed:
|
||||
\attention On POSIX platforms you are required to link your application against
|
||||
a corresponding thread library, otherwise `std::futures` won't work
|
||||
properly, this is done automatically by the provided CMake project.
|
||||
|
||||
\endcodesh
|
||||
Additionally the CMake project exports a `continuable` target which is
|
||||
importable through the \code{.cmake}find_package\endcode CMake command
|
||||
when installed:
|
||||
|
||||
\code{.sh}
|
||||
mkdir build
|
||||
cd build
|
||||
cmake ..
|
||||
cmake --build . --target INSTALL --config Release
|
||||
\endcode
|
||||
|
||||
`CMakeLists.txt`:
|
||||
In your `CMakeLists.txt`:
|
||||
|
||||
\endcodecmake
|
||||
\code{.cmake}
|
||||
find_package(continuable REQUIRED)
|
||||
\endcode
|
||||
|
||||
### Building the unit-tests
|
||||
\subsection installation-installation-pkg Through package managers
|
||||
|
||||
In order to build the unit tests clone the repository recursively with all submodules:
|
||||
Continuable is present in some package managers and registries already,
|
||||
and might be installed from there.
|
||||
|
||||
\endcodesh
|
||||
\attention The project is still looking for contributions that would help
|
||||
to make it available from various package managers in order to
|
||||
make the installation easier.
|
||||
|
||||
\subsection installation-installation-copy By copying the headers
|
||||
|
||||
If you don't want to rely on CMake or package managers it is possible to
|
||||
copy and include the `include` directories of continuable and
|
||||
[Naios/function2](https://github.com/Naios/function2) into your project.
|
||||
|
||||
As an improvement git submodules could be used:
|
||||
|
||||
\code{.sh}
|
||||
git submodule add https://github.com/Naios/continuable.git
|
||||
git submodule add https://github.com/Naios/function2.git
|
||||
\endcode
|
||||
|
||||
\section installation-unit-tests Building the unit tests
|
||||
|
||||
In order to build the unit tests clone the repository recursively
|
||||
with all submodules:
|
||||
|
||||
\code{.sh}
|
||||
# Shell:
|
||||
git clone --recursive https://github.com/Naios/continuable.git
|
||||
\endcode
|
||||
## Stability and version
|
||||
|
||||
The library follows the rules of [semantic versioning](http://semver.org/), the API is kept stable across minor versions.
|
||||
|
||||
The CI driven unit-tests are observed through the Clang sanitizers (asan, ubsan and lsan - when compiling with Clang) or Valgrind (when compiling with GCC).
|
||||
|
||||
|
||||
## Compatibility
|
||||
|
||||
Tested & compatible with:
|
||||
|
||||
- Visual Studio 2017+ Update 2
|
||||
- Clang 5.0+
|
||||
- GCC 6.0+
|
||||
|
||||
Although the build is observed with the latest toolchains earlier ones might work.
|
||||
|
||||
The library only depends on the standard library when using the `continuable/continuable-base.hpp` header, which provides the basic continuation logic.
|
||||
|
||||
> **Note:** On Posix: don't forget to **link a corresponding thread library** into your application otherwise `std::future's` won't work `(-pthread)` when using future based transforms.
|
||||
|
||||
Then CMake can be used to generate a project solution for testing.
|
||||
|
||||
*/
|
||||
}
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user