tasc is an asynchrounous worker pool library, allowing you to distribute work between multiple workers in both an asyncrhronous, and blocking API. tasc aims to be simpistic and portable, the base API does not rely on running within a context that provides the standard library, and can be run in a bare metal environments. The API aims to be very similar to that of [std::thread], so that if you understand one then understanding the other is simple.

tasc operates, by default, with a global context which relies on the standard library. The helper functions tasc::task, tasc::scope and everything under tasc::blocking will use the global context by default, and requires the global feature to be enables. When the global feature is enabled, it requires enabling the std feature which will require a dependency on the standard library.

Using Async tasc

async {
	// this will create a task, and them immediately awaits the task to completion.
	// the `.await` is just because creating a task is considered an ascynchronous process, the awaiting happens by a call to `[drop]` of the handle type.
	tasc::task(|id| println!("this is a task running asyncrhonously with an id of {id}")).await;

	// this will create a task, do some work, then join it at a later point.
	let handle = tasc::task(|id| println!("this will run on a separate thread!")).await;
	do_work();
	handle.wait().await; // here we join the thread

	// a task is capable of returning a value.
	let handle = tasc::task(|_id| {
		let foo = 1;
		let bar = 2;
		foo + bar
	});
	let result = hadle.handle.await.wait().await.unwrap(); // `[wait]` returns a result.
}

Using The Context Directly

tasc allows you to create your own context by deriving the [TaskContext] trait on a type, and then passing that to [TaskBuilder]. If the std feature is enabled, tasc will provide such a context already called [StdContext]. Using [StdContext] outside of the global context is quite simple.

async {
	// create a context with 8 worker threads.
	let cx = tasc::StdContext::new(8).await;
	tasc::TaskBuilder::<tasc::global::Signal>::from_ctx(&cx).spawn(|_id| println!("I am now spawned from the cx context!")).await;

	// optionally, we can also use the `[Default]` trait if the `std` feature is enabled, which will create a `[TaskBuilder]` using the global context and global signal.
	tasc::TaskBuilder::default().spawn(|_id| println!("I am created in the global context, prefer to use 'tasc::task' instead!")).await;
}

Scoped Tasks

tasc allows for scoped tasks, which are quite similar to scoped threads in the standard library, except it does not have the scope function.

async {
	let mut v = vec![];

	tasc::scope(|_id| {
		// borrows v mutably
		v.push(2);
	}).await;

	println!("{x:?}");
}

Using The Blocking API

tasc does not force using asynchronous code, and provides a blocking alternative such as task::blocking::task and task::blocking::scope.

let handle0 = tasc::blocking::task(|_| 20);
let bar = 5;
let handle1 = tasc::blocking::scope(|_| 20 + bar);

let sum = handle.wait().unwrap() + handle1.wait().unwrap();
println!("{sum:?}");