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

Former-commit-id: 8dc16d15f7bd14cb98b91b16d7d6b1bd756132bd

doc.go

@@ -35,7 +35,7 @@ Source code and other details for the project are available at GitHub:
 
 Current Version
 
-8.1.0
+8.1.1
 
 Installation
 
@@ -303,6 +303,99 @@ Example code:
         app.Run(iris.Addr(":8080"), iris.WithoutInterruptHandler)
     }
 
+
+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:
+
+
+    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:
+
+
+    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