# workit

simple single-threaded work queueing utility for rust

`workit` is a simple way to queue a task in a Rust project to be executed later.
It is designed for projects that do not want to implement an async runtime like
tokio, and may find a home in projects handling streams of data that may exhibit
burst behavior.

# Concept

The fundamental interface targets single-threaded projects: you queue up
closures that `workit` can take ownership of (in practice, you often use
`Arc<Mutex<T>>` with it), then every so often, when your process can spare some
cycles, you call `do_work()` and pass in an amount of time. `workit` will do a
task, check if the time has elapsed yet, if not, do another, etc.

Specifically, passed functions must be `FnMut() + Send` and return solely a
boolean indicating whether the task succeeded or failed.

You can customize how many times (at most) a task should be attempted, and how
long to wait in between reattempts of the same task if it fails.

`workit` is fully thread-safe, operates with a single global queue in the
background, and can actually be used in any context (but if you intend to spawn
multiple threads to process work and are willing to use an async runtime, you
should probably use a modern work-stealing queueing library etc. instead).

# Usage

```rust
workit::enqueue(|| {
  // one-shot task
  true
}, 1, None);

workit::enqueue(|| {
  // retryable task
  true
}, 5, Some(Duration::from_secs(1)));

// Work for 5 seconds, or until all queued work is either done or in cooldown
let status = workit::do_work(Duration::from_secs(5));

// Optionally, inspect status and act on it somehow
match status {
  QueueStatus::Empty => {},
  QueueStatus::WorkPending(len) => {
    // do something
  }
  QueueStatus::InCooldown(len) => {
    // do something else
  }
}
```

# Examples

See the tests within `src/lib.rs` for some additional abstract usage examples.