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

Revision as of 23:40, 11 August 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.

Storage duration

The storage duration is the property of an object that defines the minimum potential lifetime of the storage containing the object. The storage duration is determined by the construct used to create the object and is one of the following:

• static storage duration

• automatic storage duration
• dynamic storage duration

Static, thread,(since C++11) and automatic storage durations are associated with objects introduced by declarations and with temporary objects. The dynamic storage duration is associated with objects created by a new expression or with implicitly created objects.

The storage duration categories apply to references as well.

The storage duration of subobjects and reference members is that of their complete object.

Specifiers

The following keywords are storage class specifiers :

• static

• extern
• mutable

In a decl-specifier-seq, there can be at most one storage class specifier, except that thread_local may appear with static or extern(since C++11).

mutable has no effect on storage duration. For its usage, see const/volatile.

Other storage class specifiers can appear in the decl-specifier-seq s of the following declarations:

Anonymous unions can also be declared with static.

Static storage duration

A variable satisfying all following conditions have static storage duration :

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

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

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

Dynamic storage duration

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

• new expressions. The storage for such objects are allocated by allocation functions and deallocated by deallocation functions.
• Implicitly creation by other means. The storage for such objects overlap with some existing storage.
• Exception objects. The storage for such objects are 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.

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 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.

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, 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 explicitly declared extern, or
• they were previously declared and the prior declaration did not have internal linkage;

• data members of anonymous unions.

External linkage

The name can be referred to from the scopes in the other translation units. 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.

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.

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.

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

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.

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

Keywords

auto, register, static, extern, thread_local, mutable

Example

#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();
}

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

Defect reports

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

See also