Detailed Description

A pinned / pin-counted derivative of a Block.

By holding a pin, it is a guaranteed that the contained ByteBlock's data is loaded in RAM. Since pins are counted per thread, the PinnedBlock is a counting pointer plus a thread id. An ordinary Block can be pinned by calling Pin(), which delivers a future PinnedBlock, which is available once the data is actually loaded.

Be careful to move PinnedBlock as must as possible, since copying costs a pinning and an unpinning operation, whereas moving is free.

Definition at line 157 of file block.hpp.

Inheritance diagram for PinnedBlock:

Collaboration diagram for PinnedBlock:

#include <block.hpp>

Public Member Functions
	PinnedBlock ()=default
	Create invalid PinnedBlock. More...

	PinnedBlock (PinnedByteBlockPtr &&byte_block, size_t begin, size_t end, size_t first_item, size_t num_items, bool typecode_verify)

	PinnedBlock (const PinnedBlock &pb) noexcept
	copy-ctor: increment underlying's pin count More...

	PinnedBlock (PinnedBlock &&pb) noexcept
	move-ctor: move underlying's pin More...

	~PinnedBlock ()

PinnedByteBlockPtr	CopyPinnedByteBlock () const

const Byte *	data_begin () const
	return pointer to beginning of valid data More...

const Byte *	data_end () const
	return pointer to end of valid data More...

Block	MoveToBlock () &&
	extract Block has an unpinning move More...

PinnedBlock &	operator= (PinnedBlock &pb) noexcept
	copy-assignment: copy underlying and increase pin count More...

PinnedBlock &	operator= (PinnedBlock &&pb) noexcept
	move-assignment: move underlying, release current's pin More...

PinRequestPtr	Pin () const =delete
	not available in PinnedBlock More...

PinnedBlock	PinWait () const =delete
	not available in PinnedBlock More...

void	Reset ()
	release pin on block and reset Block pointer to nullptr More...

PinnedByteBlockPtr	StealPinnedByteBlock () &&

Block	ToBlock () const
	extract Block has an unpinned copy More...

std::string	ToString () const

Accessors to Super-Class
bool	IsValid () const
	Return whether the enclosed ByteBlock is valid. More...

const ByteBlockPtr &	byte_block () const
	access to byte_block_ More...

ByteBlockPtr &	byte_block ()
	mutable access to byte_block_ More...

size_t	num_items () const
	return number of items beginning in this block More...

size_t	pin_count (size_t local_worker_id) const
	return number of pins in underlying ByteBlock More...

void	set_begin (size_t i)
	accessor to begin_ More...

void	set_end (size_t i)
	accessor to end_ More...

size_t	size () const
	return length of valid data in bytes. More...

size_t	first_item_absolute () const
	accessor to first_item_ (absolute in ByteBlock) More...

size_t	first_item_relative () const
	return the first_item_offset relative to data_begin(). More...

bool	typecode_verify () const
	return typecode_verify from Block More...

Private Member Functions
	PinnedBlock (const Block &b, size_t local_worker_id)

Private Member Functions inherited from Block
	Block ()=default
	default-ctor: create invalid Block. More...

	Block (const Block &other)=default

	Block (Block &&other)=default

	Block (ByteBlockPtr &&byte_block, size_t begin, size_t end, size_t first_item, size_t num_items, bool typecode_verify)

const ByteBlockPtr &	byte_block () const
	access to byte_block_ More...

ByteBlockPtr &	byte_block ()
	mutable access to byte_block_ More...

size_t	first_item_absolute () const
	accessor to first_item_ (absolute in ByteBlock) More...

size_t	first_item_relative () const
	return the first_item_offset relative to data_begin(). More...

bool	IsValid () const
	Return whether the enclosed ByteBlock is valid. More...

size_t	num_items () const
	return number of items beginning in this block More...

Block &	operator= (const Block &other)=default

Block &	operator= (Block &&other)=default

PinRequestPtr	Pin (size_t local_worker_id) const

size_t	pin_count (size_t local_worker_id) const
	return number of pins in underlying ByteBlock More...

PinnedBlock	PinWait (size_t local_worker_id) const
	Convenience function to call Pin() and wait for the future. More...

void	set_begin (size_t i)
	accessor to begin_ More...

void	set_end (size_t i)
	accessor to end_ More...

size_t	size () const
	return length of valid data in bytes. More...

bool	typecode_verify () const
	Returns typecode_verify_. More...

Private Attributes
size_t	local_worker_id_
	thread id of holder of pin More...

Private Attributes inherited from Block
size_t	begin_ = 0
	beginning offset of valid bytes to read More...

ByteBlockPtr	byte_block_
	referenced ByteBlock More...

size_t	end_ = 0

size_t	first_item_ = 0

size_t	num_items_ = 0

bool	typecode_verify_ = false

Friends
std::ostream &	operator<< (std::ostream &os, const PinnedBlock &b)
	make ostreamable for debugging More...

Additional Inherited Members
Static Private Attributes inherited from Block
static constexpr bool	debug = false

Constructor & Destructor Documentation

◆ PinnedBlock() [1/5]

PinnedBlock ( )

default

Create invalid PinnedBlock.

◆ PinnedBlock() [2/5]

PinnedBlock	(	PinnedByteBlockPtr &&	byte_block,
		size_t	begin,
		size_t	end,
		size_t	first_item,
		size_t	num_items,
		bool	typecode_verify
	)

inline

Creates a block that points to the given data::PinnedByteBlock with the given offsets. The returned block is also pinned, the pin is transfered!

Definition at line 165 of file block.hpp.

References LOG.

◆ PinnedBlock() [3/5]

PinnedBlock ( const PinnedBlock & pb )

inlinenoexcept

copy-ctor: increment underlying's pin count

Definition at line 176 of file block.hpp.

References Block::byte_block_.

◆ PinnedBlock() [4/5]

PinnedBlock ( PinnedBlock && pb )

inlinenoexcept

move-ctor: move underlying's pin

Definition at line 182 of file block.hpp.

◆ ~PinnedBlock()

~PinnedBlock ( )

inline

Definition at line 213 of file block.hpp.

References Block::byte_block_, CountingPtr< Type, Deleter >::get(), and LOG.

◆ PinnedBlock() [5/5]

PinnedBlock	(	const Block &	b,
		size_t	local_worker_id
	)

inlineprivate

protected construction from an unpinned block AFTER the pin was taken, this method does NOT pin it.

Definition at line 320 of file block.hpp.

Member Function Documentation

◆ byte_block() [1/2]

const ByteBlockPtr& byte_block ( ) const

inline

access to byte_block_

Definition at line 226 of file block.hpp.

References Block::byte_block().

Referenced by BlockReader< CatBlockSource >::byte_block(), BlockReader< CatBlockSource >::CopyBlock(), and BlockPool::OnReadComplete().

◆ byte_block() [2/2]

ByteBlockPtr& byte_block ( )

inline

mutable access to byte_block_

Definition at line 229 of file block.hpp.

References Block::byte_block().

◆ CopyPinnedByteBlock()

PinnedByteBlockPtr CopyPinnedByteBlock ( ) const

inline

copy the underlying byte_block_ into a new PinnedByteBlockPtr, which increases the pin count. use StealPinnedByteBlock to move the underlying pin out (cheaper).

Definition at line 298 of file block.hpp.

References Block::byte_block_, CountingPtr< Type, Deleter >::get(), Block::operator<<, Block::Pin(), and Block::PinWait().

Referenced by BlockReader< CatBlockSource >::CopyBlock().