Give an easier and more permant solution for https://github.com/kataras/iris/pull/689

Former-commit-id: 8dc16d15f7bd14cb98b91b16d7d6b1bd756132bd

HISTORY.md

@@ -18,6 +18,109 @@ Developers are not forced to upgrade if they don't really need it. Upgrade whene
 
 **How to upgrade**: Open your command-line and execute this command: `go get -u github.com/kataras/iris`.
 
+# Sa, 29 July 2017 | v8.1.1
+
+No breaking changes, just an addition to make your life easier.
+
+This feature has been implemented after @corebreaker 's request, posted at: https://github.com/kataras/iris/issues/688. He was also tried to fix that by a [PR](https://github.com/kataras/iris/pull/689), we thanks him but the problem with that PR was the duplication and the separation of concepts, however we thanks him for pushing for a solution. The current feature's implementation gives a permant solution to host supervisor access issues.
+
+Optional host configurators added to all common serve and listen functions.
+
+Below you'll find how to gain access to the host, **the second way is the new feature.**
+
+### Hosts
+
+Access to all hosts that serve your application can be provided by
+the `Application#Hosts` field, after the `Run` method.
+
+But the most common scenario is that you may need access to the host before the `Run` method,
+there are two ways of gain access to the host supervisor, read below.
+
+First way is to use the `app.NewHost` to create a new host
+and use one of its `Serve` or `Listen` functions
+to start the application via the `iris#Raw` Runner.
+Note that this way needs an extra import of the `net/http` package.
+
+Example Code:
+
+```go
+h := app.NewHost(&http.Server{Addr:":8080"})
+h.RegisterOnShutdown(func(){
+    println("server was closed!")
+})
+
+app.Run(iris.Raw(h.ListenAndServe))
+```
+
+Second, and probably easier way is to use the `host.Configurator`.
+
+Note that this method requires an extra import statement of
+"github.com/kataras/iris/core/host" when using go < 1.9,
+if you're targeting on go1.9 then you can use the `iris#Supervisor`
+and omit the extra host import.
+
+All common `Runners` we saw earlier (`iris#Addr, iris#Listener, iris#Server, iris#TLS, iris#AutoTLS`)
+accept a variadic argument of `host.Configurator`, there are just `func(*host.Supervisor)`.
+Therefore the `Application` gives you the rights to modify the auto-created host supervisor through these.
+
+
+Example Code:
+
+```go
+package main
+
+import (
+    stdContext "context"
+    "time"
+
+    "github.com/kataras/iris"
+    "github.com/kataras/iris/context"
+    "github.com/kataras/iris/core/host"
+)
+
+func main() {
+    app := iris.New()
+
+    app.Get("/", func(ctx context.Context) {
+        ctx.HTML("<h1>Hello, try to refresh the page after ~10 secs</h1>")
+    })
+
+    app.Logger().Info("Wait 10 seconds and check your terminal again")
+    // simulate a shutdown action here...
+    go func() {
+        <-time.After(10 * time.Second)
+        timeout := 5 * time.Second
+        ctx, cancel := stdContext.WithTimeout(stdContext.Background(), timeout)
+        defer cancel()
+        // close all hosts, this will notify the callback we had register
+        // inside the `configureHost` func.
+        app.Shutdown(ctx)
+    }()
+
+    // start the server as usual, the only difference is that
+    // we're adding a second (optional) function
+    // to configure the just-created host supervisor.
+    //
+    // http://localhost:8080
+    // wait 10 seconds and check your terminal.
+    app.Run(iris.Addr(":8080", configureHost), iris.WithoutServerError(iris.ErrServerClosed))
+
+}
+
+func configureHost(su *host.Supervisor) {
+    // here we have full access to the host that will be created
+    // inside the `Run` function.
+    //
+    // we register a shutdown "event" callback
+    su.RegisterOnShutdown(func() {
+        println("server is closed")
+    })
+    // su.RegisterOnError
+    // su.RegisterOnServe
+}
+```
+
+Read more about listening and gracefully shutdown by navigating to: https://github.com/kataras/iris/tree/master/_examples/#http-listening
 
 # We, 26 July 2017 | v8.1.0