Skip to content
Browse files

Update readme

  • Loading branch information...
1 parent 613e656 commit d0ef891dbda59aa802dfe74c77d02251cbb1e245 @krestenkrab committed
Showing with 33 additions and 0 deletions.
  1. +33 −0 README.md
View
33 README.md
@@ -0,0 +1,33 @@
+# Erlang MMAP `emmap`
+
+This Erlang library provides a wrapper that allows you to memory map files into the Erlang memory space.
+
+
+## Basic Usage
+
+The basic usage is
+
+ {ok, Mem} = emmap:open("filename", [read, shared, direct]),
+ {ok, Binary} = file:pread(Mem, 100, 40),
+ ...
+ ok = file:close(Mem).
+
+The open options is a list containing zero or more of these:
+
+- `read`, `write`: Open for reading and/or writing (you can specify both).
+- `private`, `shared`: The file is opened with copy-on-write semantics, or sharing memory with the underlying file.
+- `direct`: read/pread operations do not copy memory, but rather use "resource binaries" that can change content if the underlying data is changed. This is the most performant, but also has other implications.
+- `lock`, `nolock` do (or do not) use a semaphore to control state changes internally in the NIF library.
+
+From this point, `Mem` can be used with the `file` operations
+
+- `{ok, Binary} = file:pread(Mem, Position, Length)` read Length bytes at Position in the file.
+- `ok = file:pwrite(Mem, Position, Binary)` writes to the given position.
+- `{ok, Binary} = file:read(Mem, Length)` read 1..Length bytes from current position, or return `eof` if pointer is at end of file.
+- `{ok, Pos} = file:position(Mem, Where)` see file:position/2 documentation.
+- `ok = file:close(Mem)`
+
+## Notes
+
+Using the option `direct` has the effect that the mmap file is not closed until all references to binaries coming out of read/pread have been garbage collected. This is a consequence of that such binaries are referring directly to the mmap'ed memory.
+

0 comments on commit d0ef891

Please sign in to comment.
Something went wrong with that request. Please try again.