[fix] Issue #1

Fixed goroutine leak as well as a data race when using concurrent `UI`s with a common `Engine`. Also enhanced error handling and documentation, too.

Author: Zaba505

engine.go

@@ -25,7 +25,7 @@ type execReq struct {
 
 // exec sends the given line to the backing engine and awaits the results.
 // this is a blocking call.
-func (ui *UI) exec(ctx context.Context, line string) int {
+func (ui *UI) exec(ctx context.Context, line string, reqCh chan execReq) int {
 	req := execReq{
 		ctx:    ctx,
 		line:   line,
@@ -35,14 +35,19 @@ func (ui *UI) exec(ctx context.Context, line string) int {
 	select {
 	case <-ctx.Done():
 		return 0
-	case ui.reqCh <- req:
+	case reqCh <- req:
 	}
 	return <-req.respCh
 }
 
 // runEngine provides a container for an engine to run inside.
 func runEngine(ctx context.Context, eng Engine, reqChs chan chan execReq) {
-	defer close(reqChs)
+	defer func() {
+		close(reqChs)
+		engines.Lock()
+		delete(engines.engs, eng)
+		engines.Unlock()
+	}()
 
 	for {
 		select {

example/cobra/cmd_test.go

@@ -69,7 +69,7 @@ func TestRootCmd(t *testing.T) {
 				H: echoHandler,
 			}
 
-			ui := sand.NewUI()
+			ui := new(sand.UI)
 
 			ui.SetPrefix(">")
 			ui.SetIO(&in, &out)
@@ -81,7 +81,9 @@ func TestRootCmd(t *testing.T) {
 				subT.Errorf("failed writing to input buffer: %s", err)
 			}
 
-			if err = ui.Run(nil, eng); err != io.EOF && err != nil {
+			err = ui.Run(nil, eng)
+			var ok bool
+			if err, ok = sand.IsRecoverable(err); !ok || err != io.EOF && err != nil {
 				subT.Errorf("unexpected error encountered during UI.Run(): %s", err)
 			}
 

example/echo/main.go

@@ -29,7 +29,7 @@ func (eng *EchoEngine) Exec(ctx context.Context, line string, ui io.ReadWriter)
 }
 
 func main() {
-	ui := sand.NewUI()
+	ui := new(sand.UI)
 
 	log.SetOutput(os.Stdout)
 	err := ui.Run(

example/tictactoe/main.go

@@ -171,7 +171,7 @@ func hasWinner(board [][]Player) (player Player, ok bool) {
 }
 
 func main() {
-	ui := sand.NewUI()
+	ui := new(sand.UI)
 
 	ui.SetPrefix(">")
 	ui.SetIO(os.Stdin, os.Stdout)

go.mod

@@ -3,6 +3,7 @@ module github.com/Zaba505/sand
 require (
 	github.com/golang/mock v1.1.1
 	github.com/inconshreveable/mousetrap v1.0.0 // indirect
+	github.com/pkg/errors v0.8.0
 	github.com/spf13/cobra v0.0.3
 	github.com/spf13/pflag v1.0.3 // indirect
 	golang.org/x/net v0.0.0-20181114220301-adae6a3d119a // indirect

go.sum

@@ -2,6 +2,8 @@ github.com/golang/mock v1.1.1 h1:G5FRp8JnTd7RQH5kemVNlMeyXQAztQ3mOWV95KxsXH8=
 github.com/golang/mock v1.1.1/go.mod h1:oTYuIxOrZwtPieC+H1uAHpcLFnEyAGVDL/k47Jfbm0A=
 github.com/inconshreveable/mousetrap v1.0.0 h1:Z8tu5sraLXCXIcARxBp/8cbvlwVa7Z1NHg9XEKhtSvM=
 github.com/inconshreveable/mousetrap v1.0.0/go.mod h1:PxqpIevigyE2G7u3NXJIT2ANytuPF1OarO4DADm73n8=
+github.com/pkg/errors v0.8.0 h1:WdK/asTD0HN+q6hsWO3/vpuAkAr+tw6aNJNDFFf0+qw=
+github.com/pkg/errors v0.8.0/go.mod h1:bwawxfHBFNV+L2hUp1rHADufV3IMtnDRdf1r5NINEl0=
 github.com/spf13/cobra v0.0.3 h1:ZlrZ4XsMRm04Fr5pSFxBgfND2EBVa1nLpiy1stUsX/8=
 github.com/spf13/cobra v0.0.3/go.mod h1:1l0Ry5zgKvJasoi3XT1TypsSe7PqH0Sj9dhYf7v3XqQ=
 github.com/spf13/pflag v1.0.3 h1:zPAT6CGy6wXeQ7NtTnaTerfKOsV6V6F8agHXFiazDkg=