Realm::RegionInstance Class Reference

#include <instance.h>

Inheritance diagram for Realm::RegionInstance:

Collaboration diagram for Realm::RegionInstance:

Classes
struct	DestroyedField

Public Types
typedef ::realm_id_t	id_t

Public Member Functions
	RegionInstance ()=default
constexpr	RegionInstance (id_t id)
constexpr	operator id_t () const
bool	operator< (const RegionInstance &rhs) const
bool	operator== (const RegionInstance &rhs) const
bool	operator!= (const RegionInstance &rhs) const
REALM_CUDA_HD bool	exists (void) const
Memory	get_location (void) const
const InstanceLayoutGeneric *	get_layout (void) const
void	read_untyped (size_t offset, void *data, size_t datalen) const
void	write_untyped (size_t offset, const void *data, size_t datalen) const
void	reduce_apply_untyped (size_t offset, ReductionOpID redop_id, const void *data, size_t datalen, bool exclusive=false) const
void	reduce_fold_untyped (size_t offset, ReductionOpID redop_id, const void *data, size_t datalen, bool exclusive=false) const
void *	pointer_untyped (size_t offset, size_t datalen) const
template<typename T >
T	read (size_t offset) const
template<typename T >
void	write (size_t offset, T val) const
template<typename T >
void	reduce_apply (size_t offset, ReductionOpID redop_id, T val, bool exclusive=false) const
template<typename T >
void	reduce_fold (size_t offset, ReductionOpID redop_id, T val, bool exclusive=false) const
template<typename T >
T *	pointer (size_t offset) const
Event	redistrict (RegionInstance &instance, const InstanceLayoutGeneric *layout, const ProfilingRequestSet &prs, Event wait_on=Event::NO_EVENT)
Event	redistrict (RegionInstance *instances, const InstanceLayoutGeneric **layouts, size_t num_layouts, const ProfilingRequestSet *prs, Event wait_on=Event::NO_EVENT)
	REALM_ATTR_DEPRECATED ("use RegionInstance::create_instance with layout reference instead", static Event create_instance(RegionInstance &inst, Memory memory, InstanceLayoutGeneric *ilg, const ProfilingRequestSet &prs, Event wait_on=Event::NO_EVENT))
	REALM_ATTR_DEPRECATED ("use RegionInstance::create_external_instance with layout reference instead", static Event create_external_instance(RegionInstance &inst, Memory memory, InstanceLayoutGeneric *ilg, const ExternalInstanceResource &resource, const ProfilingRequestSet &prs, Event wait_on=Event::NO_EVENT))
template<int N, typename T >
	REALM_ATTR_DEPRECATED ("use RegionInstance::create_external_instance instead", static Event create_file_instance(RegionInstance &inst, const char *file_name, const IndexSpace< N, T > &space, const std::vector< FieldID > &field_ids, const std::vector< size_t > &field_sizes, realm_file_mode_t file_mode, const ProfilingRequestSet &prs, Event wait_on=Event::NO_EVENT))
	REALM_ATTR_DEPRECATED ("use RegionInstance::create_external_instance instead", static Event create_external(RegionInstance &inst, Memory memory, uintptr_t base, InstanceLayoutGeneric *ilg, const ProfilingRequestSet &prs, Event wait_on=Event::NO_EVENT))
void	destroy (Event wait_on=Event::NO_EVENT) const
AddressSpace	address_space (void) const
Event	fetch_metadata (Processor target) const
template<int N, typename T >
IndexSpace< N, T >	get_indexspace (void) const
template<int N>
IndexSpace< N, int >	get_indexspace (void) const
REALM_INTERNAL_API_EXTERNAL_LINKAGE bool	increment_accessor_count (void)
REALM_INTERNAL_API_EXTERNAL_LINKAGE bool	decrement_accessor_count (void)
void	destroy (const std::vector< DestroyedField > &destroyed_fields, Event wait_on=Event::NO_EVENT) const
bool	can_get_strided_access_parameters (size_t start, size_t count, ptrdiff_t field_offset, size_t field_size)
void	get_strided_access_parameters (size_t start, size_t count, ptrdiff_t field_offset, size_t field_size, intptr_t &base, ptrdiff_t &stride)
void	report_instance_fault (int reason, const void *reason_data, size_t reason_size) const
template<int N, typename T >
REALM_INTERNAL_API_EXTERNAL_LINKAGE const PieceLookup::Instruction *	get_lookup_program (FieldID field_id, unsigned allowed_mask, uintptr_t &field_offset)
template<int N, typename T >
REALM_INTERNAL_API_EXTERNAL_LINKAGE const PieceLookup::Instruction *	get_lookup_program (FieldID field_id, const Rect< N, T > &subrect, unsigned allowed_mask, uintptr_t &field_offset)
ExternalInstanceResource *	generate_resource_info (bool read_only) const
ExternalInstanceResource *	generate_resource_info (const IndexSpaceGeneric &space, span< const FieldID > fields, bool read_only) const

Static Public Member Functions
static Event	create_instance (RegionInstance &inst, Memory memory, const InstanceLayoutGeneric &ilg, const ProfilingRequestSet &prs, Event wait_on=Event::NO_EVENT)
static Event	create_external_instance (RegionInstance &inst, Memory memory, const InstanceLayoutGeneric &ilg, const ExternalInstanceResource &resource, const ProfilingRequestSet &prs, Event wait_on=Event::NO_EVENT)
template<int N, typename T >
static Event	create_instance (RegionInstance &inst, Memory memory, const Rect< N, T > &rect, const std::vector< size_t > &field_sizes, size_t block_size, const ProfilingRequestSet &prs, Event wait_on=Event::NO_EVENT)
template<int N, typename T >
static Event	create_instance (RegionInstance &inst, Memory memory, const Rect< N, T > &rect, const std::map< FieldID, size_t > &field_sizes, size_t block_size, const ProfilingRequestSet &prs, Event wait_on=Event::NO_EVENT)
template<int N, typename T >
static Event	create_instance (RegionInstance &inst, Memory memory, const IndexSpace< N, T > &space, const std::vector< size_t > &field_sizes, size_t block_size, const ProfilingRequestSet &prs, Event wait_on=Event::NO_EVENT)
template<int N, typename T >
static Event	create_instance (RegionInstance &inst, Memory memory, const IndexSpace< N, T > &space, const std::map< FieldID, size_t > &field_sizes, size_t block_size, const ProfilingRequestSet &prs, Event wait_on=Event::NO_EVENT)

Public Attributes
id_t	id

Static Public Attributes
static const RegionInstance	NO_INST

Detailed Description

A RegionInstance is a handle to a region of memory that that stores persistent application data.

Member Typedef Documentation

id_t

typedef ::realm_id_t Realm::RegionInstance::id_t

Constructor & Destructor Documentation

RegionInstance() [1/2]

Realm::RegionInstance::RegionInstance ( )

default

RegionInstance() [2/2]

constexpr Realm::RegionInstance::RegionInstance ( id_t  id )

inlineexplicitconstexpr

Member Function Documentation

address_space()

AddressSpace Realm::RegionInstance::address_space

(

void

)

const

can_get_strided_access_parameters()

bool Realm::RegionInstance::can_get_strided_access_parameters	(	size_t	start,
		size_t	count,
		ptrdiff_t	field_offset,
		size_t	field_size
	)

create_external_instance()

static Event Realm::RegionInstance::create_external_instance ( RegionInstance &  inst, Memory  memory, const InstanceLayoutGeneric &  ilg, const ExternalInstanceResource &  resource, const ProfilingRequestSet &  prs, Event  wait_on = Event::NO_EVENT  )

static

Create a new region instance backed by an external resource. Realm performs no allocation, but allows access and copies as with normal instances.

Parameters

inst	The handle to the new instance.
memory	The memory to create the instance in.
ilg	The layout of the instance.
resource	The external resource to back the instance.
prs	The profiling requests for the instance.
wait_on	The event to wait on before creating the instance.

Returns

The event to wait on before using the instance.

create_instance() [1/5]

template<int N, typename T >

static Event Realm::RegionInstance::create_instance ( RegionInstance &  inst, Memory  memory, const IndexSpace< N, T > &  space, const std::map< FieldID, size_t > &  field_sizes, size_t  block_size, const ProfilingRequestSet &  prs, Event  wait_on = Event::NO_EVENT  )

static

create_instance() [2/5]

template<int N, typename T >

static Event Realm::RegionInstance::create_instance ( RegionInstance &  inst, Memory  memory, const IndexSpace< N, T > &  space, const std::vector< size_t > &  field_sizes, size_t  block_size, const ProfilingRequestSet &  prs, Event  wait_on = Event::NO_EVENT  )

static

Create a new region instance based on an index space. block_size=0 means SOA, block_size=1 means AOS, block_size>1 means hybrid (block_size fields per block).

Parameters

inst	The handle to the new instance.
memory	The memory to create the instance in.
space	The index space to create the instance for.
field_sizes	The size of each field in the instance.
block_size	The block size to use for the instance.
prs	The profiling requests for the instance.
wait_on	The event to wait on before creating the instance.

Returns

The event to wait on before using the instance.

create_instance() [3/5]

static Event Realm::RegionInstance::create_instance ( RegionInstance &  inst, Memory  memory, const InstanceLayoutGeneric &  ilg, const ProfilingRequestSet &  prs, Event  wait_on = Event::NO_EVENT  )

static

Create a new region instance. Calls to create_instance return immediately with a handle, but also return an event that must be used as a precondition for any use (or destruction) of the instance.

Parameters

inst	The handle to the new instance.
memory	The memory to create the instance in.
ilg	The layout of the instance.
prs	The profiling requests for the instance.
wait_on	The event to wait on before creating the instance.

Returns

The event to wait on before using the instance.

create_instance() [4/5]

template<int N, typename T >

static Event Realm::RegionInstance::create_instance ( RegionInstance &  inst, Memory  memory, const Rect< N, T > &  rect, const std::map< FieldID, size_t > &  field_sizes, size_t  block_size, const ProfilingRequestSet &  prs, Event  wait_on = Event::NO_EVENT  )

static

create_instance() [5/5]

template<int N, typename T >

static Event Realm::RegionInstance::create_instance ( RegionInstance &  inst, Memory  memory, const Rect< N, T > &  rect, const std::vector< size_t > &  field_sizes, size_t  block_size, const ProfilingRequestSet &  prs, Event  wait_on = Event::NO_EVENT  )

static

decrement_accessor_count()

REALM_INTERNAL_API_EXTERNAL_LINKAGE bool Realm::RegionInstance::decrement_accessor_count

(

void

)

destroy() [1/2]

void Realm::RegionInstance::destroy	(	const std::vector< DestroyedField > &	destroyed_fields,
		Event	wait_on = Event::NO_EVENT
	)		const

destroy() [2/2]

void Realm::RegionInstance::destroy

(

Event

wait_on = Event::NO_EVENT

)

const

exists()

REALM_CUDA_HD bool Realm::RegionInstance::exists

(

void

)

const

fetch_metadata()

Event Realm::RegionInstance::fetch_metadata

(

Processor

target

)

const

Fetch the metadata for an instance on a given processor. Before you can get an instance's index space or construct an accessor for a given processor, the necessary metadata for the instance must be available on to that processor. This can require network communication and/or completion of the actual allocation, so an event is returned and (as always) the application must decide when/where to handle this precondition.

Parameters

target

The processor to fetch the metadata for.

Returns

The event to wait on before using the instance.

generate_resource_info() [1/2]

ExternalInstanceResource * Realm::RegionInstance::generate_resource_info

(

bool

read_only

)

const

Generate an ExternalInstanceResource object for this instance.

This function creates an ExternalInstanceResource object that represents this instance and can be used to register it as an "external" instance, which can provide a different view on the same bits. The returned object should be deleted by the caller when no longer needed.

Parameters

read_only

A flag indicating whether the instance will be used read-only.

Returns

An ExternalInstanceResource object for this instance, or null if the instance does not support re-registration.

generate_resource_info() [2/2]

ExternalInstanceResource * Realm::RegionInstance::generate_resource_info	(	const IndexSpaceGeneric &	space,
		span< const FieldID >	fields,
		bool	read_only
	)		const

get_indexspace() [1/2]

template<int N, typename T >

IndexSpace< N, T > Realm::RegionInstance::get_indexspace

(

void

)

const

get_indexspace() [2/2]

template<int N>

IndexSpace< N, int > Realm::RegionInstance::get_indexspace

(

void

)

const

get_layout()

const InstanceLayoutGeneric * Realm::RegionInstance::get_layout

(

void

)

const

get_location()

Memory Realm::RegionInstance::get_location

(

void

)

const

get_lookup_program() [1/2]

template<int N, typename T >

REALM_INTERNAL_API_EXTERNAL_LINKAGE const PieceLookup::Instruction * Realm::RegionInstance::get_lookup_program	(	FieldID	field_id,
		const Rect< N, T > &	subrect,
		unsigned	allowed_mask,
		uintptr_t &	field_offset
	)

get_lookup_program() [2/2]

template<int N, typename T >

REALM_INTERNAL_API_EXTERNAL_LINKAGE const PieceLookup::Instruction * Realm::RegionInstance::get_lookup_program	(	FieldID	field_id,
		unsigned	allowed_mask,
		uintptr_t &	field_offset
	)

Return a compiled piece lookup program for a given field.

Parameters

field_id	The field ID to look up.
allowed_mask	A mask of allowed piece types.
field_offset	The offset of the field within the piece.

Returns

A pointer to the compiled piece lookup program.

get_strided_access_parameters()

void Realm::RegionInstance::get_strided_access_parameters	(	size_t	start,
		size_t	count,
		ptrdiff_t	field_offset,
		size_t	field_size,
		intptr_t &	base,
		ptrdiff_t &	stride
	)

increment_accessor_count()

REALM_INTERNAL_API_EXTERNAL_LINKAGE bool Realm::RegionInstance::increment_accessor_count

(

void

)

operator id_t()

constexpr Realm::RegionInstance::operator id_t ( ) const

inlineconstexpr

operator!=()

bool Realm::RegionInstance::operator!=

(

const RegionInstance &

rhs

)

const

operator<()

bool Realm::RegionInstance::operator<

(

const RegionInstance &

rhs

)

const

operator==()

bool Realm::RegionInstance::operator==

(

const RegionInstance &

rhs

)

const

pointer()

template<typename T >

T * Realm::RegionInstance::pointer

(

size_t

offset

)

const

pointer_untyped()

void * Realm::RegionInstance::pointer_untyped	(	size_t	offset,
		size_t	datalen
	)		const

Return a pointer to the instance data. Returns a null pointer if the instance storage cannot be directly accessed via load/store instructions.

Parameters

offset	The offset into the instance to read from.
datalen	The number of bytes to read.

Returns

A pointer to the instance data.

read()

template<typename T >

T Realm::RegionInstance::read

(

size_t

offset

)

const

read_untyped()

void Realm::RegionInstance::read_untyped	(	size_t	offset,
		void *	data,
		size_t	datalen
	)		const

Read data from an instance. Users are encouraged to use the various accessors which make repeated accesses much more efficient.

Parameters

offset	The offset into the instance to read from.
data	A pointer to the data to read into.
datalen	The number of bytes to read.

REALM_ATTR_DEPRECATED() [1/4]

Realm::RegionInstance::REALM_ATTR_DEPRECATED	(	"use RegionInstance::create_external_instance instead"	,
		static Event	create_externalRegionInstance &inst, Memory memory, uintptr_t base, InstanceLayoutGeneric *ilg, const ProfilingRequestSet &prs, Event wait_on=Event::NO_EVENT
	)

REALM_ATTR_DEPRECATED() [2/4]

template<int N, typename T >

Realm::RegionInstance::REALM_ATTR_DEPRECATED	(	"use RegionInstance::create_external_instance instead"	,
		static Event	create_file_instanceRegionInstance &inst, const char *file_name, const IndexSpace< N, T > &space, const std::vector< FieldID > &field_ids, const std::vector< size_t > &field_sizes, realm_file_mode_t file_mode, const ProfilingRequestSet &prs, Event wait_on=Event::NO_EVENT
	)

REALM_ATTR_DEPRECATED() [3/4]

Realm::RegionInstance::REALM_ATTR_DEPRECATED	(	"use RegionInstance::create_external_instance with layout reference instead"	,
		static Event	create_external_instanceRegionInstance &inst, Memory memory, InstanceLayoutGeneric *ilg, const ExternalInstanceResource &resource, const ProfilingRequestSet &prs, Event wait_on=Event::NO_EVENT
	)

REALM_ATTR_DEPRECATED() [4/4]

Realm::RegionInstance::REALM_ATTR_DEPRECATED	(	"use RegionInstance::create_instance with layout reference instead"	,
		static Event	create_instanceRegionInstance &inst, Memory memory, InstanceLayoutGeneric *ilg, const ProfilingRequestSet &prs, Event wait_on=Event::NO_EVENT
	)

redistrict() [1/2]

Event Realm::RegionInstance::redistrict	(	RegionInstance &	instance,
		const InstanceLayoutGeneric *	layout,
		const ProfilingRequestSet &	prs,
		Event	wait_on = Event::NO_EVENT
	)

Reuse the underlying memory of an instance to create a new instance with a different layout. The new layout must fit within the footprint of the old instance or the new allocation will fail. The old instance is always destroyed in the process.

Parameters

instance	resulting instance
layout	of a new instance to be created
prs	profiling information
wait_on	precondition to wait on

Returns

The event to wait on before using the new instance.

redistrict() [2/2]

Event Realm::RegionInstance::redistrict	(	RegionInstance *	instances,
		const InstanceLayoutGeneric **	layouts,
		size_t	num_layouts,
		const ProfilingRequestSet *	prs,
		Event	wait_on = Event::NO_EVENT
	)

Reuse the underlying memory of an instance to create a new set of instances with different layouts. Only as many of the new layouts as can fit in the footprint will be allocated. The ordering of the new layouts is important as they will be allocated in this order (pay attention to alignments). The old instance will always be destroyed in the process.

Parameters

instances	instances to be redistricted
layouts	layouts for new instances
num_layouts	number of instances and instance layouts
prs	profiling information
wait_on	precondition to wait on

Returns

The event to wait on before using the new instance.

reduce_apply()

template<typename T >

void Realm::RegionInstance::reduce_apply	(	size_t	offset,
		ReductionOpID	redop_id,
		T	val,
		bool	exclusive = false
	)		const

reduce_apply_untyped()

void Realm::RegionInstance::reduce_apply_untyped	(	size_t	offset,
		ReductionOpID	redop_id,
		const void *	data,
		size_t	datalen,
		bool	exclusive = false
	)		const

reduce_fold()

template<typename T >

void Realm::RegionInstance::reduce_fold	(	size_t	offset,
		ReductionOpID	redop_id,
		T	val,
		bool	exclusive = false
	)		const

reduce_fold_untyped()

void Realm::RegionInstance::reduce_fold_untyped	(	size_t	offset,
		ReductionOpID	redop_id,
		const void *	data,
		size_t	datalen,
		bool	exclusive = false
	)		const

report_instance_fault()

void Realm::RegionInstance::report_instance_fault	(	int	reason,
		const void *	reason_data,
		size_t	reason_size
	)		const

write()

template<typename T >

void Realm::RegionInstance::write	(	size_t	offset,
		T	val
	)		const

write_untyped()

void Realm::RegionInstance::write_untyped	(	size_t	offset,
		const void *	data,
		size_t	datalen
	)		const

Member Data Documentation

id

id_t Realm::RegionInstance::id

NO_INST

const RegionInstance Realm::RegionInstance::NO_INST

static

---

The documentation for this class was generated from the following file:

• /home/runner/work/realm/realm/realm-src/src/realm/instance.h