once pragma

Especifica que o arquivo de cabeçalho será incluído apenas uma vez pelo compilador ao compilar um arquivo de código-fonte.

Sintaxe

#pragma once

Comentários

O uso de #pragma once pode reduzir os tempos de build, pois o compilador não abrirá e lerá o arquivo novamente após o primeiro #include do arquivo na unidade de tradução. Isso se chama otimização de várias inclusões. Ela tem um efeito semelhante à expressão de proteção de inclusão, que usa definições de macro de pré-processador para evitar várias inclusões do conteúdo do arquivo. Ela também ajuda a evitar violações da regra de uma definição: o requisito de que todos os modelos, tipos, funções e objetos não tenham mais de uma definição em seu código.

Por exemplo:

// header.h
#pragma once
// Code placed here is included only once per translation unit

Recomendamos a diretiva #pragma once para código novo porque ela não polui o namespace global com um símbolo de pré-processador. Ela requer menos digitação, é menos perturbadora e não pode causar colisões de símbolo. Colisões de símbolo são erros causados quando arquivos de cabeçalho diferentes usam o mesmo símbolo de pré-processador do valor de proteção. Isso não faz parte do C++ Standard, mas é implementado com portabilidade por vários compiladores comuns.

Não há nenhuma vantagem em usar a expressão de proteção de inclusão e #pragma once no mesmo arquivo. O compilador reconhece a linguagem de proteção de inclusão e implementa a otimização de várias inclusões da mesma maneira que a diretiva #pragma once se nenhum código ou diretiva de pré-processador não comentados vierem antes ou depois da forma padrão da expressão:

// header.h
// Demonstration of the #include guard idiom.
// Note that the defined symbol can be arbitrary.
#ifndef HEADER_H_     // equivalently, #if !defined HEADER_H_
#define HEADER_H_
// Code placed here is included only once per translation unit
#endif // HEADER_H_

Recomendamos a expressão de proteção de inclusão quando o código tiver que ser portátil para compiladores que não implementam a diretiva #pragma once, para manter a consistência com o código existente, ou quando não for possível a otimização de várias inclusões. Isso pode ocorrer em projetos complexos quando caminhos de inclusão dos objetos que recebem ou receberam aliasing do sistema de arquivos impedem que o compilador identifique arquivos de inclusão idênticos por caminho canônico.

Tenha cuidado para não usar #pragma once ou incluir a expressão de proteção em arquivos de cabeçalho projetados para serem incluídos várias vezes, pois eles usam símbolos de pré-processador para controlar seus efeitos. Para obter um exemplo desse design, consulte o arquivo de cabeçalho <assert.h>. Tenha também o cuidado de gerenciar seus caminhos de inclusão para evitar a criação de vários caminhos para arquivos incluídos, o que pode prejudicar a otimização de vários inclusões para proteção de inclusão e #pragma once.

Confira também

Diretivas do Pragma e as palavras-chave do __pragma e _Pragma