I have seen this countless of times. Instead of
#ifndef _common_h_
#define _common_h_
#endif /* _common_h_ */
people sometimes define their header files in following format:
#ifndef _common_h__479124197491641974591
#define _common_h__479124197491641974591
#endif /* _common_h__479124197491641974591 */
What is that random number good for? I just couldn't successfully google any answer to this.
The idea is to make it harder to trip your include guard unintentionally, and/or to avoid triggering someone elses' include guards.
For example, if you are writing a library, and you have a Common.h header, then using _common_h_ for the guard could prevent users of your library from having _common_h_ guards in their own libraries, which is not ideal. Adding a random number makes such collisions nearly impossible.
The problem
Include guards are often declared in the form:
#ifndef X
#define X
...
#endif
The programmer is free to choose, what we will call here as, a "name". This name is often unique within a single library, but it can happen (even if rare) that two libraries define the same name. This can potentially lead to terrible headaches.
The random numbers
Since the name is often not important outside of the specific file, we can choose (or other tools can do it for us) to include a random number within the name, which will make it much harder to cause name clashes.
#pragma once
You can avoid the problem in another way, by using:
#pragma once
This is a well supported extension, which is compatible with clang, gcc and mvc, as well as many other compilers.
Related
I get roughly what it does. What I don't understand is why it's not the default? What are the use cases where some header file would need to be included multiple times?
The reason it's not the default is primarily historical these days -- when the C language was formalized, #include was specified that it must act exactly as if the user had copy-and-pasted the specified file's contents at the location of the #include-line; and C++ wanted (and wants) to remain as compatible as possible with C, so C++ inherited that behavior from C.
As for a use-case where including the same header file more than once might be useful; one instance where I found it useful was for simulating a templated-container-class in C (because C doesn't support templates directly). I had a container-implementation-header-file that looked something like this (but more elaborate; I'm showing a simplified version here for readability):
// MyContainerImplemention.h
// be sure to #define MYTYPE and MYARRAYSIZE
// before #include-ing this file!
struct ArrayOf##MYTYPE
{
MYTYPE arrayOfItems[MYARRAYSIZE];
};
inline void Set##MYTYPE##Item(struct ArrayOf##MyType * container, int which, MYTYPE item)
{
container[which] = item;
}
[... and so on for various other MYTYPE-specific methods ...]
... then my .c files could do something like:
#define MYTYPE int
#define MYARRAYSIZE 10
#include "MyContainerImplementation.h"
#undef MYARRAYSIZE
#undef MYTYPE
#define MYTYPE short
#define MYARRAYSIZE 15
#include "MyContainerImplementation.h"
#undef MYARRAYSIZE
#undef MYTYPE
struct ArrayOfint myInts;
struct ArrayOfshort myShorts;
SetintItem(&myInts, 5, 12);
SetshortItem(&myShorts, 3, 2);
[...]
... and end up with the container "class" and its associated methods implemented for each data-type, without having to manually write a new implementation of the container "class" each time.
Yes, it was extremely ugly -- but not as ugly as having to manually write out thousands of lines of redundant container-code would have been. (The real container-implementation-header-file implemented a hash table and was several hundred lines long)
Without include guards or #pragma once the compiler would have to maintain a list of included files. This is not easy, because of different possible paths to these files (and #pragma once doesn't completely solve this) and would be expecting a bit much of the original C compilers, which had to work with very limited memory.
What's true today is not necessarily true when C came about and the C pre-processor, upon which the C++ one is based, was created.
#pragma once is just a step towards having proper C++ modules so this annoying historical legacy is finally eliminated.
Yes, it's valid to include a file multiple times, and yes, each time it's included it can behave in entirely different ways. This is why making pre-compiled headers is a huge headache for compiler developers.
Guard blocks or #pragma once are included in order to prevent a file from being included multiple times.
#pragma once, while supported on most compilers, is not an official part of the c++ standard, and may not work on every compiler. You can use a guard block, which will work on any compiler. An example of a guard block in the file MyClass.hpp would be:
#ifndef MYCLASS_HPP
#define MYCLASS_HPP
//Code here
#endif
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?
I am used to putting header guards around my objects like:
#ifndef SOMETHING_H
#define SOMETHING_H
class Something {
...
}
#endif
but I have been given code where they also do:
#ifndef SOMETHING_H
#include "something.h"
#endif
for every include. Supposedly, this is better. Why? Is this redundant with guards around the object?
This is discussed in pretty good detail here:
http://c2.com/cgi/wiki?RedundantIncludeGuards
Here are the highlights:
Yes this is redundant, but for some compilers it may be faster because the compiler will avoid opening the header file if it doesn't need to.
"Good compilers make this idiom unnecessary. They notice the header is using the include-guard idiom (that is, that all non-comment code in the file is bracketed with the #ifndef). They store an internal table of header files and guard macros. Before opening any file they check the current value of the guard and then skip the entire file."
"Redundant guards have several drawbacks. They make include sections significantly harder to read. They are, well, redundant. They leak the guard name, which should be a secret implementation detail of the header. If, for example, someone renames the guard they might forget to update all the places where the guard name is assumed. Finally, they go wrong if anyone adds code outside of the guard. And of course, they are just a compile-time efficiency hack. Use only when all else fails."
The thinking behind it is the preprocessor will not need to open the header file and read the contents to determine that that header has been previously included, thus saving some time during compilation. However, most compilers these days are already smart enough to spot multiple inclusions of the same file and ignore subsequent occurrences.
It's good to have this on header and class definition files, so that on compilation, if a file is referenced in a loop (a.cpp references a.h and b.cpp, and b.cpp also references a.h, a.h will not be read again) or other similar cases.
The case that worries me most about what looks like your question is that the same constant name is being defined in different files, and possibly preventing the compiler from seeing some necessary-to-see constants, classes, types, etc. as it will "believe" that the file was "already read".
Long story short, put different #ifndef constants in different files to prevent confusion.
The purpose of doing this is to save on compile time. When the compile sees #include "something.h", it has to go out and fetch the file. If it does that ten times and the last nine all basically amount to:
#if 0
...
#endif
then you're paying the cost of finding the file and fetching it from disk nine times for no real benefit. (Technically speaking, the compiler can pull tricks to try and reduce or eliminate this cost, but that's the idea behind it.)
For small programs, the saving probably aren't very significant, and there isn't much benefit to doing it. For large programs consisting of thousands of files, it isn't uncommon for compilation to take hours, and this trick can shave off substantial amounts of time. Personally, it's not something I would do until compilation time starts becoming a real issue, and like any optimization I would look carefully at where the real costs are before running around making a bunch of changes.
I have a header with a particular set of rules that the user must follow. If the user does not want to follow the rules, they must define a preprocessor macro which will disable the checks. If the user is using the library, the user must include the header in every one of their classes that uses any code from the library or explicitly state otherwise by the above mentioned preprocessor (in this case, the header may be included implicitly [using one of the library's classes] which is fine):
// User using my library, they must include the BaseHeader.h or otherwise use the following define
// #define NOT_USING_BASE_HEADER //(can of course be defined project wide)
#include <BaseHeader.h>
// ... other includes (not necessarily from my library)
class Foo
{
//...
};
Is there a way to accomplish this? Keep in mind that the base header is also being included
I'm not sure if I understand your question entirely, but do you think this will help?
BaseHeader.h:
#pragma once
#define BASE_HEADER_INCLUDED
...
internal_header.h:
#pragma once
#ifdef NOT_USING_BASE_HEADER
#ifdef BASE_HEADER_INCLUDED
#error You can't both define NOT_USING_BASE_HEADER and include the base-header-file.
#endif
...
#elseif defined BASE_HEADER_INCLUDED
...
#else
#error You have to either define NOT_USING_BASE_HEADER or include the base header file!
#endif
If you want to make it so that it doesn't take "internal" includes of the baseheader.h, then you have to add/remove a define to make sure that it doesn't define it:
internal_header.h:
#pragma once
#define SKIP_HEADER_DEFINE
#include
#undef SKIP_HEADER_DEFINE
And in BaseHeader.h:
#pragma once
#ifndef SKIP_HEADER_DEFINE
#define BASE_HEADER_INCLUDED
#endif
Cheers,
Simon
I see at least two choices:
Document that the users must do this. This needs to be right up front, not buried ten miles deep. You are making any use of your library that doesn't follow your rules undefined behavior (obviously not UB as far as the language is concerned, but as far as your library its UB because you said so).
Do it for them. Make all of your headers #include BaseHeader.h. Don't give the user the option of invoking UB or otherwise screwing up.
BTW, BaseHeader.h is not the best name for a library header. You are asking for name collisions, and that is C++ undefined behavior, and that UB is your fault.
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)