GNU Astronomy Utilities


Next: , Previous: , Up: Gnuastro library   [Contents][Index]


10.3.4 Pointers (pointer.h)

Pointers play an important role in the C programming language. As the name suggests, they point to a byte in memory (like an address in a city). The C programming language gives you complete freedom in how to use the byte (and the bytes that follow it). Pointers are thus a very powerful feature of C. However, as the saying goes: “With great power comes great responsibility”, so they must be approached with care. The functions in this header are not very complex, they are just wrappers over some basic pointer functionality regarding pointer arithmetic and allocation (in memory or HDD/SSD).

Function:
void *
gal_pointer_increment (void *pointer, size_t increment, uint8_t type)

Return a pointer to an element that is increment elements ahead of pointer, assuming each element has type of type. For the type codes, see Library data types (type.h).

When working with the array elements of gal_data_t, we are actually dealing with void * pointers. However, pointer arithmetic doesn’t apply to void *, because the system doesn’t know how many bytes there are in each element to increment the pointer respectively. This function will use the given type to calculate where the incremented element is located in memory.

Function:
size_t
gal_pointer_num_between (void *earlier, void *later, uint8_t type)

Return the number of elements (in the given type) between earlier and later. For the type codes, see Library data types (type.h)).

Function:
void *
gal_pointer_allocate (uint8_t type, size_t size, int clear, const char *funcname, const char *varname)

Allocate an array of type type with size elements in RAM (for the type codes, see Library data types (type.h)). If clear!=0, then the allocated space is set to zero (cleared). This is effectively just a wrapper around C’s malloc or calloc functions but takes Gnuastro’s integer type codes and will also abort with a clear error if there the allocation was not successful.

When space cannot be allocated, this function will abort the program with a message containing the reason for the failure. funcname (name of the function calling this function) and varname (name of variable that needs this space) will be used in this error message if they are not NULL. In most modern compilers, you can use the generic __func__ variable for funcname. In this way, you don’t have to manually copy and paste the function name or worry about it changing later (__func__ was standardized in C99).

Function:
void *
gal_pointer_allocate_mmap (size_t size, uint8_t type, int clear, char **mmapname)

Allocate the necessary space to keep size elements of type type in HDD/SSD (a file, not in RAM). for the type codes, see Library data types (type.h). If clear!=0, then the allocated space will also be cleared. The allocation is done using C’s mmap function. The name of the file containing the allocated space is an allocated string that will be put in *mmapname.

Note that the kernel doesn’t allow an infinite number of memory mappings to files. So it is not recommended to use this function with every allocation. The best case scenario to use this function is for large arrays that are very large and can fill up the RAM. Keep the smaller arrays in RAM, which is faster and can have a (theoretically) unlimited number of allocations.

When you are done with the dataset and don’t need it anymore, don’t use free (the dataset isn’t in RAM). Just delete the file (and the allocated space for the filename) with the commands below:

remove(mmapname);
free(mmapname);

Next: , Previous: , Up: Gnuastro library   [Contents][Index]