Example

breaker/README.md

@@ -1,4 +1,30 @@
 circuit-breaker
 ===============
 
-The circuit-breaker resiliency pattern for golang
+The circuit-breaker resiliency pattern for golang.
+
+Creating a breaker takes three parameters:
+- error threshold (for opening the breaker)
+- success threshold (for closing the breaker)
+- timeout (how long to keep the breaker open)
+
+```golang
+breaker := breaker.New(3, 1, 5*time.Second)
+
+for {
+	result := breaker.Run(func() error {
+		// communicate with some external service and
+		// return an error if the communication failed
+		return nil
+	})
+
+	switch result {
+	case nil:
+		// success!
+	case BreakerOpen:
+		// our function wasn't run because the breaker was open
+	default:
+		// some other error
+	}
+}
+```

breaker/breaker_test.go

@@ -76,3 +76,24 @@ func TestBreakerStateTransitions(t *testing.T) {
 		t.Error(err)
 	}
 }
+
+func ExampleBreaker() {
+	breaker := New(3, 1, 5*time.Second)
+
+	for {
+		result := breaker.Run(func() error {
+			// communicate with some external service and
+			// return an error if the communication failed
+			return nil
+		})
+
+		switch result {
+		case nil:
+			// success!
+		case BreakerOpen:
+			// our function wasn't run because the breaker was open
+		default:
+			// some other error
+		}
+	}
+}