continuable/doc/changelog.dox

/*
  Copyright(c) 2015 - 2022 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-4-0-0 4.0.0

Various issues have been resolved:

- [#27: First class, zero-overhead ASIO integration](https://github.com/Naios/continuable/issues/27)
- [#23: VS 16.2: parameter pack must be expanded in this context](https://github.com/Naios/continuable/issues/23)
- [#21: Infinite recursion during compilation](https://github.com/Naios/continuable/issues/21)
- [#16: Add AppleClang compiler to cmake](https://github.com/Naios/continuable/issues/16)
- [#13: unit-test/test-continuable-single fails on gcc 8.2](https://github.com/Naios/continuable/issues/13)
- [#11: Forward declarations are no longer allowed in type-erased continuables](https://github.com/Naios/continuable/issues/11)

Following methods and functions have been added:

<B>Various improvements to continuable_base:</B>

- \ref continuable_base::as for casting to a continuable_base with different arguments
- \ref continuable_base::finish for 'materializing' an intermediate chained continuable_base

<B>An asychronous initiation function comparable to std::async:</B>

The asynchronous facilities make it possible now to start with a handler
instead of a continuation:

\code{.cpp}
async([] {
  // ...
}).then(...);
\endcode

- \ref async Makes it possible to start with a handler instead of a continuation, comparable to `std::async`
- \ref async_on allows to specify an additional executor parameter

<B>The result class and modifying the asynchronous control flow</B>

Every continuation handler used in \ref continuable_base::then, \ref continuable_base::next
and \ref continuable_base::fail allows now to return a \ref result which represents
the asynchronous result.

This allows recovering from failures or throwing of exception types from
handlers when exceptions are disabled.

Result handling and
- \ref result
- \ref rethrow Throws an exception or error code from a result or failure handler
- \ref cancel Throws a default constructed exception type or error code from a result or failure handler to signal cancellation.
- \ref stop \copybrief stop
- \ref make_result \copybrief make_result

Special result types
- \ref empty_result \copybrief empty_result
- \ref cancellation_result \copybrief cancellation_result
- \ref exceptional_result \copybrief exceptional_result

<B>Optimize 'ready' continuables:</B>

Continuables which are 'ready' and side effect free can now be unpacked
synchronously. Mainly such continuables are created through \ref make_ready_continuable,
\ref make_exceptional_continuable and \ref make_cancelling_continuable.

- \ref continuable_base::is_ready \copybrief continuable_base::is_ready
- \ref continuable_base::unpack \copybrief continuable_base::unpack
- \ref make_cancelling_continuable \copybrief make_cancelling_continuable

Including various helper tags for the underlying changed continuation object structure:

- \ref signature_arg_t
- \ref is_ready_arg_t
- \ref unpack_arg_t
- \ref exception_arg_t
- \ref exception_t

<B>asio asynchronous initiate token:</B>

The \ref use_continuable_t special tag can be used to make (boost) asio
return a \ref continuable_base.

- \ref use_continuable \copybrief use_continuable_t

\code{.cpp}
#include <continuable/continuable.hpp>
#include <continuable/external/asio.hpp>
#include <asio.hpp>

// ...

asio::tcp::resolver resolver(...);
resolver.async_resolve("127.0.0.1", "daytime", cti::use_continuable)
  .then([](asio::udp::resolver::iterator iterator) {
    // ...
  });
\endcode

<B>Iterating over an asynchronous control flow:</B>

The loop function was added which makes is possible to emulate an asynchronous loop,
that is comparable to a `co_await` with `for`.

- \ref loop \copybrief loop
- \ref loop_result \copybrief loop_result
- \ref loop_break \copybrief loop_break
- \ref loop_continue \copybrief loop_continue
- \ref range_loop \copybrief range_loop
- \ref range_loop \copybrief range_loop
- \ref plain_t \copybrief plain_t
- \ref make_plain \copybrief make_plain

<B>Synchronous wait transforms:</B>

The wait transforms allows to block the current thread until a \ref continuable_base
was resolved.

- \ref transforms::wait \copybrief transforms::wait
- \ref transforms::wait_for Same as \ref transforms::wait wich waits for a given duration
- \ref transforms::wait_until Same as \ref transforms::wait wich waits until a given timepoint

<B>Various changes:</B>

Many more unlisted changes including:

- \ref work \copybrief work
- \ref continuation_capacity
- \ref promisify::with \copybrief promisify::with
- \ref void_arg_t

Additional various bugfixes have been made.

\subsection changelog-versions-3-0-0 3.0.0

<B>New helper functions</B>

New helper functions were added to create ready continuables:

- \ref make_ready_continuable \copybrief make_ready_continuable
- \ref make_exceptional_continuable \copybrief make_exceptional_continuable

<B>Improvements to connections</B>

The implementation of connections were rewritten entirely.
It is possible now to connect runtime sized containers as well as
deeply nested sequences. See \ref tutorial-connecting-continuables for details.

Additionally connection overloads were added that accept two iterators
in order to come closer to the interface of the standard library.

Also \ref populate was added which makes it possible to populate
a dynamic container from \ref continuable_base objects.

<B>Disabled copies for promises and continuables entirely</B>

The \ref promise_base and \ref continuable_base is now non copyable.
This change should make it easier to work with the move only
semantic of continuables in order to make less mistakes.

<B>Traversal API</B>

A new traversal API for synchronous and asynchronous pack traversal
was added which makes it easy to specify new connection types.

\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.

*/
}