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.

const c_nil: c_void_ptr

A Chapel version of a C NULL pointer.

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)

Print this pointer

proc c_ptrTo(arr: [])

Returns a c_ptr to a 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. If the array's data is stored in more than one chunk the procedure will halt the program with an error message.

Arguments:arr -- the array for which we should retrieve a pointer
Returns:a pointer to the array data
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_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_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) param

Returns true if t is a c_ptr type or c_void_ptr.

proc c_memmove(dest, const src, 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, const src, 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, const s2, 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: 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 b to fill
Returns:

s