From c51c4cb64569c0d3df0012a229c911bddc100418 Mon Sep 17 00:00:00 2001
From: Jeremy Tregunna <jeremy@tregunna.ca>
Date: Thu, 17 Apr 2025 21:56:47 -0600
Subject: [PATCH] chore: add a README

---
 README.md | 137 ++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 137 insertions(+)
 create mode 100644 README.md

diff --git a/README.md b/README.md
new file mode 100644
index 0000000..ccbf032
--- /dev/null
+++ b/README.md
@@ -0,0 +1,137 @@
+# Task
+
+A simple and efficient scheduled task execution library for Go applications.
+
+## Overview
+
+The Task library provides a lightweight mechanism for scheduling and executing tasks with configurable intervals and rate limiting. It's particularly useful for applications that need to run background jobs, periodic maintenance tasks, or any recurring operations.
+
+## Features
+
+- Schedule tasks to run at regular intervals
+- Rate limiting to control concurrent task execution
+- Run tasks immediately (zero interval)
+- Simple interface-based design for easy integration
+
+## Installation
+
+```
+go get git.canoozie.net/jer/task
+```
+
+## Usage
+
+### Basic Example
+
+```go
+package main
+
+import (
+	"fmt"
+	"time"
+
+	"git.canoozie.net/jer/task"
+)
+
+// Define a task by implementing the Task interface
+type MyTask struct {
+	Name string
+}
+
+func (t *MyTask) Execute() error {
+	fmt.Printf("Executing task: %s\n", t.Name)
+	return nil
+}
+
+func main() {
+	// Create a task executor with a rate limit of 2 concurrent tasks
+	executor := task.NewTaskExecutor(2)
+
+	// Add tasks with different intervals
+	executor.AddTask(&MyTask{Name: "Every Second"}, 1*time.Second)
+	executor.AddTask(&MyTask{Name: "Every 5 Seconds"}, 5*time.Second)
+	executor.AddTask(&MyTask{Name: "Run Once Now"}, 0*time.Second)
+
+	// Start the task executor
+	executor.Start()
+
+	// Keep the program running
+	select {}
+}
+```
+
+### Rate Limiting
+
+The task executor includes built-in rate limiting to control how many tasks can run concurrently. This is useful for resource-intensive tasks or when you need to limit API calls.
+
+```go
+// Create an executor that allows up to 5 concurrent tasks
+executor := task.NewTaskExecutor(5)
+```
+
+### Task Interface
+
+To create a task, implement the `Task` interface:
+
+```go
+type Task interface {
+	Execute() error
+}
+```
+
+Any errors returned from `Execute()` will be logged but will not prevent future executions.
+
+## API Reference
+
+### Types
+
+#### `Task`
+```go
+type Task interface {
+	Execute() error
+}
+```
+
+### Functions
+
+#### `NewTaskExecutor`
+```go
+func NewTaskExecutor(rateLimit int) *TaskExecutor
+```
+Creates a new task executor with the specified concurrency limit.
+
+### Methods
+
+#### `AddTask`
+```go
+func (te *TaskExecutor) AddTask(task Task, interval time.Duration)
+```
+Schedules a task to run at the specified interval. If interval is 0, the task is executed immediately. Negative intervals are ignored.
+
+#### `Start`
+```go
+func (te *TaskExecutor) Start()
+```
+Starts the task executor, which will begin processing scheduled tasks.
+
+#### `Len`
+```go
+func (te *TaskExecutor) Len() int
+```
+Returns the number of tasks managed by the executor.
+
+## License
+
+Copyright (C) 2025 Jeremy Tregunna
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.