Jcontext

.travis.yml

@@ -3,4 +3,6 @@ go:
   - 1.9
   - 1.11
   - 1.13
+  - 1.15
   - tip
+script: go test -timeout 20s ${gobuild_args} ./...

README.md

@@ -3,12 +3,11 @@ Suture
 
 [![Build Status](https://travis-ci.org/thejerf/suture.png?branch=master)](https://travis-ci.org/thejerf/suture)
 
+    import "gopkg.in/thejerf/suture.v4"
+
 Suture provides Erlang-ish supervisor trees for Go. "Supervisor trees" ->
 "sutree" -> "suture" -> holds your code together when it's trying to die.
 
-This library has hit maturity, and isn't expected to be changed
-radically. This can also be imported via gopkg.in/thejerf/suture.v2 .
-
 It is intended to deal gracefully with the real failure cases that can
 occur with supervision trees (such as burning all your CPU time endlessly
 restarting dead services), while also making no unnecessary demands on the
@@ -23,6 +22,25 @@ with [godoc](https://godoc.org/github.com/thejerf/suture),
 including an example, usage, and everything else you might expect from a
 README.md on GitHub. (DRY.)
 
+Special Thanks
+--------------
+
+Special thanks to the [Syncthing team](https://syncthing.net/), who have
+been fantastic about working with me to push fixes upstream of them.
+
+Major Versions
+--------------
+
+v4 is a rewrite to make Suture function
+with [contexts](https://golang.org/pkg/context/). If you are using suture
+for the first time, I recommend it. It also changes how logging works, to
+get a single function from the user that is presented with a defined set of
+structs, rather than requiring a number of closures from the consumer.
+
+[suture v3](https://godoc.org/gopkg.in/thejerf/suture.v3) is the latest
+version that does not feature contexts. It is still supported and getting
+backported fixes as of now.
+
 Code Signing
 ------------
 
@@ -47,8 +65,28 @@ without explicitly depending on the Suture library.
 Changelog
 ---------
 
-suture uses semantic versioning.
+suture uses semantic versioning and go modules.
 
+* 4.0:
+  * Switched the entire API to be context based.
+  * Switched how logging works to take a single closure that will be
+    presented with a defined set of structs, rather than a set of closures
+    for each event.
+  * Consequently, "Stop" removed from the Service interface. A wrapper for
+    old-style code is provided.
+  * Services can now return errors. Errors will be included in the log
+    message. Two special errors control restarting behavior:
+      * ErrDoNotRestart indicates the service should not be restarted,
+        but other services should be unaffected.
+      * ErrTerminateTree indicates the parent service tree should be
+        terminated. Supervisor trees can be configured to either continue
+        terminating upwards, or terminate themselves but not continue
+        propagating the termination upwards.
+  * UnstoppedServiceReport calling semantics modified to allow correctly
+    retrieving reports from entire trees. (Prior to 4.0, a report was
+    only on the supervisor it was called on.)
+* 3.0.4:
+  * Fix a problem with adding services to a stopped supervisor.
 * 3.0.3:
   * Implemented request in Issue #37, creating a new method StopWithReport
     on supervisors that reports what services failed to stop. While a bit

supervisor.go

@@ -370,7 +370,8 @@ Add adds a service to this supervisor.
 
 If the supervisor is currently running, the service will be started
 immediately. If the supervisor is not currently running, the service
-will be started when the supervisor is.
+will be started when the supervisor is. If the supervisor was already stopped,
+this is a no-op returning an empty service-token.
 
 The returned ServiceID may be passed to the Remove method of the Supervisor
 to terminate the service.
@@ -407,7 +408,9 @@ func (s *Supervisor) Add(service Service) ServiceToken {
 	s.Unlock()
 
 	response := make(chan serviceID)
-	s.control <- addService{service, serviceName(service), response}
+	if !s.sendControl(addService{service, serviceName(service), response}) {
+		return ServiceToken{}
+	}
 	return ServiceToken{uint64(s.id)<<32 | uint64(<-response)}
 }
 

suture_test.go

@@ -716,6 +716,29 @@ func TestEverMultistarted(t *testing.T) {
 	}
 }
 
+func TestAddAfterStopping(t *testing.T) {
+	// t.Parallel()
+
+	s := NewSimple("main")
+
+	service := NewService("A1")
+	addDone := make(chan struct{})
+
+	s.ServeBackground()
+	s.Stop()
+
+	go func() {
+		s.Add(service)
+		close(addDone)
+	}()
+
+	select {
+	case <-time.After(5 * time.Second):
+		t.Fatal("Timed out waiting for Add to return")
+	case <-addDone:
+	}
+}
+
 // A test service that can be induced to fail, panic, or hang on demand.
 func NewService(name string) *FailableService {
 	return &FailableService{name, make(chan bool), make(chan int),

v4/complete_test.go

@@ -0,0 +1,48 @@
+package suture
+
+import (
+	"context"
+	"fmt"
+	"testing"
+)
+
+const (
+	JobLimit = 2
+)
+
+type IncrementorJob struct {
+	current int
+	next    chan int
+}
+
+func (i *IncrementorJob) Serve(ctx context.Context) error {
+	for {
+		select {
+		case i.next <- i.current + 1:
+			i.current++
+			if i.current >= JobLimit {
+				fmt.Println("Stopping the service")
+				return ErrDoNotRestart
+			}
+		}
+	}
+}
+
+func TestCompleteJob(t *testing.T) {
+	supervisor := NewSimple("Supervisor")
+	service := &IncrementorJob{0, make(chan int)}
+	supervisor.Add(service)
+
+	ctx, myCancel := context.WithCancel(context.Background())
+	supervisor.ServeBackground(ctx)
+
+	fmt.Println("Got:", <-service.next)
+	fmt.Println("Got:", <-service.next)
+
+	myCancel()
+
+	// Output:
+	// Got: 1
+	// Got: 2
+	// Stopping the service
+}

v4/doc.go

@@ -0,0 +1,54 @@
+/*
+
+Package suture provides Erlang-like supervisor trees.
+
+This implements Erlang-esque supervisor trees, as adapted for Go. This is
+intended to be an industrial-strength implementation, but it has not yet
+been deployed in a hostile environment. (It's headed there, though.)
+
+Supervisor Tree -> SuTree -> suture -> holds your code together when it's
+trying to fall apart.
+
+Why use Suture?
+
+ * You want to write bullet-resistant services that will remain available
+   despite unforeseen failure.
+ * You need the code to be smart enough not to consume 100% of the CPU
+   restarting things.
+ * You want to easily compose multiple such services in one program.
+ * You want the Erlang programmers to stop lording their supervision
+   trees over you.
+
+Suture has 100% test coverage, and is golint clean. This doesn't prove it
+free of bugs, but it shows I care.
+
+A blog post describing the design decisions is available at
+https://www.jerf.org/iri/post/2930 .
+
+Using Suture
+
+To idiomatically use Suture, create a Supervisor which is your top level
+"application" supervisor. This will often occur in your program's "main"
+function.
+
+Create "Service"s, which implement the Service interface. .Add() them
+to your Supervisor. Supervisors are also services, so you can create a
+tree structure here, depending on the exact combination of restarts
+you want to create.
+
+As a special case, when adding Supervisors to Supervisors, the "sub"
+supervisor will have the "super" supervisor's Log function copied.
+This allows you to set one log function on the "top" supervisor, and
+have it propagate down to all the sub-supervisors. This also allows
+libraries or modules to provide Supervisors without having to commit
+their users to a particular logging method.
+
+Finally, as what is probably the last line of your main() function, call
+.Serve() on your top level supervisor. This will start all the services
+you've defined.
+
+See the Example for an example, using a simple service that serves out
+incrementing integers.
+
+*/
+package suture

v4/errors_after_13.go

@@ -0,0 +1,9 @@
+// +build go1.13
+
+package suture
+
+import "errors"
+
+func isErr(err error, target error) bool {
+	return errors.Is(err, target)
+}

v4/errors_before_13.go

@@ -0,0 +1,7 @@
+// +build !go1.13
+
+package suture
+
+func isErr(err error, target error) bool {
+	return err == target
+}