feat(mman): BREAKING API mman as context-manager to release regions

+ Add PY3 compat utilities
+ doc(changes, tutorial): update on mman usage

Author: ankostis

doc/source/changes.rst

@@ -2,34 +2,46 @@
 Changelog
 #########
 
-**********
+2.1.0
+======
+
+* **BREAKING API:** etrofit ``git.util.mman`` as context-manager, 
+  to release memory-mapped regions held.
+  
+  The *mmap-manager(s)* are re-entrant, but not thread-safe **context-manager(s)**, 
+  to be used within a ``with ...:`` block, ensuring any left-overs cursors are cleaned up.  
+  If not entered, :meth:`StaticWindowMapManager.make_cursor()` and/or 
+  :meth:`WindowCursor.use_region()` will scream.
+
+  Get them from ``smmap.managed_mmaps()``.
+
 v0.9.0
-**********
+========
 - Fixed issue with resources never being freed as mmaps were never closed.
 - Client counting is now done manually, instead of relying on pyton's reference count
 
-**********
+
 v0.8.5
-**********
+========
 - Fixed Python 3.0-3.3 regression, which also causes smmap to become about 3 times slower depending on the code path. It's related to this bug (http://bugs.python.org/issue15958), which was fixed in python 3.4
 
-**********
+
 v0.8.4
-**********
+========
 - Fixed Python 3 performance regression
 
-**********
+
 v0.8.3
-**********
+========
 - Cleaned up code and assured it works sufficiently well with python 3
 
-**********
+
 v0.8.1
-**********
+========
 - A single bugfix
 
-**********
+
 v0.8.0 
-**********
+========
 
 - Initial Release

doc/source/tutorial.rst

@@ -5,91 +5,111 @@ Usage Guide
 ###########
 This text briefly introduces you to the basic design decisions and accompanying classes.
 
-******
 Design
-******
-Per application, there is *MemoryManager* which is held as static instance and used throughout the application. It can be configured to keep your resources within certain limits.
+======
+Per application, there must be a *MemoryManager* to be used throughout the application. 
+It can be configured to keep your resources within certain limits.
 
-To access mapped regions, you require a cursor. Cursors point to exactly one file and serve as handles into it. As long as it exists, the respective memory region will remain available.
+To access mapped regions, you require a cursor. Cursors point to exactly one file and serve as handles into it.
+As long as it exists, the respective memory region will remain available.
+
+For convenience, a buffer implementation is provided which handles cursors and resource allocation 
+behind its simple buffer like interface.
 
-For convenience, a buffer implementation is provided which handles cursors and resource allocation behind its simple buffer like interface.
 
-***************
 Memory Managers
-***************
-There are two types of memory managers, one uses *static* windows, the other one uses *sliding* windows. A window is a region of a file mapped into memory. Although the names might be somewhat misleading as technically windows are always static, the *sliding* version will allocate relatively small windows whereas the *static* version will always map the whole file.
+================
+There are two types of memory managers, one uses *static* windows, the other one uses *sliding* windows. 
+A window is a region of a file mapped into memory. Although the names might be somewhat misleading, 
+as technically windows are always static, the *sliding* version will allocate relatively small windows 
+whereas the *static* version will always map the whole file.
+
+The *static* memory-manager does nothing more than keeping a client count on the respective memory maps 
+which always map the whole file, which allows to make some assumptions that can lead to simplified 
+data access and increased performance, but reduces the compatibility to 32 bit systems or giant files.
+
+The *sliding* memory-manager therefore should be the default manager when preparing an application 
+for handling huge amounts of data on 32 bit and 64 bit platforms
 
-The *static* manager does nothing more than keeping a client count on the respective memory maps which always map the whole file, which allows to make some assumptions that can lead to simplified data access and increased performance, but reduces the compatibility to 32 bit systems or giant files.
+.. Note::
+    The *mmap-manager(s)* are re-entrant, but not thread-safe **context-manager(s)**, 
+    to be used within a ``with ...:`` block, ensuring any left-overs cursors are cleaned up.  
+    If not entered, :meth:`StaticWindowMapManager.make_cursor()` and/or 
+    :meth:`WindowCursor.use_region()` will scream.
 
-The *sliding* memory manager therefore should be the default manager when preparing an application for handling huge amounts of data on 32 bit and 64 bit platforms::
+
+Use the :math:`smmap.managed_mmaps()` to take care of all this::
 
     import smmap
     # This instance should be globally available in your application
     # It is configured to be well suitable for 32-bit or 64 bit applications.
-    mman = smmap.SlidingWindowMapManager()
+    with smmap.managed_mmaps() as mman:
     
-    # the manager provides much useful information about its current state
-    # like the amount of open file handles or the amount of mapped memory
-    mman.num_file_handles()
-    mman.mapped_memory_size()
-    # and many more ...
+        # the manager provides much useful information about its current state
+        # like the amount of open file handles or the amount of mapped memory
+        mman.num_file_handles()
+        mman.mapped_memory_size()
+        # and many more ...
 
 
 Cursors
-*******
+========
 *Cursors* are handles that point onto a window, i.e. a region of a file mapped into memory. From them you may obtain a buffer through which the data of that window can actually be accessed::
 
     import smmap.test.lib
-    fc = smmap.test.lib.FileCreator(1024*1024*8, "test_file")
-    
-    # obtain a cursor to access some file.
-    c = mman.make_cursor(fc.path)
-    
-    # the cursor is now associated with the file, but not yet usable
-    assert c.is_associated()
-    assert not c.is_valid()
-    
-    # before you can use the cursor, you have to specify a window you want to 
-    # access. The following just says you want as much data as possible starting
-    # from offset 0.
-    # To be sure your region could be mapped, query for validity
-    assert c.use_region().is_valid()		# use_region returns self
-    
-    # once a region was mapped, you must query its dimension regularly
-    # to assure you don't try to access its buffer out of its bounds
-    assert c.size()
-    c.buffer()[0]			# first byte
-    c.buffer()[1:10]			# first 9 bytes
-    c.buffer()[c.size()-1] 	# last byte
-    
-    # its recommended not to create big slices when feeding the buffer
-    # into consumers (e.g. struct or zlib). 
-    # Instead, either give the buffer directly, or use pythons buffer command.
-    buffer(c.buffer(), 1, 9)	# first 9 bytes without copying them
-    
-    # you can query absolute offsets, and check whether an offset is included
-    # in the cursor's data.
-    assert c.ofs_begin() < c.ofs_end()
-    assert c.includes_ofs(100)
-    
-    # If you are over out of bounds with one of your region requests, the 
-    # cursor will be come invalid. It cannot be used in that state
-    assert not c.use_region(fc.size, 100).is_valid()
-    # map as much as possible after skipping the first 100 bytes
-    assert c.use_region(100).is_valid()
-    
-    # You can explicitly free cursor resources by unusing the cursor's region
-    c.unuse_region()
-    assert not c.is_valid()
+
+    with smmap.managed_mmaps() as mman:
+        fc = smmap.test.lib.FileCreator(1024*1024*8, "test_file")
+        
+        # obtain a cursor to access some file.
+        c = mman.make_cursor(fc.path)
+        
+        # the cursor is now associated with the file, but not yet usable
+        assert c.is_associated()
+        assert not c.is_valid()
+        
+        # before you can use the cursor, you have to specify a window you want to 
+        # access. The following just says you want as much data as possible starting
+        # from offset 0.
+        # To be sure your region could be mapped, query for validity
+        assert c.use_region().is_valid()		# use_region returns self
+        
+        # once a region was mapped, you must query its dimension regularly
+        # to assure you don't try to access its buffer out of its bounds
+        assert c.size()
+        c.buffer()[0]			# first byte
+        c.buffer()[1:10]			# first 9 bytes
+        c.buffer()[c.size()-1] 	# last byte
+        
+        # its recommended not to create big slices when feeding the buffer
+        # into consumers (e.g. struct or zlib). 
+        # Instead, either give the buffer directly, or use pythons buffer command.
+        buffer(c.buffer(), 1, 9)	# first 9 bytes without copying them
+        
+        # you can query absolute offsets, and check whether an offset is included
+        # in the cursor's data.
+        assert c.ofs_begin() < c.ofs_end()
+        assert c.includes_ofs(100)
+        
+        # If you are over out of bounds with one of your region requests, the 
+        # cursor will be come invalid. It cannot be used in that state
+        assert not c.use_region(fc.size, 100).is_valid()
+        # map as much as possible after skipping the first 100 bytes
+        assert c.use_region(100).is_valid()
+        
+        # You can explicitly free cursor resources by unusing the cursor's region
+        c.unuse_region()
+        assert not c.is_valid()
         
 
 Now you would have to write your algorithms around this interface to properly slide through huge amounts of data. 
 
 Alternatively you can use a convenience interface.
 
-*******
+
+========
 Buffers
-*******
+========
 To make first use easier, at the expense of performance, there is a Buffer implementation which uses a cursor underneath.
 
 With it, you can access all data in a possibly huge file without having to take care of setting the cursor to different regions yourself::
@@ -112,7 +132,9 @@ With it, you can access all data in a possibly huge file without having to take
     
     # it will stop using resources automatically once it goes out of scope
     
-Disadvantages
-*************
-Buffers cannot be used in place of strings or maps, hence you have to slice them to have valid input for the sorts of struct and zlib. A slice means a lot of data handling overhead which makes buffers slower compared to using cursors directly. 
+    Disadvantages
+    --------------
+    Buffers cannot be used in place of strings or maps, hence you have to slice them to have valid 
+    input for the sorts of struct and zlib. 
+    A slice means a lot of data handling overhead which makes buffers slower compared to using cursors directly. 
 

smmap/mman.py

@@ -1,5 +1,10 @@
 """Module containing a memory memory manager which provides a sliding window on a number of memory mapped files"""
+from functools import reduce
+import logging
+import sys
+
 from .util import (
+    PY3,
     MapWindow,
     MapRegion,
     MapRegionList,
@@ -8,15 +13,29 @@
     buffer,
 )
 
-import sys
-from functools import reduce
 
-__all__ = ["StaticWindowMapManager", "SlidingWindowMapManager", "WindowCursor"]
+__all__ = ['managed_mmaps', "StaticWindowMapManager", "SlidingWindowMapManager", "WindowCursor"]
 #{ Utilities
-
+log = logging.getLogger(__name__)
 #}END utilities
 
 
+def managed_mmaps():
+    """Makes a memory-map context-manager instance for the correct python-version.
+
+    :return: either :class:`SlidingWindowMapManager` or :class:`StaticWindowMapManager` (if PY2)
+
+    If you want to change the default parameters of these classes, use them directly.
+
+    .. Tip::
+        Use it in a ``with ...:`` block, to free cached (and unused) resources.
+
+    """
+    mman = SlidingWindowMapManager if PY3 else StaticWindowMapManager
+
+    return mman()
+
+
 class WindowCursor(object):
 
     """
@@ -25,9 +44,15 @@ class WindowCursor(object):
 
     Cursors should not be created manually, but are instead returned by the SlidingWindowMapManager
 
-    **Note:**: The current implementation is suited for static and sliding window managers, but it also means
-    that it must be suited for the somewhat quite different sliding manager. It could be improved, but
-    I see no real need to do so."""
+    .. Tip::
+        This is a re-entrant, but not thread-safe context-manager, to be used within a ``with ...:`` block,
+        to ensure any left-overs cursors are cleaned up.  If not entered, :meth:`use_region()``
+        will scream.
+
+    .. Note::
+        The current implementation is suited for static and sliding window managers,
+        but it also means that it must be suited for the somewhat quite different sliding manager.
+        It could be improved, but I see no real need to do so."""
     __slots__ = (
         '_manager',  # the manger keeping all file regions
         '_rlist',   # a regions list with regions for our file
@@ -110,6 +135,10 @@ def use_region(self, offset=0, size=0, flags=0):
 
         **Note:**: The size actually mapped may be smaller than the given size. If that is the case,
         either the file has reached its end, or the map was created between two existing regions"""
+        if self._manager._entered <= 0:
+            raise ValueError('Context-manager %s not entered for %s!' %
+                             (self._manager, self))
+
         need_region = True
         man = self._manager
         fsize = self._rlist.file_size()
@@ -243,15 +272,23 @@ class StaticWindowMapManager(object):
     These clients would have to use a SlidingWindowMapBuffer to hide this fact.
 
     This type will always use a maximum window size, and optimize certain methods to
-    accommodate this fact"""
+    accommodate this fact
+
+    .. Tip::
+        The *memory-managers* are re-entrant, but not thread-safe context-manager(s),
+        to be used within a ``with ...:`` block, ensuring any left-overs cursors are cleaned up.
+        If not entered, :meth:`make_cursor()` and/or :meth:`WindowCursor.use_region()` will scream.
+
+    """
 
     __slots__ = [
-        '_fdict',           # mapping of path -> StorageHelper (of some kind
-        '_window_size',     # maximum size of a window
-        '_max_memory_size',  # maximum amount of memory we may allocate
-        '_max_handle_count',        # maximum amount of handles to keep open
-        '_memory_size',     # currently allocated memory size
+        '_fdict',               # mapping of path -> StorageHelper (of some kind
+        '_window_size',         # maximum size of a window
+        '_max_memory_size',     # maximum amount of memory we may allocate
+        '_max_handle_count',    # maximum amount of handles to keep open
+        '_memory_size',         # currently allocated memory size
         '_handle_count',        # amount of currently allocated file handles
+        '_entered',             # updated on enter/exit, when 0, `close()`
     ]
 
     #{ Configuration
@@ -280,6 +317,7 @@ def __init__(self, window_size=0, max_memory_size=0, max_open_handles=sys.maxsiz
         self._max_handle_count = max_open_handles
         self._memory_size = 0
         self._handle_count = 0
+        self._entered = 0
 
         if window_size < 0:
             coeff = 64
@@ -297,6 +335,23 @@ def __init__(self, window_size=0, max_memory_size=0, max_open_handles=sys.maxsiz
             self._max_memory_size = coeff * self._MB_in_bytes
         # END handle max memory size
 
+    def __enter__(self):
+        assert self._entered >= 0, self._entered
+        self._entered += 1
+
+        return self
+
+    def __exit__(self, exc_type, exc_value, traceback):
+        assert self._entered > 0, self._entered
+        self._entered -= 1
+        if self._entered == 0:
+            leaft_overs = self.collect()
+            if leaft_overs:
+                log.warning("Cleaned up %s left-over mmap-regions.")
+
+    def close(self):
+        self.collect()
+
     #{ Internal Methods
 
     def _collect_lru_region(self, size):
@@ -399,6 +454,9 @@ def make_cursor(self, path_or_fd):
 
         **Note:** Using file descriptors directly is faster once new windows are mapped as it
         prevents the file to be opened again just for the purpose of mapping it."""
+        if self._entered <= 0:
+            raise ValueError('Context-manager %s not entered!' % self)
+
         regions = self._fdict.get(path_or_fd)
         if regions:
             assert not regions.collect_closed_regions(), regions.collect_closed_regions()

smmap/test/test_buf.py

@@ -25,106 +25,112 @@
 class TestBuf(TestBase):
 
     def test_basics(self):
+        # invalid paths fail upon construction
+        with FileCreator(self.k_window_test_size, "buffer_test") as fc:
+            with man_optimal:
+                c = man_optimal.make_cursor(fc.path)
+                self.assertRaises(ValueError, SlidingWindowMapBuffer, type(c)())   # invalid cursor
+                self.assertRaises(ValueError, SlidingWindowMapBuffer, c, fc.size)  # offset too large
+
+                buf = SlidingWindowMapBuffer()  # can create uninitailized buffers
+                assert buf.cursor() is None
+
+                # can call end access any time
+                buf.end_access()
+                buf.end_access()
+                assert len(buf) == 0
+
+                # begin access can revive it, if the offset is suitable
+                offset = 100
+                assert buf.begin_access(c, fc.size) == False
+                assert buf.begin_access(c, offset) == True
+                assert len(buf) == fc.size - offset
+                assert buf.cursor().is_valid()
+
+                # empty begin access keeps it valid on the same path, but alters the offset
+                assert buf.begin_access() == True
+                assert len(buf) == fc.size
+                assert buf.cursor().is_valid()
+
+                # simple access
+                with open(fc.path, 'rb') as fp:
+                    data = fp.read()
+                assert data[offset] == buf[0]
+                assert data[offset:offset * 2] == buf[0:offset]
+
+                # negative indices, partial slices
+                assert buf[-1] == buf[len(buf) - 1]
+                assert buf[-10:] == buf[len(buf) - 10:len(buf)]
+
+                # end access makes its cursor invalid
+                buf.end_access()
+                assert not buf.cursor().is_valid()
+                assert buf.cursor().is_associated()         # but it remains associated
+
+                # an empty begin access fixes it up again
+                assert buf.begin_access() == True and buf.cursor().is_valid()
+                del(buf)        # ends access automatically
+                del(c)
+
+                assert man_optimal.num_file_handles() == 1
+
+    def test_performance(self):
+        # PERFORMANCE
+        # blast away with random access and a full mapping - we don't want to
+        # exaggerate the manager's overhead, but measure the buffer overhead
+        # We do it once with an optimal setting, and with a worse manager which
+        # will produce small mappings only !
         with FileCreator(self.k_window_test_size, "buffer_test") as fc:
-
-            # invalid paths fail upon construction
-            c = man_optimal.make_cursor(fc.path)
-            self.assertRaises(ValueError, SlidingWindowMapBuffer, type(c)())   # invalid cursor
-            self.assertRaises(ValueError, SlidingWindowMapBuffer, c, fc.size)  # offset too large
-
-            buf = SlidingWindowMapBuffer()  # can create uninitailized buffers
-            assert buf.cursor() is None
-
-            # can call end access any time
-            buf.end_access()
-            buf.end_access()
-            assert len(buf) == 0
-
-            # begin access can revive it, if the offset is suitable
-            offset = 100
-            assert buf.begin_access(c, fc.size) == False
-            assert buf.begin_access(c, offset) == True
-            assert len(buf) == fc.size - offset
-            assert buf.cursor().is_valid()
-
-            # empty begin access keeps it valid on the same path, but alters the offset
-            assert buf.begin_access() == True
-            assert len(buf) == fc.size
-            assert buf.cursor().is_valid()
-
-            # simple access
             with open(fc.path, 'rb') as fp:
                 data = fp.read()
-            assert data[offset] == buf[0]
-            assert data[offset:offset * 2] == buf[0:offset]
-
-            # negative indices, partial slices
-            assert buf[-1] == buf[len(buf) - 1]
-            assert buf[-10:] == buf[len(buf) - 10:len(buf)]
-
-            # end access makes its cursor invalid
-            buf.end_access()
-            assert not buf.cursor().is_valid()
-            assert buf.cursor().is_associated()         # but it remains associated
-
-            # an empty begin access fixes it up again
-            assert buf.begin_access() == True and buf.cursor().is_valid()
-            del(buf)        # ends access automatically
-            del(c)
-
-            assert man_optimal.num_file_handles() == 1
-
-            # PERFORMANCE
-            # blast away with random access and a full mapping - we don't want to
-            # exaggerate the manager's overhead, but measure the buffer overhead
-            # We do it once with an optimal setting, and with a worse manager which
-            # will produce small mappings only !
+
             max_num_accesses = 100
             fd = os.open(fc.path, os.O_RDONLY)
             for item in (fc.path, fd):
                 for manager, man_id in ((man_optimal, 'optimal'),
                                         (man_worst_case, 'worst case'),
                                         (static_man, 'static optimal')):
-                    buf = SlidingWindowMapBuffer(manager.make_cursor(item))
-                    assert manager.num_file_handles() == 1
-                    for access_mode in range(2):    # single, multi
-                        num_accesses_left = max_num_accesses
-                        num_bytes = 0
-                        fsize = fc.size
-
-                        st = time()
-                        buf.begin_access()
-                        while num_accesses_left:
-                            num_accesses_left -= 1
-                            if access_mode:  # multi
-                                ofs_start = randint(0, fsize)
-                                ofs_end = randint(ofs_start, fsize)
-                                d = buf[ofs_start:ofs_end]
-                                assert len(d) == ofs_end - ofs_start
-                                assert d == data[ofs_start:ofs_end]
-                                num_bytes += len(d)
-                                del d
-                            else:
-                                pos = randint(0, fsize)
-                                assert buf[pos] == data[pos]
-                                num_bytes += 1
-                            # END handle mode
-                        # END handle num accesses
-
-                        buf.end_access()
-                        assert manager.num_file_handles()
-                        assert manager.collect()
-                        assert manager.num_file_handles() == 0
-                        elapsed = max(time() - st, 0.001)  # prevent zero division errors on windows
-                        mb = float(1000 * 1000)
-                        mode_str = (access_mode and "slice") or "single byte"
-                        print("%s: Made %i random %s accesses to buffer created from %s "
-                              "reading a total of %f mb in %f s (%f mb/s)"
-                              % (man_id, max_num_accesses, mode_str, type(item),
-                                 num_bytes / mb, elapsed, (num_bytes / mb) / elapsed),
-                              file=sys.stderr)
-                    # END handle access mode
-                    del buf
-                # END for each manager
+                    with manager:
+                        buf = SlidingWindowMapBuffer(manager.make_cursor(item))
+                        assert manager.num_file_handles() == 1
+                        for access_mode in range(2):    # single, multi
+                            num_accesses_left = max_num_accesses
+                            num_bytes = 0
+                            fsize = fc.size
+
+                            st = time()
+                            buf.begin_access()
+                            while num_accesses_left:
+                                num_accesses_left -= 1
+                                if access_mode:  # multi
+                                    ofs_start = randint(0, fsize)
+                                    ofs_end = randint(ofs_start, fsize)
+                                    d = buf[ofs_start:ofs_end]
+                                    assert len(d) == ofs_end - ofs_start
+                                    assert d == data[ofs_start:ofs_end]
+                                    num_bytes += len(d)
+                                    del d
+                                else:
+                                    pos = randint(0, fsize)
+                                    assert buf[pos] == data[pos]
+                                    num_bytes += 1
+                                # END handle mode
+                            # END handle num accesses
+
+                            buf.end_access()
+                            assert manager.num_file_handles()
+                            assert manager.collect()
+                            assert manager.num_file_handles() == 0
+                            elapsed = max(time() - st, 0.001)  # prevent zero division errors on windows
+                            mb = float(1000 * 1000)
+                            mode_str = (access_mode and "slice") or "single byte"
+                            print("%s: Made %i random %s accesses to buffer created from %s "
+                                  "reading a total of %f mb in %f s (%f mb/s)"
+                                  % (man_id, max_num_accesses, mode_str, type(item),
+                                     num_bytes / mb, elapsed, (num_bytes / mb) / elapsed),
+                                  file=sys.stderr)
+                        # END handle access mode
+                        del buf
+                    # END for each manager
             # END for each input
             os.close(fd)

smmap/test/test_mman.py

@@ -22,60 +22,61 @@ def test_example(self):
         import smmap.test.lib
         with smmap.test.lib.FileCreator(1024 * 1024 * 8, "test_file") as fc:
             # obtain a cursor to access some file.
-            c = mman.make_cursor(fc.path)
-
-            # the cursor is now associated with the file, but not yet usable
-            assert c.is_associated()
-            assert not c.is_valid()
-
-            # before you can use the cursor, you have to specify a window you want to
-            # access. The following just says you want as much data as possible starting
-            # from offset 0.
-            # To be sure your region could be mapped, query for validity
-            assert c.use_region().is_valid()        # use_region returns self
-
-            # once a region was mapped, you must query its dimension regularly
-            # to assure you don't try to access its buffer out of its bounds
-            assert c.size()
-            c.buffer()[0]           # first byte
-            c.buffer()[1:10]            # first 9 bytes
-            c.buffer()[c.size() - 1]  # last byte
-
-            # its recommended not to create big slices when feeding the buffer
-            # into consumers (e.g. struct or zlib).
-            # Instead, either give the buffer directly, or use pythons buffer command.
-            from smmap.util import buffer
-            buffer(c.buffer(), 1, 9)    # first 9 bytes without copying them
-
-            # you can query absolute offsets, and check whether an offset is included
-            # in the cursor's data.
-            assert c.ofs_begin() < c.ofs_end()
-            assert c.includes_ofs(100)
-
-            # If you are over out of bounds with one of your region requests, the
-            # cursor will be come invalid. It cannot be used in that state
-            assert not c.use_region(fc.size, 100).is_valid()
-            # map as much as possible after skipping the first 100 bytes
-            assert c.use_region(100).is_valid()
-
-            # You can explicitly free cursor resources by unusing the cursor's region
-            c.unuse_region()
-            assert not c.is_valid()
-
-            # Buffers
-            #########
-            # Create a default buffer which can operate on the whole file
-            buf = smmap.SlidingWindowMapBuffer(mman.make_cursor(fc.path))
-
-            # you can use it right away
-            assert buf.cursor().is_valid()
-
-            buf[0]  # access the first byte
-            buf[-1]  # access the last ten bytes on the file
-            buf[-10:]  # access the last ten bytes
-
-            # If you want to keep the instance between different accesses, use the
-            # dedicated methods
-            buf.end_access()
-            assert not buf.cursor().is_valid()  # you cannot use the buffer anymore
-            assert buf.begin_access(offset=10)  # start using the buffer at an offset
+            with mman:
+                c = mman.make_cursor(fc.path)
+
+                # the cursor is now associated with the file, but not yet usable
+                assert c.is_associated()
+                assert not c.is_valid()
+
+                # before you can use the cursor, you have to specify a window you want to
+                # access. The following just says you want as much data as possible starting
+                # from offset 0.
+                # To be sure your region could be mapped, query for validity
+                assert c.use_region().is_valid()        # use_region returns self
+
+                # once a region was mapped, you must query its dimension regularly
+                # to assure you don't try to access its buffer out of its bounds
+                assert c.size()
+                c.buffer()[0]           # first byte
+                c.buffer()[1:10]            # first 9 bytes
+                c.buffer()[c.size() - 1]  # last byte
+
+                # its recommended not to create big slices when feeding the buffer
+                # into consumers (e.g. struct or zlib).
+                # Instead, either give the buffer directly, or use pythons buffer command.
+                from smmap.util import buffer
+                buffer(c.buffer(), 1, 9)    # first 9 bytes without copying them
+
+                # you can query absolute offsets, and check whether an offset is included
+                # in the cursor's data.
+                assert c.ofs_begin() < c.ofs_end()
+                assert c.includes_ofs(100)
+
+                # If you are over out of bounds with one of your region requests, the
+                # cursor will be come invalid. It cannot be used in that state
+                assert not c.use_region(fc.size, 100).is_valid()
+                # map as much as possible after skipping the first 100 bytes
+                assert c.use_region(100).is_valid()
+
+                # You can explicitly free cursor resources by unusing the cursor's region
+                c.unuse_region()
+                assert not c.is_valid()
+
+                # Buffers
+                #########
+                # Create a default buffer which can operate on the whole file
+                buf = smmap.SlidingWindowMapBuffer(mman.make_cursor(fc.path))
+
+                # you can use it right away
+                assert buf.cursor().is_valid()
+
+                buf[0]  # access the first byte
+                buf[-1]  # access the last ten bytes on the file
+                buf[-10:]  # access the last ten bytes
+
+                # If you want to keep the instance between different accesses, use the
+                # dedicated methods
+                buf.end_access()
+                assert not buf.cursor().is_valid()  # you cannot use the buffer anymore
+                assert buf.begin_access(offset=10)  # start using the buffer at an offset

smmap/test/test_tutorial.py

@@ -28,8 +28,11 @@ def buffer(obj, offset, size):
         # return obj[offset:offset + size]
 
 
+PY3 = sys.version_info[0] >= 3
+
+
 def string_types():
-    if sys.version_info[0] >= 3:
+    if PY3:
         return str
     else:
         return basestring  # @UndefinedVariable