once pragma

Especifica que el compilador incluirá el archivo de encabezado una sola vez al compilar un archivo de código fuente.

Sintaxis

#pragma once

Comentarios

El uso de #pragma once puede reducir el tiempo de compilación, ya que el compilador no abrirá y leerá el archivo después del primer #include del archivo en la unidad de traducción. Se le denomina optimización de inclusión múltiple. Tiene un efecto similar a la expresión de restricción de inclusión, que utiliza las definiciones de macro de preprocesador para evitar la inclusión múltiple de los contenidos del archivo. Esto también ayuda a evitar infracciones a la regla de definición única: el requisito de que todas las plantillas, tipos, funciones y objetos no tengan más de una definición en su código.

Por ejemplo:

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

Se recomienda la directiva #pragma once para el nuevo código, ya que no contamina el espacio de nombres global con un símbolo de preprocesador. Requiere menos escritura, es menos distractora y no puede causar colisiones de símbolos. Las colisiones de símbolos son errores causados cuando diferentes archivos de encabezado usan el mismo símbolo de preprocesador que el valor de restricción. No forma parte del estándar de C++, pero varios compiladores comunes la implementan de forma portátil.

No existe ninguna ventaja en usar la expresión de restricción de inclusión y #pragma once en el mismo archivo. El compilador reconoce la expresión de restricción de inclusión e implementa la optimización de inclusión múltiple de la misma manera que la directiva #pragma once si el código que no es de comentario o la directiva de preprocesador vienen antes o después de la forma estándar de la expresión:

// 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_

Se recomienda la expresión de restricción de inclusión cuando el código debe ser portable y migrar a los compiladores que no implementan la directiva #pragma once, para mantener la coherencia con el código existente o cuando es imposible la optimización de la inclusión múltiple. Esto puede ocurrir en proyectos complejos cuando los alias del sistema de archivos o las rutas de inclusión con alias evitan que el compilador identifique archivos de inclusión idénticos mediante la ruta canónica.

Tenga cuidado de no usar #pragma once o la expresión de restricción de inclusión en archivos de encabezado diseñados para incluirse varias veces que usen símbolos de preprocesador para controlar sus efectos. Para obtener un ejemplo de este diseño, consulte el archivo de encabezado <assert.h>. Tenga también cuidado al administrar rutas de inclusión para evitar la creación de varias rutas de acceso a archivos incluidos, que pueden anular la optimización de inclusión múltiple tanto para las restricciones de inclusión como para #pragma once.

Consulte también

Directivas pragma y las palabras clave __pragma y _Pragma