Are 'redundant include guards' necessary in Codegear RAD Studio 2009? Is the compiler smart enough to deal with this on it's own?
For example, I might have the following 'include guard' in foo.h:
#ifndef fooH
#define fooH
// ... declaration here
#endif
and the following 'redundant include guard' in use_foo.h:
#ifndef fooH
#include "foo.h"
#endif
Additionally, if the compiler is not smart enough, are 'redundant include guards' necesarry if they are being included in a source file. e.g. use_foo.cpp. ?
The portion of the code you marked as "redundant include guard" is not necessary but it is a possible optimization.
In the case of C++Builder, there is logic to detect header guards, so it should not be necessary.
In the general case, the preprocessing pass is usually pretty fast anyhow, so it's unlikely that this optimisation would buy you much anyhow.
These redundant include guards are intended to emulate the functionality of the proposed #pragma once directive: if some header file has already been included, then the preprocessor will not even attempt to locate, open and parse it anymore (as it would have to with the "ordinary" include guard technique). In many cases this makes handling of include files much more efficient (speeds up compilation).
This approach is obviously a high-maintenance one: one has to make sure that the spelling of the guard symbol is exactly the same inside the header file as well as outside.
The "redundant include guard", as you call it, speeds up compilation.
Without the redundant guard, the compiler will iterate the entire foo.h file, looking for some code that might be outside the #ifndef block. If it's a long file, and this is done many places, the compiler might waste a lot of time. But with the redundant guard, it can skip the entire #include statement and not even reopen that file.
Of course, you'd have to experiment and see the actual amount of time wasted by the compiler iterating through foo.h and not actually compiling anything; and perhaps modern compilers actually look for this pattern and automatically know not to bother opening the file at all, I don't know.
(Begin edit by 280Z28)
The following header structure is recognized by at least GCC and MSVC. Using this pattern negates virtually all benefits you could gain with guards in the including files. Note that comments are ignored when the compiler examines the structure.
// GCC will recognize this structure and not reopen the file
#ifndef SOMEHEADER_H_INCLUDED
#define SOMEHEADER_H_INCLUDED
// Visual C++ uses #pragma once to mark headers that shouldn't be reopened
#if defined(_MSC_VER) && (_MSC_VER >= 1020)
# pragma once
#endif
// header text goes here.
#endif
(End edit)
Related
As I understand, when compiling a compilation unit, the compiler's preprocessor translates #include directives by expanding the contents of the header file1 specified between the < and > (or ") tokens into the current compilation unit.
It is also my understanding, that most compilers support the #pragma once directive guarding against multiply defined symbols as a result of multiple inclusion of the same header. The same effect can be produced by following the include guard idiom.
My question is two-fold:
Is it legal for a compiler to completely ignore an #include directive if it has previously encountered a #pragma once directive or include guard pattern in this header?
Specifically with Microsoft' compiler is there any difference in this regard whether a header contains a #pragma once directive or an include guard pattern? The documentation suggests that they are handled the same, though some user feels very strongly that I am wrong, so I am confused and want clarification.
1 I'm glossing over the fact, that headers need not necessarily be files altogether.
It the compiled program cannot tell whether the compiler has ignored a header file or not, it is legal under the as-if rule to either ignore or not ignore it.
If ignoring a file results in a program that has observable behaviour different from a program produced by processing all files normally, or ignoring a file results in an invalid program whereas processing it normally does not, then it is not legal to ignore such file. Doing so is a compiler bug.
Compiler writers seem to be confident that ignoring a once-seen file that has proper include guards in place can have no effect on the resulting program, otherwise compilers would not be doing this optimisation. It is possible that they are all wrong though, and there is a counterexample that no one has found to date. It is also possible that non-existence of such counterexample is a theorem that no one has bothered to prove, as it seems intuitively obvious.
I think you can treat #pragma once as compiler language extension like for instance #pragma omp parallel that can make a loop execute in parallel causing all kinds of UB if it is not written correctly.
The standard says it is ok for pragma directive to cause implementation-defined non-conforming result:
Pragma directive [cpp.pragma]
...
causes the implementation to behave in an implementation-defined manner. The behavior might cause
translation to fail or cause the translator or the resulting program to behave in a non-conforming manner.
Any pragma that is not recognized by the implementation is ignored.
Regarding MSVC behavior you can think of it skipping the header based on its normalized path.For instance you can trick the compiler with symlinks:
test/test.h
#pragma once
static int x = 2;
Create symlink "test-link" to "test" directory:
mklink /d test-link test
Then in main.cpp:
#include "test/test.h"
#include "test/test.h"
#include "test/../test/test.h"
is ok. but
#include "test/test.h"
#include "test-link/test.h"
causes
error C2374: 'x': redefinition; multiple initialization
which would not happen in case of include guards.
Is it legal for a compiler to completely ignore an #include directive if it has previously encountered a #pragma once directive or include guard pattern in this header?
That depends on how #pramga once is defined and implemented by the compilers. It is after all a none standard feature.
But, all compilers I know that support #pramga once treat it like a non-mutable unique include guard that wraps around the complete file.
After the preprocessor resolved the include path for an include, it can check if that file was already included and if #pargma once exists for that file. If both conditions are true, it is safe to not include the file anymore, because it would follow the as-if rule, as the compiler vendor is in full controller over how the #pramga once is implemented and can ensure that the lock guard is unique, non-mutable, and wraps the whole file, and due to that a repeated inclusion of that same wile would result in an empty content that is included.
So with that respect, if they didn't make an implementation error it is safe to then ignore the include.
There is the argument against the usage of #pragma once that says that the compiler might treat the same file as different files due to symlinks and hard links. That would result in accidentally including the same file multiple times, but that won't affect the part of whether it is safe to ignore it if the compile identified it as the same file.
Specifically with Microsoft' compiler is there any difference in this regard whether a header contains a #pragma once directive or an include guard pattern? The documentation suggests that they are handled the same, though some user feels very strongly that I am wrong, so I am confused and want clarification.
If no #pragma once is used it becomes more complicated. The preprocessor needs to first check if the lock guard wraps around all contents:
#ifndef SOME_GUARD_NAME_H
#define SOME_GUARD_NAME_H
// all content of the file
#endif
Or if it is something like this:
// some content before the guard
#ifndef SOME_GUARD_NAME_H
#define SOME_GUARD_NAME_H
// some content
#else
// some more content
#endif
// some other content after the guard
And it needs to keep track of whether the SOME_GUARD_NAME_H was already defined in another file or if #undef was called by another file.
So in that case it can only ignore the content of the file if it can ensure that all relevant defines are the same and/or if the evaluation of the macros results in an empty file.
Is it legal for a compiler to completely ignore an #include directive if it has previously encountered a #pragma once directive or include guard pattern in this header?
Of course it is! It is even legal for the compiler to ignore all your source files and header files so long as behavior of the generated code is the same as if it processed everything. That's how pre-compiled headers and object files work - anything that hasn't changed can be safely ignored. Similarly, if the compiler can prove that including and not including the file are going to have exactly the same behavior, the compiler may ignore the file, regardless of the pre-processor directives.
Specifically with Microsoft' compiler is there any difference in this regard whether a header contains a #pragma once directive or an include guard pattern?
The documentation is pretty clear on that. They are identical assuming the compiler manages to identify the idiom and you haven't #undefed the macro. I've never experienced any bugs related to that either. #pragma once is safer though. I have had an instance where two headers had the same include guard and debugging that wasn't a nice experience.
#pragma once obviously refers to the file as a whole
The use of #pragma once can reduce build times, as the compiler won't
open and read the file again after the first #include of the file in
the translation unit.
really - if not to file - for what it can be related ?
the conditional compilation , so called guard idiom related not to file but to block of code. really - where, how stated that some condition related to file ?!
it related to block beginning with #if* and ended with #endif. compiler anyway need include this file again.
let do some tests. also here will be very useful cl(msvc) compiler option /showIncludes
let create header.h
// header.h
#ifndef HEADER_H_
#define HEADER_H_
int g_a = 0;
#endif
and then
#include "header.h"
#include "header.h"
only once in log
1>Note: including file: .\header.h
so header.h really included only once here.
but if do this
// header.h
#if !defined HEADER_H_
#define HEADER_H_
int g_a = 0;
#endif
or this
#if !defined(HEADER_H_)
#define HEADER_H_
int g_a = 0;
#endif
and
#include "header.h"
#include "header.h"
already 2 lines in log - header.h included 2 time.
1>Note: including file: .\header.h
1>Note: including file: .\header.h
so #ifndef HEADER_H_ have different effect compare #if !defined(HEADER_H_)
or if do
// header.h
#ifndef HEADER_H_
#define HEADER_H_
int g_a = 0;
#endif
#define XYZ
or
// header.h
#if __LINE__ // any not empty statement
#endif
#ifndef HEADER_H_
#define HEADER_H_
int g_a = 0;
#endif
and
#include "header.h"
#include "header.h"
already
1>Note: including file: .\header.h
1>Note: including file: .\header.h
again 2 lines in log - header.h included 2 time.
so if exist any not empty ( comments, sequences of whitespace characters (space, tab, new-line)) statement outside first conditional block - file already included more times.
of course possible and do next
// header.h
#include "header.h"
#undef HEADER_H_
#include "header.h"
in this case
1>Note: including file: .\header.h
1>Note: including file: .\header.h
1>.\header.h(4): error C2374: 'g_a': redefinition; multiple initialization
1>.\header.h(4): note: see declaration of g_a'
and of course in case
// header.h
#pragma once
int g_b = 0;
and
#include "header.h"
#include "header.h"
only single line
1>Note: including file: .\header.h
so based on tests can make next conclusion - if cl(msvc) - view that file have pattern
#ifndef macro // but not #if !defined macro
#define macro
// all code only here
#endif
macro associates with the file and then as long as it is not undefined - the file will not be included more. this is implicit optimization by specific compiler. and very fragile. any not white space or comment statement break it. even despite documented that #ifndef HEADER_H_ quivalently to #if !defined HEADER_H_ - by fact this is not true.
Let me start by defining what is usually called "external include-guards". Suppose you have a header file called someheader.h and a code file called source.cpp. You can have the traditional include-guards inside someheader.h:
//someheader.h
#ifndef _SOMEHEADER_H_
#define _SOMEHEADER_H_
// ...
#endif // _SOMEHEADER_H_
In the past, I have heard and read multiple times that in really large projects, it would be better for the compiling performance to also have external include guards. which means:
//source.cpp
#ifndef _SOMEHEADER_H_
#include "someheader.h"
#endif
// ...
I guess the reason for such an advice is that with the checking for whether someheader.h had already been processed happening inside source.cpp, the compiler could entirely avoid having to search for someheader.h, open it and just then do the checking. That would be particularly useful in big projects with many levels of nested header inclusions.
Is such an optimization for compiling-times still relevant nowadays, with compilers gcc and visual studio being a lot more well developed?
Let's say we have two class, Foo and Bar.
in Foo.h
#ifndef MYPROJ_FOO
#define MYPROJ_FOO
....
# endif
in Bar.cpp, do we still need to guard the include such as
#ifndef MYPROJ_FOO
#include <Foo.h>
#endif
or simple #include is sufficient? It seems redundant to me to have include guard if we already have header guard, but I see such practice quite often, hence wondering if I'm missing something. Thanks!
Functionally, it does not make any difference.
A reason why old code may be using this is as an optimisation. It means the preprocessor can avoid reading Foo.h a second time, so it can generate the result a little bit faster.
Nowadays, even if the preprocessor does read the file a second time, the performance impact of that should be small enough not to bother with it. Some preprocessors may even detect header guards automatically, remember which header guard is associated with which macro, and avoid re-reading the header file all by themselves.
No, you should not. Include guards are for headers, which are included by other files. Source files, on the other hand, should never be included by other files.
Alternatively you may consider using the (non standard, but generally accepted) extension in your header files
#pragma once
in Bar.cpp, do we still need to guard the include such as
#ifndef MYPROJ_FOO
#include <Foo.h>
#endif
or simple #include is sufficient?
Simple #include is sufficient from a correctness point of view.
It seems redundant to me to have include guard if we already have header guard, but I see such practice quite often, hence wondering if I'm missing something.
The practice was recommended by John Lakos in his book Large Scale C++ Software Design.
However, a better alternative is to use the #pragma once directive, which is supported by most modern C++ compilers.
Foo.h:
#pragma once
....
Then, you can just use
#include "Foo.h"
in any .cpp file.
or simple #include is sufficient?
Yes, it is.
It seems redundant to me to have include guard if we already have header guard,
Yes it is totally redundant.
but I see such practice quite often
I don't see such practiced, unless the codes authors have no clue what they're doing.
The code I am working has multiple headers and source files for different classes face.cc, face.hh, cell.cc, cell.hh edge.cc edge.hh and the headers contain includes like this,
#ifndef cellINCLUDED
#define cellINCLUDED
#ifndef faceINCLUDED
#define faceINCLUDED
I saw through http://www.cplusplus.com/forum/articles/10627/ and saw the way to write include guard is
#ifndef __MYCLASS_H_INCLUDED__
#define __MYCLASS_H_INCLUDED__
So in above code that I am working on, does compiler automatically understands it is looking for face.hh or cell.hh files?
better question : Is writing __CELL_H_INCLUDED__ same as cellINCLUDED ?
#ifndef __MYCLASS_H_INCLUDED__
#define __MYCLASS_H_INCLUDED__
So in above code that I am working on, does compiler automatically
understands it is looking for face.hh or cell.hh files?
No, the compiler doesn't automatically understand what you mean.
What really happens is that, when compiling a translation unit, the Compiler holds a list of globally defined MACROs. And so, what you are doing is defining the MACRO __MYCLASS_H_INCLUDED__ if it doesn't already exists.
If that macro is defined, that #ifndef until #endif will not be parsed by the actual compiler.
Hence you can test for the existence of that MACRO to determine if the Compiler has parsed that header file to include it once and only once in the translation unit... This is because the compiler compiles each translation unit as one flattened file (after merging all the #includes)
See https://en.wikipedia.org/wiki/Include_guard
Is writing __CELL_H_INCLUDED__ same as cellINCLUDED ?
Yes it is.... The reason some prefer using underscored prefixed and suffixed MACROs for include guards is because they have extremely low probability of ever being used as identifiers... but again, underscore could clash with the compiler...
I prefer something like this: CELL_H_INCLUDED
If you use cellINCLUDED, there are chances that someday, somebody may use it as an identifier in that translation unit
The preprocessor definitions have no special meaning. The only requirement is that they stay unique across the modules, and that's why the file name is typically a part of them.
In particular, the mechanics for preventing double inclusion aren't "baked in" the language and simply use the mechanics of the preprocessor.
That being said, every compiler worth attention nowadays supports #pragma once, and you could probably settle on that.
As the link you have referenced says, "compilers do not have brains of their own" - so to answer your question, no, the compile does not understand which particular files are involved. It would not even understand that '__cellINCLUDED' has anything conceptually to do with a specific file.
Instead, the include guard simply prevents the logic contained between its opening #ifndef and closing #endif from being included multiple times. You, as the programmer, are telling the compiler not to include that code multiple times - the compiler is not doing anything 'intelligent' on its own.
Nope, This is essentially telling the compiler/parser that if this has already been put into the program, don't puthave already been loaded.
This should be at the top (and have an #endif at the bottom) of your .h file.
Lets say you have mainProgram.cpp and Tools.cpp, with each of these files loading fileReader.h.
As the compiler compiles each cpp file it will attempt to load the fileReader.h. unless you tell it not to it will load all of the fileReader file in twice.
ifndef = if not defined
so when you use these (and the #endif AFTER all your code in the .h file)
you are saying:
if not defined: cellINCLUDED
then define: cellINCLUDED with the following code:
[code]
end of code
so this way when it goes to load the code in your .h file a second time it hits the if not defined bit and ignores the code on the second time.
This reduces compile time and also means if you are using a poor/old compiler it isn't trying to shove the code in again.
What happens if I include iostream or any other header file twice in my file?
I know the compiler does not throw error.
Will the code gets added twice or what happens internally?
What actually happens when we include a header file ?
Include guard prevents the content of the file from being actually seen twice by the compiler.
Include guard is basically a set of preprocessor's conditional directives at the beginning and end of a header file:
#ifndef SOME_STRING_H
#define SOME_STRING_H
//...
#endif
Now if you include the file twice then first time round macro SOME_STRING_H is not defined and hence the contents of the file is processed and seen by the compiler. However, since the first thing after #ifdef is #define, SOME_STRING_H is defined and the next time round the header file's content is not seen by the compiler.
To avoid collisions the name of the macro used in the include guard is made dependent on the name of the header file.
Header files are simple beasts. When you #include <header> all that happens is that the contents of header basically get copy-pasted into the file. To stop headers from being included multiple times, include guards are used, which is why in most header files you'll see something akin to
#ifndef SOME_HEADER_FILE_GUARD
#define SOME_HEADER_FILE_GUARD
//Contents of Header
#endif
It simply gets skipped over, due to preprocessor code along the following lines:
#ifndef MY_HEADER_H
#define MY_HEADER_H
<actual header code here>
#endif
So if you include twice, then MY_HEADER_H is already defined and everything between the #ifndef and #endif is skipped by the preprocessor.
It depends. With the exception of <assert>, the standard requires the
second (and later) includes of a standard header to be a no-op. This is
a characteristic of the header, however; the compiler will (at least
conceptually) read and include all of the header text each time it
encounters the include.
The standard practice for avoiding multiple definitions in such cases is
to use include guards: all of the C++ code in the header will be
enclosed in something like:
#ifndef SPECIAL_NAME
#define SPECIAL_NAME
// All of the C++ code here
#endif SPECIAL_NAME
Obviously, each header needs a different name. Within an application,
you can generally establish conventions based on the filename and
location; something like subsystem_filename, with
characters not legal in a C++ symbol (if you're using them in your
filenames) mapped (and very often everything upper cased). For
libraries, the best practice would be to generate a reasonably long
random sequence of characters; far more frequent (although certainly
inferior from a quality of implementation standpoint) is to ensure that
every such symbol begin with a documented prefix.
A system library can, of course, use reserved symbols (e.g. a symbol
starting with an underscore followed by a capital letter) here, to
guarantee that there is no conflict. Or it can use some entirely
different, implementation dependent technique. Microsoft, for example,
uses a compiler extension #pragma once; g++ uses include guards which
always start with _GLIBCXX (which isn't a legal symbol in user code).
These options aren't necessarily available to you.
When you include a header file, all its contents get copied to the line where the "#include" directive was placed. This is done by the preprocessor and is a step in the compilation process.
This process is the same for standard files like iostream or user-made ".h" files stored in local directory. However, the syntax slightly differs.
We use #include <filename> for files like 'iostream' which are stored in the library. Whereas, for header files in the local directory, we use #include "filename.h".
Now, what if we include header files twice:
Ideally speaking the content should be copied twice. But...
Many header files use the modern practice of mentioning #pragma once which instructs the pre-processor to copy contents only once, no matter how many times the header file is included.
Some very old codes use a concept called 'include gaurds'. I won't explain it as the other answers do so very well.
Using pragma once is the easy and the modern approach, however, include guards were used a lot previously and is a relatively complicated fix to this issue.