stack-checker.dependencies: moving the add-depends-on-class word + new docs

basis/compiler/tree/propagation/known-words/known-words.factor

@@ -1,16 +1,15 @@
 ! Copyright (C) 2008, 2010 Slava Pestov.
 ! See http://factorcode.org/license.txt for BSD license.
 USING: accessors alien alien.accessors alien.data.private arrays
-assocs byte-arrays byte-vectors classes classes.algebra
-classes.tuple classes.tuple.private combinators
-compiler.tree.comparisons compiler.tree.propagation.constraints
-compiler.tree.propagation.info compiler.tree.propagation.simple
-compiler.tree.propagation.slots fry generic.math hashtables
-kernel kernel.private layouts locals math math.floats.private
-math.functions math.integers.private math.intervals math.libm
-math.parser math.partial-dispatch math.private namespaces sbufs
-sequences slots.private splitting strings strings.private
-vectors words ;
+assocs byte-arrays byte-vectors classes classes.algebra classes.tuple
+classes.tuple.private combinators compiler.tree.comparisons
+compiler.tree.propagation.constraints compiler.tree.propagation.info
+compiler.tree.propagation.simple compiler.tree.propagation.slots fry
+generic.math hashtables kernel kernel.private layouts locals math
+math.floats.private math.functions math.integers.private
+math.intervals math.libm math.parser math.partial-dispatch
+math.private namespaces sbufs sequences slots.private splitting
+stack-checker.dependencies strings strings.private vectors words ;
 FROM: alien.c-types => (signed-interval) (unsigned-interval) ;
 IN: compiler.tree.propagation.known-words
 

basis/compiler/tree/propagation/simple/simple.factor

@@ -5,8 +5,8 @@ classes.algebra.private classes.maybe classes.tuple.private
 combinators combinators.short-circuit compiler.tree
 compiler.tree.propagation.constraints compiler.tree.propagation.info
 compiler.tree.propagation.inlining compiler.tree.propagation.nodes
-compiler.tree.propagation.slots continuations fry kernel
-math.intervals sequences stack-checker.dependencies words ;
+compiler.tree.propagation.slots continuations fry kernel make
+sequences sets stack-checker.dependencies words ;
 IN: compiler.tree.propagation.simple
 
 M: #introduce propagate-before
@@ -22,20 +22,6 @@ M: #push propagate-before
 : set-value-infos ( infos values -- )
     [ set-value-info ] 2each ;
 
-GENERIC: add-depends-on-class ( obj -- )
-
-M: class add-depends-on-class
-    +conditional+ depends-on ;
-
-M: maybe add-depends-on-class
-    class>> add-depends-on-class ;
-
-M: anonymous-union add-depends-on-class
-    members>> [ add-depends-on-class ] each ;
-
-M: anonymous-intersection add-depends-on-class
-    participants>> [ add-depends-on-class ] each ;
-
 M: #declare propagate-before
     ! We need to force the caller word to recompile when the
     ! classes mentioned in the declaration are redefined, since

basis/stack-checker/dependencies/dependencies-docs.factor

@@ -1,30 +1,75 @@
-USING: help.markup help.syntax ;
+USING: classes help.markup help.syntax ;
 IN: stack-checker.dependencies
 
-HELP: +definition+
-{ $description "Word that indicates that the dependency is a definition dependency. It is a dependency among two words in which one word depends on the definition of the another. For example, if two words are defined as " { $snippet ": o ( -- ) i ;" } " and " { $snippet ": i ( -- ) ; inline" } ", then 'o' has a definition dependency to 'i' because 'i' is inline. If the definition of 'i' changes 'o' must be recompiled." } ;
-
-HELP: +effect+
-{ $description "Word that indicates that the dependency is an effect dependency." } ;
-
 HELP: +conditional+
 { $description "Word that indicates that the dependency is a conditional dependency." } ;
 
+HELP: +effect+
+{ $description "Word that indicates that the dependency is an effect dependency." } ;
+
+HELP: +definition+
+{ $description "Word that indicates that the dependency is a definition dependency. It is a dependency among two words in which one word depends on the definition of the another. For example, if two words are defined as " { $snippet ": o ( -- ) i ;" } " and " { $snippet ": i ( -- ) ; inline" } ", then 'o' has a definition dependency to 'i' because 'i' is inline. If the definition of 'i' changes 'o' must be recompiled." } ;
+
+HELP: add-depends-on-class
+{ $values { "obj" classoid } }
+{ $description "Adds a " { $link +conditional+ } " dependency from the word to the classes mentioned in the classoid." } ;
+
+HELP: conditional-dependencies
+{ $var-description "The current word's conditional dependency checks." } ;
+
 HELP: dependencies
 { $var-description "Words that the current quotation depends on." } ;
 
+HELP: depends-on-class-predicate
+{ $class-description "Objectifies a dependency on a class predicate." } ;
+
+HELP: depends-on-flushable
+{ $class-description "Conditional dependency on a " { $link \ flushable } " word. The dependency becomes unsatisfied if the word no longer is flushable." } ;
+
+HELP: generic-dependencies
+{ $var-description "Generic words that the current quotation depends on." } ;
+
 ARTICLE: "stack-checker.dependencies" "Definition Dependency Management"
-"This vocab manages dependency data during stack checking of words. All dependencies are divided into three types:"
+"This vocab manages dependency data during stack checking of words. All dependencies are divided into three types representing how words can depend on other words:"
 { $subsections
-  +conditional+
   +definition+
   +effect+
+  +conditional+
 }
-"Temporary state:"
+"The type of the dependency determines when a word that depends on another word that is recompiled itself has to be recompiled. For example if word a has a " { $link +definition+ } " dependency on word b, and b's definition is changed, then a must be recompiled. Another dependency type is " { $link +effect+ } " which means that word depends on the stack effect of another word. It is a weaker form of dependency than +definition+. A words definition can change without its stack effect changing, but it it's stack effect is changing it implies that its definition is also changed."
+$nl
+"The third dependency type, +conditional+ encodes a conditional dependency between a word and other word which is usually a class. A condition object, kept in the word property \"dependency-checks\" evaluates if the condition is satisfied or not. If it isn't satisfied, then the word is recompiled. The types of condition objects are:"
+{ $subsections
+  depends-on-class-predicate
+  depends-on-final
+  depends-on-flushable
+  depends-on-instance-predicate
+  depends-on-method
+  depends-on-next-method
+  depends-on-tuple-layout
+}
+"The main benefit of using these condition checks is to ensure that if a word is changed, it doesn't cause 'cascading' recompilations."
+$nl
+"During stack checking, state to build dependency data is kept in the following variables:"
 { $subsections
   conditional-dependencies
   dependencies
   generic-dependencies
+}
+"Words for adding various types of dependencies:"
+{ $subsections
+  add-depends-on-c-type
+  add-depends-on-class
+  add-depends-on-class-predicate
+  add-depends-on-final
+  add-depends-on-flushable
+  add-depends-on-generic
+  add-depends-on-instance-predicate
+  add-depends-on-method
+  add-depends-on-next-method
+  add-depends-on-tuple-layout
 } ;
 
+
+
 ABOUT: "stack-checker.dependencies"

basis/stack-checker/dependencies/dependencies.factor

@@ -1,8 +1,9 @@
 ! Copyright (C) 2009, 2010 Slava Pestov.
 ! See http://factorcode.org/license.txt for BSD license.
-USING: accessors alien.c-types arrays assocs classes
-classes.algebra classes.tuple combinators.short-circuit fry
-generic kernel math namespaces sequences sets words ;
+USING: accessors alien.c-types arrays assocs classes classes.algebra
+classes.algebra.private classes.maybe classes.tuple
+combinators.short-circuit fry generic kernel math namespaces sequences
+sets words ;
 FROM: classes.tuple.private => tuple-layout ;
 IN: stack-checker.dependencies
 
@@ -26,6 +27,20 @@ SYMBOLS: +effect+ +conditional+ +definition+ ;
         ] [ 3drop ] if
     ] if ;
 
+GENERIC: add-depends-on-class ( classoid -- )
+
+M: class add-depends-on-class
+    +conditional+ depends-on ;
+
+M: maybe add-depends-on-class
+    class>> add-depends-on-class ;
+
+M: anonymous-union add-depends-on-class
+    members>> [ add-depends-on-class ] each ;
+
+M: anonymous-intersection add-depends-on-class
+    participants>> [ add-depends-on-class ] each ;
+
 GENERIC: add-depends-on-c-type ( c-type -- )
 
 M: void add-depends-on-c-type drop ;