MemMove

Usage

use MemMove;

or

import MemMove;

Support for move-initializing and deinitializing values.

The MemMove module provides functions which enable users to move-initialize and deinitialize values.

The functionality provided by this module can be used to implement collections in a manner similar to those implemented by the Chapel standard modules (such as List or Map).

Note

Throughout documentation, the term variable also includes non-const formals, array elements, record or class fields, and tuple components.

proc needsDeinit(type t) param

Warning

‘needsDeinit’ is deprecated; please use ‘needsDestroy’ instead

Check to see if a given type needs to be deinitialized.

Arguments:

t : type – A type to check for deinitialization

Returns:

true if t needs to be deinitialized

Return type:

param bool

proc needsDestroy(type t) param : bool

Check to see if a given type would normally be destroyed automatically by the compiler when its lifetime ends. For example, passing an owned class would see this function return true, whereas passing an unmanaged class would result in false.

A shared class would also result in true because the compiler destroys shared variables to decrement the reference count (and possibly the object being managed, as well).

Arguments:

t : type – A type to check

Returns:

true if t needs to be automatically destroyed

Return type:

param bool

proc explicitDeinit(ref arg: ?t)

Warning

‘explicitDeinit’ is now deprecated; please use ‘destroy’ instead

Explicitly deinitialize a variable. The variable referred to by arg should be considered uninitialized after a call to this function.

Warning

At present the compiler does not account for deinitialization performed upon a call to explicitDeinit(). It should only be called when deinitialization would not occur otherwise.

Arguments:

arg – A variable to deinitialize

proc destroy(ref obj: ?t)

Explicitly destroy a variable as the compiler would when its lifetime ends. The variable referred to by obj should be considered unusable after a call to this function, and its particular state is undefined.

This function has no effect if needsDestroy returns false for the argument’s type.

Warning

At present the compiler does not account for manual destruction performed upon a call to destroy(). It should only be called when automatic destruction would not occur otherwise.

Arguments:

obj – A variable to deinitialize

proc moveInitialize(ref dst, in src)

Move-initialize dst with the value in src. The contents of dst are not deinitialized before the move, and src is not deinitialized after the move.

Warning

If dst references an already initialized variable, it will be overwritten by the contents of src without being deinitialized first. Call destroy() to deinitialize dst if necessary.

Warning

The static types of dst and src must match, or else a compile-time error will be issued.

Note

If the compiler inserts a copy for the argument to src, then a compile-time error will be issued. The most likely cause is that the argument is used elsewhere following the call to moveInitialize. The moveFrom function can be used with the src argument to avoid the copy when certain of the variable’s usage:

moveInitialize(myDst, moveFrom(mySrc));

Arguments:

  • dst – A variable to move-initialize, whose type matches src

  • src – A value to move-initialize from

proc moveFrom(const ref src: ?t)

Move the contents of the variable or constant referred to by src into a new returned value.

Warning

The variable or constant referred to by src should be considered uninitialized after a call to this function.

Arguments:

src – A variable or constant to move

Returns:

The contents of src moved into a new value

proc moveSwap(ref x: ?t, ref y: t)

Swap the contents of the variables referred to by x and y. This function does not call the <=> operator. Unlike the <=> operator, moveSwap() does not perform assignment or initialization.

Arguments:

  • x – A variable to swap

  • y – A variable to swap

proc moveArrayElements(ref dst: [] ?eltType, const dstRegion, const ref src: [] eltType, const srcRegion) : void throws

Warning

‘moveArrayElements’ is unstable and subject to change in the future

Move-initialize a group of array elements from a group of elements in another array. This function is equivalent to a sequence of individual calls to moveInitialize().

This function only accepts rectangular arrays, rectangular domains, or ranges. The index type of the regions must also match the index type of their corresponding arrays. Any range arguments must have both an upper and lower bound.

Arguments:

  • dst – The destination array

  • dstRegion – A domain or range of indices in dst

  • src – The source array

  • srcRegion – A domain or range of indices in src

Throws:

IllegalArgumentError – if region sizes do not match, if a region contains indices not in the corresponding array, if src and dst are determined to be aliases and the regions overlap.

proc moveArrayElements(ref dst: [] ?eltType, const ref src: [] eltType) : void throws

Warning

‘moveArrayElements’ is unstable and subject to change in the future

Move-initialize a group of array elements from a group of elements in another array. This function is equivalent to a sequence of individual calls to moveInitialize().

This function only accepts rectangular arrays.

Arguments:

  • dst – The destination array

  • src – The source array

Throws:

IllegalArgumentError – if the array sizes do not match, if src and dst are determined to be aliases and overlap.

proc moveInitializeArrayElements(ref a: [?d], dstStartIndex: a.idxType, srcStartIndex: a.idxType, numElements: int)

Warning

‘moveInitializeArrayElements’ is deprecated; please use ‘moveArrayElements’ instead

Move-initialize a group of array elements from a group of elements in the same array. This function is equivalent to a sequence of individual calls to moveInitialize().

Warning

This function will halt if the value of numElements is negative, or if any of the elements in dstStartIndex..#numElements or srcStartIndex..#numElements are out of bounds.

This function will halt if the ranges dstStartIndex..#numElements and srcStartIndex..#numElements intersect.

No checks will occur when the –fast or –no-checks flags are used.

Arguments:

  • a – The array with source and destination elements

  • dstStartIndex : a.idxType – Destination index of elements to move-initialize

  • srcStartIndex : a.idxType – Source index of elements to move-initialize from

  • numElements : int – The number of elements to move-initialize

proc moveInitializeArrayElements(ref dstA: [] ?t, dstStartIndex: dstA.idxType, srcA: [] t, srcStartIndex: srcA.idxType, numElements: int)

Warning

‘moveInitializeArrayElements’ is deprecated; please use ‘moveArrayElements’ instead

Move-initialize a group of array elements from a group of elements in another array. This function is equivalent to a sequence of individual calls to moveInitialize().

Warning

This function will halt if the value of numElements is negative, or if any of the elements in dstStartIndex..#numElements or srcStartIndex..#numElements are out of bounds.

This function will halt if dstA and srcA are the same array and the ranges dstStartIndex..#numElements and srcStartIndex..#numElements intersect.

No checks will occur when the –fast or –no-checks flags are used.

Arguments:

  • dstA – The array with destination elements

  • dstStartIndex : dstA.idxType – Destination index of elements to move-initialize

  • srcA : An array with the same element type as dstA.eltType – The array with source elements

  • srcStartIndex : srcA.idxType – Source index of elements to move-initialize from

  • numElements : int – The number of elements to move-initialize