pyzim.spaceallocator.SpaceAllocator

class documentation

class SpaceAllocator(BindableMixIn):

Constructor: SpaceAllocator(free_blocks, file_end)

The SpaceAllocator is used to manage the space inside a ZIM file.

This means that the space allocator keeps track of "empty" sections in a ZIM file, so we can later efficently write data there. For example, when modifying an existing ZIM file, it's possible that an entry or a cluster becomes larger than it was before. If the ZIM file was previously using its size perfectly, that means we can't write the entry/cluster to the same location as there is not enough space there. Instead, a new location is needed, but this leaves the previous location "empty". We can later recycle this empty space and potentially write other entries/clusters there. This is the reason for the existence of this class.

This class is implemented as a modified "Contigous Allocation" component. However, rather than having a fixed max size and keeping track of allocated blocks, we have an open-end and keep track of free blocks as a tuple of (offset, size).

Additionally, this method also keeps track of the end of the file, so that we know where we can append data.

Method	`__init__`	The default constructor.
Method	`allocate`	Allocate some space inside the file and return an offset at which this data can be safely written.
Method	`mark_free`	Mark a section in the file as free.
Method	`print_status`	Print the current allocation status and details of free blocks.
Instance Variable	`file_end`	offset to the end of the file (first non-written byte)
Instance Variable	`free_blocks`	a list of tuples of (offset, size) indicating free locations
Instance Variable	`lock`	thread-safety lock

Inherited from BindableMixIn:

Method	`bind`	Bind this object to a ZIM file.
Method	`unbind`	Unbind this object. Can be called multiple times.
Property	`bound`	Whether this object is bound to a ZIM file or not.
Property	`zim`	The bound ZIM archive, if any is bound. Otherwise None.
Instance Variable	`_zim`	the bound ZIM archive or None

def __init__(self, free_blocks=None, file_end=0): ¶

overrides pyzim.bindable.BindableMixIn.__init__

The default constructor.

Parameters
free_blocks:`list` of `tuple` of (`int`, `int`)	initial free block positions, see class documentation
file_end:`int`	initial end of file (index of first non-written byte)

def allocate(self, block_size): ¶

Allocate some space inside the file and return an offset at which this data can be safely written.

This method tries to find the smallest free block of sufficient size. If none is found, storage space will be appended at the file end, reusing a potential free block directly prior to the file end.

Parameters
block_size:`int`	number of bytes to allocate

Returns
`int`	an offset at which the specified number of bytes can be written

def mark_free(self, start, length): ¶

Mark a section in the file as free.

Parameters
start:`int`	offset to section to mark as free
length:`int`	number of bytes to mark as free

def print_status(self): ¶

Print the current allocation status and details of free blocks.

file_end: int = ¶

offset to the end of the file (first non-written byte)

free_blocks: list of tuple of (int, int) = ¶

a list of tuples of (offset, size) indicating free locations

lock: threading.Lock = ¶

thread-safety lock