Decide best naming for `tasks` and `threads` modules

[ElFantasma]

Naming Proposals for Actor Module Variants

Introduction

The spawned library provides an Actor abstraction inspired by Erlang's GenServer. To support different use cases, we offer two implementations of the same Actor API:

1. An async implementation that runs on top of Tokio, where many actors are multiplexed onto a thread pool
2. A synchronous implementation that uses native OS threads, where each actor gets its own dedicated thread

Both implementations expose the same Actor trait and API, allowing users to switch between them by changing imports and removing async/.await syntax.

The Problem

The current module names — tasks and threads — are confusing:

• tasks is too generic. It doesn't convey that this version requires async/await syntax or a runtime. The word "task" is used in many contexts (todo tasks, scheduled tasks, etc.).

• threads is misleading. In async/concurrent programming, "threads" appears in terms like "green threads," "lightweight threads," and "virtual threads" — which are actually closer to our tasks implementation. Users might not realize threads means "one OS thread per actor."

Additionally, the names don't help users understand the tradeoffs:

• When should I use one vs the other?
• What are the resource implications?
• Which one is simpler to use?

We want names that:

1. Are self-explanatory to newcomers
2. Hint at the architectural differences
3. Help users choose the right version for their use case
4. Don't conflict with Rust keywords or overloaded terms

---

What Distinguishes the Two Versions

Aspect	Current tasks	Current threads
Syntax	Requires async/.await	Plain synchronous code
Runtime	Requires async runtime (Tokio)	No runtime needed
Threading model	Many actors multiplexed onto few OS threads	One dedicated OS thread per actor
Scheduling	Cooperative (actors yield control)	Preemptive (OS scheduler)
Resource usage	Lightweight, efficient for many actors	Heavier, but simpler mental model
Best for	I/O-bound, many concurrent actors	CPU-bound, blocking operations, simplicity
Extra features	Backend enum for execution control	—

---

Naming Proposals

Current Names

Async Version	Sync Version	Notes
tasks	threads	Current naming. Confusing because "tasks" is vague and "threads" is also used in async contexts (green threads).

Based on Syntax/API

Async Version	Sync Version	Notes
async	sync	Clear contrast, Rust-familiar. Con: async is a reserved keyword.
async_rt	sync	Avoids keyword, rt hints runtime needed. Con: asymmetric naming.
asynchronous	synchronous	Explicit but verbose.
awaited	direct	One uses await, one is direct. Con: "awaited" is awkward.

Based on Runtime Requirements

Async Version	Sync Version	Notes
managed	direct	Runtime manages execution vs direct OS usage. Clear and short.
hosted	standalone	Hosted on runtime vs standalone. Con: "hosted" might imply remote/cloud.
runtime	native	Needs runtime vs native OS primitives. Con: "native" might imply FFI.

Based on Threading Model

Async Version	Sync Version	Notes
multiplexed	dedicated	Actors share threads vs dedicated thread each. Accurately describes architecture.
pooled	isolated	Actors share thread pool vs isolated threads.
shared	dedicated	Similar to above, shorter. Con: "shared" is overloaded in Rust (shared references).
virtual	os	Virtual threads vs OS threads. Familiar from Java 21. Con: "virtual" has many meanings.
green	native	Green threads vs native threads. Established terminology. Con: we don't actually use green threads.

Based on Scheduling Model

Async Version	Sync Version	Notes
cooperative	preemptive	Technically accurate scheduling terms. Con: jargon-heavy for newcomers.
scheduled	threaded	Runtime-scheduled vs threaded. Con: OS threads are also "scheduled".

Based on Resource Characteristics

Async Version	Sync Version	Notes
lightweight	heavyweight	Describes resource usage. Con: sounds judgmental toward heavyweight.
light	native	Shorter version.

Based on Execution Model

Async Version	Sync Version	Notes
concurrent	parallel	Concurrency (shared resources) vs parallelism (dedicated). Con: technically imprecise.
nonblocking	blocking	Describes I/O behavior. Con: "blocking" has negative connotations.

Implementation-Specific

Async Version	Sync Version	Notes
tokio	std	Names the underlying implementation. Clear but ties naming to dependencies.

---

Recommendations

Top 3 choices:

1. multiplexed / dedicated

   • Accurately describes the core architectural difference
   • Not overloaded with other Rust meanings
   • Helps users understand performance/resource tradeoffs

2. managed / direct

   • Short and clear
   • Focuses on runtime involvement
   • Easy to remember

3. virtual / os

   • Familiar terminology (Java 21 virtual threads)
   • Short
   • Clear distinction

---

Usage Example

// Current
use spawned_concurrency::tasks::Actor;
use spawned_concurrency::threads::Actor;

// With "multiplexed/dedicated"
use spawned_concurrency::multiplexed::Actor;
use spawned_concurrency::dedicated::Actor;

// With "managed/direct"
use spawned_concurrency::managed::Actor;
use spawned_concurrency::direct::Actor;

[Oppen]

A shorter one for scheduler behavior: yield vs preemt/evict.