Implemented first basic functionality of cursor, which is only complete once some more of the memory manager is implemented. Next up is its major use_window method

Author: Byron

smmap/mman.py

@@ -1,29 +1,34 @@
 """Module containnig a memory memory manager which provides a sliding window on a number of memory mapped files"""
-
-__all__ = ["MappedMemoryManager", "MemoryCursor"]
-
 from util import (
 					MemoryWindow,
 					MappedRegion,
 					MappedRegionList,
 				)
 
+from weakref import proxy
+
+__all__ = ["MappedMemoryManager"]
+#{ Utilities
+
+#}END utilities
 
 class MemoryCursor(object):
 	"""Pointer into the mapped region of the memory manager, keeping the current window 
-	alive until it is destroyed"""
+	alive until it is destroyed.
+	
+	Cursors should not be created manually, but are instead returned by the MappedMemoryManager"""
 	__slots__ = ( 
 					'_manager',	# the manger keeping all file regions
-					'_regions',	# a regions list with regions for our file
-					'_region',	# WEAK REF to our current region
+					'_rlist',	# a regions list with regions for our file
+					'_region',	# our current region or None
 					'_ofs',		# relative offset from the actually mapped area to our start area
 					'_size'		# maximum size we should provide
 				)
 
 	def __init__(self, manager = None, regions = None):
 		self._manager = manager
-		self._regions = regions
-		self._region = region
+		self._rlist = regions
+		self._region = None
 		self._ofs = 0
 		self._size = 0
 
@@ -32,12 +37,97 @@ def __del__(self):
 
 	def _destroy(self):
 		"""Destruction code to decrement counters"""
+		self.unuse_region()
+		
+		if self._rlist is not None:
+			# Actual client count, which doesn't include the reference kept by the manager, nor ours
+			# as we are about to be deleted
+			num_clients = self._rlist.client_count() - 2
+			if num_clients == 0 and len(self._rlist) == 0:
+				# Free all resources associated with the mapped file
+				self._manager._files.pop(self._rlist.path())
+			#END remove regions list from manager
+		#END handle regions
 
 	def _copy_from(self, rhs):
 		"""Copy all data from rhs into this instance, handles usage count"""
+		self._manager = rhs._manager
+		self._rlist = rhs._rlist
+		self._region = rhs._region
+		self._ofs = rhs._ofs
+		self._size = rhs._size
+		
+		if self._region is not None:
+			self._region.increment_usage_count(1)
+		# END handle regions
+		
+	def __copy__(self):
+		"""copy module interface"""
+		cpy = type(self)()
+		cpy._copy_from(self)
+		return cpy
 
 	#{ Interface
+	def assign(self, rhs):
+		"""Assign rhs to this instance. This is required in order to get a real copy.
+		Alternativly, you can copy an existing instance using the copy module"""
+		self._destroy()
+		self._copy_from(rhs)
+		
+	def use_region(self, offset, size):
+		"""Assure we point to a window which allows access to the given offset into the file
+		:param offset: absolute offset in bytes into the file
+		:param size: amount of bytes to map
+		:return: this instance - it should be queried for whether it points to a valid memory region.
+			This is not the case if the mapping failed becaues we reached the end of the file
+		: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"""
+			
+	def unuse_region(self):
+		"""Unuse the ucrrent region. Does nothing if we have no current region
+		:note: the cursor unuses the region automatically upon destruction. It is recommended
+			to unuse the region once you are done reading from it in persistent cursors as it 
+			helps to free up resource more quickly"""
+		self._region = None
 
+	def is_valid(self):
+		""":return: True if we have a valid and usable region"""
+		return self._region is not None
+		
+	def is_associated(self):
+		""":return: True if we are associated with a specific file already"""
+		return self._rlist is not None
+		
+	def ofs_begin(self):
+		""":return: offset to the first byte pointed to by our cursor"""
+		return self._region.ofs_begin() + self._ofs
+		
+	def size(self):
+		""":return: amount of bytes we point to"""
+		return self._size
+		
+	def region_ref(self):
+		""":return: weak proxy to our mapped region.
+		:raise AssertionError: if we have no current region. This is only useful for debugging"""
+		if self._region is None:
+			raise AssertionError("region not set")
+		return proxy(self._region)
+		
+	def includes_ofs(self, ofs):
+		""":return: True if the given absolute offset is contained in the cursors 
+			current region
+		:note: always False if the cursor does not point to a valid region"""
+		if self._region is None:
+			return False
+		return (self.ofs_begin() <= ofs) and (ofs < self.ofs_end())
+		
+	def file_size(self):
+		""":return: size of the underlying file"""
+		return self._rlist.file_size()
+		
+	def path(self):
+		""":return: path of the underlying mapped file"""
+		return self._rlist.path()
 
 	#} END interface
 

smmap/test/test_mman.py

@@ -1,11 +1,22 @@
 from lib import TestBase, FileCreator
 
+from copy import copy
 from smmap.mman import *
+from smmap.mman import MemoryCursor
 
 class TestMMan(TestBase):
 
 	def test_cursor(self):
-		man = MappedMemoryManager()  
+		man = MappedMemoryManager()
+		c = MemoryCursor(man)
+		assert not c.is_valid()
+		assert not c.is_associated()
 
-	def test_basics(self):
+		# copy module
+		
+		# assign method
+		
+		
+		
+	def test_memory_manager(self):
 		pass

smmap/test/test_util.py

@@ -75,6 +75,11 @@ def test_region(self):
 		rfull2 = rfull
 		assert rfull.client_count() == 2
 
+		# usage
+		assert rfull.usage_count() == 0
+		rfull.increment_usage_count()
+		assert rfull.usage_count() == 1
+		
 		# window constructor
 		w = MemoryWindow.from_region(rfull)
 		assert w.ofs == rfull.ofs_begin() and w.ofs_end() == rfull.ofs_end()

smmap/util.py

@@ -75,8 +75,8 @@ class MappedRegion(object):
 					'_b'	, 	# beginning of mapping
 					'_mf',	# mapped memory chunk (as returned by mmap)
 					'_uc',	# total amount of usages
-					'_ms',	# actual size of the mapping
-					'__weakref__'	# allow weak references to a region
+					'_ms'	# actual size of the mapping
+					'__weakref__'
 				]
 	_need_compat_layer = sys.version_info[1] < 6
 
@@ -139,17 +139,13 @@ def client_count(self):
 		# -1: self on stack, -1 self in this method, -1 self in getrefcount
 		return getrefcount(self)-3
 
-	def adjust_client_count(self, ofs):
-		"""Adjust the client count by the given positive or negative offset"""
-		self._nc += ofs
-		
 	def usage_count(self):
 		""":return: amount of usages so far"""
 		return self._uc
 
-	def adjust_usage_count(self, ofs):
+	def increment_usage_count(self):
 		"""Adjust the usage count by the given positive or negative offset"""
-		self._uc += ofs
+		self._uc += 1
 
 	# re-define all methods which need offset adjustments in compatibility mode
 	if _need_compat_layer: