plezi 0.11.2 → 0.12.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: debb56bb8606bda13bf432ea12c79154a2240bf2
-  data.tar.gz: b7b030e87997f82457735b63f856a77b0d715c05
+  metadata.gz: c3641815744ffb10926c4e95a6fd47a7fcb4ba1f
+  data.tar.gz: a44e5be3f88040d8d46ff5adf6469fd3efad66c9
 SHA512:
-  metadata.gz: a405525ff846eff0566a3c4e00d4949a3c93625a8cb5fd5801023c453c4f7b39d4764c70d5e2614b17e7849091d7a28b672c04f6c8dac4bb9a6337f06b7f7373
-  data.tar.gz: 6a5510d3cbbfa8f99b007a3c197c201ca9751e286df4818727bf2d00ba5da74db2d86d84206c67e1a49b53db8ccca9b3e5bce5febf35bff82673e8828b3bca16
+  metadata.gz: 88072db2e3f71acb5a5b5e96764f285f20e7b8a0194e07122b24fd06e46fec9b38aa98c0a27a9c6551c3e30625b7568f8bb2765db752e20dd836da371c4bfe18
+  data.tar.gz: 77c52cfba2bfb6e2ad0c7c7a80dd0d2d84a8d0893327ccb983406b0b4e049fcbbf4134dbbdb22517ed46f19ac4d1b6093b9701c0ab6ad223cb537a31303a2da5

data/CHANGELOG.md

@@ -2,6 +2,26 @@
 
 ***
 
+Change log v.0.12.0 - API changes (throwing out dead code)
+
+**Feature** The `Controller.failed_unicast(target, method, arguments_array)` callback is here, allowing you to write a class level callback that will be called if `unicast` fails to find it's target (i.e. if the Websocket connection was already closed or the hosting server shutdown).
+
+\* the lack of this callback being called does NOT imply that the unicast was processed without errors, it's only called if the target itself wasn't found (the connection already recognized as closed). Errors can occure within the method originally called by `unicast` when the target was found but the connection was dropped while processing was underway. The `failed_unicast` callback, together with error handling in the original method (i.e. `response << "message"` returning `nil`) should cover any reasonable scenario. 
+
+**Minor**: updated asset pipeline performance; API for the `Plezi.route` methods now auto-creates an empty listening service (no assets, no templates, no public folder...) if one is missing.
+
+**Fix**: The '/*' is automatically appended to the Re-Write routes, so now writing re-write routes is easier and more intuitive.
+
+**Fix**: fixed issue with the Placebo API that could cause CPU cycles (IO.select would return immediately) and an issue where the on_close callback wouldn't be called.
+
+**Big Change**: Discarded GReactor and GRHttp in favor of [Iodine](https://github.com/boazsegev/iodine) - an Object Oriented IO Reactor for writing network services, which includes an optional Http, Websocket and even an experimental Http/2 server (all to show off it's the ability to change protocols mid-stream).
+
+**API changes**: Along with moving to a single server Iodine module, `listen` had been deprecated in favor of a simpler API, as well as many other helpers that were acting as dead-code.
+
+**Fix**: Along with switching to Iodine, certain server related issues were fixed (such as String and Symbol cookies with unexpected behavior).
+
+***
+
 Change log v.0.11.2
 
 **Fix**: Fixed an issue where the Session object wouldn't be available for websocket connections after the handshake was complete.

data/README.md

@@ -10,7 +10,9 @@ With Plezi, you can easily:
 
 3. Create a full fledged Ruby web application, taking full advantage of RESTful routing, HTTP streaming and scalable Websocket features.
 
-Plezi leverages [GRHttp server's](https://github.com/boazsegev/GRHttp) new architecture. GRHttp is a pure Ruby HTTP and Websocket Generic Server built using [GReactor](https://github.com/boazsegev/GReactor) - a multi-threaded pure ruby alternative to EventMachine with basic process forking support (enjoy forking, if your code is scaling ready).
+Plezi leverages [Iodine's server](https://github.com/boazsegev/iodine) new architecture. Iodine is a pure Ruby HTTP and Websocket Server built using [Iodine's](https://github.com/boazsegev/iodine) core library - a multi-threaded pure ruby alternative to EventMachine with process forking support (enjoy forking, if your code is scaling ready).
+
+Plezi and Iodine are written for Ruby versions 2.1.0 or greater (or API compatible variants). Version 2.2.3 is the currently recommended version.
 
 ### Plezi version data
 [![Gem Version](https://badge.fury.io/rb/plezi.svg)](http://badge.fury.io/rb/plezi)
@@ -45,7 +47,7 @@ If you're on MacOS or linux you can simply double click the `appname` script fil
 
 now go, in your browser, to: [http://localhost:3000/](http://localhost:3000/)
 
-the default first port for the app is 3000. you can set the first port to listen to by using the `-p ` option (make sure you have permissions for the requested port):
+the default port for the app is 3000. you can set the port to listen to by using the `-p ` option (make sure you have permissions for the requested port):
 
     $ ./appname -p 80
 
@@ -65,7 +67,12 @@ Here is a Hello World using a Controller class (run in `irb`):
             end
         end
 
-        listen
+        # use the host method to set up any specific host options:
+        host :default,
+              public: File.join('my', 'public', 'folder'),
+              templates: File.join('my', 'template', 'folder')
+
+
         route '*' , Controller
 
         exit # Plezi will autostart once you exit irb.
@@ -74,7 +81,7 @@ Except while using WebSockets, returning a String will automatically add the str
 
 It's also possible to define a number of controllers for a similar route. The controllers will answer in the order in which the routes are defined (this allows to group code by logic instead of url).
 
-\* please read the demo code for Plezi::StubRESTCtrl and Plezi::StubWSCtrl to learn more. Also, read more about the [GRHttp Websocket and HTTP server](https://github.com/boazsegev/GRHttp) at the core of Plezi to get more information about the amazing [HTTPRequest](http://www.rubydoc.info/github/boazsegev/GRHttp/master/GRHttp/HTTPRequest) and [HTTPResponse](http://www.rubydoc.info/github/boazsegev/GRHttp/master/GRHttp/HTTPResponse) objects.
+\* please read the demo code for Plezi::StubRESTCtrl and Plezi::StubWSCtrl to learn more. Also, read more about the [Iodine's Websocket and HTTP server](https://github.com/boazsegev/iodine) at the core of Plezi to get more information about the amazing [Request](http://www.rubydoc.info/github/boazsegev/iodine/master/Iodine/Http/Request) and [Response](http://www.rubydoc.info/github/boazsegev/iodine/master/Iodine/Http/Response) objects.
 
 ## Native Websocket and Redis support
 
@@ -114,8 +121,6 @@ Remember to connect to the service from at least two browser windows - to truly
         end
     end
 
-    listen 
-
     route '/', BroadcastCtrl
 ```
 
@@ -143,7 +148,7 @@ There are two easy ways to add Plezi websockets to your existing WebApp, dependi
 
 ### The super easy way - a Hybrid app
 
-The easiest way to add Plezi websockets to your existing application is to use [GRHttp's](https://github.com/boazsegev/GRHttp) Rack adapter to run your Rack app, while Plezi will use GRHttp's native features (such as Websockets and HTTP streaming).
+The easiest way to add Plezi websockets to your existing application is to use [Iodine's](https://github.com/boazsegev/iodine) Rack adapter to run your Rack app, while Plezi will use Iodine's native features (such as Websockets and HTTP streaming).
 
 You can eaither use your existing Plezi application or create a new mini plezi application inside your existing app folder using:
 
@@ -153,13 +158,14 @@ Next, add the `plezi` gem to your `Gemfile` and add the following line somewhere
 
 ```ruby
 require './appname/appname.rb'
-Plezi.start_rack
 ```
 
 That's it! Now you can use the Plezi API and your existing application's API at the same time and they are both running on the same server.
 
 Plezi's routes will be attempted first, so that your app can keep handling the 404 (not found) error page.
 
+\* just remember to remove any existing servers, such as `thin` of `puma` from your gemfile, otherwise they might take precedence over Plezi's choice of server (Iodine).
+
 ### The Plezi Placebo API - talking from afar
 
 To use Plezi and your App on different processes, without mixing them together, simply include the Plezi App in your existing app and call `Plezi.start_placebo` - now you can access all the websocket API that you want from your existing WebApp, but Plezi will not interfere with your WebApp in any way.
@@ -173,6 +179,7 @@ require './my_plezi_app/routes.rb'
 
 # # Make sure the following is already in your 'my_plezi_app/environment.rb' file:
 # ENV['PL_REDIS_URL'] = "redis://username:password@my.host:6379"
+# Plezi::Settings.redis_channel_name = 'unique_channel_name_for_app_b24270e2'
 
 Plezi.start_placebo
 ```
@@ -219,10 +226,10 @@ class MyReciever
         # your app's logic
     end
 end
-Plezi::Placebo.new MyReciever
+Plezi.start_placebo MyReciever
 ```
 
-Plezi will now take your class and add mimick an IO connection (the Placebo connection) on it's GRHttp serever. This Placebo connection will answer the Redis broadcasts just as if your class was a websocket controller...
+Plezi will now take your class and add mimick an IO connection (the Placebo connection) on it's Iodine serever. This Placebo connection will answer the Redis broadcasts just as if your class was a websocket controller...
 
 On the Plezi side, use multicasting or unicasting (but not broadcasting), from ANY controller:
 
@@ -250,7 +257,7 @@ class MyReciever
     end
 end
 
-pl = Plezi::Placebo.new MyReciever
+pl = Plezi.start_placebo MyReciever
 
 Plezi.redis_connection.set 'MainUUIDs', pl.uuid
 
@@ -270,7 +277,7 @@ end
 
 ## Native HTTP streaming with Asynchronous events
 
-Plezi comes with native HTTP streaming support, alowing you to use Plezi Events and Timers to send an Asynchronous response.
+Plezi comes with native HTTP streaming support (Http will use chuncked encoding unless experimental Http/2 is in use), alowing you to use Plezi Events and Timers to send an Asynchronous response.
 
 Let's make the classic 'Hello World' use HTTP Streaming:
 
@@ -288,13 +295,12 @@ Let's make the classic 'Hello World' use HTTP Streaming:
             end
         end
 
-        listen
         route '*' , Controller
 ```
 
 Notice you can nest calls to the `response.stream_async` method, allowing you to breakdown big blocking tasks into smaller chunks. `response.stream_async` will return immediately, scheduling the task for background processing.
 
-You can also handle other tasks asynchronously using the [GReactor API](http://www.rubydoc.info/gems/greactor)'s.
+You can also handle other tasks asynchronously using the [Iodine's API](http://www.rubydoc.info/gems/iodine).
 
 More on asynchronous events and timers later.
 
@@ -305,7 +311,6 @@ Plezi supports magic routes, in similar formats found in other systems, such as:
 Plezi assummes all simple routes to be RESTful routes with the parameter `:id` ( `"/user" == "/user/(:id)"` ).
 
     require 'plezi'
-    listen
 
     # this route demos a route for listing/showing posts,
     # with or without revision numbers or page-control....
@@ -324,8 +329,8 @@ now visit:
 Plezi can be used to create virtual hosts for the same service, allowing you to handle different domains and subdomains with one app:
 
     require 'plezi'
-    listen
-    host 'localhost', alias: 'localhost2'
+
+    host 'localhost', alias: 'localhost2', public: File.join('my', 'public', 'folder')
 
     shared_route '/humans.txt' do |req, res|
         res << "we are people - shared by all routes."
@@ -349,10 +354,11 @@ Now visit:
 * [http://localhost:3000/]( http://localhost:3000/ )
 * [http://127.0.0.1:3000/humans.txt]( http://127.0.0.1:3000/humans.txt )
 * [http://localhost:3000/humans.txt]( http://localhost:3000/humans.txt )
+* notice: `localhost2` will only work if it was defined in your OS's `hosts` file.
 
 ## Plezi Logging
 
-The Plezi module (also `PL`) delegates to the GReactor methods, helping with logging as well as the support you already noticed for dynamic routes, dynamic services and more.
+The Plezi module (also `PL`) delegates to the Iodine methods, helping with logging as well as the support you already noticed for dynamic routes, dynamic services and more.
 
 Logging:
 
@@ -360,7 +366,7 @@ Logging:
 
     # simple logging of strings
     PL.info 'log info'
-    GReactor.info 'This is the same, but more direct.'
+    Iodine.info 'This is the same, but more direct.'
     PL.warn 'log warning'
     PL.error 'log error'
     PL.fatal "log a fatal error (shuoldn't be needed)."
@@ -373,11 +379,11 @@ Logging:
         PL.error e
     end
 
-Please notice it is faster to use the GReactor API directly when using API that is delegated to GReactor.
+Please notice it is faster to use the Iodine's API directly when using API that is delegated to Iodine.
 
 ## Plezi Events and Timers
 
-The Plezi module (also `PL`) also delegates to the [GReactor's API](http://www.rubydoc.info/gems/greactor/GReactor) to help with asynchronous tasking, callbacks, timers and customized shutdown cleanup.
+The Plezi module (also `PL`) also delegates to the [Iodine's API](http://www.rubydoc.info/gems/greactor/iodine) to help with asynchronous tasking, callbacks, timers and customized shutdown cleanup.
 
 Asynchronous callbacks (works only while services are active and running):
 
@@ -388,17 +394,14 @@ Asynchronous callbacks (works only while services are active and running):
     end
 
     # shutdown callbacks
-    GReactor.on_shutdown(Kernel, :my_shutdown_proc, Time.now) { puts "this will run after shutdown." }
-    GReactor.on_shutdown() { puts "this will run too." }
+    Iodine.on_shutdown(Kernel, :my_shutdown_proc, Time.now) { puts "this will run after shutdown." }
+    Iodine.on_shutdown() { puts "this will run too." }
 
     # a timer
-    GReactor.run_after 2, -> {puts "this will wait 2 seconds to run... too late. for this example"}
-
-    # an asynchronous method call with an optional callback block
-    GReactor.callback(Kernel, :puts, "Plezi will start eating our code once we exit terminal.") {puts 'first output finished'}
+    Iodine.run_after(2) {puts "this will wait 2 seconds to run... too late. for this example"}
 
-    GReactor.run_async {puts "notice that the background tasks will only start once the Plezi's engine is running."}
-    GReactor.run_async {puts "exit Plezi to observe the shutdown callbacks."}
+    Iodine.run {puts "notice that the background tasks will only start once the Plezi's engine is running."}
+    Iodine.run {puts "exit Plezi to observe the shutdown callbacks."}
 
 ## Re-write Routes
 
@@ -435,8 +438,6 @@ By using a route with the a 'false' controller, the parameters extracted are aut
         end
     end
 
-    listen
-
     # this is our re-write route.
     # it will extract the locale and re-write the request.
     route '/:locale{fr|en}/*', false
@@ -500,8 +501,6 @@ and and other OAuth2 authentication service. For example:
                     scope: "public_profile,email") if ENV['FB_APP_ID'] && ENV['FB_APP_SECRET']
 
 
-    listen
-
     create_auth_shared_route do |service_name, token, remote_user_id, remote_user_email, remote_response|
         # we will create a temporary cookie storing a login message. replace this code with your app's logic
         flash[:login] = "#{remote_response['name']} (#{remote_user_email}) from #{service_name}"

data/docs/async_helpers.md

@@ -2,19 +2,19 @@
 
 (todo: write documentation)
 
-Inside Plezi's core code is a pure Ruby IO reactor called [GReactor](https://github.com/boazsegev/GReactor) (Generic Reactor), a very powerful Asynchronous Workflow Engine that allows us to enjoy both Multi-Threading and Multi-Processing.
+Inside Plezi's core code is a pure Ruby IO reactor called [Iodine](https://github.com/boazsegev/iodine), a wonderful Asynchronous Workflow Engine that allows us to enjoy both Multi-Threading and Multi-Processing.
 
-Although multi-threading is highly regarded, it should be pointed out that using the GReactor with just one thread is both faster and more efficient. But, since some tasks that take more time (blocking tasks) can't be broken down into smaller tasks, using a number of threads (and/or processes) is a better practice.
+Although multi-threading is highly regarded, it should be pointed out that using the [Iodine](https://github.com/boazsegev/iodine) with just one thread is both faster and more efficient. But, since some tasks that take more time (blocking tasks) can't be broken down into smaller tasks, using a number of threads (and/or processes) is a better practice.
 
-You can read more about the [GReactor](https://github.com/boazsegev/GReactor) and it's amazing features in it's [documentation](http://www.rubydoc.info/github/boazsegev/GReactor/master).
+You can read more about [Iodine](https://github.com/boazsegev/iodine) and it's amazing features in it's [documentation](http://www.rubydoc.info/github/boazsegev/iodine/master).
 
 Here we will discuss the methods used for asynchronous processing of different tasks that allow us to break big heavy tasks into smaller bits, allowing our application to 'flow' and stay responsive even while under heavy loads.
 
 ## Asynchronous HTTP responses
 
-Inside Plezi's core code is a pure Ruby HTTP and Websocket Server (and client) called [GRHttp](https://github.com/boazsegev/GRHttp) (Generic HTTP), which allows for native HTTP streaming.
+Inside Plezi's core code is a pure Ruby Http and Websocket Server (and client) that comes with [Iodine](https://github.com/boazsegev/iodine) and allows for native Http/1.1 streaming using `chunked` encoding or native Http/2 streaming (built-in to the protocol).
 
-Asynchronous HTTP method calls can be nested, but shouldn't be called on after the other.
+Asynchronous Http method calls can be nested, but shouldn't be called one after the other.
 
 i.e.:
 
@@ -29,9 +29,9 @@ response.stream_async {  "I don't know..."  }
 Since streaming is done asynchronously, and since Plezi is multi-threaded by default (this can be changed to single threaded, but is less recomended unless you know your code doesn't block - see `Plezi::Settings.max_threads = number`), Asynchronous HTTP method nesting makes sure that the code doesn't conflict and that race conditions don't occure within the same HTTP response.
 
 
-#### GRHttp's `response.stream_async &block`
+#### Iodines's `response.stream_async &block`
 
-GRHttp's response object, which is accessed by the controller using the `response` method (or the `@response` object), allows easy access to HTTP streaming.
+Iodines's response object, which is accessed by the controller using the `response` method (or the `@response` object), allows easy access to HTTP streaming.
 
 For example (run this in the terminal using `irb`):
 
@@ -49,7 +49,6 @@ class MyController
     end
 end
 
-listen
 route '/', MyController
 
 exit
@@ -59,14 +58,14 @@ As noted above, `response.stream_async` calls should always be nested and never
 
 Calling `response.stream_async`
 
-#### GRHttp's `response.stream_array enum, &block`
+#### Iodines's `response.stream_array enum, &block`
 
-To make nesting easier, GRHttp's response object provides the `response.stream_array enum, &block` method.
+To make nesting easier, Iodines's response object provides the `response.stream_array enum, &block` method.
 
 Here's our modified example:
 
 ```ruby
-require `plezi`
+require 'plezi'
 
 class MyController
     def index
@@ -75,7 +74,6 @@ class MyController
     end
 end
 
-listen
 route '/', MyController
 
 exit
@@ -84,7 +82,7 @@ exit
 You can also add data to the array while 'looping', which allows you to use the array as a 'flag' for looped streaming. The following is a very limited example, which could be used for "lazy loading" data from a database, in order to save on system resources or send large table data using JSON "packets".
 
 ```ruby
-require `plezi`
+require 'plezi'
 
 class MyController
     def index
@@ -97,7 +95,6 @@ class MyController
     end
 end
 
-listen
 route '/', MyController
 
 exit
@@ -105,91 +102,144 @@ exit
 
 ## Asynchronous code execution
 
-[GReactor](https://github.com/boazsegev/GReactor) (Generic Reactor), a very powerful Asynchronous Workflow Engine which offers a very intuitve and easy to use API both for queuing code snippets (blocks / methods) and for schedualing non-persistent timed events (future timed events are discarded during shutdown and need to be re-initiated).
+[Iodine](https://github.com/boazsegev/iodine) has a very powerful Asynchronous Workflow Engine which offers a very intuitve and simplified way to use API both for queuing code snippets (blocks / methods) and for schedualing non-persistent timed events (future timed events are discarded during shutdown and need to be re-initiated).
 
 ### The Asynchronous "Queue"
 
-`GReactor` (in short: `GR`) offers a number of methods that allow us to easily queue code execution.
+`Iodine`'s core is built with simplicity in mind, making the programmer happy. With this in mind, Iodine offers a single and simple method that allow us to easily queue code execution.
 
 
-#### `GR.run_async(arg1, arg2, arg3...) {block}`
+#### `Iodine.run(arg1, arg2, arg3...) {block}`
 
-`GR.run_async` takes arguments to be passed to a block of code prior to execution. This allows us to seperate the `Proc` object creation fron the data handling and possibly (but not always) optimize our code.
+`Iodine.run` takes arguments to be passed to a block of code prior to execution. This allows us to seperate the `Proc` object creation fron the data handling and possibly (but not always) optimize our code.
 
 For example:
 
 ```ruby
-require `plezi`
+require 'plezi'
 
 class MyController
     def index
-        GR.run_async(Time.now) {|t| puts "Someone poked me at: #{t}"} # maybe send an email?
+        # Plezi.run automatically defers to Iodine.run
+        Plezi.run(Time.now) {|t| puts "Someone poked me at: #{t}" } # maybe send an email?
         "Hello World"
     end
 end
 
-listen
+
 route '/', MyController
 
 exit
 ```
 
-#### `GR.callback(object, method, arg1, arg2...) {|returned_value| callback block}`
-
-Another common method imployed is the `GR.callback`, which allows us to layer asynchronous code:
+This might be optimized like so:
 
 ```ruby
-require `plezi`
+require 'plezi'
 
 class MyController
     def index
-        GR.callback(self, :print_poke, Time.now) { puts "Printed poke."}
+        Iodine.run Time.now, &self.class.action_proc
         "Hello World"
     end
+
     protected
-    def print_poke time
-        puts "Someone poked me at: #{time}"
+
+    def self.action_proc
+        @proc ||= Proc.new {|t| puts "Someone poked me at: #{t}" } # maybe send an email?
     end
 end
 
-listen
 route '/', MyController
 
 exit
 ```
 
-#### `GR.queue(proc, arguments_array)`
+### Timed events
 
-GReactor's asynchronous engine is, in it's core, based off this simple method which accepts two elements:
+Sometimes we want to schedule something to be done in a while, ormaybe we want a task to repeat every certain intevral...
 
-1. An object that answers to `call`
-2. An array of arguments to be passed to that object (or `nil`).
+In come Iodine's TimedEvents: `Iodine.run_after` and `Iodine.run_every`
 
-This method allows us to easily reuse Proc objects without constantly creating new Proc objects and releasing them from memory.
+#### `Iodine.run_every(seconds, arg1, arg2...) {|arg1, arg2..., timed_event| block }`
 
-For example:
+`Iodine.run_every` is very similar to the `Iodine.run`, except it automatically injects an argument to our block, the timed even itself, as the last (optional) parameter. This allows us to stop the repeating event should the need arise.
 
 ```ruby
-require `plezi`
+require 'plezi'
 
 class MyController
+    def index
+        counter = 0
+        # Plezi.run_every automatically defers to Iodine.run_every
+        Plezi.run_every(1, "Counting: %i") do |str, timer|
+            counter +=1
+            puts(str % counter)
+            timer.stop! if counter >= 3
+        end
+        "Hello World"
+    end
+end
+
+
+route '/', MyController
+
+exit
+```
+
+A similar approach could have been accomplished by setting a repeat limit:
 
-    POKE_TASK = -> {|time| puts "Someone poked me at: #{time}"}
+```ruby
+require 'plezi'
 
+class MyController
     def index
-        GR.queue POKE_TASK, [Time.now]
+        timer = Iodine.run_every(1, "Counting down: %i") do |str, timer|
+            puts(str % timer.repeat_limit)
+        end
+        timer.repeat_limit = 3
         "Hello World"
     end
 end
 
-listen
+
 route '/', MyController
 
 exit
 ```
 
+#### `Iodine.run_after(seconds, arg1, arg2...) {|arg1, arg2..., timed_event| block}`
 
-### Timed events
+`Iodine.run_after` is very similar to the `Iodine.run_every`, except it is designed to "self destruct" after only only execution.
+
+The timed event allows us to create a new event with the same job, if we wish to.
+
+```ruby
+require 'plezi'
+
+class MyController
+    def index
+        counter = 0
+        # Plezi.run_after automatically defers to Iodine.run_after
+        Iodine.run_after(1, "Counting: %i") do |str, timer|
+            counter +=1
+            puts(str % counter)
+            Iodine.run_after(1, str, &timer.job) if counter < 3
+        end
+        "Hello World"
+    end
+end
+
+
+route '/', MyController
+
+exit
+```
+
+/// To Do: complete doc.
 
 ## The Graceful Shutdown
 
+Enter `Iodine.on_shutdown` - a reverse shutdown task queue (LIFO).
+
+/// To Do: complete doc.