Changes between Version 1 and Version 2 of WatchedObjects


Ignore:
Timestamp:
Oct 10, 2009, 2:35:28 AM (10 years ago)
Author:
rme
Comment:

--

Legend:

Unmodified
Added
Removed
Modified
  • WatchedObjects

    v1 v2  
    1010The WATCH function arranges for the specified object to be monitored
    1111for writes.  This is done via the system's memory-management hardware,
    12 so read-only access to the object runs at full speed.
     12so reading the object takes place at full speed.
    1313
    1414When any write to the object is attempted, the condition
     
    3636
    3737
     38'''PRIMITIVE-WATCH object [function]'''
     39
     40Like WATCH, except it doesn't give ''object'' any
     41special treatment;  it simply uses it as-is.
     42
     43
    3844'''UNWATCH object [function]'''
    3945
     
    4349object is returned.
    4450
    45 A note on thread-safety: avoid unwatching an object when a
    46 WRITE-TO-WATCHED-OBJECT condition might be being handled in some other
    47 thread.  The lisp tries to detect when it would be unsafe to unwatch
     51A note on thread-safety: avoid unwatching an object from a thread while
     52some other thread might be signaling or handling a
     53WRITE-TO-WATCHED-OBJECT condition.
     54The lisp tries to detect when it would be unsafe to unwatch
    4855an object; UNWATCH will return NIL and not unwatch the object in such
    4956a case.  Nevertheless, there may be subtle race conditions lurking
     
    5158
    5259
    53 '''WATCHED-OBJECT-AND-LOCATION condition [function]'''
    54 
    55 When passed a WRITE-TO-WATCHED-OBJECT condition, this function
    56 returns, as multiple values, the "user-level" object that is the
    57 destination of the write and the "location" (index, key, or slot name)
    58 of the write within the object, if that can be determined.
    59 
    60 
    6160'''WRITE-TO-WATCHED-OBJECT [condition]'''
    6261
    6362This condition is signaled when a watched object is written to.  There
    64 are two slots of interest: the "object" slot and the "location" slot.
     63are three slots of interest: the "object" slot, the "containing-object"
     64slot, and the "location" slot.
    6565
    66 The object slot is the "user-level" object that was written.  That is,
    67 if the user did (watch some-hash-table), then the object slot will
    68 contain some-hash-table, even though the actual object that was
    69 written to is the underlying hash-table-vector.
     66The object slot is the actual object that was the target of a write operation.
     67
     68If the object slot contains something that is a part of some larger
     69composite object, then the containing-object slot will contain
     70that object.  For example, if object is a hash-table-vector, then the
     71contents of the containing-object will be the hash table of which the
     72hash-table-vector is a part.  If the contents of object slot
     73aren't part of any larger object, then the containing-object and
     74object slots will contain the same thing.
    7075
    7176The contents of the location slot differs according to what is in the
     
    7782name.  If object is a cons cell, location will be either the actual
    7883car or cdr of the cons cell, depending on which half of the cons cell
    79 was written to.  If location is NIL, the location could not be
     84was written to.  If the object is some other uvector, then location
     85will contain the uvector index of the element that was about to be
     86written.  If location is NIL, the location could not be
    8087determined.