Recent changes to Pipelines

Pipelines modified by g-dollar

g-dollar — Wed, 09 Apr 2014 11:07:05 -0000

--- v20
+++ v21
@@ -18,7 +18,7 @@

 [TOC]

-#Installer
+#Pipelines
 This interface is the entry point to all pipelines.

 Even though the pipeline requests are asynchronous, they are not **multi-threaded**, meaning none of the requests are executed until after the current method completes.  Because of the apartment model, request ordering is preserved, and top-level contexts ensure synchronization for atomic model updates.
@@ -70,6 +70,8 @@
 #Uninstall Pipeline
 The uninstall pipeline reverses the operations of the install pipeline, but does not execute anything in the Resource Loader thread.  Use the same **route** from the **install()** call.

+Note that **uninstall()** is done *by name* and not by GO reference.  To participate in the Uninstall pipeline the GO must be in the **Locator**, or no callbacks are invoked.
+
 This is a top-level context with the **update lock** held.

 ##Unloaded Callback

Pipelines modified by g-dollar

g-dollar — Fri, 17 May 2013 10:43:08 -0000

--- v19
+++ v20
@@ -62,7 +62,7 @@
 * (Resource Loader) If **RequireResourceLoader** is implemented, invokes the **GO.load()** method, passing **ResourceLoader** and **Resources** interfaces.  If not implemented, no action is taken; this is done to maintain the order of **install** calls with their callbacks.  When complete, the load request is passed to the reply-to target (Game Cycle).
 * (Game Cycle) Obtain the **update lock** for the remainder of the steps.
 * (Game Cycle) call the **objectLoaded()** method, passing the GO and error status.  This is a good place to trigger additional installs that depend on a GO being completely installed before certain methods can be called successfully.
-* (Game Cycle) if **GO.locatable** flag is set, register with the **Locator** service.
+* (Game Cycle) if **GO.locatable** flag is set, register with **Locator**.
 * (Game Cycle) if **RequireLocatable** is implemented, register mappings with **Locator**.
 * (Game Cycle) if **RequireTimer** or **TimerCallback** are implemented, register with **TimerService**.  The **RequireTimer** takes priority here, so a GO implementing both interfaces must put itself in **RequireTimer**.
 * (Game Cycle) if the request contains a **route**, obtain each GO from the **Locator** and pass installed GO to its **LoadedCallback** (if implemented).
@@ -81,8 +81,8 @@
 * (Game Cycle) call the **objectUnloaded()** method, passing the GO and error status.
 * (Game Cycle) if **RequireTimer** or **TimerCallback** are implemented, unregister with **TimerService**.  The **RequireTimer** takes priority here, so a GO implementing both interfaces must put itself in **RequireTimer**.
 * (Game Cycle) if **RequireLocatable** is implemented, remove mappings from **Locator**.
-* (Game Cycle) if **GO.locatable** flag is set, remove from the **Locator** service.
-* (Game Cycle) if the uninstall request contains a **route**, obtain each GO from the **Locator** and pass installed GO to its **UnloadedCallback** (if implemented).
+* (Game Cycle) if **GO.locatable** flag is set, remove from **Locator**.
+* (Game Cycle) if the request contains a **route**, obtain each GO from the **Locator** and pass installed GO to its **UnloadedCallback** (if implemented).

 #Event Pipeline
 This pipeline is for making asynchronous requests for additional code to execute.  This makes it convenient to schedule something to happen after the current method completes, and keeps the model in a consistent state, by not mutating it at that time.

Pipelines modified by g-dollar

g-dollar — Fri, 17 May 2013 10:37:28 -0000

--- v18
+++ v19
@@ -4,7 +4,7 @@

 AGE has these pipelines:

-* Install: for loading data and connecting to GOs.
+* Install: for loading data, connecting to AGE and other GOs.
 * Uninstall: for reversing the effect of Install.
 * Event: for inter-GO communication.

@@ -18,8 +18,14 @@

 [TOC]

+#Installer
+This interface is the entry point to all pipelines.
+
+Even though the pipeline requests are asynchronous, they are not **multi-threaded**, meaning none of the requests are executed until after the current method completes.  Because of the apartment model, request ordering is preserved, and top-level contexts ensure synchronization for atomic model updates.
+
 #Marker Interfaces
-These indicate which services the GO requires.
+Game objects (hereafter **GO**) opt-in for AGE services by implementing the *marker interface* of each required service.  These interfaces follow the naming pattern **RequireXXX** where **XXX** represents the service.
+
 ##RequireResourceLoader
 Indicates requirement for asynchronous resource loading.
 ##RequireTimer
@@ -27,17 +33,17 @@
 ##TimerCallback
 Indicates the GO itself is a timer to be registered.
 ##RequireLocatable
-Indicates requirement for registering multiple name/GO mappings in the Locator.
+Indicates requirement for registering multiple name/GO mappings in the **Locator**.
+
+Individual components can use additional marker interfaces as necessary, e.g. to conditionally accept a routed GO on its **LoadedCallback**.

 #Install Pipeline
-The Install pipeline is asynchronous; it is started by calling the *install()* method, and passing the GO to install.  The GO should be minimally initialized at this point, because the Pipeline will take over the actual "work" of initializing.
+The Install pipeline is started by calling the *install()* method, and passing the GO to install.  The GO should be minimally initialized at this point, because the Pipeline will take over the actual "work" of initializing.

-Game objects (hereafter **GO**) opt-in for system services by implementing the *marker interface* of each required service.  These interfaces follow the naming pattern **RequireXXX** where **XXX** represents the service.
-
-The first stop on the Install Pipeline is a dedicated Resource Loader thread for the time-consuming work of initializing a GO from resources, e.g. texture bitmaps, object models, etc.
+The first stop on the Install Pipeline is the Resource Loader task, for the time-consuming work of initializing a GO from resources, e.g. texture bitmaps, object models, etc.

 ##Load Request
-The **LoadObject** message contains the information used by the threads in the Install Pipeline:
+The **LoadObject** message contains the information used by the tasks in the Install Pipeline:

 * the GO to target.
 * a reply-to **TaskChannel** to notify when complete.
@@ -52,22 +58,22 @@
 ##Default Behavior
 The install pipeline proceeds as follows (the thread executing is in parentheses):

-1. (Caller) Call the **install()** method, which sends a message to the Resource Loader thread and returns.  the reply-to target is the Game Cycle, and the **LoadedCallback** is the remainder of the steps from step 3.  **Do not access the GO** after this point, until **objectLoaded()** is called (step 4).
+1. (Caller) Call the **install()** method, which sends a message to the Resource Loader task and returns.  the reply-to target is the Game Cycle, and the **LoadedCallback** is the remainder of the steps from step 3.  **Do not access the GO** after this point, until **objectLoaded()** (step 4) or a routed **LoadedCallback** is called (step 8).
 * (Resource Loader) If **RequireResourceLoader** is implemented, invokes the **GO.load()** method, passing **ResourceLoader** and **Resources** interfaces.  If not implemented, no action is taken; this is done to maintain the order of **install** calls with their callbacks.  When complete, the load request is passed to the reply-to target (Game Cycle).
 * (Game Cycle) Obtain the **update lock** for the remainder of the steps.
 * (Game Cycle) call the **objectLoaded()** method, passing the GO and error status.  This is a good place to trigger additional installs that depend on a GO being completely installed before certain methods can be called successfully.
 * (Game Cycle) if **GO.locatable** flag is set, register with the **Locator** service.
 * (Game Cycle) if **RequireLocatable** is implemented, register mappings with **Locator**.
 * (Game Cycle) if **RequireTimer** or **TimerCallback** are implemented, register with **TimerService**.  The **RequireTimer** takes priority here, so a GO implementing both interfaces must put itself in **RequireTimer**.
-* (Game Cycle) if the install request contains a **route**, obtain each GO from the **Locator** and pass installed GO to its **LoadedCallback** (if implemented).
+* (Game Cycle) if the request contains a **route**, obtain each GO from the **Locator** and pass installed GO to its **LoadedCallback** (if implemented).

 #Uninstall Pipeline
-The uninstall pipeline reverses the operations of the install pipeline, but does not execute anything in the Resource Loader thread.
+The uninstall pipeline reverses the operations of the install pipeline, but does not execute anything in the Resource Loader thread.  Use the same **route** from the **install()** call.

 This is a top-level context with the **update lock** held.

 ##Unloaded Callback
-The dual of the **Loaded** callback is the **Unloaded** callback.  This is meant to undo whatever the effect of **Loaded** was.
+The dual of **LoadedCallback** is **UnloadedCallback**.  This is meant to undo whatever the effect of **LoadedCallback** was.

 ##Default Behavior

Pipelines modified by g-dollar

g-dollar — Tue, 14 May 2013 10:21:45 -0000

Install Pipeline modified by g-dollar

g-dollar — Mon, 13 May 2013 10:49:16 -0000

--- v16
+++ v17
@@ -58,7 +58,7 @@
 * (Game Cycle) call the **objectLoaded()** method, passing the GO and error status.  This is a good place to trigger additional installs that depend on a GO being completely installed before certain methods can be called successfully.
 * (Game Cycle) if **GO.locatable** flag is set, register with the **Locator** service.
 * (Game Cycle) if **RequireLocatable** is implemented, register mappings with **Locator**.
-* (Game Cycle) if **RequireTimer** or **TimerCallback** are implemented, register with **TimerService**.  The **RequireTimer** takes priority here, so a GO implementing both interfaces must register itself in **RequireTimer**.
+* (Game Cycle) if **RequireTimer** or **TimerCallback** are implemented, register with **TimerService**.  The **RequireTimer** takes priority here, so a GO implementing both interfaces must put itself in **RequireTimer**.
 * (Game Cycle) if the install request contains a **route**, obtain each GO from the **Locator** and pass installed GO to its **LoadedCallback** (if implemented).

 #Uninstall Pipeline
@@ -68,6 +68,15 @@

 ##Unloaded Callback
 The dual of the **Loaded** callback is the **Unloaded** callback.  This is meant to undo whatever the effect of **Loaded** was.
+
+##Default Behavior
+
+1. (Game Cycle) Obtain the **update lock** for the remainder of the steps.
+* (Game Cycle) call the **objectUnloaded()** method, passing the GO and error status.
+* (Game Cycle) if **RequireTimer** or **TimerCallback** are implemented, unregister with **TimerService**.  The **RequireTimer** takes priority here, so a GO implementing both interfaces must put itself in **RequireTimer**.
+* (Game Cycle) if **RequireLocatable** is implemented, remove mappings from **Locator**.
+* (Game Cycle) if **GO.locatable** flag is set, remove from the **Locator** service.
+* (Game Cycle) if the uninstall request contains a **route**, obtain each GO from the **Locator** and pass installed GO to its **UnloadedCallback** (if implemented).

 #Event Pipeline
 This pipeline is for making asynchronous requests for additional code to execute.  This makes it convenient to schedule something to happen after the current method completes, and keeps the model in a consistent state, by not mutating it at that time.

Install Pipeline modified by g-dollar

g-dollar — Mon, 13 May 2013 10:41:39 -0000

--- v15
+++ v16
@@ -83,3 +83,10 @@

 ##Event Callback
 This callback gets the GO that was sent as the event.  This is an excellent place to put game logic.
+
+##Default Behavior
+This is how the Game Cycle thread handles Event Requests:
+
+1. (Game Cycle) Obtain the **update lock** for the remainder of the steps.
+* (Game Cycle) call the **objectEvent()** method, passing the GO.  This is a good place to trigger additional installs/uninstalls/events that are **unrouted** or you want to process it before any **route** targets do.
+* (Game Cycle) if the event request contains a **route**, obtain each GO from the **Locator** and pass event GO to its **EventCallback** (if implemented).

Install Pipeline modified by g-dollar

g-dollar — Mon, 13 May 2013 10:32:49 -0000

--- v14
+++ v15
@@ -1,12 +1,20 @@
-Game objects (hereafter **GO**) opt-in for system services by implementing the *marker interface* of each required service.  These interfaces follow the naming pattern **RequireXXX** where **XXX** represents the service.
+A **Pipeline** is a fancy name for an asynchronous send/receive model, where the receive side uses **marker interfaces** to determine what to call on the received object.

-The goals of the Install Pipeline:
+To encourage indirect coupling, you specify the names of target components via a **route**, so the call-site determines which other components "see" the pipeline GO on "the other end".
+
+AGE has these pipelines:
+
+* Install: for loading data and connecting to GOs.
+* Uninstall: for reversing the effect of Install.
+* Event: for inter-GO communication.
+
+The goals of the Pipelines:

 * Asynchronous design acknowledges the task of resource acquisition and offloads that work to a different thread.
-* Easy to add/remove a GO at the call site.  A call to **install()** does it all!
-* Require minimum information "in hand"; just the GO to install, and the **Installer** interface.
-* Standard way for everything to be initialized and "enter" the system.
-* Uniform "context" (threading, locking, interfaces) to perform these actions.
+* Easy to target a GO at the call site.  A call to **install/uninstall/event()** does it all!
+* Require minimum information "in hand"; just the GO to operate on, and the **Installer** interface.
+* Standard way for everything to be initialized and enter/exit the system.
+* Uniform "top-level context" (threading, locking, interfaces) to perform these actions.

 [TOC]

@@ -22,7 +30,11 @@
 Indicates requirement for registering multiple name/GO mappings in the Locator.

 #Install Pipeline
-The install pipeline is asynchronous; it is started by calling the *install()* method, and passing the GO to install.  The object should be minimally initialized at this point, because the Resource Loader thread will take over the actual "work" of initializing.
+The Install pipeline is asynchronous; it is started by calling the *install()* method, and passing the GO to install.  The GO should be minimally initialized at this point, because the Pipeline will take over the actual "work" of initializing.
+
+Game objects (hereafter **GO**) opt-in for system services by implementing the *marker interface* of each required service.  These interfaces follow the naming pattern **RequireXXX** where **XXX** represents the service.
+
+The first stop on the Install Pipeline is a dedicated Resource Loader thread for the time-consuming work of initializing a GO from resources, e.g. texture bitmaps, object models, etc.

 ##Load Request
 The **LoadObject** message contains the information used by the threads in the Install Pipeline:
@@ -30,10 +42,12 @@
 * the GO to target.
 * a reply-to **TaskChannel** to notify when complete.
 * a **LoadedCallback** to execute in that context when it receives this message.  The Game Cycle uses a **LoadedCallback** that's outlined below.
-* an optional list of **bind targets** to have their **LoadedCallback** invoked.
+* an optional list of **bind targets**, called a **route**, to have their **LoadedCallback** invoked.

 ##Loaded Callback
 This is called for every GO that completes the install pipeline.  It is called on the Game Cycle's thread, so thread-safety is necessary if interacting with the UI (or other) thread of the application.
+
+This is a top-level context with the **update lock** held.

 ##Default Behavior
 The install pipeline proceeds as follows (the thread executing is in parentheses):
@@ -45,7 +59,27 @@
 * (Game Cycle) if **GO.locatable** flag is set, register with the **Locator** service.
 * (Game Cycle) if **RequireLocatable** is implemented, register mappings with **Locator**.
 * (Game Cycle) if **RequireTimer** or **TimerCallback** are implemented, register with **TimerService**.  The **RequireTimer** takes priority here, so a GO implementing both interfaces must register itself in **RequireTimer**.
-* (Game Cycle) if the install request contains **bind targets**, obtain each GO from the **Locator** and pass installed GO to its **LoadedCallback** (if implemented).
+* (Game Cycle) if the install request contains a **route**, obtain each GO from the **Locator** and pass installed GO to its **LoadedCallback** (if implemented).

 #Uninstall Pipeline
 The uninstall pipeline reverses the operations of the install pipeline, but does not execute anything in the Resource Loader thread.
+
+This is a top-level context with the **update lock** held.
+
+##Unloaded Callback
+The dual of the **Loaded** callback is the **Unloaded** callback.  This is meant to undo whatever the effect of **Loaded** was.
+
+#Event Pipeline
+This pipeline is for making asynchronous requests for additional code to execute.  This makes it convenient to schedule something to happen after the current method completes, and keeps the model in a consistent state, by not mutating it at that time.
+
+The **GameObject** class is reused here to represent an event.
+
+To participate in the Event pipeline, a target GO must be in the **Locator** and implement the **EventCallback** interface.  The Event pipeline does not check for any other marker interfaces.
+
+This is a top-level context with the **update lock** held.
+
+##Event Request
+This is analogous to the **LoadObject** request.  The most-important part of this is the **route**.
+
+##Event Callback
+This callback gets the GO that was sent as the event.  This is an excellent place to put game logic.

Install Pipeline modified by g-dollar

g-dollar — Tue, 07 May 2013 17:05:07 -0000

--- v13
+++ v14
@@ -39,7 +39,7 @@
 The install pipeline proceeds as follows (the thread executing is in parentheses):

 1. (Caller) Call the **install()** method, which sends a message to the Resource Loader thread and returns.  the reply-to target is the Game Cycle, and the **LoadedCallback** is the remainder of the steps from step 3.  **Do not access the GO** after this point, until **objectLoaded()** is called (step 4).
-* (Resource Loader) If **RequireResourceLoader** is implemented, invokes the **GO.load()** method, passing **Resources** interface.  When this completes, the load request is passed to the reply-to target (Game Cycle).
+* (Resource Loader) If **RequireResourceLoader** is implemented, invokes the **GO.load()** method, passing **ResourceLoader** and **Resources** interfaces.  If not implemented, no action is taken; this is done to maintain the order of **install** calls with their callbacks.  When complete, the load request is passed to the reply-to target (Game Cycle).
 * (Game Cycle) Obtain the **update lock** for the remainder of the steps.
 * (Game Cycle) call the **objectLoaded()** method, passing the GO and error status.  This is a good place to trigger additional installs that depend on a GO being completely installed before certain methods can be called successfully.
 * (Game Cycle) if **GO.locatable** flag is set, register with the **Locator** service.

Install Pipeline modified by g-dollar

g-dollar — Fri, 03 May 2013 14:28:32 -0000

--- v12
+++ v13
@@ -29,26 +29,23 @@

 * the GO to target.
 * a reply-to **TaskChannel** to notify when complete.
-* a **LoadedCallback** to execute in that context when it receives this message.
+* a **LoadedCallback** to execute in that context when it receives this message.  The Game Cycle uses a **LoadedCallback** that's outlined below.
 * an optional list of **bind targets** to have their **LoadedCallback** invoked.

 ##Loaded Callback
-This is called for every GO that completes the install pipeline.  It is called on the Game Cycle's thread, so thread-safety is necessary if interacting with the UI thread of the application.
+This is called for every GO that completes the install pipeline.  It is called on the Game Cycle's thread, so thread-safety is necessary if interacting with the UI (or other) thread of the application.

-This callback is also a good place to "sequence" installs of GO's that depend on other GO's being completely installed first, via additional calls to **install()**.
-
-The Game Cycle uses a **LoadedCallback** that's outlined below.
-
+##Default Behavior
 The install pipeline proceeds as follows (the thread executing is in parentheses):

 1. (Caller) Call the **install()** method, which sends a message to the Resource Loader thread and returns.  the reply-to target is the Game Cycle, and the **LoadedCallback** is the remainder of the steps from step 3.  **Do not access the GO** after this point, until **objectLoaded()** is called (step 4).
 * (Resource Loader) If **RequireResourceLoader** is implemented, invokes the **GO.load()** method, passing **Resources** interface.  When this completes, the load request is passed to the reply-to target (Game Cycle).
 * (Game Cycle) Obtain the **update lock** for the remainder of the steps.
-* (Game Cycle) call the **objectLoaded()** method, passing the GO and error status.
+* (Game Cycle) call the **objectLoaded()** method, passing the GO and error status.  This is a good place to trigger additional installs that depend on a GO being completely installed before certain methods can be called successfully.
 * (Game Cycle) if **GO.locatable** flag is set, register with the **Locator** service.
+* (Game Cycle) if **RequireLocatable** is implemented, register mappings with **Locator**.
 * (Game Cycle) if **RequireTimer** or **TimerCallback** are implemented, register with **TimerService**.  The **RequireTimer** takes priority here, so a GO implementing both interfaces must register itself in **RequireTimer**.
-* (Game Cycle) if **RequireLocatable** is implemented, register mappings with **Locator**.
-* (Game Cycle) if the install request contains **bind targets**, obtain each GO from the **Locator** and pass the GO to its **LoadedCallback** (if implemented).
+* (Game Cycle) if the install request contains **bind targets**, obtain each GO from the **Locator** and pass installed GO to its **LoadedCallback** (if implemented).

 #Uninstall Pipeline
 The uninstall pipeline reverses the operations of the install pipeline, but does not execute anything in the Resource Loader thread.

Install Pipeline modified by g-dollar

g-dollar — Fri, 03 May 2013 14:13:37 -0000

--- v11
+++ v12
@@ -21,17 +21,23 @@
 ##RequireLocatable
 Indicates requirement for registering multiple name/GO mappings in the Locator.

-#Load Request
+#Install Pipeline
+The install pipeline is asynchronous; it is started by calling the *install()* method, and passing the GO to install.  The object should be minimally initialized at this point, because the Resource Loader thread will take over the actual "work" of initializing.
+
+##Load Request
 The **LoadObject** message contains the information used by the threads in the Install Pipeline:

-* the GO to target
-* a reply-to **TaskChannel** to notify when complete
-* a **LoadedCallback** to execute in that context when it receives this message
+* the GO to target.
+* a reply-to **TaskChannel** to notify when complete.
+* a **LoadedCallback** to execute in that context when it receives this message.
+* an optional list of **bind targets** to have their **LoadedCallback** invoked.
+
+##Loaded Callback
+This is called for every GO that completes the install pipeline.  It is called on the Game Cycle's thread, so thread-safety is necessary if interacting with the UI thread of the application.
+
+This callback is also a good place to "sequence" installs of GO's that depend on other GO's being completely installed first, via additional calls to **install()**.

 The Game Cycle uses a **LoadedCallback** that's outlined below.
-
-#Install Pipeline
-The install pipeline is asynchronous; it is started by calling the *install()* method, and passing the GO to install.  The object should be minimally initialized at this point, because the Resource Loader thread will take over the actual "work" of initializing.

 The install pipeline proceeds as follows (the thread executing is in parentheses):

@@ -39,16 +45,10 @@
 * (Resource Loader) If **RequireResourceLoader** is implemented, invokes the **GO.load()** method, passing **Resources** interface.  When this completes, the load request is passed to the reply-to target (Game Cycle).
 * (Game Cycle) Obtain the **update lock** for the remainder of the steps.
 * (Game Cycle) call the **objectLoaded()** method, passing the GO and error status.
-* (Game Cycle) register with the **Locator** service.
+* (Game Cycle) if **GO.locatable** flag is set, register with the **Locator** service.
 * (Game Cycle) if **RequireTimer** or **TimerCallback** are implemented, register with **TimerService**.  The **RequireTimer** takes priority here, so a GO implementing both interfaces must register itself in **RequireTimer**.
 * (Game Cycle) if **RequireLocatable** is implemented, register mappings with **Locator**.
-* (Game Cycle) if the GO is an instance of **Scene**, register it with **RenderService**.  Otherwise, if there is no **bind-to namelist** obtain the current **Scene** and pass the GO to its **LoadedCallback**.
-* (Game Cycle) if the install request contains a **bind-to namelist**, obtain each GO from the **Locator** and pass the GO to its **LoadedCallback** (if implemented).
-
-##Loaded Callback
-This is called for every GO that completes the install pipeline.  It is called on the Game Cycle's thread, so thread-safety is necessary if interacting with the UI thread of the application.
-
-This callback is also a good place to "sequence" installs of GO's that depend on other GO's being completely installed first, via additional calls to **install()**.
+* (Game Cycle) if the install request contains **bind targets**, obtain each GO from the **Locator** and pass the GO to its **LoadedCallback** (if implemented).

 #Uninstall Pipeline
 The uninstall pipeline reverses the operations of the install pipeline, but does not execute anything in the Resource Loader thread.