fix #13: refactor tests and docs

Author: kamilsk

Makefile

@@ -144,6 +144,10 @@ test-quick:
 	@go test -timeout $(TIMEOUT) $(PACKAGES)
 .PHONY: test-quick
 
+test-verbose:
+	@go test -race -timeout $(TIMEOUT) -v $(PACKAGES)
+.PHONY: test-verbose
+
 test-with-coverage:
 	@go test \
 		-cover \

README.md

@@ -46,64 +46,18 @@ if err := semaphore.Acquire(breaker.BreakByTimeout(time.Minute), 5); err != nil
 }
 ```
 
-more consistent and reliable.
+more consistent and reliable. Additionally, I want to implement a Graceful Shutdown
+and Circuit Breaker on the same mechanism.
 
 ## 🤼‍♂️ How to
 
-```go
-import (
-	"bytes"
-	"context"
-	"fmt"
-	"io"
-	"net/http"
-	"os"
-	"time"
-
-	"github.com/kamilsk/breaker"
-)
-
-var NewYear = time.Time{}.AddDate(time.Now().Year(), 0, 0)
+### Do HTTP request with retries
 
-func Handle(rw http.ResponseWriter, req *http.Request) {
-	ctx, cancel := context.WithCancel(req.Context())
-	defer cancel()
-
-	deadline, _ := time.ParseDuration(req.Header.Get("X-Timeout"))
-	interrupter := breaker.Multiplex(
-		breaker.BreakByContext(context.WithTimeout(ctx, deadline)),
-		breaker.BreakByDeadline(NewYear),
-		breaker.BreakBySignal(os.Interrupt),
-	)
-	defer interrupter.Close()
-
-	buf, work := bytes.NewBuffer(nil), Work(ctx, struct{}{})
-	for {
-		select {
-		case b, ok := <-work:
-			if !ok {
-				rw.WriteHeader(http.StatusOK)
-				io.Copy(rw, buf)
-				return
-			}
-			buf.WriteByte(b)
-		case <-interrupter.Done():
-			rw.WriteHeader(http.StatusPartialContent)
-			rw.Header().Set("Content-Range", fmt.Sprintf("bytes=0-%d", buf.Len()))
-			io.Copy(rw, buf)
-			return
-		}
-	}
-}
-
-func Work(ctx context.Context, _ struct{}) <-chan byte {
-	outcome := make(chan byte, 1)
+...
 
-	go func() { ... }()
+### Graceful Shutdown HTTP server
 
-	return outcome
-}
-```
+...
 
 ## 🧩 Integration
 
@@ -115,6 +69,30 @@ You can use [go modules](https://github.com/golang/go/wiki/Modules) to manage it
 $ go get github.com/kamilsk/breaker@latest
 ```
 
+## 🤲 Outcomes
+
+### Console tool to execute commands for a limited time
+
+The example shows how to execute console commands for ten minutes.
+
+```bash
+$ date
+# Thu Jan  7 21:02:21
+$ breakit after 10m -- database run --port=5432
+$ breakit after 10m -- server run --port=8080
+$ breakit ps
+# +--------------------------+---------------------+
+# | Process                  | Done                |
+# +--------------------------+---------------------+
+# | database run --port=5432 | Thu Jan  7 21:12:24 |
+# | server run --port=8080   | Thu Jan  7 21:12:31 |
+# +--------------------------+---------------------+
+# |                    Total |                   2 |
+# +--------------------------+---------------------+
+```
+
+See more details [here][cli].
+
 ---
 
 made with ❤️ for everyone
@@ -137,5 +115,6 @@ made with ❤️ for everyone
 [awesome.page]:     https://github.com/avelino/awesome-go#goroutines
 [awesome.icon]:     https://cdn.rawgit.com/sindresorhus/awesome/d7305f38d29fed78fa85652e3a63e154dd8e8829/media/badge.svg
 
+[cli]:              https://github.com/octolab/breakit
 [retry]:            https://github.com/kamilsk/retry
 [semaphore]:        https://github.com/kamilsk/semaphore

breaker.go

@@ -10,53 +10,104 @@ import (
 	"time"
 )
 
-// New returns a new Breaker which can interrupted only by the Close call.
+// New returns a new breaker, which can be interrupted only by a Close call.
+//
+//  interrupter := breaker.New()
+//  go background.Job().Do(interrupter)
+//
+//  <-time.After(time.Minute)
+//  interrupter.Close()
+//
 func New() Interface {
 	return newBreaker().trigger()
 }
 
-// BreakByChannel returns a new Breaker based on the channel.
-func BreakByChannel(ch <-chan struct{}) Interface {
-	return (&channelBreaker{newBreaker(), ch}).trigger()
+// BreakByChannel returns a new breaker based on the channel.
+//
+//  signal := make(chan struct{})
+//  go func() {
+//  	<-time.After(time.Minute)
+//  	close(signal)
+//  }()
+//
+//  interrupter := breaker.BreakByChannel(signal)
+//  defer interrupter.Close()
+//
+//  background.Job().Do(interrupter)
+//
+func BreakByChannel(signal <-chan struct{}) Interface {
+	return (&channelBreaker{newBreaker(), signal}).trigger()
 }
 
-// BreakByContext returns a new Breaker based on the Context.
+// BreakByContext returns a new breaker based on the Context.
 //
-//  interrupter := breaker.BreakByContext(context.WithTimeout(req.Context(), time.Minute)),
+//  interrupter := breaker.BreakByContext(context.WithTimeout(req.Context(), time.Minute))
 //  defer interrupter.Close()
 //
 //  background.Job().Do(interrupter)
 //
 func BreakByContext(ctx context.Context, cancel context.CancelFunc) Interface {
-	return &contextBreaker{ctx, cancel}
+	return (&contextBreaker{ctx, cancel}).trigger()
 }
 
 // BreakByDeadline closes the Done channel when the deadline occurs.
+//
+//  interrupter := breaker.BreakByDeadline(time.Now().Add(time.Minute))
+//  defer interrupter.Close()
+//
+//  background.Job().Do(interrupter)
+//
 func BreakByDeadline(deadline time.Time) Interface {
 	timeout := time.Until(deadline)
 	if timeout < 0 {
 		return closedBreaker()
 	}
-	return newTimedBreaker(timeout).trigger()
+	return newTimeoutBreaker(timeout).trigger()
 }
 
-// BreakBySignal closes the Done channel when signals will be received.
+// BreakBySignal closes the Done channel when the breaker will receive OS signals.
+//
+//  interrupter := breaker.BreakBySignal(os.Interrupt)
+//  defer interrupter.Close()
+//
+//  background.Job().Do(interrupter)
+//
 func BreakBySignal(sig ...os.Signal) Interface {
 	if len(sig) == 0 {
 		return closedBreaker()
 	}
-	return newSignaledBreaker(sig).trigger()
+	return newSignalBreaker(sig).trigger()
 }
 
 // BreakByTimeout closes the Done channel when the timeout happens.
+//
+//  interrupter := breaker.BreakByTimeout(time.Minute)
+//  defer interrupter.Close()
+//
+//  background.Job().Do(interrupter)
+//
 func BreakByTimeout(timeout time.Duration) Interface {
 	if timeout < 0 {
 		return closedBreaker()
 	}
-	return newTimedBreaker(timeout).trigger()
+	return newTimeoutBreaker(timeout).trigger()
 }
 
-// ToContext converts the Breaker into the Context.
+// ToContext converts the breaker into the Context.
+//
+//  interrupter := breaker.Multiplex(
+//  	breaker.BreakBySignal(os.Interrupt),
+//  	breaker.BreakByTimeout(time.Minute),
+//  )
+//  defer interrupter.Close()
+//
+//  request, err := http.NewRequestWithContext(breaker.ToContext(interrupter), ...)
+//  if err != nil { handle(err) }
+//
+//  response, err := http.DefaultClient.Do(request)
+//  if err != nil { handle(err) }
+//  handle(response)
+//
 func ToContext(br Interface) context.Context {
 	ctx, cancel := context.WithCancel(context.Background())
 	go func() {
@@ -104,7 +155,7 @@ func (br *breaker) Err() error {
 	return nil
 }
 
-// IsReleased returns true if resources associated with the Breaker were released.
+// IsReleased returns true if resources associated with the breaker were released.
 func (br *breaker) IsReleased() bool {
 	return atomic.LoadInt32(&br.released) == 1
 }
@@ -125,7 +176,7 @@ func (br *channelBreaker) Close() {
 	})
 }
 
-// trigger starts listening internal signal to close the Done channel.
+// trigger starts listening to the internal signal to close the Done channel.
 func (br *channelBreaker) trigger() Interface {
 	go func() {
 		select {
@@ -150,7 +201,7 @@ func (br *contextBreaker) Close() {
 	br.cancel()
 }
 
-// IsReleased returns true if resources associated with the Breaker were released.
+// IsReleased returns true if resources associated with the breaker were released.
 func (br *contextBreaker) IsReleased() bool {
 	select {
 	case <-br.Done():
@@ -164,7 +215,7 @@ func (br *contextBreaker) trigger() Interface {
 	return br
 }
 
-func newSignaledBreaker(signals []os.Signal) *signalBreaker {
+func newSignalBreaker(signals []os.Signal) *signalBreaker {
 	return &signalBreaker{newBreaker(), make(chan os.Signal, len(signals)), signals}
 }
 
@@ -182,7 +233,7 @@ func (br *signalBreaker) Close() {
 	})
 }
 
-// trigger starts listening required signals to close the Done channel.
+// trigger starts listening to the required signals to close the Done channel.
 func (br *signalBreaker) trigger() Interface {
 	go func() {
 		signal.Notify(br.relay, br.signals...)
@@ -198,7 +249,7 @@ func (br *signalBreaker) trigger() Interface {
 	return br
 }
 
-func newTimedBreaker(timeout time.Duration) *timeoutBreaker {
+func newTimeoutBreaker(timeout time.Duration) *timeoutBreaker {
 	return &timeoutBreaker{newBreaker(), time.NewTimer(timeout)}
 }
 
@@ -215,7 +266,7 @@ func (br *timeoutBreaker) Close() {
 	})
 }
 
-// trigger starts listening internal timer to close the Done channel.
+// trigger starts listening to the internal timer to close the Done channel.
 func (br *timeoutBreaker) trigger() Interface {
 	go func() {
 		select {