Initial commit

go-kata · Jan 24, 2021 · e273076 · e273076
commit e273076
Show file tree

Hide file tree

Showing 8 changed files with 350 additions and 0 deletions.
diff --git a/.gitignore b/.gitignore
@@ -0,0 +1 @@
+/.idea/
diff --git a/LICENSE b/LICENSE
@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2021 Alexey A Maximov
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
diff --git a/README.md b/README.md
@@ -0,0 +1,19 @@
+# KDone [![GoDoc](https://godoc.org/github.com/go-kata/kdone?status.svg)](https://godoc.org/github.com/go-kata/kdone)
+
+Published under the MIT licence.
+
+This repository provides Golang tools for destroying objects.
+
+See the documentation by reference above for information about packages.
+
+## Installation
+
+`go get github.com/go-kata/kdone`
+
+## Versioning convention
+
+**This is a beta version.** API is not stabilized for now.
+
+*Till the first major release* minor version (`v0.x.0`) must be treated as a major version and patch version (`v0.0.x`) must be treated as a minor version.
+
+For example, changing of version from `v0.1.0` to `v0.1.1` indicates compatible changes, but when version changes `v0.1.1` to `v0.2.0` this means that the last version breaks the API.
diff --git a/destructor.go b/destructor.go
@@ -0,0 +1,31 @@
+package kdone
+
+// Destructor represents an object destructor.
+//
+// The usual identifier for variables of this type is dtor.
+type Destructor interface {
+	// DestroyStack destroys an associated object.
+	Destroy() error
+	// MustDestroy is a variant of the Destroy that panics on error.
+	MustDestroy()
+}
+
+// DestructorFunc represents a functional object destructor.
+type DestructorFunc func() error
+
+// Destroy implements the Destructor interface.
+func (f DestructorFunc) Destroy() error {
+	return f()
+}
+
+// MustDestroy implements the Destructor interface.
+func (f DestructorFunc) MustDestroy() {
+	if err := f(); err != nil {
+		panic(err)
+	}
+}
+
+// Noop specifies the destructor which does nothing.
+var Noop = DestructorFunc(func() error {
+	return nil
+})
diff --git a/go.mod b/go.mod
@@ -0,0 +1,7 @@
+module github.com/go-kata/kdone
+
+go 1.14
+
+require (
+	github.com/go-kata/kerror v0.1.0
+)
diff --git a/kdone.go b/kdone.go
@@ -0,0 +1,2 @@
+// Package kdone provides tools for destroying objects.
+package kdone
diff --git a/reaper.go b/reaper.go
@@ -0,0 +1,113 @@
+package kdone
+
+import "github.com/go-kata/kerror"
+
+// Reaper represents a mechanism of deferred call of destructors.
+type Reaper struct {
+	// destructors specifies destructors the responsibility of calling which was assumed by this reaper.
+	destructors []Destructor
+	// released specifies whether was this reaper released
+	// from the responsibility for calling destructors.
+	released bool
+	// finalized specifies whether did this reapers call destructors.
+	finalized bool
+}
+
+// NewReaper returns a new reaper.
+func NewReaper() *Reaper {
+	return &Reaper{}
+}
+
+// Assume passes the responsibility for calling the given destructor to this reaper.
+func (r *Reaper) Assume(dtor Destructor) error {
+	if r == nil {
+		kerror.NPE()
+		return nil
+	}
+	if r.released {
+		return kerror.New(kerror.EIllegal,
+			"reaper was already released from responsibility for calling destructors")
+	}
+	if r.finalized {
+		return kerror.New(kerror.EIllegal, "reaper has already called destructors")
+	}
+	if dtor == nil {
+		return kerror.New(kerror.EInvalid, "reaper cannot assume responsibility for calling nil destructor")
+	}
+	r.destructors = append(r.destructors, dtor)
+	return nil
+}
+
+// MustAssume is a variant of the Assume that panics on error.
+func (r *Reaper) MustAssume(dtor Destructor) {
+	if err := r.Assume(dtor); err != nil {
+		panic(err)
+	}
+}
+
+// Release releases this reaper from the responsibility for calling destructors
+// and pass it to caller by return a composite destructor that calls destructors
+// in the backward order.
+func (r *Reaper) Release() (Destructor, error) {
+	if r == nil {
+		return Noop, nil
+	}
+	if r.released {
+		return nil, kerror.New(kerror.EIllegal,
+			"reaper was already released from responsibility for calling destructors")
+	}
+	if r.finalized {
+		return nil, kerror.New(kerror.EIllegal, "reaper has already called destructors")
+	}
+	destructors := r.destructors
+	finalized := &r.finalized
+	dtor := DestructorFunc(func() error {
+		if *finalized {
+			return kerror.New(kerror.EIllegal, "reaper has already called destructors")
+		}
+		return reap(destructors...)
+	})
+	r.released = true
+	return dtor, nil
+}
+
+// MustRelease is a variant of the Release that panics on error.
+func (r *Reaper) MustRelease() Destructor {
+	dtor, err := r.Release()
+	if err != nil {
+		panic(err)
+	}
+	return dtor
+}
+
+// Finalize calls destructors in the backward order
+// if this reaper was not released from this responsibility yet.
+func (r *Reaper) Finalize() error {
+	if r == nil || r.released {
+		return nil
+	}
+	if r.finalized {
+		return kerror.New(kerror.EIllegal, "reaper has already called destructors")
+	}
+	err := reap(r.destructors...)
+	r.finalized = true
+	return err
+}
+
+// MustFinalize is a variant of the Finalize that panics on error.
+func (r *Reaper) MustFinalize() {
+	if err := r.Finalize(); err != nil {
+		panic(err)
+	}
+}
+
+// reap calls given destructors in the backward order.
+func reap(destructors ...Destructor) error {
+	coerr := kerror.NewCollector()
+	for i := len(destructors) - 1; i >= 0; i-- {
+		coerr.Collect(kerror.Try(func() error {
+			return destructors[i].Destroy()
+		}))
+	}
+	return coerr.Error()
+}
diff --git a/reaper_test.go b/reaper_test.go
@@ -0,0 +1,156 @@
+package kdone
+
+import (
+	"testing"
+
+	"github.com/go-kata/kerror"
+)
+
+type testObjectInitializer = func(t *testing.T, c *int, value int) (int, Destructor, error)
+
+func newTestObject(t *testing.T, c *int, value int) (int, Destructor, error) {
+	t.Logf("test object (%d) was initialized", value)
+	return value, DestructorFunc(func() error {
+		*c -= value
+		t.Logf("test object (%d) was finalized", value)
+		return nil
+	}), nil
+}
+
+func newTestObjectWithError(t *testing.T, c *int, value int) (int, Destructor, error) {
+	t.Logf("test object (%d) was initialized (but will not be finalized...)", value)
+	return value, DestructorFunc(func() error {
+		*c -= value
+		t.Logf("test object (%d) was finalized", value)
+		return nil
+	}), kerror.New(kerror.ECustom, "test error")
+}
+
+func newTestObjectWithPanic(t *testing.T, c *int, value int) (int, Destructor, error) {
+	t.Logf("test object (%d) was initialized (but will not be finalized...)", value)
+	kerror.Panic("keep calm, this is a test panic")
+	return value, DestructorFunc(func() error {
+		*c -= value
+		t.Logf("test object (%d) was finalized (and panic now, boo!)", value)
+		return nil
+	}), nil
+}
+
+func newTestObjectWithPanicInDestructor(t *testing.T, c *int, value int) (int, Destructor, error) {
+	t.Logf("test object (%d) was initialized", value)
+	return value, DestructorFunc(func() error {
+		*c -= value
+		t.Logf("test object (%d) was finalized (and panic now, boo!)", value)
+		kerror.Panic("keep calm, this is a test panic")
+		return nil
+	}), nil
+}
+
+func newTestCompositeObject(t *testing.T, e testObjectInitializer, c *int, values ...int) (int, Destructor, error) {
+	reaper := NewReaper()
+	defer reaper.MustFinalize()
+	sum := 0
+	for _, value := range values {
+		obj, dtor, err := newTestObject(t, c, value)
+		if err != nil {
+			return 0, nil, err
+		}
+		reaper.MustAssume(dtor)
+		sum += obj
+	}
+	if e != nil {
+		obj, dtor, err := e(t, c, 1000)
+		if err != nil {
+			return 0, nil, err
+		}
+		reaper.MustAssume(dtor)
+		sum += obj
+	}
+	return sum, reaper.MustRelease(), nil
+}
+
+func TestReaper(t *testing.T) {
+	var c int
+	defer func() {
+		if c != -6 {
+			t.Fail()
+			return
+		}
+	}()
+	obj, dtor, err := newTestCompositeObject(t, nil, &c, 1, 2, 3)
+	if err != nil {
+		t.Fail()
+		return
+	}
+	defer dtor.MustDestroy()
+	if c != 0 {
+		t.Fail()
+		return
+	}
+	if obj != 6 {
+		t.Fail()
+		return
+	}
+}
+
+func TestReaperWithError(t *testing.T) {
+	var c int
+	_, _, err := newTestCompositeObject(t, newTestObjectWithError, &c, 1, 2, 3)
+	if err == nil {
+		t.Fail()
+		return
+	}
+	if c != -6 {
+		t.Fail()
+		return
+	}
+	t.Logf("\n%+v\n", err)
+}
+
+func TestReaperWithPanic(t *testing.T) {
+	var c int
+	defer func() {
+		if c != -6 {
+			t.Fail()
+			return
+		}
+		v := recover()
+		if v == nil {
+			t.Fail()
+			return
+		}
+		t.Logf("\n%+v\n", v)
+	}()
+	_, _, _ = newTestCompositeObject(t, newTestObjectWithPanic, &c, 1, 2, 3)
+}
+
+func TestReaperWithPanicInDestructor(t *testing.T) {
+	var c int
+	defer func() {
+		if c != -1006 {
+			t.Fail()
+			return
+		}
+	}()
+	obj, dtor, err := newTestCompositeObject(t, newTestObjectWithPanicInDestructor, &c, 1, 2, 3)
+	if err != nil {
+		t.Fail()
+		return
+	}
+	defer func() {
+		dtorErr := dtor.Destroy()
+		if dtorErr == nil {
+			t.Fail()
+			return
+		}
+		t.Logf("\n%+v\n", dtorErr)
+	}()
+	if c != 0 {
+		t.Fail()
+		return
+	}
+	if obj != 1006 {
+		t.Fail()
+		return
+	}
+}
Original file line number	Diff line number	Diff line change
		@@ -0,0 +1,2 @@
		// Package kdone provides tools for destroying objects.
		package kdone