Skip to content

API reference

Jump to bottom
Mike Teixeira edited this page Dec 15, 2017 · 8 revisions

Currently under construction

Table of contents

nova::start_sync

template <typename Callable, typename ... Params>
void start_sync(Callable&& callable, Params&&... args);

template <typename Callable, typename ... Params>
void start_sync(unsigned threadCount, Callable&& callable, Params&&... args);

Starts the job system with the given number of threads (defaults to std::thread::hardware_concurrency() and includes the main thread) and enters the given callable object with the given parameters.

Returns when the callable returns.

nova::start_async

template <typename Callable, typename ... Params>
void start_async(Callable&& callable, Params&&... args);

template <typename Callable, typename ... Params>
void start_async(unsigned threadCount, Callable&& callable, Params&&... args);

Starts the job system with the given number of threads (defaults to std::thread::hardware_concurrency() and includes the main thread) and enters the given callable object with the given parameters.

Returns after all worker threads are stopped with nova::kill_all_workers.

nova::kill_all_workers

void kill_all_workers();

Pushes one poison pill invocation per worker thread (including the main thread) to the thread pool. These invocations will cause any thread that runs them to stop processing invocations. Invocations that were pushed prior to kill_all_workers being called will still run, but any pushed afterwards (such as by invocations that are still being processed) will not.

If the program was started with nova::start_async this will cause that function to return. Otherwise it will cause the system to idle indefinitely.

nova::bind

template <typename Callable, typename ... Params>
auto bind(Callable&& callable, Params&&... args);

Wraps the given callable and parameters in a runnable object and returns it. If the runnable must be captured, capture it with auto, i.e.:

auto fn = nova::bind(SomeFunc, arg1, arg2);

nova::bind_batch

template <typename Callable, typename ... Params>
auto bind_batch(Callable&& callable, Params&&... args);

Wraps the given callable and parameters, which include a numeric range, in a batch runnable object and returns it. Any batch runnables invoked with nova::call, nova::push, or nova::push_dependent will be invoked as a set of runnables, each of which has a contiguous portion of the original range.

Params&&... args must include a sequential pair of values that satisfy std::is_integral and represent, respectively, the start and end of the range to be split, and the first value in the pair must be the first parameter to satisfy std::is_integral.

If the runnable must be captured, capture it with auto, i.e.:

auto bfn = nova::bind_batch(SomeBatchFunc, 0, 5000);

nova::call

template<typename ... Runnables, typename ... Controls>
void call(Runnables&&... runnables);

Queues the given runnables to be invoked on the thread pool and returns once their invocations have all finished.

If Controls contains nova::to_main the runnables will be invoked on the main thread, otherwise they may be invoked on any thread.

If Controls contains nova::return_main control will be on the main thread when the call returns, otherwise it may be on any thread (regardless of what thread it was called from).

Under the hood this attaches a nova::dependency_token to the runnables and uses the Windows Fiber API to suspend the current call stack and switch back to it when the dependency_tokens expire.

nova::push

template<typename ... Runnables, typename ... Controls>
void push(Runnables&&... runnables);

Queues the given runnables to be invoked on the thread pool and returns immediately.

If Controls contains nova::to_main the runnables will be invoked on the main thread, otherwise they may be invoked on any thread.

If Controls contains nova::dependent and the function is called from within a synchronous invocation the lifetime of that synchronous invocation will be extended to include the given runnables.

nova::dependent

struct dependent {};

A control that causes nova::push's invokees to extend the lifetime of an active synchronous invocation, preventing that invocation from returning until all the invokees have returned.

Passed to nova::push as an optional template parameter:

nova::push(...); // Doesn't extend synchronous invocation.
nova::push<nova::dependent>(...); // Extends synchronous invocation.

Does nothing when passed to nova::call.

nova::to_main

struct to_main {};

A control that causes nova::push's and nova::call's invokees to be run on the main thread.

Passed to nova::push or nova::call as an optional template parameter:

// Don't invoke on main thread:
nova::push(...);
nova::call(...);

// Do invoke on main thread:
nova::push<nova::to_main>(...);
nova::call<nova::to_main>(...);

nova::return_main

struct return_main {};

A control that causes nova::call to return to the main thread:

// May be on any thread
...
nova::call<nova::return_main>(...);
// On main thread
...

Passed to nova::call as an optional template parameter:

nova::call(...); // May return on any thread.
nova::call<nova::return_main>(...); // Returns to main thread.

Does nothing when passed to nova::push.

nova::dependency_token

class dependency_token {
public:
	dependency_token() {}

	dependency_token(const dependency_token &) = default;
	dependency_token& operator=(const dependency_token&) = default;

	dependency_token(dependency_token &&) = default;
	dependency_token& operator=(dependency_token&&) = default;

	template<typename Runnable, 
		std::enable_if_t<!std::is_same<std::decay_t<Runnable>, dependency_token>::value, int> = 0>
	dependency_token(Runnable&& runnable);

	void Release();
};

Holds a runnable to be invoked once the token and all its copies have either been destructed or released (via Release).

Uses a std::shared_ptr under the hood, so creation requires a dynamic allocation, and copying is relatively expensive.

nova::parallel_for

template<typename Callable, typename ... Params>
void parallel_for(std::size_t start, std::size_t end, Callable&& callable, Params&&... args);

Invokes the callable once for every value between start (inclusive) and end (exclusive), passing in the current value and the given parameters.

nova::switch_to_main

void switch_to_main();

A no-op that always returns to the main thread. Functionally (but not literally) equivalent to

nova::call<nova::return_main>();
Clone this wiki locally