From 8205e8b42ae12f8092b0fa24a35924d0b7286c18 Mon Sep 17 00:00:00 2001
From: louyuting <1849491904@qq.com>
Date: Mon, 7 Sep 2020 22:37:52 +0800
Subject: [PATCH] add doc.go for flow and circuit breaker
---
api/doc.go | 2 +-
core/circuitbreaker/doc.go | 113 +++++++++++++++++++++++++++++++++++++
core/flow/doc.go | 3 +
3 files changed, 117 insertions(+), 1 deletion(-)
create mode 100644 core/circuitbreaker/doc.go
create mode 100644 core/flow/doc.go
diff --git a/api/doc.go b/api/doc.go
index 7da157955..04418ed14 100644
--- a/api/doc.go
+++ b/api/doc.go
@@ -6,7 +6,7 @@
// 2. api.InitWithConfig(confEntity *config.Entity), using customized config Entity to initialize
// 3. api.InitWithConfigFile(configPath string), using yaml file to initialize.
//
-// Here is the example code to use sentinel.
+// Here is the example code to use sentinel:
//
// import sentinel "github.com/alibaba/sentinel-golang/api"
//
diff --git a/core/circuitbreaker/doc.go b/core/circuitbreaker/doc.go
new file mode 100644
index 000000000..dd351551e
--- /dev/null
+++ b/core/circuitbreaker/doc.go
@@ -0,0 +1,113 @@
+// Package circuitbreaker implements the circuit breaker.
+//
+// Sentinel circuit breaker module converts each Rule into a CircuitBreaker. Each CircuitBreaker has its own statistical structure.
+//
+// Sentinel circuit breaker module supports three strategies:
+//
+// 1. SlowRequestRatio: the ratio of slow response time entry(entry's response time is great than max slow response time) exceeds the threshold. The following entry to resource will be broken.
+// In SlowRequestRatio strategy, user must set max response time.
+// 2. ErrorRatio: the ratio of error entry exceeds the threshold. The following entry to resource will be broken.
+// 3. ErrorCount: the number of error entry exceeds the threshold. The following entry to resource will be broken.
+//
+// Sentinel circuit breaker is implemented based on state machines. There are three state:
+//
+// 1. Closed: all entries could pass checking;
+// 2. Open: the circuit breaker is broken, all entries are blocked. After retry timeout, circuit breaker switches state to Half-Open and allows one entry to probe whether the resource returns to its expected state;
+// 3. Half-Open: the circuit breaker is in a temporary state of probing, only one entry is allowed to access resource, others are blocked.
+//
+// Sentinel circuit breaker provides the listener to listen on the state changes.
+//
+// type StateChangeListener interface {
+// OnTransformToClosed(prev State, rule Rule)
+//
+// OnTransformToOpen(prev State, rule Rule, snapshot interface{})
+//
+// OnTransformToHalfOpen(prev State, rule Rule)
+// }
+//
+// Here is the example code to use circuit breaker:
+//
+// type stateChangeTestListener struct {}
+//
+// func (s *stateChangeTestListener) OnTransformToClosed(prev circuitbreaker.State, rule circuitbreaker.Rule) {
+// fmt.Printf("rule.steategy: %+v, From %s to Closed, time: %d\n", rule.Strategy, prev.String(), util.CurrentTimeMillis())
+// }
+//
+// func (s *stateChangeTestListener) OnTransformToOpen(prev circuitbreaker.State, rule circuitbreaker.Rule, snapshot interface{}) {
+// fmt.Printf("rule.steategy: %+v, From %s to Open, snapshot: %.2f, time: %d\n", rule.Strategy, prev.String(), snapshot, util.CurrentTimeMillis())
+// }
+//
+// func (s *stateChangeTestListener) OnTransformToHalfOpen(prev circuitbreaker.State, rule circuitbreaker.Rule) {
+// fmt.Printf("rule.steategy: %+v, From %s to Half-Open, time: %d\n", rule.Strategy, prev.String(), util.CurrentTimeMillis())
+// }
+//
+// func main() {
+// err := sentinel.InitDefault()
+// if err != nil {
+// log.Fatal(err)
+// }
+// ch := make(chan struct{})
+// // Register a state change listener so that we could observer the state change of the internal circuit breaker.
+// circuitbreaker.RegisterStateChangeListeners(&stateChangeTestListener{})
+//
+// _, err = circuitbreaker.LoadRules([]*circuitbreaker.Rule{
+// // Statistic time span=10s, recoveryTimeout=3s, slowRtUpperBound=50ms, maxSlowRequestRatio=50%
+// {
+// Resource: "abc",
+// Strategy: circuitbreaker.SlowRequestRatio,
+// RetryTimeoutMs: 3000,
+// MinRequestAmount: 10,
+// StatIntervalMs: 10000,
+// MaxAllowedRtMs: 50,
+// Threshold: 0.5,
+// },
+// // Statistic time span=10s, recoveryTimeout=3s, maxErrorRatio=50%
+// {
+// Resource: "abc",
+// Strategy: circuitbreaker.ErrorRatio,
+// RetryTimeoutMs: 3000,
+// MinRequestAmount: 10,
+// StatIntervalMs: 10000,
+// Threshold: 0.5,
+// },
+// })
+// if err != nil {
+// log.Fatal(err)
+// }
+//
+// fmt.Println("Sentinel Go circuit breaking demo is running. You may see the pass/block metric in the metric log.")
+// go func() {
+// for {
+// e, b := sentinel.Entry("abc")
+// if b != nil {
+// //fmt.Println("g1blocked")
+// time.Sleep(time.Duration(rand.Uint64()%20) * time.Millisecond)
+// } else {
+// if rand.Uint64()%20 > 9 {
+// // Record current invocation as error.
+// sentinel.TraceError(e, errors.New("biz error"))
+// }
+// //fmt.Println("g1passed")
+// time.Sleep(time.Duration(rand.Uint64()%80+10) * time.Millisecond)
+// e.Exit()
+// }
+// }
+// }()
+//
+// go func() {
+// for {
+// e, b := sentinel.Entry("abc")
+// if b != nil {
+// //fmt.Println("g2blocked")
+// time.Sleep(time.Duration(rand.Uint64()%20) * time.Millisecond)
+// } else {
+// //fmt.Println("g2passed")
+// time.Sleep(time.Duration(rand.Uint64()%80) * time.Millisecond)
+// e.Exit()
+// }
+// }
+// }()
+// <-ch
+// }
+//
+package circuitbreaker
diff --git a/core/flow/doc.go b/core/flow/doc.go
new file mode 100644
index 000000000..d5afe54dc
--- /dev/null
+++ b/core/flow/doc.go
@@ -0,0 +1,3 @@
+// Package flow implements the flow shaping control.
+//
+package flow