Pragma once: Difference between revisions
No edit summary |
Cyberbot II (talk | contribs) Rescuing 1 sources. #IABot |
||
| Line 3: | Line 3: | ||
{{manual|date=March 2013}}}} |
{{manual|date=March 2013}}}} |
||
In the [[C (programming language)|C]] and [[C++]] programming languages, '''#pragma once''' is a non-standard but widely supported [[C preprocessor|preprocessor directive]] designed to cause the current [[source file]] to be included only once in a single compilation. Thus, <code>#pragma once</code> serves the same purpose as [[include guard|<code>#include</code> guard]]s, but with several advantages, including: less code, avoidance of name clashes, and sometimes improvement in compilation speed.<ref>{{cite web|author= |url= |
In the [[C (programming language)|C]] and [[C++]] programming languages, '''#pragma once''' is a non-standard but widely supported [[C preprocessor|preprocessor directive]] designed to cause the current [[source file]] to be included only once in a single compilation. Thus, <code>#pragma once</code> serves the same purpose as [[include guard|<code>#include</code> guard]]s, but with several advantages, including: less code, avoidance of name clashes, and sometimes improvement in compilation speed.<ref>{{cite web|author= |url=http://www.gamesfromwithin.com/articles/0501/000067.html |title=Games from Within: Even More Experiments with Includes |publisher=Web.archive.org |date=2005-01-25 |accessdate=2013-08-19 |deadurl=yes |archiveurl=https://web.archive.org/web/20080930061318/http://www.gamesfromwithin.com/articles/0501/000067.html |archivedate=September 30, 2008 }}</ref> |
||
==Example== |
==Example== |
||
Revision as of 02:02, 2 April 2016
 | This article has multiple issues. Please help improve it or discuss these issues on the talk page. (Learn how and when to remove these template messages)
|
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 improvement in compilation speed.[1]
Example
- 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
The most common alternative to #pragma once is to use #define to set an include guard macro, the name of which is picked by the programmer to be unique to that file. For example,
#ifndef GRANDPARENT_H
#define GRANDPARENT_H
... contents of grandparent.h
#endif /* !GRANDPARENT_H */
This is more complicated, possibly less efficient, and prone to error as there are no mechanisms to prevent a programmer accidentally using the same macro name in more than one file, which would result in only one of the files being included. This problem renders #pragma once to be advantageous. Since the compiler itself is responsible for handling #pragma once, the programmer cannot make errors which cause name clashes.
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. It is important to note that some 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]
Caveats
Identifying the same file on a file system is not a trivial task.[5] Symbolic links and hard links may cause the same file to be found under different names. Compilers may use a heuristic that compares file size, modification time and content.[6] This backfires when the same file is intentionally copied into several parts of a project. With include guard based on file path these copies would be treated differently while #pragma once may arbitrarily treat them as the same file in a compiler-dependent way.
Portability
| Compiler | #pragma once |
|---|---|
| Clang | Supported[7] |
| Comeau C/C++ | Supported[8] |
| C++Builder XE3 | Supported[9] |
| Digital Mars C++ | Supported[10] |
| GCC | Supported[11] (since 3.4[5]) |
| HP C/aC++ | Supported[12] (since at least A.06.12) |
| IBM XL C/C++ | Supported[13] (since 13.1.1) |
| Intel C++ Compiler | Supported[14] |
| Microsoft Visual C++ | Supported[15] |
| Pelles C | Supported[16] |
| ARM DS-5 | Supported[17] |
| IAR C/C++ | Supported[18] |
| Solaris Studio C/C++ | Not supported[19][20] |
References
- ^ "Games from Within: Even More Experiments with Includes". Web.archive.org. 2005-01-25. Archived from the original on September 30, 2008. Retrieved 2013-08-19.
{{cite web}}: Unknown parameter|deadurl=ignored (|url-status=suggested) (help) - ^ "The C Preprocessor: 1. The C Preprocessor". Gcc.gnu.org. 1996-02-01. Retrieved 2013-08-19.
- ^ ""Clang" CFE Internals Manual — Clang 3.4 documentation". Clang.llvm.org. Retrieved 2013-08-19.
- ^ "clang: File manipulation routines". Clang.llvm.org. Retrieved 2013-08-19.
- ^ a b "GCC 3.4 Release Series — Changes, New Features, and Fixes". Gcc.gnu.org. Retrieved 2013-08-19.
- ^ "should_stack_file() function in GCC source code".
- ^ "clang: clang: Pragma.cpp Source File". Clang.llvm.org. Retrieved 2013-08-19.
- ^ "Comeau C++ Pre-Release User Documentation: Pragmas". Comeaucomputing.com. Retrieved 2013-08-19.
- ^ "#pragma once - RAD Studio XE3". Docwiki.embarcadero.com. 2010-12-02. Retrieved 2013-08-19.
- ^ "Pragmas". Digital Mars. Retrieved 2013-08-19.
- ^ "Alternatives to Wrapper #ifndef". Gcc.gnu.org. Retrieved 2013-08-20.
- ^ http://h20565.www2.hp.com/hpsc/doc/public/display?docId=emr_na-c02936807.
{{cite web}}: Missing or empty|title=(help) - ^ "Supported GCC pragmas". IBM. Retrieved 2015-02-20.
- ^ "Diagnostic 1782: #pragma once is obsolete. Use #ifndef guard instead". Intel Developer Zones. Retrieved 4 December 2013.
- ^ "once (C/C++)". Msdn.microsoft.com. Retrieved 2013-08-19.
- ^ IDE help/documentation
- ^ "ARM Information Center". ARM. Retrieved 2013-12-17.
- ^ "IAR C/C++ Development Guide" (PDF). IAR Systems. Retrieved 4 December 2013.
- ^ "Solaris Studio 12.4: C++ User's Guide". Oracle. Retrieved 2015-02-20.
- ^ "Solaris Studio 12.4: C User's Guide". Oracle. Retrieved 2015-02-20.