pragma once

From Wikipedia, the free encyclopedia
Jump to: navigation, search

In the C and C++ programming languages, #pragma once is a non-standard but widely supported preprocessor directive designed to cause the current source file to be included only once in a single compilation. Thus, #pragma once serves the same purpose as #include guards, but with several advantages, including: less code, avoidance of name clashes, and sometimes improved compile speed.[1]

Example[edit]

File "grandparent.h"
#pragma once
 
struct foo 
{
    int member;
};
File "parent.h"
#include "grandparent.h"
File "child.c"
#include "grandparent.h"
#include "parent.h"

Advantages and disadvantages[edit]

The primary advantage is that since the compiler itself is responsible for handling #pragma once, it is not necessary for the programmer to create new macro names such as GRANDPARENT_H in the Include guard article's example. This eliminates the risk of name clashes, meaning that no header file can fail to be included at least once.

Using #pragma once instead of include guards will for some compilers improve compilation speed since it is a higher-level mechanism; the compiler itself can compare filenames or inodes without having to invoke the C preprocessor to scan the header for #ifndef and #endif.

Common compilers such as GCC, Clang, and EDG-based compilers include specific optimizations to recognize and optimize the handling of include guards, and thus little or no speedup benefit is obtained from the use of #pragma once.[2][3][4]

Portability[edit]

Compiler #pragma once
Clang Supported[5]
Comeau C/C++ Supported[6]
C++Builder XE3 Supported[7]
Digital Mars C++ Supported[8]
GCC Supported[9] (since 3.4[10])
Intel C++ Compiler Supported[11]
Microsoft Visual C++ Supported[12]
Pelles C Supported[13]
ARM DS-5 Supported[14]
IAR C/C++ Supported[15]

References[edit]

  1. ^ "Games from Within: Even More Experiments with Includes". Web.archive.org. 2005-01-25. Retrieved 2013-08-19. 
  2. ^ "The C Preprocessor: 1. The C Preprocessor". Gcc.gnu.org. 1996-02-01. Retrieved 2013-08-19. 
  3. ^ "“Clang” CFE Internals Manual — Clang 3.4 documentation". Clang.llvm.org. Retrieved 2013-08-19. 
  4. ^ "clang: File manipulation routines". Clang.llvm.org. Retrieved 2013-08-19. 
  5. ^ "clang: clang: Pragma.cpp Source File". Clang.llvm.org. Retrieved 2013-08-19. 
  6. ^ "Comeau C++ Pre-Release User Documentation: Pragmas". Comeaucomputing.com. Retrieved 2013-08-19. 
  7. ^ "#pragma once - RAD Studio XE3". Docwiki.embarcadero.com. 2010-12-02. Retrieved 2013-08-19. 
  8. ^ "Pragmas". Digital Mars. Retrieved 2013-08-19. 
  9. ^ "Alternatives to Wrapper #ifndef". Gcc.gnu.org. Retrieved 2013-08-20. 
  10. ^ "GCC 3.4 Release Series — Changes, New Features, and Fixes". Gcc.gnu.org. Retrieved 2013-08-19. 
  11. ^ "Diagnostic 1782: #pragma once is obsolete. Use #ifndef guard instead.". Intel Developer Zones. Retrieved 4 December 2013. 
  12. ^ "once (C/C++)". Msdn.microsoft.com. Retrieved 2013-08-19. 
  13. ^ IDE help/documentation
  14. ^ "ARM Information Center". ARM. Retrieved 2013-12-17. 
  15. ^ "IAR C/C++ Development Guide". IAR Systems. Retrieved 4 December 2013.