Merge pull request #7 from hibiken/feature/doc

Add package documentation

asynq.go

@@ -4,7 +4,7 @@ import "github.com/go-redis/redis/v7"
 
 /*
 TODOs:
-- [P0] Go docs + CONTRIBUTION.md + docs.go
+- [P0] Go docs + CONTRIBUTION.md
 - [P0] command to list each queue tasks
 - [P0] command to retry tasks from "retry", "dead" queue
 - [P1] Add Support for multiple queues and priority

background.go

@@ -11,7 +11,17 @@ import (
 	"github.com/hibiken/asynq/internal/rdb"
 )
 
-// Background is a top-level entity for the background-task processing.
+// Background is responsible for managing the background-task processing.
+//
+// Background manages background queues to process tasks and retry if
+// necessary. If the processing of a task is unsuccessful, background will
+// schedule it for a retry with an exponential backoff until either the task
+// gets processed successfully or it exhausts its max retry count.
+//
+// Once a task exhausts its retries, it will be moved to the "dead" queue and
+// will be kept in the queue for some time until a certain condition is met
+// (e.g., queue size reaches a certain limit, or the task has been in the
+// queue for a certain amount of time).
 type Background struct {
 	mu      sync.Mutex
 	running bool
@@ -21,7 +31,8 @@ type Background struct {
 	processor *processor
 }
 
-// NewBackground returns a new Background instance.
+// NewBackground returns a new Background with the specified number of workers
+// given a redis configuration .
 func NewBackground(numWorkers int, config *RedisConfig) *Background {
 	r := rdb.NewRDB(newRedisClient(config))
 	poller := newPoller(r, 5*time.Second)

client.go

@@ -7,18 +7,26 @@ import (
 	"github.com/hibiken/asynq/internal/rdb"
 )
 
-// Client is an interface for scheduling tasks.
+// A Client is responsible for scheduling tasks.
+//
+// A Client is used to register task that should be processed
+// immediately or some time in the future.
+//
+// Clients are safe for concurrent use by multiple goroutines.
 type Client struct {
 	rdb *rdb.RDB
 }
 
-// NewClient creates and returns a new client.
+// NewClient and returns a new Client given a redis configuration.
 func NewClient(config *RedisConfig) *Client {
 	r := rdb.NewRDB(newRedisClient(config))
 	return &Client{r}
 }
 
-// Process enqueues the task to be performed at a given time.
+// Process registers a task to be processed at the specified time.
+//
+// Process returns nil if the task was registered successfully,
+// otherwise returns non-nil error.
 func (c *Client) Process(task *Task, processAt time.Time) error {
 	msg := &rdb.TaskMessage{
 		ID:      uuid.New(),

doc.go

@@ -0,0 +1,47 @@
+/*
+Package asynq provides a framework for background task processing.
+
+The Client is used to register a task to be processed at the specified time.
+
+	client := asynq.NewClient(&asynq.RedisConfig{
+	    Addr: "localhost:6379",
+	})
+
+	t := &asynq.Task{
+	    Type:    "send_email",
+	    Payload: map[string]interface{}{"recipient_id": 123},
+	}
+
+	err := client.Process(t, time.Now().Add(10 * time.Minute))
+
+The Background is used to run the background processing with a given
+handler with the specified number of workers.
+    bg := asynq.NewBackground(20, &asynq.RedisConfig{
+        Addr: "localhost:6379",
+    })
+
+    bg.Run(handler)
+
+Handler is an interface that implements ProcessTask method that
+takes a Task and return an error. Handler should return nil if
+the processing is successful, otherwise return non-nil error
+so that the task will be retried after some delay.
+
+    type TaskHandler struct {
+        // ...
+    }
+
+    func (h *TaskHandler) ProcessTask(task *asynq.Task) error {
+        switch task.Type {
+        case "send_email":
+            // send email logic
+        case "generate_thumbnail":
+            // generate thumbnail image
+        //...
+        default:
+            return fmt.Errorf("unepected task type %q", task.Type)
+        }
+        return nil
+    }
+*/
+package asynq