memory: update docs

docs/design/part-memory.txt

@@ -68,29 +68,62 @@ can free the memory. The GstMemoryFreeFunction of the allocator will be called
 to cleanup the memory.
 
 
-Sharing
--------
+Access management
+-----------------
 
 GstMemory objects can be shared between multiple GstBuffer objects. It is
-important that when a thread writes to the shared memory that the other
-buffer don't not see the changes.
+important that when a thread writes to the shared GstMemory that the other
+buffers don't not see the changes.
 
-We add a separate shared counter that counts the amount of objects that share
-this GstMemory object. The counter is initially 0, meaning that the object is
-not shared with any object. When a GstBuffer (or other object) adds a ref to
-the GstMemorty, it will also increase the shared count.
+We need 2 concepts:
 
-When the GstMemory is removed from the buffer, the ref count and the shared
-counter will be decreased.
+ - count how many objects are sharing this GstMemory (exclusive counter)
+ - control the READ/WRITE access to the GstMemory (locking)
 
-We don't want to use the refcount for this purpose because language bindings
-might keep arbitrary references to the object.
+* exclusive counter
 
-A GstMemory object with a shared counter > 1 is not writable. Any attempt to
-map with WRITE access or resize will fail. _make_mapped() with WRITE access
-will make a copy.
+ Each object that wants to keep a reference to the GstMemory and doesn't want to
+ see the changes from other owners of the same GstMemory needs to lock the
+ GstMemory in EXCLUSIVE mode, which will increase the exclusive counter.
 
+ The exclusive counter counts the amount of objects that share this GstMemory
+ object. The counter is initially 0, meaning that the object is not shared with
+ any object. When a GstBuffer (or other object) receives a ref to a GstMemory,
+ it will lock in EXCLUSIVE mode.
 
+ When the GstMemory is removed from the buffer, both the ref count and the
+ exclusive counter will be decreased with gst_object_unref() and
+ gst_memory_unlock () respectively.
+
+* locking
+
+ All read and write access must be performed between a gst_memory_lock() and
+ gst_memory_unlock() pair with the requested access method.
+
+ A gst_memory_lock() can fail when a WRITE lock is requested and the exclusive
+ counter is > 1. Indeed a GstMemory object with an exclusive counter > 1 is
+ locked EXCLUSIVELY by at least 2 objects and is therefore not writable. 
+ 
+ Once the memory is locked with a certain access mode, it can be recursively
+ locked with the same or narrower access mode. For example, first locking the
+ memory in READWRITE mode allows you to recusively lock the memory in
+ READWRITE, READ and WRITE mode. Memory locked in READ mode cannot be locked
+ recursively in WRITE or READWRITE mode. 
+
+ Note that multiple threads can READ lock the memory concurrently but cannot
+ lock the memory in WRITE mode because the exclusive counter must be > 1.
+
+ All calls to gst_memory_lock() need to be paired with one gst_memory_unlock()
+ call with the same access mode. When the last refcount of the memory is
+ removed, the should be no more outstanding locks.
+
+Note that a shared counter of both 0 and 1 leaves the memory writable. The
+reason is to make it easy to create and pass ownership of the memory to
+another object while keeping it the memory writable. When the memory is
+created with a shared count of 0, it is writable. When the memory is then
+added to another object, the shared count is incremented to 1 and the memory
+remains writable. The 0 share counter has a similar purpose as the floating
+reference in GObject.
 
 
 Memory layout
@@ -128,10 +161,14 @@ Data Access
  the required memory mappings when needed.
 
  Mapping a memory region requires the caller to specify the access method: READ
- and/or WRITE.
+ and/or WRITE. Mapping a memory region will first try to get a lock on the
+ memory in the requested access mode. This means that the map operation can
+ fail when WRITE access is requested on a non-writable memory object (it has
+ an exclusive counter > 1, the memory is already locked in an incompatible
+ access mode or the memory is marked readonly).
 
  After the data has been accessed in the object, the unmap call must be
- performed.
+ performed, which will unlock the memory again.
 
  It is allowed to map multiple times with different access modes. for each of
  the map calls, an corresponding unmap call needs to be made. WRITE-only memory