Update Docs + README, Adde more examples

- updates docs, cleanup up a bit of code.
- added more examples

Author: Dean Karn

README.md

@@ -1,6 +1,6 @@
 ##KMS
 
-![Project status](https://img.shields.io/badge/version-1.1.0-green.svg)
+![Project status](https://img.shields.io/badge/version-1.2.0-green.svg)
 [![Build Status](https://semaphoreci.com/api/v1/joeybloggs/kms/branches/master/badge.svg)](https://semaphoreci.com/joeybloggs/kms)
 [![Coverage Status](https://coveralls.io/repos/github/go-playground/kms/badge.svg)](https://coveralls.io/github/go-playground/kms)
 [![Go Report Card](https://goreportcard.com/badge/github.com/go-playground/kms)](https://goreportcard.com/report/github.com/go-playground/kms)
@@ -15,38 +15,16 @@ Sure there are other libraries, but they are focused on handling graceful shutdo
 code such as graceful shutdown of an http server, but this library allows you to glue together multiple
 unrelated(or related) services running within the same process/application.
 
-eg.
+Doesn't Go 1.8 handle graceful shutdown?
+------------
+Yes and No, it does not yet handle Hijacked connections, like WebSockets, see:
+- https://github.com/golang/go/issues/4674#issuecomment-257549871
+- https://github.com/golang/go/issues/17721#issuecomment-257572027
 
-```go
-
-// start CRON service running tasks..
-go startCRON()
-
-// listen for shutdown signal(s), non-blocking
-kms.Listen(false)
-
-// serve http site ( using built in http listener)
-// this site also has WebSocket functionality
-kmshttp.ListenAndServe(":3007", nil)
+but this package does; furthermore this package isn't just for graceful http shutdown but graceful shutdown of anything and everything.
 
-```
-
-This library will allow you to gracefully shutdown the http server, any WebSockets and any CRON jobs that may be running using the following:
-
-```go
-
-kms.Wait()
-kms.Done()
-
-// chaining is also supported eg. defer kms.Wait().Done()
-
-<-kms.ShutdownInitiated()
-
-and is some cases
-
-<-kms.ShutdownComplete()
-
-```
+When Go 1.8 comes out I will transparently make changes to let the std lib handle idle connections as
+it has lower level access to them, but continue to handle Hijacked connections.
 
 Installation
 -----------
@@ -59,77 +37,36 @@ go get -u github.com/go-playground/kms
 
 Built In
 --------
-There are a few built in graceful shutdown helpers using the kms package for TCP, Unix Sockets and HTTP graceful shutdown.
+There are a few built in graceful shutdown helpers using the kms package for:
+- TCP
+- Unix Sockets
+- HTTP(S) graceful shutdown.
 
-Example
+Examples
 -------
+[see here](https://github.com/go-playground/kms/tree/master/examples) for more
+
 ```go
 package main
 
 import (
-	"fmt"
 	"net/http"
 	"time"
 
 	"github.com/go-playground/kms"
 	"github.com/go-playground/kms/kmsnet/kmshttp"
 )
 
-var (
-	// simple variable to prove the CRON job finishes gracefully.
-	complete bool
-)
-
 func main() {
 
-	go fakeWebsocketHandler()
-	go cronJob()
-
-	kms.Listen(false)
+	// listen for shutdown signal(s) with timeout, non-blocking
+	kms.ListenTimeout(false, time.Minute*3)
 
 	http.HandleFunc("/", func(w http.ResponseWriter, r *http.Request) {
 		w.Write([]byte("Home"))
 	})
 
 	kmshttp.ListenAndServe(":3007", nil)
-
-	fmt.Println("CRON completed gracefully? ", complete)
-}
-
-// crude CRON job examples
-func cronJob() {
-
-	// a long running job that fires every x minutes
-	for {
-		time.Sleep(time.Second * 1)
-		kms.Wait()
-		complete = false
-
-		// long running DB calls
-		time.Sleep(time.Second * 10)
-
-		complete = true
-		kms.Done()
-	}
-}
-
-// faking a single WebSocket, just to show how
-func fakeWebsocketHandler() {
-
-	message := make(chan []byte)
-
-FOR:
-	for {
-		select {
-		case <-kms.ShutdownInitiated():
-			close(message)
-			// close WebSocket connection here
-			break FOR
-		case b := <-message:
-			fmt.Println(string(b))
-		}
-	}
-
 }
 ```
 

doc.go

@@ -0,0 +1,27 @@
+/*
+Pacakge kms (Killing Me Softly) is a library that aids in graceful shutdown of a process/application.
+
+Example:
+	package main
+
+	import (
+		"net/http"
+		"time"
+
+		"github.com/go-playground/kms"
+		"github.com/go-playground/kms/kmsnet/kmshttp"
+	)
+
+	func main() {
+
+		// listen for shutdown signal(s) with timeout, non-blocking
+		kms.ListenTimeout(false, time.Minute*3)
+
+		http.HandleFunc("/", func(w http.ResponseWriter, r *http.Request) {
+			w.Write([]byte("Home"))
+		})
+
+		kmshttp.ListenAndServe(":3007", nil)
+	}
+*/
+package kms

examples/http/main.go

@@ -0,0 +1,21 @@
+package main
+
+import (
+	"net/http"
+	"time"
+
+	"github.com/go-playground/kms"
+	"github.com/go-playground/kms/kmsnet/kmshttp"
+)
+
+func main() {
+
+	// listen for shutdown signal(s) with timeout, non-blocking
+	kms.ListenTimeout(false, time.Minute*3)
+
+	http.HandleFunc("/", func(w http.ResponseWriter, r *http.Request) {
+		w.Write([]byte("Home"))
+	})
+
+	kmshttp.ListenAndServe(":3007", nil)
+}

examples/rpc/main.go

@@ -0,0 +1,88 @@
+package main
+
+import (
+	"fmt"
+	"log"
+	"net/rpc"
+	"syscall"
+	"time"
+
+	"github.com/go-playground/kms"
+	"github.com/go-playground/kms/kmsnet"
+)
+
+// RPCListener ...
+type RPCListener struct {
+}
+
+// Hello ...
+func (l *RPCListener) Hello(in *string, out *string) (err error) {
+	res := fmt.Sprintf("Hello %s", *in)
+	*out = *(&res)
+	return nil
+}
+
+func main() {
+
+	go testAndKill()
+
+	inbound, err := kmsnet.NewTCPListener("tcp", ":4444")
+	if err != nil {
+		log.Fatal(err)
+	}
+	defer inbound.Close()
+
+	// for TLS just wrap 'inbound'
+	// newInbound := tls.NewListener(inbound, tlsConfig)
+	// defer newInbound.Close()
+	//
+	// ...
+	// s.Accept(newInbound)
+	// ...
+
+	s := rpc.NewServer()
+
+	err = s.Register(new(RPCListener))
+	if err != nil {
+		log.Fatal(err)
+	}
+
+	// listen for shutdown signal(s), non-blocking with timeout
+	kms.ListenTimeout(false, time.Minute*3)
+
+FOR:
+	for {
+		select {
+		case <-kms.ShutdownInitiated():
+			break FOR
+		default:
+			s.Accept(inbound)
+		}
+	}
+
+	<-kms.ShutdownComplete()
+}
+
+func testAndKill() {
+
+	time.Sleep(time.Second * 1)
+
+	var in, out string
+
+	in = "Joeybloggs"
+
+	client, err := rpc.Dial("tcp", "localhost:4444")
+	if err != nil {
+		log.Fatal(err)
+	}
+	defer client.Close()
+
+	err = client.Call("RPCListener.Hello", &in, &out)
+	if err != nil {
+		log.Fatal(err)
+	}
+
+	fmt.Printf("Server returned '%s'\n", out)
+
+	syscall.Kill(syscall.Getpid(), syscall.SIGTERM)
+}

kms.go

@@ -2,7 +2,6 @@ package kms
 
 import (
 	"fmt"
-	"log"
 	"os"
 	"os/signal"
 	"sync"
@@ -21,7 +20,7 @@ type killingMeSoftly struct {
 }
 
 // SignalFn is the function type used to signal kms of a shutdown siganl.
-// by default this library listens for syscall.SIGINT, syscall.SIGTERMand syscall.SIGHUP
+// by default this library listens for syscall.SIGINT, syscall.SIGTERM and syscall.SIGHUP
 // os.Signal's but you can override with whatever signals or logic you wish.
 type SignalFn func() <-chan os.Signal
 
@@ -138,19 +137,19 @@ func Listen(block bool) {
 
 		close(notify)
 
-		log.Printf("signal %s received, attempting soft shutdown...\n", sig)
+		fmt.Printf("Gracefully stopping (signal: %s)... ", sig)
 
 		if hardShutdown.Load().(bool) {
 			// listen for another signal, if another happens.. force shutdown
 			go func() {
-				sig := <-s
-				fmt.Printf("received additional %s, hard shutdown initiated\n", sig)
+				<-s
+				fmt.Println("done")
 				exit(1)
 			}()
 		}
 
 		killMeSoftly.wg.Wait()
-		log.Println("soft shutdown complete, ending process")
+		fmt.Println("done")
 		close(done)
 	}()
 
@@ -176,17 +175,17 @@ func ListenTimeout(block bool, wait time.Duration) {
 
 		close(notify)
 
-		log.Printf("signal %s received, attempting soft shutdown for %s...\n", sig, wait)
+		fmt.Printf("Gracefully stopping (signal: %s, timeout: %s)... ", sig, wait)
 
 		if hardShutdown.Load().(bool) {
 			go func() {
 				select {
 
 				case <-time.After(wait):
-					fmt.Println("timeout reached, hard shutdown initiated")
+					fmt.Println("timed out")
 					exit(1)
-				case sig := <-s:
-					fmt.Printf("received additional %s, hard shutdown initiated\n", sig)
+				case <-s:
+					fmt.Println("done")
 					exit(1)
 				case <-done:
 				}
@@ -197,7 +196,7 @@ func ListenTimeout(block bool, wait time.Duration) {
 				select {
 
 				case <-time.After(wait):
-					fmt.Println("timeout reached, hard shutdown initiated")
+					fmt.Println("timed out")
 					exit(1)
 				case <-done:
 				}
@@ -206,7 +205,7 @@ func ListenTimeout(block bool, wait time.Duration) {
 		}
 
 		killMeSoftly.wg.Wait()
-		log.Println("soft shutdown complete, ending process")
+		fmt.Println("done")
 		close(done)
 	}()