17.4.3 Funzioni per allocare memoria e macro di servizio

L’API fornisce alcune funzioni per effettuare allocazioni di memoria che possono essere passate a gawk, e anche un certo numero di macro che possono tornare utili. Questa sottosezione le presenta come prototipi di funzione, nel modo con cui il codice dell’estensione potrebbe usarle:

void *gawk_malloc(size_t size);

Chiama la versione corretta di malloc() per allocare memoria, che può in seguito essere messa a disposizione di gawk.

void *gawk_calloc(size_t nmemb, size_t size);

Chiama la versione corretta di calloc() per allocare memoria che che può in seguito essere messa a disposizione di gawk.

void *gawk_realloc(void *ptr, size_t size);

Chiama la versione corretta di realloc() per allocare memoria che può in seguito essere messa a disposizione di gawk.

void gawk_free(void *ptr);

Chiama la versione corretta di free() per liberare memoria che era stata allocata con gawk_malloc(), gawk_calloc() o gawk_realloc().

L’API deve fornire queste funzioni perché è possibile che un’estensione sia stata compilata e costruita usando una versione diversa della libreria C rispetto a quella usata per il programma eseguibile gawk.¹⁰⁹ Se gawk usasse la propria versione di free() per liberare della memoria acquisita tramite una differente versione di malloc(), il risultato sarebbe molto probabilmente differente da quello atteso.

Tre macro di utilità possono essere usate per allocare memoria tramite gawk_malloc(), gawk_calloc, e gawk_realloc(). Se l’allocazione non riesce, gawk termina l’esecuzione con un messaggio di errore fatale. Queste macro dovrebbero essere usate come se fossero dei richiami a procedure che non restituiscono un codice di ritorno:

#define emalloc(pointer, type, size, message) …

Gli argomenti per questa macro sono i seguenti:

pointer

La variabile di tipo puntatore che punterà alla memoria allocata.

type

Il tipo della variabile puntatore. Questo è usato per definire il tipo quando si chiama gawk_malloc().

size

Il numero totale di byte da allocare.

message

Un messaggio da anteporre all’eventuale messaggio di errore fatale. Questo è solitamente il nome della funzione che sta usando la macro.

Per esempio, si potrebbe allocare il valore di una stringa così:

awk_value_t risultato;
char *message;
const char greet[] = "Non v'allarmate!";

emalloc(message, char *, sizeof(greet), "myfunc");
strcpy(message, greet);
make_malloced_string(message, strlen(message), & risultato);

#define ezalloc(pointer, type, size, message) …

Questo è simile a emalloc(), ma chiama gawk_calloc() invece che gawk_malloc(). Gli argomenti sono gli stessi della macro emalloc(), ma questa macro garantisce che la memoria allocata sia inizializzata a zeri binari.

#define erealloc(pointer, type, size, message) …

Questo è simile a emalloc(), ma chiama gawk_realloc() invece che gawk_malloc(). Gli argomenti sono gli stessi della macro emalloc().

Due ulteriori funzioni allocano oggetti MPFR e GMP per essere usati da funzioni di estensione che necessitino di creare e di restituire valori di questo tipo:

void *get_mpfr_ptr();

Alloca e inizializza un oggetto MPFR e restituisce un puntatore allo stesso. Se l’allocazione non riesce, gawk termina con un errore fatale “out of memory” (memoria esaurita). Se gawk era stato compilato senza il supporto MPFR, chiamare questa funzione genera un errore fatale.

void *get_mpz_ptr();

Alloca e inizializza un oggetto GMP e restituisce un puntatore allo stesso. Se l’allocazione non riesce, gawk termina con un errore fatale “out of memory” (memoria esaurita). Se gawk era stato compilato senza il supporto MPFR, chiamare questa funzione genera un errore fatale.

Entrambe queste funzioni restituiscono un codice di ritorno ‘void *’, poiché il file di intestazione gawkapi.h non dovrebbe avere dipendenze da <mpfr.h> (e <gmp.h>, che è incluso da <mpfr.h>). I codici di ritorno effettivamente restituiti sono di tipo mpfr_ptr e mpz_ptr rispettivamente, e si dovrebbero assegnare in maniera appropriata questi codici di ritorno prima di assegnare i risultati a variabili del tipo corretto.