Routines for allocation and reclamation of global memory regions and local address resolution in partitioned global address space. More...

Collaboration diagram for Global memory and PGAS address semantics:

Classes
struct	dart_gptr_t
	DART Global pointer type. More...

Macros
#define	DART_GPTR_NULL
	A NULL global pointer. More...

#define	DART_GPTR_ISNULL(gptr_)
	Test for NULL global pointer. More...

#define	DART_GPTR_EQUAL(gptr1_, gptr2_)
	Compare two global pointers. More...

Functions
dart_ret_t	dart_gptr_getaddr (const dart_gptr_t gptr, void **addr)
	Get the local memory address for the specified global pointer gptr. More...

dart_ret_t	dart_gptr_setaddr (dart_gptr_t gptr, void addr)
	Set the local memory address for the specified global pointer such the the specified address. More...

static	__attribute__ ((unused)) dart_ret_t dart_gptr_incaddr(dart_gptr_t *gptr
	Add 'offs' to the address specified by the global pointer. More...

dart_ret_t	dart_gptr_getflags (dart_gptr_t gptr, uint16_t *flags)
	Get the flags field for the segment specified by the global pointer. More...

dart_ret_t	dart_gptr_setflags (dart_gptr_t *gptr, uint16_t flags)
	Set the flags field for the segment specified by the global pointer. More...

dart_ret_t	dart_allocator_new (size_t pool_size, dart_team_t team, dart_allocator_t *new_allocator)
	Create a new allocator for non-collective global memory allocations. More...

dart_ret_t	dart_allocator_alloc (size_t nelem, dart_datatype_t dtype, dart_gptr_t *gptr, dart_allocator_t allocator)
	Allocate global memory from a DART allocator instance created using dart_allocator_new. More...

dart_ret_t	dart_allocator_free (dart_gptr_t *gptr, dart_allocator_t allocator)
	Free memory allocated through dart_allocator_alloc. More...

dart_ret_t	dart_allocator_destroy (dart_allocator_t *allocator)
	Destroy an allocator created through dart_allocator_new. More...

dart_ret_t	dart_memalloc (size_t nelem, dart_datatype_t dtype, dart_gptr_t *gptr)
	Allocates memory for `nelem` elements of type `dtype` in the global address space of the calling unit and returns a global pointer to it. More...

dart_ret_t	dart_memfree (dart_gptr_t gptr)
	Frees memory in the global address space allocated by a previous call of dart_memalloc. More...

dart_ret_t	dart_team_memalloc_aligned (dart_team_t teamid, size_t nelem, dart_datatype_t dtype, dart_gptr_t *gptr)
	Collective function on the specified team to allocate `nelem` elements of type `dtype` of memory in each unit's global address space with a local displacement of the specified type. More...

dart_ret_t	dart_team_memfree (dart_gptr_t gptr)
	Collective function to free global memory previously allocated using dart_team_memalloc_aligned. More...

dart_ret_t	dart_team_memregister_aligned (dart_team_t teamid, size_t nelem, dart_datatype_t dtype, void addr, dart_gptr_t gptr)
	Collective function similar to dart_team_memalloc_aligned but on previously externally allocated memory. More...

dart_ret_t	dart_team_memregister (dart_team_t teamid, size_t nlelem, dart_datatype_t dtype, void addr, dart_gptr_t gptr)
	Collective function, attaches external memory previously allocated by the user. More...

dart_ret_t	dart_team_memderegister (dart_gptr_t gptr)
	Collective function similar to dart_team_memfree() but on previously externally allocated memory. More...

Detailed Description

Routines for allocation and reclamation of global memory regions and local address resolution in partitioned global address space.

Macro Definition Documentation

◆ DART_GPTR_EQUAL

#define DART_GPTR_EQUAL	(	gptr1_,
		gptr2_
	)

#include </tmp/tmporruphar/dart-if/include/dash/dart/if/dart_globmem.h>

Value:

((gptr1_.unitid == gptr2_.unitid) &&      \
   (gptr1_.segid  == gptr2_.segid)  &&      \
   (gptr1_.teamid == gptr2_.teamid) &&      \
   (gptr1_.addr_or_offs.offset ==           \
    gptr2_.addr_or_offs.offset) )

Compare two global pointers.

Definition at line 128 of file dart_globmem.h.

Referenced by dash::EpochSynchronizedAllocator< ElementType, LMemSpace, AllocationPolicy, LocalAlloc >::deallocate(), dash::EpochSynchronizedAllocator< ElementType, LMemSpace, AllocationPolicy, LocalAlloc >::get_local_allocator(), dash::GlobRef< T >::operator=(), and dash::GlobPtr< event_ctr_t, globmem_t >::operator==().

◆ DART_GPTR_ISNULL

#define DART_GPTR_ISNULL ( gptr_ )

#include </tmp/tmporruphar/dart-if/include/dash/dart/if/dart_globmem.h>

Value:

(gptr_.unitid<0 && gptr_.segid==0 &&  \
   gptr_.teamid==DART_TEAM_NULL   &&    \
   gptr_.addr_or_offs.addr==0)

Test for NULL global pointer.

Definition at line 118 of file dart_globmem.h.

Referenced by dash::EpochSynchronizedAllocator< ElementType, LMemSpace, AllocationPolicy, LocalAlloc >::allocate(), dash::allocator::GlobalAllocationPolicy< allocation_static, synchronization_collective, LMemSpaceTag >::allocate_segment(), dash::allocator::GlobalAllocationPolicy< allocation_static, synchronization_collective, memory_space_host_tag >::allocate_segment(), dash::EpochSynchronizedAllocator< ElementType, LMemSpace, AllocationPolicy, LocalAlloc >::attach(), dash::GlobIter< value_type, Pattern_t, GlobMem_t >::dart_gptr(), dash::EpochSynchronizedAllocator< ElementType, LMemSpace, AllocationPolicy, LocalAlloc >::deallocate(), dash::EpochSynchronizedAllocator< ElementType, LMemSpace, AllocationPolicy, LocalAlloc >::deallocate_local(), dash::allocator::GlobalAllocationPolicy< allocation_static, synchronization_collective, memory_space_host_tag >::deallocate_segment(), dash::EpochSynchronizedAllocator< ElementType, LMemSpace, AllocationPolicy, LocalAlloc >::detach(), dash::GlobLocalMemoryPool< dash::HostSpace >::flush_local(), dash::GlobPtr< event_ctr_t, globmem_t >::is_local(), dash::GlobSharedRef< T, GlobalPointerType >::operator=(), and dash::GlobPtr< event_ctr_t, globmem_t >::operator==().

◆ DART_GPTR_NULL

#define DART_GPTR_NULL

#include </tmp/tmporruphar/dart-if/include/dash/dart/if/dart_globmem.h>

Value:

(dart_gptr_t){ .unitid = -1, \
               .flags  =  0, \
               .segid  =  0, \
               .teamid  =  DART_TEAM_NULL, \
               .addr_or_offs.offset = 0 }

A NULL global pointer.

Definition at line 105 of file dart_globmem.h.

Referenced by dash::allocator::GlobalAllocationPolicy< allocation_static, synchronization_collective, memory_space_host_tag >::allocate_segment(), dash::allocator::GlobalAllocationPolicy< allocation_static, synchronization_single, memory_space_host_tag >::allocate_segment(), dash::EpochSynchronizedAllocator< ElementType, LMemSpace, AllocationPolicy, LocalAlloc >::attach(), dash::GlobIter< value_type, Pattern_t, GlobMem_t >::dart_gptr(), dash::UnorderedMapLocalIter< Key, Mapped, Hash, Pred, LMemSpace >::dart_gptr(), dash::EpochSynchronizedAllocator< ElementType, LMemSpace, AllocationPolicy, LocalAlloc >::detach(), dash::GlobLocalMemoryPool< dash::HostSpace >::flush_local(), dash::EpochSynchronizedAllocator< ElementType, LMemSpace, AllocationPolicy, LocalAlloc >::get_local_allocator(), dash::GlobHeapMem< ElementType, LocalMemorySpace, AllocationPolicy, LocalAlloc >::grow(), and dash::GlobPtr< event_ctr_t, globmem_t >::operator=().

Function Documentation

◆ attribute()

static __attribute__ ( (unused) )

inlinestatic

#include </tmp/tmporruphar/dart-if/include/dash/dart/if/dart_globmem.h>

Add 'offs' to the address specified by the global pointer.

Set the unit information for the specified global pointer.

Parameters

gptr	Global pointer
offs	Offset by which to increment `gptr`

Returns: DART_OK on success, any other of dart_ret_t otherwise.

Thread safety: This function is safe to be called by multiple threads in parallel.

Parameters

gptr	Global Pointer
unit	The global unit to set in `gptr`

Returns: DART_OK on success, any other of dart_ret_t otherwise.

Thread safety: This function is safe to be called by multiple threads in parallel.

◆ dart_allocator_alloc()

dart_ret_t dart_allocator_alloc	(	size_t	nelem,
		dart_datatype_t	dtype,
		dart_gptr_t *	gptr,
		dart_allocator_t	allocator
	)

#include </tmp/tmporruphar/dart-if/include/dash/dart/if/dart_globmem.h>

Allocate global memory from a DART allocator instance created using dart_allocator_new.

The operation is not a collective operation but only involves the local unit. The resulting dart_gptr_t can be communicated to other units for global memory access.

Parameters

nelem	The number elements to be allocated.
dtype	The type of elements to be allocated.
gptr	Pointer to the resulting dart_gptr_t.
allocator	The allocator from which memory is allocated.

Returns: DART_OK on success, DART_ERR_NOMEM if the memory pool is exhausted, any other of dart_ret_t otherwise.

Thread safety: This function is safe to be called by multiple threads in parallel.

◆ dart_allocator_destroy()

dart_ret_t dart_allocator_destroy ( dart_allocator_t * allocator )

#include </tmp/tmporruphar/dart-if/include/dash/dart/if/dart_globmem.h>

Destroy an allocator created through dart_allocator_new.

This is a collective operation.

Parameters

allocator The allocator to be destroyed.

Returns: DART_OK on success, any other of dart_ret_t otherwise.

{team}

◆ dart_allocator_free()

dart_ret_t dart_allocator_free	(	dart_gptr_t *	gptr,
		dart_allocator_t	allocator
	)

#include </tmp/tmporruphar/dart-if/include/dash/dart/if/dart_globmem.h>

Free memory allocated through dart_allocator_alloc.

This call is only valid on the unit that allocated the memory.

Parameters

gptr	Pointer to the dart_gptr_t, will be reset to `DART_GPTR_NULL`.
allocator	The allocator from which the memory was allocated.

Returns: DART_OK on success, any other of dart_ret_t otherwise.

Thread safety: This function is safe to be called by multiple threads in parallel.

◆ dart_allocator_new()

dart_ret_t dart_allocator_new	(	size_t	pool_size,
		dart_team_t	team,
		dart_allocator_t *	new_allocator
	)

#include </tmp/tmporruphar/dart-if/include/dash/dart/if/dart_globmem.h>

Create a new allocator for non-collective global memory allocations.

This operation is collective among the units in team. The pool_size should be a power of 2 and will be scaled up to the next larger power of 2 if that is not the case.

Note: The allocator uses a simple buddy allocator in the background. For mixed-size allocations, the resulting fragmentation may lead to a lower net availability of the underlying memory pool.

Parameters

	pool_size	The size (in Bytes) of the local memory pool from which global memory is allocated in dart_allocator_alloc.
	team	The team describing the group of units.
[out]	new_allocator	Pointer the newly created allocator.

Returns: DART_OK on success, any other of dart_ret_t otherwise.

{team}

◆ dart_gptr_getaddr()

dart_ret_t dart_gptr_getaddr	(	const dart_gptr_t	gptr,
		void **	addr
	)

#include </tmp/tmporruphar/dart-if/include/dash/dart/if/dart_globmem.h>

Get the local memory address for the specified global pointer gptr.

I.e., if the global pointer has affinity to the local unit, return the local memory address.

Parameters

	gptr	Global pointer
[out]	addr	Pointer to a pointer that will hold the local address if the `gptr` points to a local memory element.

Returns: DART_OK on success, any other of dart_ret_t otherwise.

Thread safety: This function is safe to be called by multiple threads in parallel.

Referenced by dash::GlobPtr< event_ctr_t, globmem_t >::local().

◆ dart_gptr_getflags()

dart_ret_t dart_gptr_getflags	(	dart_gptr_t	gptr,
		uint16_t *	flags
	)

#include </tmp/tmporruphar/dart-if/include/dash/dart/if/dart_globmem.h>

Get the flags field for the segment specified by the global pointer.

Parameters

gptr	Global Pointer describing a segment.
flags	The flags to get for segment in `gptr`

Returns: DART_OK on success, any other of dart_ret_t otherwise.

Thread safety: This function is safe to be called by multiple threads in parallel.

◆ dart_gptr_setaddr()

dart_ret_t dart_gptr_setaddr	(	dart_gptr_t *	gptr,
		void *	addr
	)

#include </tmp/tmporruphar/dart-if/include/dash/dart/if/dart_globmem.h>

Set the local memory address for the specified global pointer such the the specified address.

Parameters

gptr	Global pointer
addr	Pointer holding the local address to set in `gptr`.

Returns: DART_OK on success, any other of dart_ret_t otherwise.

Thread safety: This function is safe to be called by multiple threads in parallel.

◆ dart_gptr_setflags()

dart_ret_t dart_gptr_setflags	(	dart_gptr_t *	gptr,
		uint16_t	flags
	)

#include </tmp/tmporruphar/dart-if/include/dash/dart/if/dart_globmem.h>

Set the flags field for the segment specified by the global pointer.

The flags are stored in the segment's meta data. The lower 8 bit of the flags are stored in the .flags field of the gptr for fast access. The remaining flags can be queried through dart_gptr_getflags.

Parameters

gptr	Global Pointer describing a segment.
flags	The flags to set for segment in `gptr`

Returns: DART_OK on success, any other of dart_ret_t otherwise.

Thread safety: This function is safe to be called by multiple threads in parallel.

◆ dart_memalloc()

dart_ret_t dart_memalloc	(	size_t	nelem,
		dart_datatype_t	dtype,
		dart_gptr_t *	gptr
	)

#include </tmp/tmporruphar/dart-if/include/dash/dart/if/dart_globmem.h>

Allocates memory for nelem elements of type dtype in the global address space of the calling unit and returns a global pointer to it.

This is not a collective function.

Parameters

	nelem	The number of elements of type `dtype` to allocate.
	dtype	The type to use.
[out]	gptr	Global Pointer to hold the allocation

Todo:: Does dart_memalloc really allocate in global memory?

Returns: DART_OK on success, any other of dart_ret_t otherwise.

Thread safety: This function is safe to be called by multiple threads in parallel.

Referenced by dash::allocator::GlobalAllocationPolicy< allocation_static, synchronization_single, memory_space_host_tag >::allocate_segment().

◆ dart_memfree()

dart_ret_t dart_memfree ( dart_gptr_t gptr )

#include </tmp/tmporruphar/dart-if/include/dash/dart/if/dart_globmem.h>

Frees memory in the global address space allocated by a previous call of dart_memalloc.

This is not a collective function.

Parameters

gptr	Global pointer to the memory allocation to free

Returns: DART_OK on success, any other of dart_ret_t otherwise.

Thread safety: This function is safe to be called by multiple threads in parallel.

Referenced by dash::allocator::GlobalAllocationPolicy< allocation_static, synchronization_single, memory_space_host_tag >::deallocate_segment().

◆ dart_team_memalloc_aligned()

dart_ret_t dart_team_memalloc_aligned	(	dart_team_t	teamid,
		size_t	nelem,
		dart_datatype_t	dtype,
		dart_gptr_t *	gptr
	)

#include </tmp/tmporruphar/dart-if/include/dash/dart/if/dart_globmem.h>

Collective function on the specified team to allocate nelem elements of type dtype of memory in each unit's global address space with a local displacement of the specified type.

The allocated memory is team-aligned, i.e., a global pointer to anywhere in the allocation can easily be formed locally. The global pointer to the beginning of the allocation is returned in gptr on each participating unit. Each participating unit has to call dart_team_memalloc_aligned with the same specification of teamid, dtype and nelem. Each unit will receive the a global pointer to the beginning of the allocation (on unit 0) in gptr. Accessibility of memory allocated with this function is limited to those units that are part of the team allocating the memory. I.e., if unit X was not part of the team that allocated the memory M, then X may not be able to access a memory location in M.

Parameters

	teamid	The team participating in the collective memory allocation.
	nelem	The number of elements to allocate per unit.
	dtype	The data type of elements in `addr`.
[out]	gptr	Global pointer to store information on the allocation.

Returns: DART_OK on success, any other of dart_ret_t otherwise.

{team}

Referenced by dash::allocator::GlobalAllocationPolicy< allocation_static, synchronization_collective, memory_space_host_tag >::allocate_segment().

◆ dart_team_memderegister()

dart_ret_t dart_team_memderegister ( dart_gptr_t gptr )

#include </tmp/tmporruphar/dart-if/include/dash/dart/if/dart_globmem.h>

Collective function similar to dart_team_memfree() but on previously externally allocated memory.

Does not de-allocate memory.

Parameters

gptr	Pointer to a global pointer object to set up.

Returns: DART_OK on success, any other of dart_ret_t otherwise.

See also: dart_team_memregister; dart_team_memregister_aligned

Thread safety: This function is not thread-safe.

◆ dart_team_memfree()

dart_ret_t dart_team_memfree ( dart_gptr_t gptr )

#include </tmp/tmporruphar/dart-if/include/dash/dart/if/dart_globmem.h>

Collective function to free global memory previously allocated using dart_team_memalloc_aligned.

After this operation, the global pointer should not be used in any communication unless re-used in another allocation. After this operation, the global pointer can be reset using DART_GPTR_NULL.

Parameters

gptr	Global pointer pointing to the memory to deallocate.

See also: DART_GPTR_NULL

Returns: DART_OK on success, any other of dart_ret_t otherwise.

{team}

Referenced by dash::allocator::GlobalAllocationPolicy< allocation_static, synchronization_collective, memory_space_host_tag >::deallocate_segment().

◆ dart_team_memregister()

dart_ret_t dart_team_memregister	(	dart_team_t	teamid,
		size_t	nlelem,
		dart_datatype_t	dtype,
		void *	addr,
		dart_gptr_t *	gptr
	)

#include </tmp/tmporruphar/dart-if/include/dash/dart/if/dart_globmem.h>

Collective function, attaches external memory previously allocated by the user.

Does not perform any memory allocation.

Parameters

teamid	The team to participate in the collective operation.
nlelem	The number of local elements allocated in `addr` to attach.
dtype	The data type of elements in `addr`.
addr	Pointer to pre-allocated memory to be registered.
gptr	Pointer to a global pointer object to set up.

Returns: DART_OK on success, any other of dart_ret_t otherwise.

Thread safety: This function is not thread-safe.

◆ dart_team_memregister_aligned()

dart_ret_t dart_team_memregister_aligned	(	dart_team_t	teamid,
		size_t	nelem,
		dart_datatype_t	dtype,
		void *	addr,
		dart_gptr_t *	gptr
	)

#include </tmp/tmporruphar/dart-if/include/dash/dart/if/dart_globmem.h>

Collective function similar to dart_team_memalloc_aligned but on previously externally allocated memory.

Does not perform any memory allocation.

Parameters

teamid	The team to participate in the collective operation.
nelem	The number of elements already allocated in `addr`.
dtype	The data type of elements in `addr`.
addr	Pointer to pre-allocated memory to be registered.
gptr	Pointer to a global pointer object to set up.

Returns: DART_OK on success, any other of dart_ret_t otherwise.

See also: dart_team_memalloc_aligned

{team}

Classes

Macros

Functions

Detailed Description

Macro Definition Documentation

◆ DART_GPTR_EQUAL

◆ DART_GPTR_ISNULL

◆ DART_GPTR_NULL

Function Documentation

◆ __attribute__()

◆ dart_allocator_alloc()

◆ dart_allocator_destroy()

◆ dart_allocator_free()

◆ dart_allocator_new()

◆ dart_gptr_getaddr()

◆ dart_gptr_getflags()

◆ dart_gptr_setaddr()

◆ dart_gptr_setflags()

◆ dart_memalloc()

◆ dart_memfree()

◆ dart_team_memalloc_aligned()

◆ dart_team_memderegister()

◆ dart_team_memfree()

◆ dart_team_memregister()

◆ dart_team_memregister_aligned()

◆ attribute()