Insidie ​​di progettazione API in C [chiuso]

Quali sono alcuni difetti che ti fanno impazzire nelle API C (incluse librerie standard, librerie di terze parti e intestazioni all'interno di un progetto)? L'obiettivo è identificare le insidie ​​della progettazione API in C, in modo che le persone che scrivono nuove librerie C possano imparare dagli errori del passato.

Spiega perché il difetto è negativo (preferibilmente con un esempio) e prova a suggerire un miglioramento. Sebbene la tua soluzione potrebbe non essere pratica nella vita reale (è troppo tardi per risolvere strncpy), dovrebbe dare un avvertimento per i futuri scrittori di biblioteche.

Sebbene il focus di questa domanda siano le API C, i problemi che influenzano la tua capacità di usarli in altre lingue sono i benvenuti.

Si prega di dare un difetto per risposta, in modo che la democrazia possa ordinare le risposte.

Funziona con valori di ritorno incoerenti o illogici. Due buoni esempi:

1) Alcune funzioni di Windows che restituiscono un HANDLE usano NULL / 0 per un errore (CreateThread), alcune usano INVALID_HANDLE_VALUE / -1 per un errore (CreateFile).

2) La funzione POSIX 'time' restituisce '(time_t) -1' in caso di errore, il che è davvero illogico poiché 'time_t' può essere di tipo con o senza segno.

Funzioni o parametri con nomi non descrittivi o affermativi. Per esempio:

1) CreateFile, nell'API di Windows, in realtà non crea un file, ma crea un handle di file. Può creare un file, proprio come può 'open', se richiesto tramite un parametro. Questo parametro ha valori chiamati 'CREATE_ALWAYS' e 'CREATE_NEW' i cui nomi non suggeriscono nemmeno la loro semantica. ("CREATE_ALWAYS" significa che fallisce se il file esiste? O crea un nuovo file sopra di esso? "CREATE_NEW" significa che crea sempre un nuovo file e fallisce se il file esiste già? O crea un nuovo file sopra?)

2) pthread_cond_wait nell'API POSIX pthreads, che nonostante il suo nome è un'attesa incondizionata .

Tipi opachi che vengono passati attraverso l'interfaccia come maniglie di tipo eliminato. Il problema è, ovviamente, che il compilatore non può controllare il codice utente per i tipi di argomento corretti.

Questo è disponibile in varie forme e sapori, tra cui, ma non limitato a:

• void* abuso

• usando intcome handle di risorse (esempio: la libreria CDI)

• argomenti digitati in modo stringa

I tipi più distinti (= non possono essere utilizzati in modo completamente intercambiabile) sono associati allo stesso tipo di tipo eliminato, peggio. Naturalmente, il rimedio è semplicemente quello di fornire puntatori opachi dattiloscritti lungo le linee di (esempio C):

typedef struct Foo Foo;
typedef struct Bar Bar;

Foo* createFoo();
Bar* createBar();

int doSomething(Foo* foo);
void somethingElse(Foo* foo, Bar* bar);

void destroyFoo(Foo* foo);
void destroyBar(Bar* bar);

Funziona con convenzioni di restituzione di stringhe incoerenti e spesso ingombranti.

Ad esempio, getcwd richiede un buffer fornito dall'utente e le sue dimensioni. Ciò significa che un'applicazione deve impostare un limite arbitrario sulla lunghezza della directory corrente o fare qualcosa del genere ( da CCAN ):

 /* *This* is why people hate C. */
len = 32;
cwd = talloc_array(ctx, char, len);
while (!getcwd(cwd, len)) {
    if (errno != ERANGE) {
        talloc_free(cwd);
        return NULL;
    }
    cwd = talloc_realloc(ctx, cwd, char, len *= 2);
}

La mia soluzione: restituire una mallocstringa ed. È semplice, robusto e non meno efficiente. Tranne le piattaforme integrate e i sistemi più vecchi, in mallocrealtà è abbastanza veloce.

Funzioni che accettano / restituiscono tipi di dati composti in base al valore o che utilizzano callback.

Ancora peggio se detto tipo è un sindacato o contiene bit-field.

Dal punto di vista di un chiamante C, questi sono effettivamente OK, ma non scrivo in C o C ++ a meno che non sia richiesto, quindi di solito chiamo tramite un FFI. La maggior parte degli SFI non supporta i sindacati o i campi di bit e alcuni (come Haskell e MLton) non possono supportare le strutture passate per valore. Per coloro che sono in grado di gestire strutture per valore, almeno Common Lisp e LuaJIT sono costretti su percorsi lenti - L'interfaccia di funzione esterna comune di Lisp deve effettuare una chiamata lenta tramite libffi e LuaJIT rifiuta di compilare il percorso del codice contenente la chiamata. Le funzioni che possono richiamare negli host attivano anche percorsi lenti su LuaJIT, Java e Haskell, con LuaJIT che non è in grado di compilare tale chiamata.