ModernC++
Programming
12.TranslationUnitsI
LinkageandOneDefinitionRule
FedericoBusato
2025-04-14
TranslationUnit
HeaderFileandSourceFile
Headerfilesallowdefininginterfaces(.h,.hpp,.hxx),whilekeepingthe
implementationinseparatedsourcefiles(.c,.cpp,.cxx).
TranslationUnit
Atranslationunit(orcompilationunit)isthebasicunitofcompilationinC++.It
consistsofthecontentofasinglesourcefile,plusthecontentofanyheaderfile
directlyorindirectlyincludedbyit
Asingletranslationunitcanbecompiledintoanobjectfile,library,orexecutable
program
6/54
CompileProcess
7/54
LocalandGlobalScope
Scope
Thescopeofavariable/function/objectistheregionofthecodewithintheentity
canbeaccessed
LocalScope/BlockScope
Entitiesthataredeclaredinsideafunctionorablockarecalledlocalvariables.
Theirmemoryaddressisnotvalidoutsidetheirscope
GlobalScope/FileScope/NamespaceScope
Entitiesthataredefinedoutsideallfunctions.
Theyholdasinglememorylocationthroughoutthelife-timeoftheprogram
8/54
LocalandGlobalScope
intvar1;//globalscope
intf(){
intvar2;//localscope
}
structA{
intvar3;//dependsonwheretheinstanceof'A'isused
};
9/54
Linkage
Linkage
Linkagereferstothevisibilityofsymbolstothelinker
NoLinkage
Nolinkagereferstosymbolsinthelocalscopeofdeclarationandnotvisibletothe
linker
InternalLinkage
Internallinkagereferstosymbolsvisibleonlyinscopeofasingletranslationunit.
Thesamesymbolnamehasadifferentmemoryaddressindistincttranslationunits
ExternalLinkage
Externallinkagereferstoentitiesthatexist(visible/accessible)outsideasingle
translationunit.Theyareaccessibleandhavethesameidenticalmemoryaddress
throughthewholeprogram,whichisthecombinationofalltranslationunits
10/54
StorageDuration1/2
StorageDuration
Thestorageduration(ordurationclass)determinesthedurationofavariable,
namelywhenitiscreatedanddestroyed
StorageDurationAllocationDeallocation
AutomaticCodeblockstartCodeblockend
StaticProgramstartProgramend
DynamicMemoryallocationMemorydeallocation
ThreadThreadstartThreadend
en.cppreference.com/w/cpp/language/storage_duration
11/54
StorageDuration2/2
•Automaticstorageduration.Localvariablestemporaryallocatedonregistersor
stack(dependingoncompiler,architecture,etc.).
Ifnotexplicitlyinitialized,theirvalueisundefined
•Staticstorageduration.Thestorageofanobjectisallocatedwhentheprogram
beginsanddeallocatedwhentheprogramends.
Ifnotexplicitlyinitialized,itiszero-initialized
•Dynamicstorageduration.Theobjectisallocatedanddeallocatedbyusing
dynamicmemoryallocationfunctions(new/delete).
Ifnotexplicitlyinitialized,itsmemorycontentisundefined
•ThreadstoragedurationC++11.Theobjectisallocatedwhenthethread
beginsanddeallocatedwhenthethreadends.Eachthreadhasitsowninstanceof
theobject
12/54
StorageDurationExamples
intv1;//staticduration
voidf(){
intv2;//automaticduration
autov3=3;//automaticduration
autoarray=newint[10];//dynamicduration(allocation)
}//array,v2,v3variablesdeallocation(fromstack)
//thememoryassociatedto"array"isnotdeallocated
intmain(){
f();
}
//mainend:v1isdeallocated
13/54
StorageClass
StorageClassSpecifier
Thestorageclassforavariabledeclarationisatypespecifierthat,togetherwith
thescope,governsitsstoragedurationandlinkage
StorageClassNotesScopeStorageDurationLinkage
nostorageclasslocalvardecl.LocalautomaticNolinkage
nostorageclassglobalvardecl.GlobalstaticExternal
staticLocalstatic
Function
Dependent
staticGlobalstaticInternal
externGlobalstaticExternal
thread_localC++11anythreadlocalany
14/54
StorageClassExamples
intv1;//nostorageclass
staticintv2=2;//staticstorageclass
externintv3;//externalstorageclass
thread_localintv4;//threadlocalstorageclass
thread_localstaticintv5;//threadlocalandstaticstorageclasses
intmain(){
intv6;//autostorageclass
autov7=3;//autostorageclass
staticintv8;//staticstorageclass
thread_localintv9;//threadlocalandautostorageclasses
autoarray=newint[10];//autostorageclass("array"variable)
}
15/54
staticKeywordforLocalVariables
staticlocalvariablesareallocatedwhentheprogrambegins,initializedwhenthe
functioniscalledthefirsttime,anddeallocatedwhentheprogramends
intf(){
staticintval=1;
val++;
returnval;
}
intmain(){
cout<<f();//print2("val"isinitialized)
cout<<f();//print3
cout<<f();//print4
}
16/54
staticKeywordforGlobalVariables
staticglobalvariablesorfunctionsarevisibleonlywithinthetranslationunitwhere
theyaredeclared→internallinkage
•Non-staticglobalvariablesorfunctionswiththesamenameindifferenttranslation
unitsproducenamecollision(ornameconflict)→multipledefinitionsatlink-time
intvar1=3;//externallinkage
//(inconflictwithvariablesinother
//translationunitswiththesamename)
staticintvar2=4;//internallinkage(visibleonlyinthe
//currenttranslationunit)
voidf1(){}//externallinkage(couldconflict)
staticvoidf2(){}//internallinkage
17/54
AnonymousNamespace1/2
Anamespacewithnoidentifieriscalledunnamed/anonymousnamespace
Entitieswithinananonymousnamespacehaveinternallinkageand,therefore,areused
fordeclaringuniqueidentifiers,visibleonlyinthesamesourcefile
Anonymousnamespacevs.globalstaticfunctions/variables:
•Entitieswithingananonymousnamespacehavethesamepropertiesofstatic
declarationsatglobalscope
•Inaddition,anonymousnamespacesallowtypedeclarationsandclassdefinitions
•Anonymousnamespacesarelessverbosethanstaticvariables/functionsbut,
entitieswithinananonymousnamespacearelessvisibleifthescopecontains
manylines
18/54
AnonymousNamespace2/2
main.cpp
#include<iostream>
namespace{//anonymous,internallinkage
voidf(){std::cout<<"main";}
usingmy_int=int;//notpossible
//with'static'
}//namespace
intmain(){
f();//print"main"
}
source.cpp
#include<iostream>
namespace{//anonymous,internallinkage
voidf(){std::cout<<"source";}
usingmy_int=unsigned;//noconflicts
}//namespace
intg(){
f();//print"source",noconflicts
}
19/54
externKeyword
externkeywordisusedtodeclaretheexistenceofglobalvariablesorfunctionsin
anothertranslationunit→externallinkage
•thevariableorfunctionmustbedefinedinoneandonlyonetranslationunit
•itisredundantforfunctions
•itisnecessaryforvariablestopreventthecompilertoassociateamemorylocation
inthecurrenttranslationunit
Note:ifthesameidentifierwithinatranslationunitappearswithbothinternalandexternal
linkage,thebehaviorisundefined
20/54
ExternalLinkageExample
intvar1=3;//externallinkage
//(inconflictwithvariablesinother
//translationunitswiththesamename)
externintvar3;//externallinkage
//(implementedinanothertranslationunit)
voidf1(){}//externallinkage(couldconflict)
externvoidf4();//externallinkage
//(implementedinanothertranslationunit)
21/54
LinkageofconstandconstexprVariables
constvariableshaveinternallinkageatglobalscope
constexprvariablesimplyconst,whichimpliesinternallinkage
note:thesamevariablehasdifferentmemoryaddressesondifferenttranslationunits(code
bloat)
constintvar1=3;//internallinkage
constexprintvar2=2;//internallinkage
staticconstintvar3=3;//internallinkage(redundant)
staticconstexprintvar4=2;//internallinkage(redundant)
intmain(){}
22/54
StaticInitializationOrderFiasco1/2
InC++,theorderinwhichglobalvariablesareinitializedatruntimeisnotdefined.
Thisintroducesasubtleproblemcalledstaticinitializationorderfiasco
source.cpp
intf(){return3;}//run-timefunction
intx=f();//run-timeevalutation
main.cpp
externintx;
inty=x;//run-timeinitialized
intmain(){
cout<<y;//print"3"or"0"dependingonthelinkingorder
}
23/54
StaticInitializationOrderFiasco2/2
source.cpp
constexprintf(){return3;}//compile-time/run-timefunction
constinitintx=f();//compile-timeinitialized(C++20)
main.cpp
constinitexternintx;//compile-timeinitialized(C++20)
inty=x;//run-timeinitialized
intmain(){
cout<<y;//print"3"!!
}
24/54
LinkageSummary1/2
NoLinkage:Localvariables,functions,classes
•staticlocalvariableaddressdependsonthelinkageofitsfunction
InternalLinkage:
(notaccessiblebyothertranslationunits,noconflicts,differentmemoryaddresses)
•GlobalVariables:
◦static
◦non-inline,non-template,non-specialized,non-externconst/constexpr
•Functions:static
•Anonymousnamespacecontent,evenstructures/classes
25/54
LinkageSummary2/2
ExternalLinkage:
(accessiblebyothertranslationunits,potentialconflicts,samememoryaddress)
•GlobalVariables:
◦nospecifier,orextern
◦template/specializedC++14(noconflictsfortemplate,seeODR)
◦inlineconst/constexprC++17(noconflicts,seeODR)
•Functions:
◦nospecifier(noconflictswithinline,seeODR),orextern
◦template/specialized(noconflictsfortemplate,seeODR)
Note:inline,constexpr(whichimpliesinlineforfunctions)functionsarenot
accessiblebyothertranslationunitsevenwithexternallinkage
•Enumerators,Classesandtheirstatic,non-staticmembers
26/54
CodeStructure1
•oneheader,twosourcefiles→twotranslationunits
•theheaderisincludedinbothtranslationunits
27/54
CodeStructure2
•twoheaders,twosourcefiles→twotranslationunits
•oneheaderfordeclarations(.hpp),andtheotheroneforimplementations
(.i.hpp)
•theheaderandtheheaderimplementationareincludedinbothtranslationunits
*separateheaderdeclarationandimplementationisnotmandatory,butitcouldhelptobetter
organizethecode
28/54
ClassinMultipleTranslationUnits1/2
header.hpp:
classA{
public:
voidf();
staticvoidg();
private:
intx;
staticinty;
};
main.cpp:
#include"header.hpp"
#include<iostream>
intmain(){
Aa;
std::cout<<a.x;//print1
std::cout<<A::y;//print2
}
source.cpp:
#include"header.hpp"
voidA::f(){}
voidA::g(){}
intA::y=2;
//intA::x=1;//non-staticdatamember
//cannotbedefinedout-of-line
29/54
ClassinMultipleTranslationUnits2/2
header.hpp:
structA{
staticinty1;//zero-init
//staticinty2=3;//compileerror
//mustbeinitializedout-of-class
inlinestaticinty3=4;//inlineinitialization(C++17)
constintz=3;//C++11andlater
//constintz;//compileerror
//mustbeinitialized
staticconstintw1;//zero-init
staticconstintw2=4;//inline-init
};
source.cpp:
#include"header.hpp"
intA::y1=2;
constintA::w1=3;
30/54
OneDefinitionRule(ODR)
(1)Inany(single)translationunit,atemplate,type,function,orobject,cannot
havemorethanonedefinition
-Compilererrorotherwise
-Anynumberofdeclarationsareallowed
(2)Intheentireprogram,anobjectornon-inlinefunctioncannothavemore
thanonedefinition
-Multipledefinitionslinkingerrorotherwise
-Entitieswithinternallinkageindifferenttranslationunitsareallowed,eveniftheir
namesandtypesarethesame
(3)Atemplate,type,orinlinefunctions/variables,canbedefinedinmorethan
onetranslationunit.Foragivenentity,eachdefinitionmustbethesame
-Undefinedbehaviorotherwise
-Commoncase:sameheaderincludedinmultipletranslationunits
31/54
ODR-Point(1),(2)
header.hpp:
voidf();//DECLARATION
main.cpp:
#include"header.hpp"
#include<iostream>
inta=1;//externallinkage
//inta=7;//compilererror,Point(1)
externintb;
staticintc=2;//internallinkage
intmain(){
std::cout<<a;//print1
std::cout<<b;//print5
std::cout<<c;//print2
f();
}
source.cpp:
#include"header.hpp"
#include<iostream>
//linkingerror,multipledefinitions
//inta=2;//Point(2)
intb=5;//ok
//internallinkage
staticintc=4;//ok
voidf(){//DEFINITION
//std::cout<<a;//'a'isnotvisible
std::cout<<b;//print5
std::cout<<c;//print4
}
32/54
GlobalVariableIssues-ODRPoint(2)
header.hpp:
#include<iostream>
structA{
A(){std::cout<<"A()";}
∼A(){std::cout<<"∼A()";}
};
//Aobj;//linkingerrormultipledefinitions,Point(2)
constAconst_obj{};//"const/constexpr"impliesinternallinkage
constexprfloatPI=3.14f;
source1.cpp:
#include"header.hpp"
voidf(){std::cout<<&PI;}
//address:0x1234ABCD
//print"A()"thefirsttime
//print"∼A()"thefirsttime
source2.cpp:
#include"header.hpp"
voidf(){std::cout<<&PI;}
//printaddress:0x3820FDAC!!
//print"A()"thesecondtime!!
//print"∼A()"thesecondtime!!
33/54
CommonClassError-ODRPoint(2)
header.hpp:
structA{
voidf(){};//inlineDEFINITION
voidg();//DECLARATION
voidh();//DECLARATION
};
voidA::g(){}//DEFINITION
main.cpp:
#include"header.hpp"
//linkingerror
//multipledefinitionsofA::g()
intmain(){}
source.cpp:
#include"header.hpp"
//linkingerror
//multipledefinitionsofA::g()
voidA::h(){}//DEFINITION,ok
34/54
ODR-Point(3)
ODRPoint(3):Atemplate,type,orinlinefunctions/variables,canbe
definedinmorethanonetranslationunit
•Thelinkerremovesalldefinitionsofaninline/templateentityexceptone
•Alldefinitionsmustbeidenticaltoavoidundefinedbehaviorduetoarbitrary
linkingorder
•inline/templateentitieshaveauniquememoryaddressacrossalltranslation
units
•inline/templateentitieshavethesamelinkageasthecorresponding
variables/functionswithoutthespecifier
35/54
inlineFunctions/Variables1/2
inline
inlinespecifierallowsafunctionoravariable(inC++17)tobeidentically
defined(notonlydeclared)inmultipletranslationunits
•inlineisoneofthemostmisunderstoodfeaturesofC++
•inlineisahintforthelinker.Withoutit,thelinkercanemit“multiple
definitions”error
•inlineentitiescannotbeexported,namely,usedbyothertranslationunitseven
iftheyhaveexternallinkage(relatedwarning:-Wundefined-inline)
•inlinedoesn’tmeanthatthecompilerisforcedtoperformfunctioninlining.It
justincreasestheoptimizationheuristicthreshold
36/54
inlineFunctions/Variables2/2
voidf(){}
inlinevoidg(){}
f():
•Cannotbedefinedinaheaderincludedinmultiplesourcefiles
•Thelinkerissuesa“multipledefinitions”error
g():
•Canbedefinedinaheaderandincludedinmultiplesourcefiles
37/54
constexprandinline
constexprfunctionsareimplicitlyinline
constexprvariablesarenotimplicitlyinline.C++17addedinlinevariables
voidf1(){}//externallinkage
//potentialmultipledefinitionserror
constexprvoidf2(){}//externallinkage,implicitlyinline
//multipledefinitionsallowed
constexprintx=3;//
internallinkage
//differentfilesallowsdistinctdefinitions
//->differentaddresses,codebloat
inlineconstexprinty=3;//externallinkageuniquememoryaddress
//->potentialundefinedbehavior
intmain(){}
38/54
OneDefinitionRule-Point(3)1/2
header.hpp:
inlinevoidf(){}//thefunctionismarked'inline'(nolinkingerror)
inlineintv=3;//thevariableismarked'inline'(nolinkingerror)(C++17)
template<typenameT>
voidg(Tx){}//thefunctionisatemplate(nolinkingerror)
usingvar_t=int;//typescanbedefinedmultipletimes(nolinkingerror)
main.cpp:
#include"header.hpp"
intmain(){
f();
g(3);//g<int>generated
}
source.cpp:
#include"header.hpp"
voidh(){
f();
g(5);//g<int>generated
}
39/54
OneDefinitionRule-Point(3)2/2
Alternativeorganization:
header.hpp:
inlinevoidf();//DECLARATION
inlineintv;//DECLARATION
template<typenameT>
voidg(Tx);//DECLARATION
usingvar_t=int;//type
#include"header.i.hpp"
header.i.hpp:
voidf(){}//DEFINITION
intv=3;//DEFINITION
template<typenameT>
voidg(Tx){}//DEFINITION
main.cpp:
#include"header.hpp"
intmain(){
f();
g(3);//g<int>generated
}
source.cpp:
#include"header.hpp"
voidh(){
f();
g(5);//g<int>generated
}
40/54
FunctionTemplate-Case1
header.hpp:
template<typenameT>
voidf(Tx){};//DECLARATIONandDEFINITION
main.cpp:
#include"header.hpp"
intmain(){
f(3);//callf<int>()
f(3.3f);//callf<float>()
f('a');//callf<char>()
}
source.cpp:
#include"header.hpp"
voidh(){
f(3);//callf<int>()
f(3.3f);//callf<float>()
f('a');//callf<char>()
}
f<int>(),f<float>(),f<char>()aregeneratedtwotimes(inbothtranslationunits)
41/54
FunctionTemplate-Case2
header.hpp:
template<typenameT>
voidf(Tx);//DECLARATION
main.cpp:
#include"header.hpp"
intmain(){
f(3);//callf<int>()
f(3.3f);//callf<float>()
//f('a');//linkingerror
}//thespecializationdoesnotexist
source.cpp:
#include"header.hpp"
template<typenameT>
voidf(Tx){}//DEFINITION
//templateINSTANTIATION
templatevoidf<int>(int);
templatevoidf<float>(float);
//anyexplicitinstanceisalso
//fine,e.g.f<int>(3)
42/54
FunctionTemplateandSpecialization
header.hpp:
template<typenameT>
voidf(){}//DECLARATIONandDEFINITION
main.cpp:
#include"header.hpp"
intmain(){
f<char>();//usethegenericfunction
f<int>();//usethespecialization
}
source.cpp:
#include"header.hpp"
template<>
voidf<int>(){}//SPECIALIZATION
//DEFINITION
43/54
FunctionTemplate-externKeyword
C++11
header.hpp:
template<typenameT>
voidf(){}//DECLARATIONandDEFINITION
main.cpp:
#include"header.hpp"
externtemplatevoidf<int>();
//f<int>()isnotgeneratedbythe
//compilerinthistranslationunit
intmain(){
f<int>();
}
source.cpp:
#include"header.hpp"
voidg(){
f<int>();
}
//or'templatevoidf<int>();'
44/54
ODRFunctionTemplateCommonError
header.hpp:
template<typenameT>
voidf();//DECLARATION
//template<>//linkingerror
//voidf<int>(){}//multipledefinitions->includedtwice
//fullspecializationsarelikestandardfunctions
//itcanbesolvedbyadding"inline"
main.cpp:
#include"header.hpp"
intmain(){}
source.cpp:
#include"header.hpp"
//somecode
45/54
ClassTemplate-Case1
header.hpp:
template<typenameT>
structA{
Tx=3;//"inline"DEFINITION
staticinlineTy=3;//"inline"DEFINITION(C++17)
voidf(){};//"inline"DEFINITION
};
main.cpp:
#include"header.hpp"
intmain(){
A<int>a1;//ok
A<float>a2;//ok
A<char>a3;//ok
}
source.cpp:
#include"header.hpp"
intg(){
A<int>a1;//ok
A<float>a2;//ok
A<char>a3;//ok
}
46/54
ClassTemplate-Case2
header.hpp:
template<typenameT>
structA{
staticTx;
voidf();//DECLARATION
};
#include"header.i.hpp"
header.i.hpp:
template<typenameT>
TA<T>::x=3;//DEFINITION
template<typenameT>
voidA<T>::f(){}//DEFINITION
main.cpp:
#include"header.hpp"
intmain(){
A<int>a1;//ok
A<float>a2;//ok
A<char>a3;//ok
}
source.cpp:
#include"header.hpp"
intg(){
A<int>a1;//ok
A<float>a2;//ok
A<char>a3;//ok
}
47/54
ClassTemplate-Case3
header.hpp:
template<typenameT>
structA{
staticTx;
voidf();//DECLARATION
};
main.cpp:
#include"header.hpp"
intmain(){
A<int>a1;//ok
//A<char>a2;//linkingerror
}//'f()'isundefined
//while'x'hasanundefined
//valueforA<char>
source.cpp:
#include"header.hpp"
template<typenameT>
intA<T>::x=3;//initialization
template<typenameT>
voidA<T>::f(){}//DEFINITION
//templateINSTANTIATION
templateclassA<int>;
48/54
ClassTemplate-externKeyword
C++11
header.hpp:
template<typenameT>
structA{
Tx;
voidf(){}
};
source.cpp:
#include"header.hpp"
externtemplateclassA<int>;
//A<int>isnotgeneratedbythe
//compilerinthistranslationunit
intmain(){
A<int>a;
}
source.cpp:
#include"header.hpp"
//templateINSTANTIATION
templateclassA<int>;
//oranyinstantiationofA<int>
49/54
UndefinedBehavior-inlineFunction
main.cpp:
#include<iostream>
inlineintf(){return3;}
voidg();
intmain(){
std::cout<<f();//print3
std::cout<<g();//print3!!
}//not5
source.cpp:
//samesignatureandinline
inlineintf(){return5;}
intg(){returnf();}
Thelinkercanarbitrarychooseoneofthetwodefinitionsoff().With-O3,the
compilercouldinlinef()ing(),sonowg()return5
Thisissueiseasytodetectintrivialexamplesbuthardtofindinlargecodebase
Solution:staticoranonymousnamespace
50/54
UndefinedBehavior-MemberFunction
header.hpp:
#include<iostream>
structA{
intf(){return3;}
};
intg();
main.cpp:
#include"header.hpp"
intmain(){
Aa;
std::cout<<a.f();//print3
std::cout<<g();//print3!!
}
source.cpp:
structA{
intf(){return5;}
};
intg(){
Aa;
returna.f();
}
51/54
UndefinedBehavior-FunctionTemplate
header.hpp:
template<typenameT>
intf(){
return3;
}
intg();
main.cpp:
#include"header.hpp"
intmain(){
std::cout<<f<int>();//print3
std::cout<<g();//print3!!
}
source.cpp:
template<typenameT>
intf(){
return5;
}
intg(){
returnf<int>();
}
52/54
UndefinedBehavior
OtherODRviolationsareevenharder(ifnotimpossible)tofind,seeDiagnosing
HiddenODRViolationsinVisualC++
SometoolsforpartiallydetectingODRviolations:
•-detect-odr-violationsflagforgold/llvmlinker
•-Wodr-fltoflagforGCC
•Clangaddresssanitizer+ASAN_OPTIONS=detect_odr_violation=2
(link)
Anothersolutioncouldbeincludedallfilesinasingletranslationunit
53/54
ODR-DeclarationsandDefinitionsSummary
•Header:declarationof
-functions,structures,classes,types,alias
-templatefunctions,structs,classes
-externvariables,functions
•Header(implementation):definitionof
-inlinevariables/functions
-templatevariables/functions/classes
-globalstatic,non-static
const/constexprvariablesandconstexpr
functions
•Sourcefile:definitionof
-functions,includingtemplatefullspecializations
-classes
-externandstaticglobalvariables/functions
54/54