added more docs. Changed package name to redisqueue to polute the namespace less for apps that want to use "queue"

Author: ssoroka

README.markdown

@@ -21,15 +21,15 @@ This is a redis-based queue for usage in Go. I evaluated a lot of other options
 Adding jobs to a queue.
 
 ```
-import "github.com/AgileBits/go-redis-queue/queue"
+import "github.com/AgileBits/go-redis-queue/redisqueue"
 ```
 
 ```
 c, err := redis.Dial("tcp", "127.0.0.1:6379")
 if err != nil { ... }
 defer c.Close()
 
-q := queue.New("some_queue_name", c)
+q := redisqueue.New("some_queue_name", c)
 
 wasAdded, err := q.Push("basic item")
 if err != nil { ... }
@@ -47,7 +47,7 @@ c, err := redis.Dial("tcp", "127.0.0.1:6379")
 if err != nil { ... }
 defer c.Close()
 
-q := queue.New("some_queue_name", c)
+q := redisqueue.New("some_queue_name", c)
 
 for !timeToQuit {
   job, err = q.Pop()
@@ -66,7 +66,7 @@ c, err := redis.Dial("tcp", "127.0.0.1:6379")
 if err != nil { ... }
 defer c.Close()
 
-q := queue.New("some_queue_name", c)
+q := redisqueue.New("some_queue_name", c)
 
 for !timeToQuit {
   jobs, err := q.PopJobs(100) // argument is "limit"
@@ -84,4 +84,5 @@ for !timeToQuit {
 ## Requirements
 
 - Redis 2.6.0 or greater
+- github.com/garyburd/redigo/redis
 - Go

queue/queue.go renamed to redisqueue/queue.go

@@ -1,4 +1,4 @@
-package queue
+package redisqueue
 
 import (
 	"fmt"
@@ -8,22 +8,26 @@ import (
 	"github.com/garyburd/redigo/redis"
 )
 
+// Queue holds a reference to a redis connection and a queue name.
 type Queue struct {
 	c    redis.Conn
 	Name string
 }
 
+// New defines a new Queue
 func New(queueName string, c redis.Conn) *Queue {
 	return &Queue{
 		c:    c,
 		Name: queueName,
 	}
 }
 
+// Push pushes a single job on to the queue. The job string can be any format, as the queue doesn't really care.
 func (q *Queue) Push(job string) (bool, error) {
 	return q.Schedule(job, time.Now())
 }
 
+// Schedule schedule a job at some point in the future, or some point in the past. Scheduling a job far in the past is the same as giving it a high priority, as jobs are popped in order of due date.
 func (q *Queue) Schedule(job string, when time.Time) (bool, error) {
 	score := when.UnixNano()
 	added, err := redis.Bool(q.c.Do("ZADD", q.Name, score, job))
@@ -32,15 +36,18 @@ func (q *Queue) Schedule(job string, when time.Time) (bool, error) {
 
 }
 
+// Pending returns the count of jobs pending, including scheduled jobs that are not due yet.
 func (q *Queue) Pending() (int64, error) {
 	return redis.Int64(q.c.Do("ZCARD", q.Name))
 }
 
+// FlushQueue removes everything from the queue. Useful for testing.
 func (q *Queue) FlushQueue() error {
 	_, err := q.c.Do("DEL", q.Name)
 	return err
 }
 
+// Pop removes and returns a single job from the queue. Safe for concurrent use (multiple goroutines must use their own Queue objects and redis connections)
 func (q *Queue) Pop() (string, error) {
 	jobs, err := q.PopJobs(1)
 	if err != nil {
@@ -52,25 +59,11 @@ func (q *Queue) Pop() (string, error) {
 	return jobs[0], nil
 }
 
+// PopJobs returns multiple jobs from the queue. Safe for concurrent use (multiple goroutines must use their own Queue objects and redis connections)
 func (q *Queue) PopJobs(limit int) ([]string, error) {
 	return redis.Strings(popJobsScript.Do(q.c, q.Name, fmt.Sprintf("%d", time.Now().UnixNano()), strconv.Itoa(limit)))
 }
 
-// func (q *Queue) PopJobs(limit int) ([]string, error) {
-// 	jobs, err := redis.Strings(q.c.Do("ZRANGEBYSCORE", q.Name, "-inf", time.Now().UnixNano(), "LIMIT", 0, limit))
-// 	if err != nil {
-// 		return jobs, err
-// 	}
-//
-//   if len(jobs) > 0 {
-//     _, err = q.c.Do("ZREM", q.Name, quoteArgs(jobs))
-//     if err != nil {
-//       return []string{}, err
-//     }
-//   }
-// 	return jobs, nil
-// }
-//
 func quoteArgs(args []string) string {
 	result := ""
 	for i := range args {

queue/queue_test.go renamed to redisqueue/queue_test.go

@@ -1,10 +1,10 @@
-package queue_test
+package redisqueue_test
 
 import (
 	"testing"
 	"time"
 
-	"github.com/AgileBits/go-redis-queue/queue"
+	"github.com/AgileBits/go-redis-queue/redisqueue"
 	"github.com/garyburd/redigo/redis"
 )
 
@@ -16,7 +16,7 @@ func TestQueueTasks(t *testing.T) {
 	}
 	defer c.Close()
 
-	q := queue.New("basic_queue", c)
+	q := redisqueue.New("basic_queue", c)
 
 	err = q.FlushQueue()
 	if err != nil {
@@ -62,7 +62,7 @@ func TestQueueTaskScheduling(t *testing.T) {
 	}
 	defer c.Close()
 
-	q := queue.New("scheduled_queue", c)
+	q := redisqueue.New("scheduled_queue", c)
 
 	err = q.FlushQueue()
 	if err != nil {
@@ -121,7 +121,7 @@ func TestPopOrder(t *testing.T) {
 	}
 	defer c.Close()
 
-	q := queue.New("scheduled_queue", c)
+	q := redisqueue.New("scheduled_queue", c)
 
 	err = q.FlushQueue()
 	if err != nil {
@@ -195,7 +195,7 @@ func TestPopMultiOrder(t *testing.T) {
 	}
 	defer c.Close()
 
-	q := queue.New("scheduled_queue", c)
+	q := redisqueue.New("scheduled_queue", c)
 
 	err = q.FlushQueue()
 	if err != nil {

queue/scripts.go renamed to redisqueue/scripts.go

@@ -1,4 +1,4 @@
-package queue
+package redisqueue
 
 import "github.com/garyburd/redigo/redis"