- more on the map cache, update some of the functions

1 files changed, 42 insertions, 18 deletions

diff --git a/doc/sch-design.txt b/doc/sch-design.txt
index 090def4..ad4c2ff 100644
--- a/doc/sch-design.txt
+++ b/doc/sch-design.txt
@@ -8,9 +8,34 @@ as needed.
 
 == Map Cache ==
 
-The map cache keeps a dynamically-constructed set of tree locations in
-memory, grouped by the name of their top-level container, and maintains
-each set of entries inside of a specific subcontainer.
+The map cache keeps a dynamically-constructed group of sets of entries
+in memory, grouped by the name of their top-level container, and for
+each set of entries maintains a copy of the set's releative
+distinguished name.  The map cache can be used to quickly answer whether
+or not a particular search request crosses into the portion of the DIT
+which is "served" by the data in the cache.
+
+=== Internal Representation ===
+
+At the topmost level, the map cache is a table.  Each entry in the table
+contains the name of a top-level container entry and a table of sets.
+
+Each set in a container's table of sets contains the relative
+distinguished name (RDN) of the set, a linked list of map entries, and a
+set of indexes into the list.  Each set can also hold a data pointer on
+behalf of the backend.
+
+Each item in a set's list of entries contains the entry's relative
+distinguished name (relative to the set, which is itself relative to the
+group-of-sets container), the entry's whole distinguished name, a unique
+identifier (which, currently, stores the NDN of the directory server
+entry which was used to create this entry) and a data pointer which is
+kept on behalf of the backend (which, currently, stores a Slapi_DN for
+the directory server entry which was used to create this entry and the
+full Slapi_Entry for the generated entry).
+
+The set indexes its entry list using an entry's unique identifier and
+its relative distinguished name.
 
 == Back End ==
 
@@ -107,12 +132,12 @@ need to escape the double-quote using a '\' character.  Naturally the
 === Implemented Functions ===
   * first(PATTERN[,DEFAULT])
     - Evaluates the pattern, and if one or more values is available,
-      provides that value.  If no values result, then DEFAULT is
+      provides the first value.  If no values result, then DEFAULT is
       evaluated as a pattern and the result is provided.
   * match(ATTRIBUTE,PATTERN[,DEFAULT])
     - Selects the value of ATTRIBUTE which matches the globbing pattern
-      PATTERN.  If zero or two or more values match, and a DEFAULT was
-      specified, the DEFAULT is produced, otherwise an error occurs.
+      PATTERN.  If no values match, and a DEFAULT was specified, the
+      DEFAULT is produced, otherwise an error occurs.
     - Example (examining "cn=group"):
         dn: cn=group
 	member: bob
@@ -125,9 +150,8 @@ need to escape the double-quote using a '\' character.  Naturally the
       %match("member","*","jim")  -> bob,dave (when a list is acceptable)
   * regmatch(ATTRIBUTE,PATTERN[,DEFAULT])
     - Selects the value of ATTRIBUTE which matches the extended regular
-      expression PATTERN.  If zero or two or more values match, and a
-      DEFAULT was specified, the DEFAULT is produced, otherwise an error
-      occurs.
+      expression PATTERN.  If no values match, and a DEFAULT was
+      specified, the DEFAULT is produced.
     - Example (examining "cn=group"):
         dn: cn=group
 	member: bob
@@ -142,10 +166,10 @@ need to escape the double-quote using a '\' character.  Naturally the
   * regsub(ATTRIBUTE,PATTERN,TEMPLATE[,DEFAULT])
     - Selects the value of ATTRIBUTE which matches the extended regular
       expression PATTERN and uses TEMPLATE to construct the output.  If
-      zero or two or more values match, and a DEFAULT was specified, the
-      DEFAULT is produced, otherwise an error occurs.  The template is
-      used to construct a result using the n'th substring from the
-      matched value by using the sequence "%n" in the template.
+      no values match, and a DEFAULT was specified, the DEFAULT is
+      produced, otherwise an error occurs.  The template is used to
+      construct a result using the n'th substring from the matched value
+      by using the sequence "%n" in the template.
     - Example (examining "cn=group"):
         dn: cn=group
 	member: bob
@@ -159,8 +183,7 @@ need to escape the double-quote using a '\' character.  Naturally the
       %regsub("member","^e.*","%1","jim") -> jim
   * deref(THISATTRIBUTE,THATATTRIBUTE)
     - Creates a separated list of the values of THATATTRIBUTE for
-      directory entries named by this entry's THISATTRIBUTE.  Will fail
-      if used to attempt to generate an RDN.
+      directory entries named by this entry's THISATTRIBUTE.
     - Example (examining "cn=group"):
         dn: cn=group
 	member: uid=bob
@@ -177,9 +200,10 @@ need to escape the double-quote using a '\' character.  Naturally the
       %deref(",","member","uid") -> bob,pete (when a list is acceptable)
   * referred(SET,THATATTRIBUTE,THATOTHERATTRIBUTE)
     - Creates a separated list of the values of THATOTHERATTRIBUTE for
-      directory entries which have entries in the named SET and which
-      also have this entry's name as a value for THATATTRIBUTE.  Will
-      fail if used to attempt to generate an RDN.
+      directory entries which have entries in the current group in the
+      named SET and which also have this entry's name as a value for
+      THATATTRIBUTE.  Will fail if used in a context where a single
+      value is required.
     - Example (examining "cn=group"):
         dn: cn=group
         -