Changeset 2840 for trunk/kLdr/kLdrInternal.h

Timestamp:

Oct 29, 2006, 2:32:25 AM (19 years ago)

Author:

bird

Message:

think I got the state stuff right now.

File:

• trunk/kLdr/kLdrInternal.h (modified) (3 diffs)

trunk/kLdr/kLdrInternal.h

@@ -65 +65 @@
 /**
  * The state of a dynamic loader module.
+ * @image html KLDRSTATE.gif "The state diagram"
  */
 typedef enum KLDRSTATE
@@ -70 +71 @@
     /** The usual invalid 0 enum. */
     KLDRSTATE_INVALID = 0,
-    /** The module has just been opened and has no references.
+
+    /** The module has just been opened and linked into the load list.
+     *
      * Prev state: -
-     * Next state: MAPPED, DESTROYED
+     * Next state: MAPPED, PENDING_DESTROY
      */
     KLDRSTATE_OPEN,
-    /** The module been mapped.
+
+    /** The module segments has been mapped into the process memory.
+     *
      * Prev state: OPEN
-     * Next state: LOADED_PREREQUISITES, DESTROYED
+     * Next state: LOADED_PREREQUISITES, PENDING_DESTROY
      */
     KLDRSTATE_MAPPED,
     /** The module has been reloaded and needs to be fixed up again.
-     * (The loader can still be in a re-entrant mode.)
+     * This can occure when the loader is called recursivly.
+     *
+     * The reason RELOADED modules must go back to the PENDING_GC state is
+     * because we want to guard against uninit order issues, and therefore
+     * doesn't unmap modules untill all pending termintation callbacks has
+     * been executed.
+     *
      * Prev state: PENDING_GC
-     * Next state: LOADED_PREREQUISITES, PENDING_GC
+     * Next state: RELOADED_LOADED_PREREQUISITES, PENDING_GC
      */
     KLDRSTATE_RELOADED,
+
     /** The immediate prerequisites have been loaded.
-     * Prev state: MAPPED, RELOADED
-     * Next state: FIXED_UP, DESTROYED
+     *
+     * Prev state: MAPPED
+     * Next state: FIXED_UP, PENDING_DESTROY
      */
     KLDRSTATE_LOADED_PREREQUISITES,
+    /** The immediate prerequisites have been loaded for a reloaded module.
+     *
+     * Prev state: RELOADED
+     * Next state: RELOADED_FIXED_UP, PENDING_GC
+     */
+    KLDRSTATE_RELOADED_LOADED_PREREQUISITES,
+
     /** Fixups has been applied.
+     *
      * Prev state: LOADED_PREREQUISITES
-     * Next state: PENDING_INIT, DESTROYED
+     * Next state: PENDING_INITIALIZATION, PENDING_DESTROY
      */
     KLDRSTATE_FIXED_UP,
+    /** Fixups has been applied.
+     *
+     * Prev state: RELOADED_LOADED_PREREQUISITES
+     * Next state: PENDING_INITIALIZATION, PENDING_GC
+     */
+    KLDRSTATE_RELOADED_FIXED_UP,
+
     /** Pending initialization.
-     * (The loader can now be in a re-entrant mode.)
-     * Prev state: FIXED_UP
-     * Next state: PENDING_INITIALIZATION, PENDING_GC
+     * While the module is in this state the loader is in reentrant mode.
+     *
+     * Prev state: FIXED_UP, RELOADED_FIXED_UP
+     * Next state: INITIALIZATION, PENDING_GC
      */
     KLDRSTATE_PENDING_INITIALIZATION,
+
     /** Initializing.
-     * (The loader is now in a re-entrant mode.)
+     * While the module is in this state the loader is in reentrant mode.
+     *
      * Prev state: PENDING_INITIALIZATION
      * Next state: GOOD, PENDING_GC
      */
     KLDRSTATE_INITIALIZING,
+
+    /** Initialization failed.
+     *
+     * This is somewhat similar to PENDING_GC except that, a module
+     * in this state cannot be reloaded untill we've done GC. This ensures
+     * that a init failure during recursive loading is propagated up.
+     *
+     * While the module is in this state the loader is in reentrant mode.
+     *
+     * Prev state: INITIALIZING
+     * Next state: GC
+     */
+    KLDRSTATE_INITIALIZATION_FAILED,
+
     /** The module has been successfully loaded and initialized.
-     * (The loader can still be in a re-entrant mode.)
+     * While the module is in this state the loader can be in reentrant
+     * or 'unused' mode.
+     *
      * Prev state: INITIALIZING
      * Next state: PENDING_TERMINATION
-     * Re-entrant.
      */
     KLDRSTATE_GOOD,
+
     /** Pending termination, reference count is 0.
-     * (The loader can now be in a re-entrant mode.)
+     * While the module is in this state the loader is in reentrant mode.
+     *
      * Prev state: GOOD
      * Next state: TERMINATING, GOOD
      */
     KLDRSTATE_PENDING_TERMINATION,
+
     /** Terminating, reference count is still 0.
-     * (The loader is now in a re-entrant mode, but loading is a bit restricted.)
+     * While the module is in this state the loader is in reentrant mode.
+     *
      * Prev state: PENDING_TERMINATION
      * Next state: PENDING_GC
      */
     KLDRSTATE_TERMINATING,
+
     /** Pending garbage collection.
-     * (The loader can still be in a re-entrant mode.)
-     * Prev state: TERMINATING, INITIALIZING, PENDING_INITIALIZATION
+     *
+     * Prev state: TERMINATING, PENDING_INITIALIZATION, INITIALIZATION_FAILED
      * Next state: GC, RELOADED
      */
     KLDRSTATE_PENDING_GC,
+
     /** Being garbage collected.
-     * Prev state: PENDING_GC
+     *
+     * Prev state: PENDING_GC, INITIALIZATION_FAILED
      * Next state: PENDING_DESTROY, DESTROYED
      */
     KLDRSTATE_GC,
+
     /** The module has be unlinked, but there are still stack references to it.
-     * Prev state: GC
+     *
+     * Prev state: GC, FIXED_UP, LOADED_PREREQUISITES, MAPPED, OPEN
      * Next state: DESTROYED
      */
     KLDRSTATE_PENDING_DESTROY,
+
     /** The module has been destroyed and is no longer valid.
+     *
      * Prev state: GC, PENDING_DESTROY
      */
     KLDRSTATE_DESTROYED,
+
     /** The end of valid states (exclusive) */
     KLDRSTATE_END = KLDRSTATE_DESTROYED,
@@ -194 +252 @@
         struct KLDRDYLDMOD *pPrev;
     } Load;
-    /** The termination list linkage. */
+    /** The termination list linkage.
+     * A module will be linked into the termination list upon a successful
+     * return from module initialization. */
     struct
     {