CPtr¶

Usage

use CPtr;

or

import CPtr;

This module contains Chapel types that can serve as C pointer types for the purposes of interoperability and methods to work with them.

See also C Interoperability.

type c_void_ptr = chpl__c_void_ptr¶: A Chapel type alias for ‘void*’ in C.

proc c_nil¶: A Chapel version of a C NULL pointer.

proc is_c_nil(x): bool¶

Returns: true if the passed value is a NULL pointer (ie 0).

class c_ptr¶

Represents a local C pointer for the purpose of C integration. This class represents the equivalent to a C language pointer. Instances of this class support assignment to other instances or nil, == or != comparison with a c_void_ptr or with nil, and casting to another c_ptr type or to the c_void_ptr type.

As with a Chapel class, a c_ptr can be tested non-nil simply by including it in an if statement conditional, like so:

var x: c_ptr = c_ptrTo(...);
if x then do writeln("x is not nil");
if !x then do writeln("x is nil");

Additionally, a c_ptr can be output like so:

var x: c_ptr = c_ptrTo(...);
writeln(x); // outputs nil or e.g. 0xabc123000000

type eltType¶: The type that this pointer points to

proc this(i: integral) ref¶: Retrieve the i’th element (zero based) from a pointer to an array. Does the equivalent of ptr[i] in C.

proc deref() ref¶: Get element pointed to directly by this pointer. If the pointer refers to an array, this will return ptr[0].

proc writeThis(ch) throws¶: Print this pointer

record c_array¶

This class represents a C array with fixed size. A variable of type c_array can coerce to a c_ptr with the same element type. In that event, the pointer will be equivalent to c_ptrTo(array[0]). A c_array behaves similarly to a homogeneous tuple except that its indices start at 0 and it is guaranteed to be stored in contiguous memory. A c_array variable has value semantics. Declaring one as a function local variable will create the array elements in the function’s stack. Assigning or copy initializing will result in copying the elements (vs resulting in two pointers that refer to the same elements). A nil c_array is not representable in Chapel.

type eltType¶: The array element type

param size¶: The fixed number of elements

proc init(type eltType, param size)¶

proc deinit()¶

proc ref this(i: integral) ref: eltType: Retrieve the i’th element (zero based) from the array. Does the equivalent of arr[i] in C. Includes bounds checking when such checks are enabled.

proc ref this(param i: integral) ref: eltType: As with the previous function, returns the i’th element (zero based) from the array. This one emits a compilation error if i is out of bounds.

proc writeThis(ch) throws¶: Print the elements

proc init=(other: c_array)¶

proc type c_array.=(ref lhs: c_array, rhs: c_array)¶: Copy the elements from one c_array to another. Raises an error at compile time if the array sizes or element types do not match.

proc =(ref lhs: c_ptr, ref rhs: c_array)¶

proc c_ptrTo(arr: [])¶

Returns a c_ptr to the elements of a non-distributed Chapel rectangular array. Note that the existence of this c_ptr has no impact on the lifetime of the array. The returned pointer will be invalid if the original array is freed or even reallocated. Domain assignment could make this c_ptr invalid.

Arguments: arr – the array for which a pointer should be returned
Returns: a pointer to the array’s elements

proc c_ptrTo(ref x: ?t): c_ptr(t)

Returns a c_ptr to any Chapel object. Note that the existence of the c_ptr has no impact of the lifetime of the object. In many cases the object will be stack allocated and could go out of scope even if this c_ptr remains.

Arguments: x – the by-reference argument to get a pointer to. The argument should not be an array or domain (there is a different overload for arrays). Records, class instances, integral, real, imag, and complex types are supported.
Returns: a pointer to the argument passed by reference

proc c_sizeof(type x): size_t¶

Return the size in bytes of a type, as with the C sizeof built-in.

Warning

This method is intended for C interoperability. To enhance flexibility, it is possible to request the sizes of Chapel types. However, be aware:

Chapel types are not necessarily stored in contiguous memory

Behavior of c_sizeof with Chapel types may change

Behavior given a Chapel class type is not well-defined

proc c_offsetof(type t, param fieldname: string): size_t¶

Return the offset of a field in a record.

Warning

This method is intended for C interoperability. To enhance flexibility, it is possible to request the offset of elements within a Chapel record. However, be aware:

Chapel types are not necessary stored in contiguous memory
Behavior of c_offsetof may change
Behavior given a Chapel class type field is not well-defined

proc c_calloc(type eltType, size: integral): c_ptr(eltType)¶

Allocate memory and initialize all bits to 0. Note that this simply zeros memory, it does not call Chapel initializers (it is meant for primitive types and C interoperability only.) This memory should eventually be freed with c_free.

Arguments

eltType – the type of the elements to allocate
size – the number of elements to allocate space for

Returns

a c_ptr(eltType) to allocated memory

proc c_malloc(type eltType, size: integral): c_ptr(eltType)¶

Allocate memory that is not initialized. This memory should eventually be freed with c_free.

Arguments

eltType – the type of the elements to allocate
size – the number of elements to allocate space for

Returns

a c_ptr(eltType) to allocated memory

proc c_aligned_alloc(type eltType, alignment: integral, size: integral): c_ptr(eltType)¶

Allocate aligned memory that is not initialized. This memory should be eventually freed with c_free.

This function is intended to behave similarly to the C17 function aligned_alloc.

Arguments

eltType – the type of the elements to allocate
alignment – the memory alignment of the allocation which must be a power of two and a multiple of c_sizeof(c_void_ptr).
size – the number of elements to allocate space for

Returns

a c_ptr(eltType) to allocated memory

proc c_free(data: c_void_ptr)¶

Free memory that was allocated with c_calloc or c_malloc.

Arguments: data – the c_ptr to memory that was allocated. Note that both c_ptr(t) and c_void_ptr can be passed to this argument.

proc isAnyCPtr(type t: c_ptr) param¶: Returns true if t is a c_ptr type or c_void_ptr.

proc c_memmove(dest: c_void_ptr, const src: c_void_ptr, n: integral)¶

Copies n potentially overlapping bytes from memory area src to memory area dest.

This is a simple wrapper over the C memmove() function.

Arguments

dest – the destination memory area to copy to
src – the source memory area to copy from
n – the number of bytes from src to copy to dest

proc c_memcpy(dest: c_void_ptr, const src: c_void_ptr, n: integral)¶

Copies n non-overlapping bytes from memory area src to memory area dest. Use c_memmove if memory areas do overlap.

This is a simple wrapper over the C memcpy() function.

Arguments

dest – the destination memory area to copy to
src – the source memory area to copy from
n – the number of bytes from src to copy to dest

proc c_memcmp(const s1: c_void_ptr, const s2: c_void_ptr, n: integral)¶

Compares the first n bytes of memory areas s1 and s2

This is a simple wrapper over the C memcmp() function.

Returns: returns an integer less than, equal to, or greater than zero if the first n bytes of s1 are found, respectively, to be less than, to match, or be greater than the first n bytes of s2.

proc c_memset(s: c_void_ptr, c: integral, n: integral)¶

Fill bytes of memory with a particular byte value.

This is a simple wrapper over the C memset() function.

Arguments

s – the destination memory area to fill
c – the byte value to use
n – the number of bytes of s to fill

Returns

s