<commit_before># PoolQueue
PoolQueue is a C++ library for asynchronous operations. Its primary
feature is asynchronous promises, inspired by the [Javascript
Promises/A+ specification](https://promisesaplus.com/). The library
also contains a thread pool and a timer, both built using asynchronous
promises. The library implementation makes use of C++11 features but
has no external dependencies (the test suite and some examples require
Boost).

PoolQueue is developed by Shoestring Research, LLC and is available
under the [Apache License Version
2.0](http://www.apache.org/licenses/LICENSE-2.0).

## Promise basics
The [Javascript
Promises/A+ specification](https://promisesaplus.com/) describes a promise:

> A promise represents the eventual result of an asynchronous
> operation. The primary way of interacting with a promise is through
> its then method, which registers callbacks to receive either a
> promise’s eventual value or the reason why the promise cannot be
> fulfilled.

A PoolQueue `Promise` can be in one of three states: *pending* (aka
not settled), *fulfilled*, or *rejected*. Pending, aka not settled,
means that the `Promise` has not yet been fulfilled or
rejected. Fulfilled means that the `Promise` has a value (possibly
`void`). Rejected means that the `Promise` has an exception.

A `Promise` can have function callbacks to invoke when it is settled
(either fulfilled or rejected). Whichever callback is invoked, the
`Promise` will be fulfilled if the callback returns or rejected if the
callback throws an exception. The exception to this is if the callback
returns a `Promise`. In this case the original `Promise` will settle
with the result of the returned `Promise` (callbacks will not be
invoked again).

A `Promise` can have dependent `Promise`s created and attached using
the `then()` or `except()` methods. When a `Promise` is settled, it
invokes the appropriate callback if present, and then recursively
settles dependent `Promise`s with the result (value or exception). A
dependent `Promise` newly attached to an already settled `Promise`
will be settled immediately.

Example:

    #include <poolqueue/Promise.hpp>
    ...
    pq::Promise p;
    p.then(
      [](const std::string& s) {
        std::cout << "fulfilled with " << s << '\n';
      },
      [](const std::exception_ptr& e) {
        try {
          if (e)
            std::rethrow_exception(e);
        }
        catch (const std::exception& e) {
          std::cout << "rejected with " << e.what() << '\n';
        }
      });
    ...
    // possibly in another thread
    p.settle(std::string("how now brown cow");

The lambdas attached with `then()` are deferred until the `Promise` is
settled.

Additional example code is under examples/:

* [Basic `Promise` usage]()
* [Chaining `Promise`s]()
* [Callback returning a `Promise`]()

## Promise details
A PoolQueue `Promise` holds a shared pointer to its state. Copying a
`Promise` produces another reference to the same state, not a brand
new `Promise`. This allows lambdas to capture `Promise`s by value.<commit_msg>Add example URLs.<commit_after># PoolQueue
PoolQueue is a C++ library for asynchronous operations. Its primary
feature is asynchronous promises, inspired by the [Javascript
Promises/A+ specification](https://promisesaplus.com/). The library
also contains a thread pool and a timer, both built using asynchronous
promises. The library implementation makes use of C++11 features but
has no external dependencies (the test suite and some examples require
Boost).

PoolQueue is developed by Shoestring Research, LLC and is available
under the [Apache License Version
2.0](http://www.apache.org/licenses/LICENSE-2.0).

## Promise basics
The [Javascript
Promises/A+ specification](https://promisesaplus.com/) describes a promise:

> A promise represents the eventual result of an asynchronous
> operation. The primary way of interacting with a promise is through
> its then method, which registers callbacks to receive either a
> promise’s eventual value or the reason why the promise cannot be
> fulfilled.

A PoolQueue `Promise` can be in one of three states: *pending* (aka
not settled), *fulfilled*, or *rejected*. Pending, aka not settled,
means that the `Promise` has not yet been fulfilled or
rejected. Fulfilled means that the `Promise` has a value (possibly
`void`). Rejected means that the `Promise` has an exception.

A `Promise` can have function callbacks to invoke when it is settled
(either fulfilled or rejected). Whichever callback is invoked, the
`Promise` will be fulfilled if the callback returns or rejected if the
callback throws an exception. The exception to this is if the callback
returns a `Promise`. In this case the original `Promise` will settle
with the result of the returned `Promise` (callbacks will not be
invoked again).

A `Promise` can have dependent `Promise`s created and attached using
the `then()` or `except()` methods. When a `Promise` is settled, it
invokes the appropriate callback if present, and then recursively
settles dependent `Promise`s with the result (value or exception). A
dependent `Promise` newly attached to an already settled `Promise`
will be settled immediately.

Example:

    #include <poolqueue/Promise.hpp>
    ...
    pq::Promise p;
    p.then(
      [](const std::string& s) {
        std::cout << "fulfilled with " << s << '\n';
      },
      [](const std::exception_ptr& e) {
        try {
          if (e)
            std::rethrow_exception(e);
        }
        catch (const std::exception& e) {
          std::cout << "rejected with " << e.what() << '\n';
        }
      });
    ...
    // possibly in another thread
    p.settle(std::string("how now brown cow");

The lambdas attached with `then()` are deferred until the `Promise` is
settled.

Additional example code is under examples/:

* [Basic `Promise` usage](https://github.com/rhashimoto/poolqueue/blob/master/examples/Promise_basics.cpp)
* [Chaining `Promise`s](https://github.com/rhashimoto/poolqueue/blob/master/examples/Promise_chain.cpp)
* [Callback returning a `Promise`](https://github.com/rhashimoto/poolqueue/blob/master/examples/Promise_sub.cpp)

## Promise details
A PoolQueue `Promise` holds a shared pointer to its state. Copying a
`Promise` produces another reference to the same state, not a brand
new `Promise`. This allows lambdas to capture `Promise`s by value.
{'fraction_non_alphanumeric': 0.09343157234676282, 'fraction_numerical': 0.0018811725975858284, 'mean_word_length': 4.0236220472440944, 'pattern_counts': {'":': 0, '<': 29, '<?xml version=': 0, '>': 15, 'https://': 7, 'lorem ipsum': 0, 'www.': 2, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '3533815', 'n_tokens_mistral': 1758, 'n_tokens_neox': 1670, 'n_words': 797}