.

include/wendelin/bigfile/file.h

@@ -129,7 +129,8 @@ struct bigfile_ops {
      *      virt_unlock()
      *
      * XXX mention VMA.mmap_overlay_server?
-     * called under virtmem lock
+     *
+     * Called under virtmem lock.
      *
      * NOTE blk and blklen are in blocks, not pages.
      *
@@ -142,14 +143,14 @@ struct bigfile_ops {
     // remmap_blk_read is called to remmap a block into vma again, after e.g.
     // RW dirty page was discarded.
     //
-    // called under virtmem lock.
+    // Called under virtmem lock.
     //
     // XXX error -> bug (must not fail)
     int (*remmap_blk_read) (VMA *vma, BigFile *file, blk_t blk);
 
     /* munmap is called when vma set up via mmap_setup_read is going to be unmapped.
      *
-     * called under virtmem lock.
+     * Called under virtmem lock.
      * Must not fail.
      */
     void (*munmap) (VMA *vma, BigFile *file);

wcfs/client/wcfs.cpp

@@ -390,6 +390,7 @@ error _FileH::close() {
     xerr::Contextf E("wcfs %s: conn @%s: close f<%s>", v(wconn->_wc->mountpoint), v(wconn->at), v(fileh.foid));
 
     // XXX change all fileh.mmaps to cause EFAULT on any access after fileh.close
+    // XXX "watch foid -" -> wconn.wlink (stop watchingthe file)
 
     // remove fileh from wconn._filehtab
     // fileh.close can be called several times and after first call another
@@ -405,7 +406,8 @@ error _FileH::close() {
 
 // mmap creates file mapping representing file[blk_start +blk_len) data as of wconn.at database state.
 //
-// If vma != nil, created mapping is associated with that vma of user-space virtual memory manager.
+// If vma != nil, created mapping is associated with that vma of user-space virtual memory manager:
+// virtmem calls FileH::mmap under virtmem lock when virtmem fileh is mmapped into vma.
 pair<Mapping, error> _FileH::mmap(int64_t blk_start, int64_t blk_len, VMA *vma) {
     _FileH& f = *this;
     xerr::Contextf E("wcfs %s: conn @%s: mmap f<%s> [blk%ld +blk%ld)",
@@ -430,6 +432,7 @@ pair<Mapping, error> _FileH::mmap(int64_t blk_start, int64_t blk_len, VMA *vma)
     // XXX wconn.atMu.RLock()
     // XXX defer wconn.atMu.RUnlock()
 
+    // NOTE virtmem lock is held by virtmem caller
     // XXX f locking?
 
     // create memory with head/f mapping and applied pins
@@ -491,18 +494,17 @@ pair<Mapping, error> _FileH::mmap(int64_t blk_start, int64_t blk_len, VMA *vma)
 // unmap releases mapping memory from address space.
 //
 // After call to unmap the mapping must no longer be used.
+// The association in between mapping and linked virtmem VMA is reset.
 //
-// virtmem calls unmap when VMA is unmapped, thus
-// unmap must be called under virtmem lock for mappings associated with a VMA.
-// The association in between mapping and linked VMA is reset.
+// Virtmem calls Mapping.unmap under virtmem lock when VMA is unmapped.
 error _Mapping::unmap() {
     Mapping mmap = newref(this);    // XXX newref for std::remove
     FileH f = mmap->fileh;
     xerr::Contextf E("wcfs %s: conn @%s: f<%s>: unmap",
             v(f->wconn->_wc->mountpoint), v(f->wconn->at), v(f->foid));
 
+    // NOTE virtmem lock is held by virtmem caller
     // XXX locking
-    // XXX make sure mmap cannot be XXX
 
     if (mmap->vma != nil) {
         mmap->_assertVMAOk();
@@ -615,6 +617,7 @@ error _Mapping::_remmapblk(int64_t blk, zodb::Tid at) {
     xerr::Contextf E("wcfs %s: conn @%s: f<%s>: remmapblk #%ld @%s",
             v(f->wconn->_wc->mountpoint), v(f->wconn->at), v(f->foid), blk, v(at));
 
+    // XXX locking done by callers (document)
 
     ASSERT(mmap->blk_start <= blk && blk < mmap->blk_stop());
     error err;
@@ -663,11 +666,15 @@ error _Mapping::_remmapblk(int64_t blk, zodb::Tid at) {
 }
 
 // remmap_blk remmaps file[blk] in its place again.
-// virtmem calls this to remmap a block after RW dirty page was e.g. discarded.
+//
+// Virtmem calls Mapping.remmap_blk under virtmem lock to remmap a block after
+// RW dirty page was e.g. discarded.
 error _Mapping::remmap_blk(int64_t blk) {
     _Mapping& mmap = *this;
 
+    // NOTE virtmem lock is held by virtmem caller
     // XXX locking
+
     if (!(mmap.blk_start <= blk && blk < mmap.blk_stop()))
         panic("remmap_blk: blk out of Mapping range");