blob: 0325e7416510f40c700223119922b785b26bf96e [file] [log] [blame]
Vitaly Bukacbed2062015-08-17 12:54:05 -07001// Copyright 2014 The Chromium Authors. All rights reserved.
2// Use of this source code is governed by a BSD-style license that can be
3// found in the LICENSE file.
4
5// This file contains macros and macro-like constructs (e.g., templates) that
6// are commonly used throughout Chromium source. (It may also contain things
7// that are closely related to things that are commonly used that belong in this
8// file.)
9
10#ifndef BASE_MACROS_H_
11#define BASE_MACROS_H_
12
13#include <stddef.h> // For size_t.
14#include <string.h> // For memcpy.
15
16// Put this in the declarations for a class to be uncopyable.
17#define DISALLOW_COPY(TypeName) \
18 TypeName(const TypeName&) = delete
19
20// Put this in the declarations for a class to be unassignable.
21#define DISALLOW_ASSIGN(TypeName) \
22 void operator=(const TypeName&) = delete
23
24// A macro to disallow the copy constructor and operator= functions
25// This should be used in the private: declarations for a class
26#define DISALLOW_COPY_AND_ASSIGN(TypeName) \
27 TypeName(const TypeName&); \
28 void operator=(const TypeName&)
29
30// An older, deprecated, politically incorrect name for the above.
31// NOTE: The usage of this macro was banned from our code base, but some
32// third_party libraries are yet using it.
33// TODO(tfarina): Figure out how to fix the usage of this macro in the
34// third_party libraries and get rid of it.
35#define DISALLOW_EVIL_CONSTRUCTORS(TypeName) DISALLOW_COPY_AND_ASSIGN(TypeName)
36
37// A macro to disallow all the implicit constructors, namely the
38// default constructor, copy constructor and operator= functions.
39//
40// This should be used in the private: declarations for a class
41// that wants to prevent anyone from instantiating it. This is
42// especially useful for classes containing only static methods.
43#define DISALLOW_IMPLICIT_CONSTRUCTORS(TypeName) \
44 TypeName(); \
45 DISALLOW_COPY_AND_ASSIGN(TypeName)
46
47// The arraysize(arr) macro returns the # of elements in an array arr.
48// The expression is a compile-time constant, and therefore can be
49// used in defining new arrays, for example. If you use arraysize on
50// a pointer by mistake, you will get a compile-time error.
51
52// This template function declaration is used in defining arraysize.
53// Note that the function doesn't need an implementation, as we only
54// use its type.
55template <typename T, size_t N> char (&ArraySizeHelper(T (&array)[N]))[N];
56#define arraysize(array) (sizeof(ArraySizeHelper(array)))
57
58
59// Use implicit_cast as a safe version of static_cast or const_cast
60// for upcasting in the type hierarchy (i.e. casting a pointer to Foo
61// to a pointer to SuperclassOfFoo or casting a pointer to Foo to
62// a const pointer to Foo).
63// When you use implicit_cast, the compiler checks that the cast is safe.
64// Such explicit implicit_casts are necessary in surprisingly many
65// situations where C++ demands an exact type match instead of an
66// argument type convertible to a target type.
67//
68// The From type can be inferred, so the preferred syntax for using
69// implicit_cast is the same as for static_cast etc.:
70//
71// implicit_cast<ToType>(expr)
72//
73// implicit_cast would have been part of the C++ standard library,
74// but the proposal was submitted too late. It will probably make
75// its way into the language in the future.
76template<typename To, typename From>
77inline To implicit_cast(From const &f) {
78 return f;
79}
80
81// The COMPILE_ASSERT macro can be used to verify that a compile time
82// expression is true. For example, you could use it to verify the
83// size of a static array:
84//
85// COMPILE_ASSERT(arraysize(content_type_names) == CONTENT_NUM_TYPES,
86// content_type_names_incorrect_size);
87//
88// or to make sure a struct is smaller than a certain size:
89//
90// COMPILE_ASSERT(sizeof(foo) < 128, foo_too_large);
91//
92// The second argument to the macro is the name of the variable. If
93// the expression is false, most compilers will issue a warning/error
94// containing the name of the variable.
95
96#undef COMPILE_ASSERT
97#define COMPILE_ASSERT(expr, msg) static_assert(expr, #msg)
98
99// bit_cast<Dest,Source> is a template function that implements the
100// equivalent of "*reinterpret_cast<Dest*>(&source)". We need this in
101// very low-level functions like the protobuf library and fast math
102// support.
103//
104// float f = 3.14159265358979;
105// int i = bit_cast<int32>(f);
106// // i = 0x40490fdb
107//
108// The classical address-casting method is:
109//
110// // WRONG
111// float f = 3.14159265358979; // WRONG
112// int i = * reinterpret_cast<int*>(&f); // WRONG
113//
114// The address-casting method actually produces undefined behavior
115// according to ISO C++ specification section 3.10 -15 -. Roughly, this
116// section says: if an object in memory has one type, and a program
117// accesses it with a different type, then the result is undefined
118// behavior for most values of "different type".
119//
120// This is true for any cast syntax, either *(int*)&f or
121// *reinterpret_cast<int*>(&f). And it is particularly true for
122// conversions between integral lvalues and floating-point lvalues.
123//
124// The purpose of 3.10 -15- is to allow optimizing compilers to assume
125// that expressions with different types refer to different memory. gcc
126// 4.0.1 has an optimizer that takes advantage of this. So a
127// non-conforming program quietly produces wildly incorrect output.
128//
129// The problem is not the use of reinterpret_cast. The problem is type
130// punning: holding an object in memory of one type and reading its bits
131// back using a different type.
132//
133// The C++ standard is more subtle and complex than this, but that
134// is the basic idea.
135//
136// Anyways ...
137//
138// bit_cast<> calls memcpy() which is blessed by the standard,
139// especially by the example in section 3.9 . Also, of course,
140// bit_cast<> wraps up the nasty logic in one place.
141//
142// Fortunately memcpy() is very fast. In optimized mode, with a
143// constant size, gcc 2.95.3, gcc 4.0.1, and msvc 7.1 produce inline
144// code with the minimal amount of data movement. On a 32-bit system,
145// memcpy(d,s,4) compiles to one load and one store, and memcpy(d,s,8)
146// compiles to two loads and two stores.
147//
148// I tested this code with gcc 2.95.3, gcc 4.0.1, icc 8.1, and msvc 7.1.
149//
150// WARNING: if Dest or Source is a non-POD type, the result of the memcpy
151// is likely to surprise you.
152
153template <class Dest, class Source>
154inline Dest bit_cast(const Source& source) {
155 COMPILE_ASSERT(sizeof(Dest) == sizeof(Source), VerifySizesAreEqual);
156
157 Dest dest;
158 memcpy(&dest, &source, sizeof(dest));
159 return dest;
160}
161
162// Used to explicitly mark the return value of a function as unused. If you are
163// really sure you don't want to do anything with the return value of a function
164// that has been marked WARN_UNUSED_RESULT, wrap it with this. Example:
165//
166// scoped_ptr<MyType> my_var = ...;
167// if (TakeOwnership(my_var.get()) == SUCCESS)
168// ignore_result(my_var.release());
169//
170template<typename T>
171inline void ignore_result(const T&) {
172}
173
174// The following enum should be used only as a constructor argument to indicate
175// that the variable has static storage class, and that the constructor should
176// do nothing to its state. It indicates to the reader that it is legal to
177// declare a static instance of the class, provided the constructor is given
178// the base::LINKER_INITIALIZED argument. Normally, it is unsafe to declare a
179// static variable that has a constructor or a destructor because invocation
180// order is undefined. However, IF the type can be initialized by filling with
181// zeroes (which the loader does for static variables), AND the destructor also
182// does nothing to the storage, AND there are no virtual methods, then a
183// constructor declared as
184// explicit MyClass(base::LinkerInitialized x) {}
185// and invoked as
186// static MyClass my_variable_name(base::LINKER_INITIALIZED);
187namespace base {
188enum LinkerInitialized { LINKER_INITIALIZED };
189
190// Use these to declare and define a static local variable (static T;) so that
191// it is leaked so that its destructors are not called at exit. If you need
192// thread-safe initialization, use base/lazy_instance.h instead.
193#define CR_DEFINE_STATIC_LOCAL(type, name, arguments) \
194 static type& name = *new type arguments
195
196} // base
197
198#endif // BASE_MACROS_H_