Document io.mmap and add mapped-file-closed? flag check

core/system/system-docs.factor

@@ -29,7 +29,7 @@ ARTICLE: "os" "System interface"
 { $subsection millis }
 "Exiting the Factor VM:"
 { $subsection exit }
-{ $see-also "file-streams" "network-streams" "io.launcher" } ;
+{ $see-also "file-streams" "network-streams" "io.launcher" "io.mmap" } ;
 
 ABOUT: "os"
 

extra/help/handbook/handbook.factor

@@ -131,7 +131,7 @@ ARTICLE: "collections" "Collections"
 { $subsection "graphs" }
 { $subsection "buffers" } ;
 
-USING: io.sockets io.launcher ;
+USING: io.sockets io.launcher io.mmap ;
 
 ARTICLE: "io" "Input and output" 
 { $subsection "streams" }
@@ -145,7 +145,8 @@ ARTICLE: "io" "Input and output"
 { $subsection "stream-binary" }
 { $subsection "styles" }
 { $subsection "network-streams" }
-{ $subsection "io.launcher" } ;
+{ $subsection "io.launcher" }
+{ $subsection "io.mmap" } ;
 
 ARTICLE: "tools" "Developer tools"
 { $subsection "tools.annotations" }

extra/io/mmap/mmap-docs.factor

@@ -0,0 +1,38 @@
+USING: help.markup help.syntax alien math ;
+IN: io.mmap
+
+HELP: mapped-file
+{ $class-description "The class of memory-mapped files, opened by " { $link <mapped-file> } " and closed by " { $link close-mapped-file } ". The following two slots are of interest to users:"
+    { $list
+        { { $link mapped-file-length } " - the length of the mapped file area, in bytes" }
+        { { $link mapped-file-address } " - an " { $link alien } " pointing at the file's memory area" }
+    }
+} ;
+
+HELP: <mapped-file>
+{ $values { "path" "a pathname string" } { "length" integer } { "mmap" mapped-file } }
+{ $contract "Opens a file and maps the first " { $snippet "length" } " bytes into memory. The length is permitted to exceed the length of the file on disk, in which case the remaining space is padded with zero bytes." }
+{ $notes "You must call " { $link close-mapped-file } " when you are finished working with the returned object, to reclaim resources. The " { $link with-mapped-file } " provides an abstraction which can close the mapped file for you." }
+{ $errors "Throws an error if a memory mapping could not be established." } ;
+
+HELP: (close-mapped-file)
+{ $values { "mmap" mapped-file } }
+{ $contract "Releases system resources associated with the mapped file. This word should not be called by user code; use " { $link close-mapped-file } " instead." }
+{ $errors "Throws an error if a memory mapping could not be established." } ;
+
+HELP: close-mapped-file
+{ $values { "mmap" mapped-file } }
+{ $description "Releases system resources associated with the mapped file." }
+{ $errors "Throws an error if a memory mapping could not be established." } ;
+
+ARTICLE: "io.mmap" "Memory-mapped files"
+"The " { $vocab-link "io.mmap" } " vocabulary implements support for memory-mapped files."
+{ $subsection <mapped-file> }
+{ $subsection close-mapped-file }
+"A combinator which wraps the above two words:"
+{ $subsection with-mapped-file }
+"Memory mapped files implement the " { $link "sequence-protocol" } " and present themselves as a sequence of bytes. The underlying memory area can also be accessed directly:"
+{ $subsection mapped-file-address }
+"Data can be read and written from the memory area using alien words. See " { $link "reading-writing-memory" } "." ;
+
+ABOUT: "io.mmap"

extra/io/mmap/mmap.factor

@@ -4,20 +4,31 @@ USING: continuations io.backend kernel quotations sequences
 system alien sequences.private ;
 IN: io.mmap
 
-TUPLE: mapped-file length address handle ;
+TUPLE: mapped-file length address handle closed? ;
 
-M: mapped-file length mapped-file-length ;
+: check-closed ( mapped-file -- mapped-file )
+    dup mapped-file-closed? [
+        "Mapped file is closed" throw
+    ] when ; inline
+
+M: mapped-file length check-closed mapped-file-length ;
 
 M: mapped-file nth-unsafe
-    mapped-file-address swap alien-unsigned-1 ;
+    check-closed mapped-file-address swap alien-unsigned-1 ;
 
 M: mapped-file set-nth-unsafe
-    mapped-file-address swap set-alien-unsigned-1 ;
+    check-closed mapped-file-address swap set-alien-unsigned-1 ;
 
 INSTANCE: mapped-file sequence
 
 HOOK: <mapped-file> io-backend ( path length -- mmap )
-HOOK: close-mapped-file io-backend ( mmap -- )
+
+HOOK: (close-mapped-file) io-backend ( mmap -- )
+
+: close-mapped-file ( mmap -- )
+    check-closed
+    t over set-mapped-file-closed?
+    (close-mapped-file) ;
 
 : with-mapped-file ( path length quot -- )
     >r <mapped-file> r>

extra/io/unix/mmap/mmap.factor

@@ -15,7 +15,7 @@ M: unix-io <mapped-file> ( path length -- obj )
     dup PROT_READ PROT_WRITE bitor MAP_FILE MAP_SHARED bitor
     r> mmap-open \ mapped-file construct-boa ;
 
-M: unix-io close-mapped-file ( mmap -- )
+M: unix-io (close-mapped-file) ( mmap -- )
     [ mapped-file-address ] keep
     [ mapped-file-length munmap ] keep
     mapped-file-handle close

extra/io/windows/mmap/mmap.factor

@@ -78,10 +78,8 @@ M: windows-io <mapped-file> ( path length -- mmap )
         -roll -rot 2array \ mapped-file construct-boa
     ] with-destructors ;
 
-M: windows-io close-mapped-file ( mapped-file -- )
+M: windows-io (close-mapped-file) ( mapped-file -- )
     [
-        dup mapped-file-handle [
-            close-always
-        ] each
+        dup mapped-file-handle [ close-always ] each
         mapped-file-address UnmapViewOfFile win32-error=0/f
     ] with-destructors ;