From d8a8452961316e88ad8cdcb441d5c13d77499f2e Mon Sep 17 00:00:00 2001
From: stephen mcquay <stephen@mcquay.me>
Date: Sun, 4 Oct 2015 15:47:24 -0700
Subject: [PATCH] Added NewPrecise and changed New to be simpler

---
 bps.go      | 40 +++++++++++++++++++++++++++-------------
 bps_test.go | 10 +++++-----
 readme.md   |  4 ++--
 3 files changed, 34 insertions(+), 20 deletions(-)

diff --git a/bps.go b/bps.go
index 18c1f44..250ada9 100644
--- a/bps.go
+++ b/bps.go
@@ -1,5 +1,4 @@
-// Package bps is a simple tool for keeping track of the rate of bytes
-// transmitted
+// Package bps keeps track of byte rates
 package bps
 
 import (
@@ -13,11 +12,12 @@ const (
 	minResolution = 3
 )
 
-// BPS keeps track of state for byte counts
+// BPS calculates bandwith rates.
 //
-// Instantiate a BPS then feed bytes either via BPS.Add, or writing to it. When
-// the accumulated values are needed call BPS.Cur. When the BPS is no loner
-// needed call BPS.Close
+// Instantiate a BPS using one of the New* functions then feed bytes either via
+// BPS.Add, or writing to it (it implements io.Writer). When the accumulated
+// values are needed call BPS.Rate. When the BPS is no loner needed call
+// BPS.Close
 type BPS struct {
 	sync.RWMutex
 
@@ -37,15 +37,29 @@ type BPS struct {
 	timeI int
 }
 
-// New Returns a populated and ready to use BPS. interval is the amount of time
-// (for example 60 seconds) over which to track byte flow (bytes/second for the
-// last interval), and resolution is used in the following calculation:
+// New Returns a populated and ready to use BPS.
 //
-// dt = interval / resolution (s)
+// bytes per second are reported for the last time interval (defined by
+// interval), and is updated every (interval / 100) seconds.
+func New(interval time.Duration) (*BPS, error) {
+	return NewPrecise(interval, 100)
+}
+
+// MustNew behaves like New, but panics on error.
+func MustNew(interval time.Duration) *BPS {
+	b, err := New(interval)
+	if err != nil {
+		panic(err)
+	}
+	return b
+}
+
+// NewPrecise behaves like New, but allows the user to specify the temporal
+// resolution.
 //
-// where the dt is the temporal resolution of the updates (add or remove
-// information every dt).
-func New(interval time.Duration, resolution uint) (*BPS, error) {
+// If you need to query more or less frequently than interval / 100 you'll want
+// to use this function.
+func NewPrecise(interval time.Duration, resolution uint) (*BPS, error) {
 	if resolution < minResolution {
 		return nil, fmt.Errorf("resolution must be larger than %d", minResolution)
 	}
diff --git a/bps_test.go b/bps_test.go
index 836b89f..25e6a96 100644
--- a/bps_test.go
+++ b/bps_test.go
@@ -13,7 +13,7 @@ func init() {
 }
 
 func TestSimple(t *testing.T) {
-	bw, err := New(1*time.Second, 100)
+	bw, err := New(1 * time.Second)
 	if err != nil {
 		t.Fatalf("failure to make reasonable BPS: %v", err)
 	}
@@ -21,7 +21,7 @@ func TestSimple(t *testing.T) {
 }
 
 func TestBadResolution(t *testing.T) {
-	_, err := New(1*time.Hour, 1)
+	_, err := New(1 * time.Hour)
 	if err == nil {
 		t.Fatal("expected an error, got nil")
 	}
@@ -29,7 +29,7 @@ func TestBadResolution(t *testing.T) {
 
 func TestWriter(t *testing.T) {
 	t.Parallel()
-	bw, err := New(1*time.Second, 100)
+	bw, err := New(1 * time.Second)
 	if err != nil {
 		t.Fatalf("failure to make reasonable BPS: %v", err)
 	}
@@ -55,7 +55,7 @@ func TestWriter(t *testing.T) {
 
 func TestAdd(t *testing.T) {
 	t.Parallel()
-	bw, err := New(1*time.Second, 100)
+	bw, err := New(1 * time.Second)
 	if err != nil {
 		t.Fatalf("failure to make reasonable BPS: %v", err)
 	}
@@ -79,7 +79,7 @@ func TestAdd(t *testing.T) {
 
 func TestHumanBytes(t *testing.T) {
 	t.Parallel()
-	bw, err := New(100*time.Second, 10)
+	bw, err := NewPrecise(100*time.Second, 10)
 	if err != nil {
 		t.Fatalf("failure to make reasonable BPS: %v", err)
 	}
diff --git a/readme.md b/readme.md
index 3a53b16..0efbdfb 100644
--- a/readme.md
+++ b/readme.md
@@ -1,11 +1,11 @@
 # bps
 
-`bps` is used to keep track of rates
+`bps` is used to keep track of bandwidth rates
 
 It is intended to be used as such:
 
     // report on the rate over a 60 second interval, update every second
-	bw, _ := New(60*time.Second, 60)
+	bw, _ := New(60*time.Second)
 	bw.Add(10)
 	b := &bytes.Buffer{}
 	b.Write([]byte("helloooooooooooooooooooooooooooooooooooooooooooooo"))