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.
-
proc
c_nil
: c_void_ptr¶ 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 withnil
, and casting to anotherc_ptr
type or to thec_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
-
type
-
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)¶ Print the elements
-
proc
length
¶
-
proc
init
(other: c_array)
-
type
-
proc
=
(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 a Chapel rectangular array. Note that the existence of thisc_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 thisc_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 thec_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 thisc_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_free
(data: c_void_ptr)¶ Free memory that was allocated with
c_calloc
orc_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 b to fill
Returns: s