pmemblk – arrays of pmem-resident blocks

See also

PMDK libpmemblk man page.

class nvm.pmemblk.BlockPool(block_pool)

This class represents the Block Pool opened or created using create() or open().

bsize()

This method returns the block size of the specified block memory pool. It’s the value which was passed as block size to create().

Returns:the block size.
close()

This method closes the memory pool. The block memory pool itself lives on in the file that contains it and may be re-opened at a later time using open().

nblock()

This method returns the usable space in the block memory pool, expressed as the number of blocks available.

Returns:usable space in block memory pool in number of blocks.
read(block_num)

This method reads a block from memory pool at specified block number.

Note

Reading a block that has never been written will return an empty buffer.

Returns:data at block.
set_error(block_num)

This method sets the error state for block number blockno in memory pool. A block in the error state returns errno EIO when read. Writing the block clears the error state and returns the block to normal use.

Returns:On success, zero is returned. On error, an exception will be raised.
set_zero(block_num)

This method writes zeros to block number blockno in memory pool. Using this function is faster than actually writing a block of zeros since libpmemblk uses metadata to indicate the block should read back as zero.

Returns:On success, zero is returned. On error, an exception will be raised.
write(data, block_num)

This method writes a block from data to block number blockno in the memory pool. The write is atomic with respect to other reads and writes. In addition, the write cannot be torn by program failure or system crash; on recovery the block is guaranteed to contain either the old data or the new data, never a mixture of both.

Returns:On success, zero is returned. On error, an exception will be raised.
nvm.pmemblk.check(filename, block_size=0)

This function performs a consistency check of the file indicated by path and returns True if the memory pool is found to be consistent. Any inconsistencies found will cause it to return False, in which case the use of the file with libpmemblk will result in undefined behavior.

Note

When block size is non-zero, it will compare it to the block size of the pool and return False when they don’t match.

Returns:True if memory pool is consistent, False otherwise.
nvm.pmemblk.check_version(major_required, minor_required)

Checks the libpmemblk version according to the specified major and minor versions required.

Parameters:
  • major_required – Major version required.
  • minor_required – Minor version required.
Returns:

returns True if the nvm has the required version, or raises a RuntimeError exception in case of failure.
nvm.pmemblk.create(filename, block_size=<Mock id='140327077841104'>, pool_size=<Mock id='140327077841232'>, mode=438)

This function function creates a block memory pool with the given total pool size divided up into as many elements of block size as will fit in the pool.

Note

Since the transactional nature of a block memory pool requires some space overhead in the memory pool, the resulting number of available blocks is less than poolsize / block size, and is made available to the caller via the nblock().

If the error prevents any of the pool set files from being created, this function will raise an exception.

Parameters:
  • filename – specifies the name of the memory pool file to be created.
  • block_size – the size of the blocks (defaults to PMEMBLK_MIN_BLK).
  • pool_size – the size of the pool (defaults to PMEMBLK_MIN_POOL).
  • mode – specifies the permissions to use when creating the file.
Returns:

the new block memory pool created.
Return type:

BlockPool
nvm.pmemblk.open(filename, block_size=0)

This function opens an existing block memory pool, returning a memory pool.

Note

If an error prevents the pool from being opened, this function will rise an exception. If the block size provided is non-zero, it will verify the given block size matches the block size used when the pool was created. Otherwise, it will open the pool without verification of the block size.

Parameters:filename – Filename must be an existing file containing a block memory pool as created by the create() method. The application must have permission to open the file and memory map it with read/write permissions.
Returns:the block memory pool.
Return type:BlockPool