1// Copyright 2017 The Abseil Authors.
2//
3// Licensed under the Apache License, Version 2.0 (the "License");
4// you may not use this file except in compliance with the License.
5// You may obtain a copy of the License at
6//
7// https://www.apache.org/licenses/LICENSE-2.0
8//
9// Unless required by applicable law or agreed to in writing, software
10// distributed under the License is distributed on an "AS IS" BASIS,
11// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12// See the License for the specific language governing permissions and
13// limitations under the License.
14//
15// -----------------------------------------------------------------------------
16// kConstInit
17// -----------------------------------------------------------------------------
18//
19// A constructor tag used to mark an object as safe for use as a global
20// variable, avoiding the usual lifetime issues that can affect globals.
21
22#ifndef ABSL_BASE_CONST_INIT_H_
23#define ABSL_BASE_CONST_INIT_H_
24
25// In general, objects with static storage duration (such as global variables)
26// can trigger tricky object lifetime situations. Attempting to access them
27// from the constructors or destructors of other global objects can result in
28// undefined behavior, unless their constructors and destructors are designed
29// with this issue in mind.
30//
31// The normal way to deal with this issue in C++11 is to use constant
32// initialization and trivial destructors.
33//
34// Constant initialization is guaranteed to occur before any other code
35// executes. Constructors that are declared 'constexpr' are eligible for
36// constant initialization. You can annotate a variable declaration with the
37// ABSL_CONST_INIT macro to express this intent. For compilers that support
38// it, this annotation will cause a compilation error for declarations that
39// aren't subject to constant initialization (perhaps because a runtime value
40// was passed as a constructor argument).
41//
42// On program shutdown, lifetime issues can be avoided on global objects by
43// ensuring that they contain trivial destructors. A class has a trivial
44// destructor unless it has a user-defined destructor, a virtual method or base
45// class, or a data member or base class with a non-trivial destructor of its
46// own. Objects with static storage duration and a trivial destructor are not
47// cleaned up on program shutdown, and are thus safe to access from other code
48// running during shutdown.
49//
50// For a few core Abseil classes, we make a best effort to allow for safe global
51// instances, even though these classes have non-trivial destructors. These
52// objects can be created with the absl::kConstInit tag. For example:
53// ABSL_CONST_INIT absl::Mutex global_mutex(absl::kConstInit);
54//
55// The line above declares a global variable of type absl::Mutex which can be
56// accessed at any point during startup or shutdown. global_mutex's destructor
57// will still run, but will not invalidate the object. Note that C++ specifies
58// that accessing an object after its destructor has run results in undefined
59// behavior, but this pattern works on the toolchains we support.
60//
61// The absl::kConstInit tag should only be used to define objects with static
62// or thread_local storage duration.
63
64namespace absl {
65
66enum ConstInitType {
67 kConstInit,
68};
69
70} // namespace absl
71
72#endif // ABSL_BASE_CONST_INIT_H_
73