Extern: richiamare funzioni esterne a Gambas

Introduzione

Gambas consente di utilizzare potenzialità e capacità di sistemi esterni mediante il richiamo di loro funzioni contenute in apposite librerie.
Talvolta, infatti, può capitare nella programmazione la necessità di utilizzare funzionalità che la corrente versione di Gambas, essendone priva, non può direttamente offrire ^{[Nota 1]}, ma che sono invece espresse da sistemi esterni.
L'istruzione che Gambas pone a disposizione del programmatore per richiamare tali funzioni esterne è: Extern.

Per il richiamo di funzioni esterne è necessario conoscere in particolare tre elementi:

• il quid, ossia il cosa fare, cosa ottenere;
• la funzione esterna che ci consente di realizzare quel quid;
• la libreria nella quale è contenuta la funzione da richiamare.

Se quel che si vuole ottenere è possibile solamente attraverso l'uso di una funzione esterna a Gambas, bisognerà individuare la specifica funzione che consente di realizzare il nostro obiettivo. La funzione esterna, utile allo scopo del programma, dovrà essere richiamata dal nostro programma Gambas. Poiché tale funzione esterna è scritta in C, bisognerà interpretare il significato e tradurla in forma comprensibile a Gambas. Inoltre, poiché essa è appunto esterna a Gambas, bisognerà conoscere il luogo ove essa si trova. Il luogo che contiene la funzione esterna è la "Libreria"; ed anzi una specifica libreria, la quale, pertanto, andrà dichiarata in anticipo rispetto alla funzione. Le librerie, contenenti funzioni esterne a Gambas, richiamabili da Gambas, sono quelle con estensione .so, ossia le "Librerie condivise" ^{[ Nota 2 ]}. E' opportuno, quando possibile, indicare anche il numero della versione della Libreria.
Se la libreria si trova in una cartella diversa da quella dedicata alle librerie (/user/lib/), sarà necessario specificare anche il percorso.

Possiamo, dunque, dire che è un po' come se Extern annunciasse: « Farò in modo che il programma utilizzi questa funzione "xxxx(yyy)", la quale non appartiene alle risorse di Gambas, ma si trova nella libreria: zzzz.so ».

Identificazione e dichiarazione della Libreria contenente la Funzione esterna

La Libreria, contenente la funzione esterna da richiamare, può essere dichiarata separatamente, e prima della dichiarazione Extern, mediante la parola-chiave Library:

Library "libreria_esterna:num_vers"

Extern......

La Libreria, però, può anche essere dichiarata all'interno dell'istruzione di Extern mediante la parola In:

Extern ................. In "libreria_esterna:num_vers"

Se è presente anche il numero della versione della Libreria, esso va scritto così come riportato nel file, e la parte relativa all'estensione .so. va sostituita con il carattere dei due punti ( : ).
Facciamo l'esempio della Libreria libsane.so.1.0.29 .
Essa sarà scritta così:

Library "libsane:1.0.29"

Ugualmente, se la dichiareremo all'interno dell'istruzione di Extern.
Ad esempio, per chiamare la funzione sane_init() scriveremo:

Private Extern sane_init() In "libsane:1.0.29"

Per evitare che la versione della Libreria richiamata non coincida con la versione effettivamente presente in un sistema operativo, si può porre anche solo il primo numero della versione. In tal caso sarà caricata comunque la versione più recente che comincia per il numero indicato.

Quindi, invece di scrivere per esempio:

Library "libsane:1.0.29"

si scriverà semplicemente:

Library "libsane:1"

Al fine, poi, di non incorrere in un errore nel richiamare la corretta versione della Libreria, è possibile evitare ogni riferimento al numero di versione, indicando così soltanto il puro nome della Libreria medesima:

Library "libsane"

Ad ogni modo l'opportunità, di richiamare il nome della libreria comprensivo della sua intera versione in dettaglio, sta anche nella circostanza che in caso vi siano presenti più versioni della medesima libreria, sarà richiamata e dunque utilizzata in Gambas la versione prescelta e specificata.

Dichiarazione della Funzione esterna mediante Extern

La Funzione esterna, che intendiamo utilizzare, deve essere dichiarata mediante l'istruzione Extern. Questa dichiarazione va effettuata esternamente alle sub-procedure (routine).

La dichiarazione deve contenere:
1) il nome della funzione esterna da utilizzare;
2) la specificazione degli eventuali argomenti della funzione esterna (espressi ovviamente secondo le modalità del linguaggio Gambas);
3) l'eventuale valore ritornato dalla funzione esterna.

La dichiarazione di una Funzione esterna può essere "Publica" o "Privata".

Una Funzione esterna dichiarata in C, ad esempio, in questo modo:

int nome_funzione(int valore1, char valore2)

in Gambas verrà dichiarata con Extern nella seguente maniera:

Private Extern nome_funzione(valore1 As Integer, valore2 As Byte) As Integer

oppure, se si intende dichiararla come Pubblica, si avrà ovviamente:

Public Extern nome_funzione(valore1 As Integer, valore2 As Byte) As Integer

Ordine delle dichiarazioni nel codice del programma

La funzione vera e propria, da richiamare per il suo utilizzo, sarà posta ovviamente all'interno di una routine. Dunque, nel caso di dichiarazione separata della Libreria, la scaletta delle dichiarazioni sarà la seguente:
1) dichiarazione della Libreria contenente la funzione;
2) dichiarazione mediante Extern della funzione esterna che si andrà ad utilizzare (questa dichiarazione avverrà al di fuori e prima della routine che farà uso di quella funzione);
3) chiamata ed uso della funzione esterna.

Esempio astratto:

' Dichiariamo la Libreria contenente la funzione esterna che ci interessa:
Library "libreria_esterna:num_vers"


' Ora dichiariamo la funzione esterna specifica che ci interessa.
' Ipotizziamo che in C sia così scritta: int funzione_esterna(const char * valoreStringa, int valoreInteger).
' La funzione esterna, dunque, richiede che le siano passati due valori: uno è una Stringa, l'altro è un Integer. Essa, poi, restituirà un valore Integer.
' In Gambas la dichiameremo così:
Private Extern funzione_esterna(valoreStringa As String, valoreInteger As Integer) As Integer

Public Sub Button1_Click()

 Dim primoValore As String
 Dim secondoValore As Integer
 Dim rit_funz As Integer
 
  primoValore = "testo qualsiasi"
  
  secondoValore = 1000
  
' Invochiamo la funzione esterna che ci interessa, e le passiamo i due valori, affinché li elabori.
' Essa ritornerà per "valore" un dato di tipo Intero.
  rit_funz = funzione_esterna(primoValore, secondoValore)
  
' Vediamo in console il valore ritornato dalla funzione esterna:
  Print rit_funz
  
End

Uso del nome di una funzione già utilizzato da Gambas

Qualora si debba utilizzare una funzione esterna avente il nome identico ad una funzione propria di Gambas, è necessario formalmente usare un nome diverso indicando, però, nella dichiarazione con Extern il vero nome della funzione esterna preceduto dal comando Exec.

Nel seguente esempio pratico dobbiamo dichiarare ed usare la funzione kill presente nella libreria esterna libc:6:

int kill(pid_t pid, int sig);

Il nome della funzione esterna kill, però, è - come si nota - identico alla funzione Kill( ) propria di Gambas ^{[Nota 3]}. Pertanto, assegneremo alla funzione esterna un nome qualsiasi, purché diverso da quello di ogni altra funzione di Gambas, ma richiameremo il suo vero nome all'atto della dichiarazione della funzione esterna, facendolo precedere dal comando Exec:

Private Extern kill_C(pid AS Integer, sig AS Integer) AS Integer In "libc:6" Exec "kill"

Analogamente se è stato utilizzato il comando Library per dichiarare la libreria esterna da utilizzare:

Library "libc:6"

Private Extern kill_C(pid AS Integer, sig AS Integer) AS Integer Exec "kill"

Uso di funzioni esterne di più Librerie

Può accadere la necessità di utilizzare le funzioni esterne di due o più Librerie. In tal caso si potranno dichiarare tranquillamente le necessarie librerie esterne all'inizio della Classe sia con la parola chiave "Library", e comunque prima della dichiarazione con Extern, sia con "In":

Library "libreria_1:num_vers"

Private Extern funzione_esterna_della_libreria_1(......)


Library "libreria_2:num_vers"

Private Extern funzione_esterna_della_libreria_2(......)


' Quindi di seguito le varie sub-routine della Classe
......
......

V'è da evidenziare, però, che, qualora le librerie esterne vengano dichiarate con la parola chiave "Library" non all'inizio della Classe, ma all'interno fra una sub-routine e l'altra, la dichiarazione di una Libreria influenzerà ogni dichiarazione con Extern successiva. Cosicché, in questo caso, bisognerà dichiarare la Libreria corrispondente prima di Extern e della routine contenente la funzione da utilizzare:

Library "libreria_1:num_vers"

Private Extern funzione_esterna_della_libreria_1(valoreA As ..., ValoreB As ...) As ...

Public Sub prima_routine_esempio(Aval As ..., Bval As ....)
  ......' qui l'uso della funzione esterna della libreria_1
End


Library "libreria_2:num_vers"

Private Extern funzione_esterna_della_libreria_2(valoreC As ..., ValoreD As ...) As ...

Public Sub seconda_routine_esempio(Cval As ..., Dval As ...)
  ......' qui l'uso della funzione esterna della libreria_2
End

Qualora nell'esempio precedente fosse necessario richiamare, per utilizzare, una funzione esterna presente nella 1^ Libreria, si dovrà dichiarare nuovamente la 1^ Libreria.

Esempi pratici

Mostriamo appresso un semplice esempio pratico utilizzando la funzione esterna usleep( ) dichiarata nel file header di sistema "/usr/include/unistd.h", la quale provoca una sospensione dell'esecuzione del programma per un intervallo di microsecondi (µs) indicati nel primo argomento della funzione esterna medesima.

Facendo ancora riferimento ai tre punti esposti all'inizio, avremo:

1) Il quid: vogliamo far sì che il nostro applicativo resti in attesa per 3500000 microsecondi;

2) per ottenere questo risultato sappiamo che è necessario richiamare una specifica, particolare funzione esterna, che sarebbe usleep(), e che è dichiarata nel file header di sistema "/usr/include/unistd.h" come segue:

int usleep (__useconds_t __useconds)

Questa funzione va così interpretata:
- int : vuol dire che ritorna un valore integer;
- usleep : è il nome identificatore della funzione;
- (__useconds_t __useconds) : è il parametro della funzione esterna, in questo caso occupa 4 byte e, dunque, in Gambas equivale a un Integer.

In Gambas questa funzione esterna sarà, dunque, così tradotta:

Extern usleep(__useconds As Integer) As Integer

quest'ultimo "As Integer" (esterno ai parametri specifici della funzione esterna) è ovviamente giustificato dal fatto che detta funzione restituisce un valore integer;

3) il luogo ove questa funzione è contenuta: questa funzione è presente nella Libreria dinamica condivisa "libc.so.6":

Il tutto, allora, sarebbe così da impostarsi:

' Dichiarazione della Libreria contenente la funzione esterna che si intende utilizzare:
Library "libc:6"
 
' Dichiarazione mediante "Extern" della funzione esterna da utilizzare:
' int usleep (__useconds_t __useconds)
' Sleep USECONDS microseconds.
Private Extern usleep(__useconds As Integer) As Integer


Public Sub Main()
 
 Dim i As Integer
  
  Print "Attesa..."
   
' Viene praticamente richiamata ed utilizzata la funzione esterna, e le si passa il valore (µs 3500000) come suo argomento:
  i = usleep(3500000)
  If i < 0 Then Error.Raise("Errore alla funzione 'usleep()' !")
 
  Print "Fine programma"
  
End

---

Altro esempio pratico, ma ora utilizzando la funzione esterna modf( ) della libreria delle funzioni matematiche libm.so.6 :

' Dichiarazione della Libreria contenente la funzione esterna da utilizzare:
Library "libm:6"

' Dichiarazione mediante Extern della funzione esterna da utilizzare:
' modf (_Mdouble_ __x, _Mdouble_ *__iptr)
' Break VALUE into integral and fractional parts.
Private Extern modf(__x As Float, __iptr As Pointer) As Float
 
  
Public Sub Main()
 
 Dim f, intero, frazione As Float
  
  f = 5.123456
  
' Uso della funzione esterna:
  frazione = modf(f, VarPtr(intero))
  
' Mostra in console il risultato:
  Print "Parte intera: "; intero
  Print "Parte decimale: "; frazione
  
End

Funzione esterna che fa riferimento ad una funzione interna Callback

Alcune funzioni esterne possono avere nei propri parametri riferimenti ad altre funzioni interne al codice dell'applicativo usate come callback (o gestore dell'evento) per gestire eventi asincroni. Sostanzialmente viene detto alla libreria quando far accedere un evento, e soprattutto come, che nella funzione esterna viene espresso appunto dalla funzione callback. Dunque viene detto alla libreria, una volta sola e prima di tutto, come fare a raggiungere il gestore dell'evento. Quando è il momento, la libreria invoca la funzione interna callback, passandogli eventualmente dei valori come argomenti. Tali argomenti, dunque, sono valori che vengono semplicemente passati alla funzione interna callback.
Le funzioni di callback, definite così perché vengono attivate non dal programmatore ma dal codice interno, sono ideali per i casi in cui un'attività viene eseguita ripetutamente.

Nella funzione esterna la funzione callback viene espressa semplicemente indicando il suo nome. Ad esempio potremmo avere un funzione esterna scritta in C:

int funzione_esterna_callback(...... *param1, funzione_callback, void *param3)

In Gambas all'atto della dichiarazione della funzione esterna con Extern la funzione callback viene dichiarata, quale argomento della predetta funzione esterna, come variabile di tipo Puntatore. Essa potrà assumere un nome qualsiasi, dato che in questa fase esso non è fondamentale.
Pertanto, la funzione esterna dell'esempio precedente in Gambas sarà così espressa:

Private Extern funzione_esterna_callback(param1 As Pointer, funzione_callback As Pointer, param3 As Pointer) As Integer

Esempio astratto

Poniamo che la funzione espressa in C sia quella indicata appena sopra. In Gambas avremo:

Private Extern funzione_esterna_callback(param1 As Pointer, funzione_callback As Pointer, param3 As Pointer) As Integer

Public Sub esempio()

 Dim rit As Integer
 Dim val1, val2 As Pointer

 val1 = una_qualsiasi_funzione_esterna(.........)
 
' Viene invocata la funzione esterna, la quale a sua volta richiama la funzione interna "callback":
  rit = funzione_esterna_callback(val1, funzione_interna_callback, val2)

End


Private Function funzione_interna_callback(vlr As Pointer, data As Pointer)

' Qui il codice specifico della funzione interna "callback"
  ......

End

Note

[1] Prendiamo come esempio il possibile diretto rapporto fra Gambas ed il sistema sonoro ALSA: attualmente non esiste uno specifico Componente di Gambas per richiamare e gestire direttamente le risorse di ALSA.
Così, se non si avesse in alcun modo la possibilità di richiamare, e quindi di utilizzare le funzioni proprie di ALSA, non sarebbe possibile interloquire con Gambas in modo diretto con questo sistema esterno. Non sarebbe insomma possibile via Gambas gestire le capacità di ALSA, e dunque utilizzare le sue funzioni e potenzialità.
L'istruzione Extern ci consente di superare questo muro, questo limite.

[2] Una libreria condivisa (Shared Library) è un file binario contenente un insieme di funzioni richiamabili o classi. Esse hanno un nome particolare, detto soname, composto dalle lettere iniziali lib, dal nome specifico della libreria, da .so, da un punto e dal numero della versione.

[3] E' identico, eccezione fatta per la prima lettera del nome della funzione che in Gambas è comunque sempre maiuscola.

Riferimenti

• http://gambaswiki.org/wiki/lang/extdecl
• http://gambaswiki.org/wiki/doc/extern