Socket
Socket
Sign inDemoInstall

gitee.com/pengdacn/suture

Package Overview
Dependencies
0
Maintainers
0
Alerts
File Explorer

Install Socket

Protect your apps from supply chain attacks

Install

gitee.com/pengdacn/suture

Package suture provides Erlang-like supervisor trees. This implements Erlang-esque supervisor trees, as adapted for Go. This is an industrial-strength, tested library deployed into hostile environments, not just a proof of concept or a toy. If you are reading this, you are reading the documentation for the v3 version, which is not the latest. If you want the latest v4, be sure to be using gitee.com/pengdacn/suture/v4. This rewrites the API to be in terms of contexts. Supervisor Tree -> SuTree -> suture -> holds your code together when it's trying to fall apart. Why use Suture? 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 http://www.jerf.org/iri/post/2930 . 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.

    v4.0.4+incompatible

Version published
Maintainers
0

Readme

Suture
======

[![Build Status](https://travis-ci.org/thejerf/suture.png?branch=master)](https://travis-ci.org/thejerf/suture)

    import "gitee.com/pengdacn/suture/v4"

Suture provides Erlang-ish supervisor trees for Go. "Supervisor trees" ->
"sutree" -> "suture" -> holds your code together when it's trying to die.

If you are reading this on pkg.go.dev, you should [visit the v4 docs](https://pkg.go.dev/gitee.com/pengdacn/suture/v4).

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
"service" code, and providing hooks to perform adequate logging with in a
production environment.

[A blog post describing the design decisions](http://www.jerf.org/iri/post/2930)
is available.

This module is fairly fully covered
with [godoc](https://pkg.go.dev/gitee.com/pengdacn/suture/v4)
including an example, usage, and everything else you might expect from a
README.md on GitHub. (DRY.)

v3 and before (which existed before go module support) documentation
is [also available](https://pkg.go.dev/github.com/thejerf/suture).

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
------------

Starting with the commit after ac7cf8591b, I will be signing this repository
with the ["jerf" keybase account](https://keybase.io/jerf). If you are viewing
this repository through GitHub, you should see the commits as showing as
"verified" in the commit view.

(Bear in mind that due to the nature of how git commit signing works, there
may be runs of unverified commits; what matters is that the top one is signed.)

Aspiration
----------

One of the big wins the Erlang community has with their pervasive OTP
support is that it makes it easy for them to distribute libraries that
easily fit into the OTP paradigm. It ought to someday be considered a good
idea to distribute libraries that provide some sort of supervisor tree
functionality out of the box. It is possible to provide this functionality
without explicitly depending on the Suture library.

Changelog
---------

suture uses semantic versioning and go modules.

* 4.0.2:
  * Add the ability to specify a handler for non-string panics to format
    them.
  * Fixed an issue where trying to close a currently-panicked service was
    having problems. (This may have leaked goroutines in other ways too.)
  * Merged a PR that addresses race conditions in the test suite. (These
    seem to have been isolated to the test suite and not have affected the
    core code.)
* 4.0.1:
  * Add a channel returned from ServeBackground that can be used to
    examine any error coming out of the supervisor once it is stopped.
  * Tweak up the docs to try to make it more clear suture's special
    error returns are checked via errors.Is when possible, addressing
    issue #51.
* 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
    tricky to use, see warning
    about
    [TOCTOU](https://en.wikipedia.org/wiki/Time-of-check_to_time-of-use)
    issues in the godoc, it can be useful at program tear-down time.
* 3.0.2:
  * Fixed issue #35 caused by the 3.0.1 change to panic when calling .Stop
    on an unServe()d supervisor. It needs to correctly notice that .Stop
    has been called, and not start up instead, which is the contract of the
    Service interface.
* 3.0.1:
  * Fixed issue #34: Calling supervisor.Stop() while something is trying
    to shut down a service could incorrectly report the  service failed to
    shut down.
  * Calling ".Stop()" on an unstarted supervisor now panics. This is
    superior to its previous behavior, which is hanging forever.
    This is justified by the fact that the Supervisor can't provide its
    guarantees about how services are started and stopped if it is not
    itself started and stopped correctly. Further pushing me in this
    direction is that it's fairly easy to use the Supervisor correctly.
* 3.0:
  * Added a default jitter of up to 50% on the restart intervals. While
    this is a backwards-compatible change from a source perspective, this
    does represent a non-trivial behavior change. It should generally be a
    good thing, but this is released as a major version as a warning.
* 2.0.4
  * Added option PassThroughPanics, to allow panics to propagate up through
    the supervisor.
* 2.0.3
  * Accepted PR #23, making the logging functions in the supervisor public.
  * Added a new Supervisor method RemoveAndWait, allowing you to make a
    best effort way to wait for a service to terminate.
  * Accepted PR #24, adding an optional IsCompletable interface that
    Services can implement that indicates they do not need to be restarted
    upon a normal return.
* 2.0.2
  * Fixed issue #21. gccgo doesn't like `case (<-c)`, with the parentheses.
    Of course the parens aren't doing anything useful anyhow. No behavior
    changes.
* 2.0.1
  * __Test code change only__. Addresses the possibility that one of the
    tests can spuriously fail if they run in a certain order.
* 2.0.0
  * Major version due to change to the signature of the logging methods:

    A race condition could occur when the Supervisor rendered the service
    name via fmt.Sprintf("%#v"), because fmt examines the entire object
    regardless of locks through reflection. 2.0.0 changes the supervisors
    to snapshot the Service's name once, when it is added, and to pass it
    to the logging methods.
  * Removal of use of sync/atomic due to possible brokenness in the Debian
    architecture.
* 1.1.2
  * TravisCI showed that the fix for 1.1.1 induced a deadlock in Go 1.4 and
    before.
  * If the supervisor is terminated before a service, the service goroutine
    could be orphaned trying the shutdown notification to the supervisor.
    This should no longer occur.
* 1.1.1
  * Per #14, the fix in 1.1.0 did not actually wait for the Supervisor
    to stop.
* 1.1.0
  * Per #12, Supervisor.stop now tries to wait for its children before
    returning. A careful reading of the original .Stop() contract
    says this is the correct behavior.
* 1.0.1
  * Fixed data race on the .state variable.
* 1.0.0
  * Initial release.

FAQs

Last updated on 04 Mar 2022

Did you know?

Socket installs a GitHub app to automatically flag issues on every pull request and report the health of your dependencies. Find out what is inside your node modules and prevent malicious activity before you update the dependencies.

Install

Related posts

SocketSocket SOC 2 Logo

Product

  • Package Alerts
  • Integrations
  • Docs
  • Pricing
  • FAQ
  • Roadmap

Stay in touch

Get open source security insights delivered straight into your inbox.


  • Terms
  • Privacy
  • Security

Made with ⚡️ by Socket Inc