sub-rotina pthread_key_create

Propósito

Cria uma chave de dados específica de encadeamento.

Biblioteca

Biblioteca de encadeamentos (libpthreads.a)

Sintaxe

#include <pthread.h>

int pthread_key_create ( key, destructor ) pthread_key_t * key; void (* destructor) (void *);

Descrição

A subroutine pthread_key_create cria uma chave de dados específica de encadeamento. A chave é compartilhada entre todas as threads dentro do processo, mas cada thread possui dados específicos associados à chave. Os dados específicos da thread são um pointer void, inicialmente configurado como NULL.

O aplicativo é responsável por garantir que essa subroutine seja chamada apenas uma vez para cada chave solicitada. Isso pode ser feito, por exemplo, chamando a subroutine antes de criar outras threads, ou usando o recurso de inicialização única.

Geralmente, dados específicos de encadeamento são ponteiros para armazenamento alocado dinamicamente. Ao congelar o armazenamento, o valor deve ser configurado como NULL. Não é recomendado lançar este ponteiro em tipo de dados escalares (int por exemplo), pois os casts podem não ser portáteis, e porque o valor de NULL é dependente de implementação.

Uma rotina de destruidor opcional pode ser especificada. Ele será chamado para cada thread quando ele for finalizado e descolado, após a chamada para as rotinas de limpeza, se o valor específico não for NULL. Geralmente, a rotina de destruidor irá liberar os dados específicos do encadeamento de armazenamento. Ele receberá os dados específicos da thread como parâmetro.

Nota: O arquivo de cabeçalho pthread.h deve ser o primeiro arquivo incluído de cada arquivo de origem usando a biblioteca de encadeamentos. Caso contrário, deve ser usada a sinalização de compilação -D_THREAD_SAFE , ou o compilador cc_r utilizado. Neste caso, a sinalização é automaticamente definida.

Parâmetros

Item	Descrição
Chave	Pontos para onde a chave será armazenada.
destruidor	Aponta para uma rotina de destruidor opcional, usada para limpeza de dados sobre a finalização do fio. Se nenhuma limpeza for desejada, este ponteiro deverá ser NULL.

Valores De Retorno

Se bem-sucedida, a função pthread_key_create armazena o valor da chave recém-criada em * key e retorna zero. Caso contrário, um número de erro é retornado para indicar o erro.

Códigos De Erro

A função pthread_key_create falhará se:

Item	Descrição
EAGAIN	O sistema faltou os recursos necessários para criar uma outra chave de dados específica do encadeamento, ou o limite imposto pelo sistema sobre o número total de chaves por processo PTHREAD_KEYS_MAX foi excedido.
ENOMEM	A memória insuficiente existe para criar a chave.

A função pthread_key_create não retornará um código de erro de EINTR.