Difference between revisions of "cpp/language/storage duration"

Latest revision as of 19:44, 1 November 2024

The storage class specifiers are a part of the decl-specifier-seq of a name's declaration syntax. Together with the scope of the name, they control two independent properties of the name: its storage duration and its linkage.

Specifier	Can appear in the decl-specifier-seq s of
	Variable declarations				Function declarations			Structured binding declarations (since C++17)
	Non-member		Member		Non-member	Member
	Non-parameter	Function parameter	Non-static	Static	Non-member	Non-static	Static
auto	Block scope only	Yes	No	No	No	No	No	N/A
register	Block scope only	Yes	No	No	No	No	No	N/A
static	Yes	No	Declares static		Namespace scope only	Declares static		Yes
thread_local	Yes	No	No	Yes	No	No	No	Yes
extern	Yes	No	No	No	Yes	No	No	No

Anonymous unions can also be declared with static.

register is a hint that the variable so declared will be heavily used, so that its value can be stored in a CPU register. The hint can be ignored, and in most implementations it will be ignored if the address of the variable is taken. This use is deprecated.

(until C++17)

[edit] Static storage duration

A variable satisfying all following conditions has static storage duration :

It belongs to a namespace scope or are first declared with static or extern.

It does not have thread storage duration.

(since C++11)

The storage for these entities lasts for the duration of the program.

Thread storage duration

All variables declared with thread_local have thread storage duration.

The storage for these entities lasts for the duration of the thread in which they are created. There is a distinct object or reference per thread, and use of the declared name refers to the entity associated with the current thread.

(since C++11)

[edit] Automatic storage duration

The following variables have automatic storage duration :

Variables that belong to a block scope and are not explicitly declared static, thread_local,(since C++11) or extern. The storage for such variables lasts until the block in which they are created exits.
Variables that belong to a parameter scope (i.e. function parameters). The storage for a function parameter lasts until immediately after its destruction.

[edit] Dynamic storage duration

Objects created by the following methods during program execution have dynamic storage duration :

new expressions. The storage for such objects is allocated by allocation functions and deallocated by deallocation functions.
Implicitly creation by other means. The storage for such objects overlaps with some existing storage.
Exception objects. The storage for such objects is allocated and deallocated in an unspecified way.

[edit] Linkage

A name can have external linkage , module linkage(since C++20), internal linkage, or no linkage:

An entity whose name has external linkage can be redeclared in another translation unit, and the redeclaration can be attached to a different module(since C++20).

An entity whose name has module linkage can be redeclared in another translation unit, as long as the redeclaration is attached to the same module.

(since C++20)

An entity whose name has internal linkage can be redeclared in another scope in the same translation unit.
An entity whose name has no linkage can only be redeclared in the same scope.

The following linkages are recognized:

[edit] No linkage

Any of the following names declared at block scope have no linkage:

variables that are not explicitly declared extern (regardless of the static modifier);
local classes and their member functions;
other names declared at block scope such as typedefs, enumerations, and enumerators.

Names not specified with external, module,(since C++20) or internal linkage also have no linkage, regardless of which scope they are declared in.

[edit] Internal linkage

Any of the following names declared at namespace scope have internal linkage:

variables, variable templates(since C++14), functions, or function templates declared static;
non-template (since C++14)variables of non-volatile const-qualified type, unless

they are inline,	(since C++17)
they are declared in the purview of a module interface unit (outside the private module fragment, if any) or module partition,	(since C++20)

they are explicitly declared extern, or
they were previously declared and the prior declaration did not have internal linkage;

data members of anonymous unions.

In addition, all names declared in unnamed namespaces or a namespace within an unnamed namespace, even ones explicitly declared extern, have internal linkage.

(since C++11)

[edit] External linkage

Variables and functions with external linkage also have language linkage, which makes it possible to link translation units written in different programming languages.

Any of the following names declared at namespace scope have external linkage, unless they are declared in an unnamed namespace or their declarations are attached to a named module and are not exported(since C++20):

variables and functions not listed above (that is, functions not declared static, non-const variables not declared static, and any variables declared extern);
enumerations;
names of classes, their member functions, static data members (const or not), nested classes and enumerations, and functions first introduced with friend declarations inside class bodies;
names of all templates not listed above (that is, not function templates declared static).

Any of the following names first declared at block scope have external linkage:

names of variables declared extern;
names of functions.

Module linkage

Names declared at namespace scope have module linkage if their declarations are attached to a named module and are not exported, and do not have internal linkage.

(since C++20)

[edit] Static block variables

Block variables with static or thread(since C++11) storage duration are initialized the first time control passes through their declaration (unless their initialization is zero- or constant-initialization, which can be performed before the block is first entered). On all further calls, the declaration is skipped.

If the initialization throws an exception, the variable is not considered to be initialized, and initialization will be attempted again the next time control passes through the declaration.
If the initialization recursively enters the block in which the variable is being initialized, the behavior is undefined.

If multiple threads attempt to initialize the same static local variable concurrently, the initialization occurs exactly once (similar behavior can be obtained for arbitrary functions with std::call_once).

Usual implementations of this feature use variants of the double-checked locking pattern, which reduces runtime overhead for already-initialized local statics to a single non-atomic boolean comparison.

(since C++11)

The destructor for a block variable with static storage duration is called at program exit, but only if the initialization took place successfully.

Variables with static storage duration in all definitions of the same inline function (which may be implicitly inline) all refer to the same object defined in one translation unit, as long as the function has external linkage.

[edit] Translation-unit-local entities

The concept of translation-unit-local entities is standardized in C++20, see this page for more details.

An entity is translation-unit-local (or TU-local for short) if

it has a name with internal linkage, or
it does not have a name with linkage and is introduced within the definition of a TU-local entity, or
it is a template or template specialization whose template argument or template declaration uses a TU-local entity.

Bad things (usually violation of ODR) can happen if the type of a non-TU-local entity depends on a TU-local entity, or if a declaration of, or a deduction guide for,(since C++17) a non-TU-local entity names a TU-local entity outside its

function-body for a non-inline function or function template
initializer for a variable or variable template
friend declarations in a class definition
use of value of a variable, if the variable is usable in constant expressions

Such uses are disallowed in a module interface unit (outside its private-module-fragment, if any) or a module partition, and are deprecated in any other context.

A declaration that appears in one translation unit cannot name a TU-local entity declared in another translation unit that is not a header unit. A declaration instantiated for a template appears at the point of instantiation of the specialization.

(since C++20)

[edit] Notes

Names at the top-level namespace scope (file scope in C) that are const and not extern have external linkage in C, but internal linkage in C++.

Since C++11, auto is no longer a storage class specifier; it is used to indicate type deduction.

In C, the address of a register variable cannot be taken, but in C++, a variable declared register is semantically indistinguishable from a variable declared without any storage class specifiers.	(until C++17)
In C++, unlike C, variables cannot be declared register.	(since C++17)

Names of thread_local variables with internal or external linkage referred from different scopes may refer to the same or to different instances depending on whether the code is executing in the same or in different threads.

The extern keyword can also be used to specify language linkage and explicit template instantiation declarations, but it's not a storage class specifier in those cases (except when a declaration is directly contained in a language linkage specification, in which case the declaration is treated as if it contains the extern specifier).

Storage class specifiers, except for thread_local, are not allowed on explicit specializations and explicit instantiations:

template<class T>
struct S
{
    thread_local static int tlm;
};
 
template<>
thread_local int S<float>::tlm = 0; // "static" does not appear here

A const (may be implied by constexpr) variable template used to have internal linkage by default, which was inconsistent with other templated entities. Defect report CWG2387 corrected this.	(since C++14)
`inline` acts as a workaround for CWG2387 by giving external linkage by default. This is why the inline was added to many variable templates and then removed after having CWG2387 accepted. Standard library implementations also need to use inline as long as a supported compiler has not get CWG2387 implemented. See GCC Bugzilla #109126 and MSVC STL PR #4546.	(since C++17)

Feature-test macro	Value	Std	Feature
`__cpp_threadsafe_static_init`	200806L	(C++11)	Dynamic initialization and destruction with concurrency

[edit] Keywords

auto, register, static, extern, thread_local, mutable

[edit] Example

Run this code

#include <iostream>
#include <mutex>
#include <string>
#include <thread>
 
thread_local unsigned int rage = 1;
std::mutex cout_mutex;
 
void increase_rage(const std::string& thread_name)
{
    ++rage; // modifying outside a lock is okay; this is a thread-local variable
    std::lock_guard<std::mutex> lock(cout_mutex);
    std::cout << "Rage counter for " << thread_name << ": " << rage << '\n';
}
 
int main()
{
    std::thread a(increase_rage, "a"), b(increase_rage, "b");
 
    {
        std::lock_guard<std::mutex> lock(cout_mutex);
        std::cout << "Rage counter for main: " << rage << '\n';
    }
 
    a.join();
    b.join();
}

Possible output:

Rage counter for a: 2
Rage counter for main: 1
Rage counter for b: 2

[edit] Defect reports

The following behavior-changing defect reports were applied retroactively to previously published C++ standards.

DR	Applied to	Behavior as published	Correct behavior
CWG 216	C++98	unnamed class and enumeration in class scope have different linkage from those in namespace scope	they all have external linkage in these scopes
CWG 389	C++98	a name with no linkage should not be used to declare an entity with linkage	a type without linkage shall not be used as the type of a variable or function with linkage, unless the variable or function has C language linkage
CWG 426	C++98	an entity could be declared with both internal and external linkage in the same translation unit	the program is ill-formed in this case
CWG 527	C++98	the type restriction introduced by the resolution of CWG 389 was also applied to variables and functions that cannot be named outside their own translation units	the restriction is lifted for these variables and functions (i.e. with no linkage or internal linkage, or declared within unnamed namespaces)
CWG 809	C++98	register served very little function	deprecated
CWG 1648	C++11	static was implied even if thread_local is combined with extern	implied only if no other storage class specifier is present
CWG 1686	C++98 C++11	the name of a non-static variable declared in namespace scope had internal linkage only if it is explicitly declared const (C++98) or constexpr (C++11)	only required the type to be const-qualified
CWG 2019	C++98	the storage duration of reference members were unspecified	same as their complete object
CWG 2387	C++14	unclear whether const-qualified variable template have internal linkage by default	const qualifier does not affect the linkage of variable templates or their instances
CWG 2533	C++98	the storage duration of implicitly- created objects were unclear	made clear
CWG 2850	C++98	it was unclear when the storage for function parameters are deallocated	made clear
CWG 2872	C++98	the meaning of “can be referred to” was unclear	improved wording
P2788R0	C++20	declaring a const-qualified variable in a namespace gave it internal linkage even in a module unit	internal linkage is not given

[edit] References

C++23 standard (ISO/IEC 14882:2024):

6.7.5 Storage duration [basic.stc]

C++20 standard (ISO/IEC 14882:2020):

6.7.5 Storage duration [basic.stc]

C++17 standard (ISO/IEC 14882:2017):

6.7 Storage duration [basic.stc]

C++14 standard (ISO/IEC 14882:2014):

3.7 Storage duration [basic.stc]

C++11 standard (ISO/IEC 14882:2011):

3.7 Storage duration [basic.stc]

C++03 standard (ISO/IEC 14882:2003):

3.7 Storage duration [basic.stc]

C++98 standard (ISO/IEC 14882:1998):

3.7 Storage duration [basic.stc]

[edit] See also

C documentation for storage duration

@@ Line 89: / Line 89: @@
 ====Static storage duration====
-A variable satisfying all following conditions have ''static storage duration''{{sep}}:
+A variable satisfying all following conditions has ''static storage duration''{{sep}}:
 * It belongs to a {{rlpsd|scope#Namespace scope}} or are first declared with {{c/core|static}} or {{c/core|extern}}.
 {{rrev|since=c++11|
@@ Line 107: / Line 107: @@
 The following variables have ''automatic storage duration''{{sep}}:
 * Variables that belong to a {{rlpsd|scope#Block scope}} and are not explicitly declared {{c/core|static}}{{rev inl|since=c++11|, {{c/core|thread_local}},}} or {{c/core|extern}}<!-- no need to mention “auto” and “register” here -->. The storage for such variables lasts until the block in which they are created exits.
-* Variables that belong to a parameter scope (i.e. function parameters). The storage for a function parameter lasts until immediately after its {{rlp|operator other#Built-in function call operator|destruction}}
+* Variables that belong to a parameter scope (i.e. function parameters). The storage for a function parameter lasts until immediately after its {{rlp|operator other#Built-in function call operator|destruction}}.
 ====Dynamic storage duration====
 Objects created by the following methods during program execution have ''dynamic storage duration''{{sep}}:
-* {{rlp|new|{{c/core|new}} expressions}}. The storage for such objects are allocated by [[cpp/memory/new/operator new|allocation functions]] and deallocated by [[cpp/memory/new/operator delete|deallocation functions]].
+* {{rlp|new|{{c/core|new}} expressions}}. The storage for such objects is allocated by [[cpp/memory/new/operator new|allocation functions]] and deallocated by [[cpp/memory/new/operator delete|deallocation functions]].
-* {{rlp|object#Object creation|Implicitly creation}} by other means. The storage for such objects overlap with some existing storage.
+* {{rlp|object#Object creation|Implicitly creation}} by other means. The storage for such objects overlaps with some existing storage.
-* {{rlps|throw#Exception object}}s. The storage for such objects are allocated and deallocated in an unspecified way.
+* {{rlps|throw#Exception object}}s. The storage for such objects is allocated and deallocated in an unspecified way.
 ===Linkage===
-A name that denotes object, reference, function, type, template, namespace, or value, may have ''linkage''. If a name has linkage, it refers to the same entity as the same name introduced by a declaration in another scope. If a variable, function, or another entity with the same name is declared in several scopes, but does not have sufficient linkage, then several instances of the entity are generated.
+A name can have ''external linkage''{{sep}}{{rev inl|since=c++20|, ''module linkage''}}, ''internal linkage'', or ''no linkage'':
+* An entity whose name has external linkage can be {{rlp|conflicting declarations#Multiple declarations of the same entity|redeclared}} in another {{rlp|translation phases|translation unit}}{{rev inl|since=c++20|, and the redeclaration can be {{rlp|modules#Module ownership|attached to a different module}}}}.
+{{rrev|since=c++20|
+* An entity whose name has module linkage can be redeclared in another translation unit, as long as the redeclaration is attached to the same module.
+}}
+* An entity whose name has internal linkage can be redeclared in another scope in the same translation unit.
+* An entity whose name has no linkage can only be redeclared in the same scope.
 The following linkages are recognized:
 ====No linkage====
-The name can be referred to only from the scope it is in.
 Any of the following names declared at block scope have no linkage:
-* variables that aren't explicitly declared {{c/core|extern}} (regardless of the {{c/core|static}} modifier);
+* variables that are not explicitly declared {{c/core|extern}} (regardless of the {{c/core|static}} modifier);
 * {{rlpsd|class#Local classes}} and their member functions;
 * other names declared at block scope such as typedefs, enumerations, and enumerators.
@@ Line 131: / Line 135: @@
 ====Internal linkage====
-The name can be referred to from all scopes in the current translation unit.
 Any of the following names declared at namespace scope have internal linkage:
 * variables{{rev inl|since=c++14|, variable templates}}, functions, or function templates declared {{c/core|static}};
 * {{rev inl|since=c++14|non-template }}variables of non-volatile const-qualified type, unless
-{{rrev|since=c++17|
+{{rev begin}}
+{{rev|since=c++17|
 :* they are inline,
 }}
-{{rrev|since=c++20|
+{{rev|since=c++20|
 :* they are declared in the purview of a {{rlp|modules#Module declarations|module interface unit}} (outside the {{rlpsd|modules#Private module fragment}}, if any) or {{rlp|modules#Module partitions|module partition}},
 }}
+{{rev end}}
 :* they are explicitly declared {{c/core|extern}}, or
 :* they were previously declared and the prior declaration did not have internal linkage;
@@ Line 147: / Line 151: @@
 {{rrev|since=c++11|
-In addition, all names declared in {{rlp|namespace|unnamed namespace}} or a namespace within an unnamed namespace, even ones explicitly declared {{c/core|extern}}, have internal linkage.
+In addition, all names declared in {{rlpsd|namespace#Unnamed namespaces}} or a namespace within an unnamed namespace, even ones explicitly declared {{c/core|extern}}, have internal linkage.
 }}
 ====External linkage====
-The name can be referred to from the scopes in the other translation units. Variables and functions with external linkage also have {{rlp|language linkage}}, which makes it possible to link translation units written in different programming languages.
+Variables and functions with external linkage also have {{rlp|language linkage}}, which makes it possible to link translation units written in different programming languages.
 Any of the following names declared at namespace scope have external linkage, unless they are declared in an unnamed namespace{{rev inl|since=c++20| or their declarations are attached to a named module and are not exported}}:
@@ Line 165: / Line 169: @@
 {{rrev|since=c++20|
 ====Module linkage====
-The name can be referred to only from the scopes in the same module unit or in the other translation units of the same named module.
+Names declared at namespace scope have module linkage if their declarations are attached to a named module and are not exported, and do not have internal linkage.
-Names declared at namespace scope have module linkage if their declarations are attached to a named module and are not exported, and don't have internal linkage.
 }}
@@ Line 247: / Line 249: @@
 ===Keywords===
-{{rev inl|until=c++11|{{ltt|cpp/keyword/auto}}, }}{{rev inl|until=c++17|{{ltt|cpp/keyword/register}}, }}{{ltt|cpp/keyword/static}}, {{ltt|cpp/keyword/extern}}{{rev inl|since=c++11|, {{ltt|cpp/keyword/thread_local}}}}, {{ltt|cpp/keyword/mutable}}
+{{ltt|cpp/keyword/auto}},
+{{ltt|cpp/keyword/register}},
+{{ltt|cpp/keyword/static}},
+{{ltt|cpp/keyword/extern}},
+{{ltt|cpp/keyword/thread_local}},
+{{ltt|cpp/keyword/mutable}}
 ===Example===
@@ Line 299: / Line 306: @@
 {{dr list item|wg=cwg|dr=2533|std=C++98|before=the storage duration of implicitly-<br>created objects were unclear|after=made clear}}
 {{dr list item|wg=cwg|dr=2850|std=C++98|before=it was unclear when the storage for<br>function parameters are deallocated|after=made clear}}
+{{dr list item|wg=cwg|dr=2872|std=C++98|before=the meaning of “can be referred to” was unclear|after=improved wording}}
 {{dr list item|paper=P2788R0|std=C++20|before=declaring a const-qualified variable in a namespace<br>gave it internal linkage even in a module unit|after=internal linkage is not given}}
 {{dr list end}}
+===References===
+{{ref std c++23}}
+{{ref std|section=6.7.5|title=Storage duration|id=basic.stc}}
+{{ref std end}}
+{{ref std c++20}}
+{{ref std|section=6.7.5|title=Storage duration|id=basic.stc}}
+{{ref std end}}
+{{ref std c++17}}
+{{ref std|section=6.7|title=Storage duration|id=basic.stc}}
+{{ref std end}}
+{{ref std c++14}}
+{{ref std|section=3.7|title=Storage duration|id=basic.stc}}
+{{ref std end}}
+{{ref std c++11}}
+{{ref std|section=3.7|title=Storage duration|id=basic.stc}}
+{{ref std end}}
+{{ref std c++03}}
+{{ref std|section=3.7|title=Storage duration|id=basic.stc}}
+{{ref std end}}
+{{ref std c++98}}
+{{ref std|section=3.7|title=Storage duration|id=basic.stc}}
+{{ref std end}}
 ===See also===

Compiler support
Freestanding and hosted
Language
Standard library
Standard library headers
Named requirements
Feature test macros (C++20)
Language support library
Concepts library (C++20)
Metaprogramming library (C++11)
Diagnostics library
General utilities library
Strings library
Containers library
Iterators library
Ranges library (C++20)
Algorithms library
Numerics library
Localizations library
Input/output library
Filesystem library (C++17)
Regular expressions library (C++11)
Concurrency support library (C++11)
Execution support library (C++26)
Technical specifications
Symbols index
External libraries

cppreference.com

Namespaces

Variants

Views

Actions

Difference between revisions of "cpp/language/storage duration"

Latest revision as of 19:44, 1 November 2024

Contents

[edit] Storage duration

[edit] Specifiers

[edit] Static storage duration

Thread storage duration

[edit] Automatic storage duration

[edit] Dynamic storage duration

[edit] Linkage

[edit] No linkage

[edit] Internal linkage

[edit] External linkage

Module linkage

[edit] Static block variables

[edit] Translation-unit-local entities

[edit] Notes

[edit] Keywords

[edit] Example

[edit] Defect reports

[edit] References

[edit] See also

Navigation

Toolbox