1This is libitm.info, produced by makeinfo version 5.1 from libitm.texi. 2 3Copyright (C) 2011-2020 Free Software Foundation, Inc. 4 5 Permission is granted to copy, distribute and/or modify this document 6under the terms of the GNU Free Documentation License, Version 1.2 or 7any later version published by the Free Software Foundation; with no 8Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts. A 9copy of the license is included in the section entitled "GNU Free 10Documentation License". 11INFO-DIR-SECTION GNU Libraries 12START-INFO-DIR-ENTRY 13* libitm: (libitm). GNU Transactional Memory Library 14END-INFO-DIR-ENTRY 15 16 This manual documents the GNU Transactional Memory Library. 17 18 Copyright (C) 2011-2020 Free Software Foundation, Inc. 19 20 Permission is granted to copy, distribute and/or modify this document 21under the terms of the GNU Free Documentation License, Version 1.2 or 22any later version published by the Free Software Foundation; with no 23Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts. A 24copy of the license is included in the section entitled "GNU Free 25Documentation License". 26 27 28File: libitm.info, Node: Top, Next: Enabling libitm, Up: (dir) 29 30Introduction 31************ 32 33This manual documents the usage and internals of libitm, the GNU 34Transactional Memory Library. It provides transaction support for 35accesses to a process' memory, enabling easy-to-use synchronization of 36accesses to shared memory by several threads. 37 38* Menu: 39 40* Enabling libitm:: How to enable libitm for your applications. 41* C/C++ Language Constructs for TM:: 42 Notes on the language-level interface supported 43 by gcc. 44* The libitm ABI:: Notes on the external ABI provided by libitm. 45* Internals:: Notes on libitm's internal synchronization. 46* GNU Free Documentation License:: 47 How you can copy and share this manual. 48* Library Index:: Index of this documentation. 49 50 51File: libitm.info, Node: Enabling libitm, Next: C/C++ Language Constructs for TM, Prev: Top, Up: Top 52 531 Enabling libitm 54***************** 55 56To activate support for TM in C/C++, the compile-time flag '-fgnu-tm' 57must be specified. This enables TM language-level constructs such as 58transaction statements (e.g., '__transaction_atomic', *note C/C++ 59Language Constructs for TM:: for details). 60 61 62File: libitm.info, Node: C/C++ Language Constructs for TM, Next: The libitm ABI, Prev: Enabling libitm, Up: Top 63 642 C/C++ Language Constructs for TM 65********************************** 66 67Transactions are supported in C++ and C in the form of transaction 68statements, transaction expressions, and function transactions. In the 69following example, both 'a' and 'b' will be read and the difference will 70be written to 'c', all atomically and isolated from other transactions: 71 72 __transaction_atomic { c = a - b; } 73 74 Therefore, another thread can use the following code to concurrently 75update 'b' without ever causing 'c' to hold a negative value (and 76without having to use other synchronization constructs such as locks or 77C++11 atomics): 78 79 __transaction_atomic { if (a > b) b++; } 80 81 GCC follows the Draft Specification of Transactional Language 82Constructs for C++ (v1.1) 83(https://sites.google.com/site/tmforcplusplus/) in its implementation of 84transactions. 85 86 The precise semantics of transactions are defined in terms of the 87C++11/C11 memory model (see the specification). Roughly, transactions 88provide synchronization guarantees that are similar to what would be 89guaranteed when using a single global lock as a guard for all 90transactions. Note that like other synchronization constructs in C/C++, 91transactions rely on a data-race-free program (e.g., a nontransactional 92write that is concurrent with a transactional read to the same memory 93location is a data race). 94 95 96File: libitm.info, Node: The libitm ABI, Next: Internals, Prev: C/C++ Language Constructs for TM, Up: Top 97 983 The libitm ABI 99**************** 100 101The ABI provided by libitm is basically equal to the Linux variant of 102Intel's current TM ABI specification document (Revision 1.1, May 6 2009) 103but with the differences listed in this chapter. It would be good if 104these changes would eventually be merged into a future version of this 105specification. To ease look-up, the following subsections mirror the 106structure of this specification. 107 1083.1 [No changes] Objectives 109=========================== 110 1113.2 [No changes] Non-objectives 112=============================== 113 1143.3 Library design principles 115============================= 116 1173.3.1 [No changes] Calling conventions 118-------------------------------------- 119 1203.3.2 [No changes] TM library algorithms 121---------------------------------------- 122 1233.3.3 [No changes] Optimized load and store routines 124---------------------------------------------------- 125 1263.3.4 [No changes] Aligned load and store routines 127-------------------------------------------------- 128 1293.3.5 Data logging functions 130---------------------------- 131 132The memory locations accessed with transactional loads and stores and 133the memory locations whose values are logged must not overlap. This 134required separation only extends to the scope of the execution of one 135transaction including all the executions of all nested transactions. 136 137 The compiler must be consistent (within the scope of a single 138transaction) about which memory locations are shared and which are not 139shared with other threads (i.e., data must be accessed either 140transactionally or nontransactionally). Otherwise, non-write-through TM 141algorithms would not work. 142 143 For memory locations on the stack, this requirement extends to only 144the lifetime of the stack frame that the memory location belongs to (or 145the lifetime of the transaction, whichever is shorter). Thus, memory 146that is reused for several stack frames could be target of both data 147logging and transactional accesses; however, this is harmless because 148these stack frames' lifetimes will end before the transaction finishes. 149 1503.3.6 [No changes] Scatter/gather calls 151--------------------------------------- 152 1533.3.7 [No changes] Serial and irrevocable mode 154---------------------------------------------- 155 1563.3.8 [No changes] Transaction descriptor 157----------------------------------------- 158 1593.3.9 Store allocation 160---------------------- 161 162There is no 'getTransaction' function. 163 1643.3.10 [No changes] Naming conventions 165-------------------------------------- 166 1673.3.11 Function pointer encryption 168---------------------------------- 169 170Currently, this is not implemented. 171 1723.4 Types and macros list 173========================= 174 175'_ITM_codeProperties' has changed, *note Starting a transaction: 176txn-code-properties. '_ITM_srcLocation' is not used. 177 1783.5 Function list 179================= 180 1813.5.1 Initialization and finalization functions 182----------------------------------------------- 183 184These functions are not part of the ABI. 185 1863.5.2 [No changes] Version checking 187----------------------------------- 188 1893.5.3 [No changes] Error reporting 190---------------------------------- 191 1923.5.4 [No changes] inTransaction call 193------------------------------------- 194 1953.5.5 State manipulation functions 196---------------------------------- 197 198There is no 'getTransaction' function. Transaction identifiers for 199nested transactions will be ordered but not necessarily sequential 200(i.e., for a nested transaction's identifier IN and its enclosing 201transaction's identifier IE, it is guaranteed that IN >= IE). 202 2033.5.6 [No changes] Source locations 204----------------------------------- 205 2063.5.7 Starting a transaction 207---------------------------- 208 2093.5.7.1 Transaction code properties 210................................... 211 212The bit 'hasNoXMMUpdate' is instead called 'hasNoVectorUpdate'. Iff it 213is set, vector register save/restore is not necessary for any target 214machine. 215 216 The 'hasNoFloatUpdate' bit ('0x0010') is new. Iff it is set, 217floating point register save/restore is not necessary for any target 218machine. 219 220 'undoLogCode' is not supported and a fatal runtime error will be 221raised if this bit is set. It is not properly defined in the ABI why 222barriers other than undo logging are not present; Are they not necessary 223(e.g., a transaction operating purely on thread-local data) or have they 224been omitted by the compiler because it thinks that some kind of global 225synchronization (e.g., serial mode) might perform better? The 226specification suggests that the latter might be the case, but the former 227seems to be more useful. 228 229 The 'readOnly' bit ('0x4000') is new. *TODO* Lexical or dynamic 230scope? 231 232 'hasNoRetry' is not supported. If this bit is not set, but 233'hasNoAbort' is set, the library can assume that transaction rollback 234will not be requested. 235 236 It would be useful if the absence of externally-triggered rollbacks 237would be reported for the dynamic scope as well, not just for the 238lexical scope ('hasNoAbort'). Without this, a library cannot exploit 239this together with flat nesting. 240 241 'exceptionBlock' is not supported because exception blocks are not 242used. 243 2443.5.7.2 [No changes] Windows exception state 245............................................ 246 2473.5.7.3 [No changes] Other machine state 248........................................ 249 2503.5.7.4 [No changes] Results from beginTransaction 251.................................................. 252 2533.5.8 Aborting a transaction 254---------------------------- 255 256'_ITM_rollbackTransaction' is not supported. '_ITM_abortTransaction' is 257supported but the abort reasons 'exceptionBlockAbort', 'TMConflict', and 258'userRetry' are not supported. There are no exception blocks in 259general, so the related cases also do not have to be considered. To 260encode '__transaction_cancel [[outer]]', compilers must set the new 261'outerAbort' bit ('0x10') additionally to the 'userAbort' bit in the 262abort reason. 263 2643.5.9 Committing a transaction 265------------------------------ 266 267The exception handling (EH) scheme is different. The Intel ABI requires 268the '_ITM_tryCommitTransaction' function that will return even when the 269commit failed and will have to be matched with calls to either 270'_ITM_abortTransaction' or '_ITM_commitTransaction'. In contrast, gcc 271relies on transactional wrappers for the functions of the Exception 272Handling ABI and on one additional commit function (shown below). This 273allows the TM to keep track of EH internally and thus it does not have 274to embed the cleanup of EH state into the existing EH code in the 275program. '_ITM_tryCommitTransaction' is not supported. 276'_ITM_commitTransactionToId' is also not supported because the 277propagation of thrown exceptions will not bypass commits of nested 278transactions. 279 280 void _ITM_commitTransactionEH(void *exc_ptr) ITM_REGPARM; 281 void *_ITM_cxa_allocate_exception (size_t); 282 void _ITM_cxa_free_exception (void *exc_ptr); 283 void _ITM_cxa_throw (void *obj, void *tinfo, void (*dest) (void *)); 284 void *_ITM_cxa_begin_catch (void *exc_ptr); 285 void _ITM_cxa_end_catch (void); 286 287 The EH scheme changed in version 6 of GCC. Previously, the compiler 288added a call to '_ITM_commitTransactionEH' to commit a transaction if an 289exception could be in flight at this position in the code; 'exc_ptr' is 290the address of the current exception and must be non-zero. Now, the 291compiler must catch all exceptions that are about to be thrown out of a 292transaction and call '_ITM_commitTransactionEH' from the catch clause, 293with 'exc_ptr' being zero. 294 295 Note that the old EH scheme never worked completely in GCC's 296implementation; libitm currently does not try to be compatible with the 297old scheme. 298 299 The '_ITM_cxa...' functions are transactional wrappers for the 300respective '__cxa...' functions and must be called instead of these in 301transactional code. '_ITM_cxa_free_exception' is new in GCC 6. 302 303 To support this EH scheme, libstdc++ needs to provide one additional 304function ('_cxa_tm_cleanup'), which is used by the TM to clean up the 305exception handling state while rolling back a transaction: 306 307 void __cxa_tm_cleanup (void *unthrown_obj, void *cleanup_exc, 308 unsigned int caught_count); 309 310 Since GCC 6, 'unthrown_obj' is not used anymore and always null; 311prior to that, 'unthrown_obj' is non-null if the program called 312'__cxa_allocate_exception' for this exception but did not yet called 313'__cxa_throw' for it. 'cleanup_exc' is non-null if the program is 314currently processing a cleanup along an exception path but has not 315caught this exception yet. 'caught_count' is the nesting depth of 316'__cxa_begin_catch' within the transaction (which can be counted by the 317TM using '_ITM_cxa_begin_catch' and '_ITM_cxa_end_catch'); 318'__cxa_tm_cleanup' then performs rollback by essentially performing 319'__cxa_end_catch' that many times. 320 3213.5.10 Exception handling support 322--------------------------------- 323 324Currently, there is no support for functionality like 325'__transaction_cancel throw' as described in the C++ TM specification. 326Supporting this should be possible with the EH scheme explained 327previously because via the transactional wrappers for the EH ABI, the TM 328is able to observe and intercept EH. 329 3303.5.11 [No changes] Transition to serial-irrevocable mode 331--------------------------------------------------------- 332 3333.5.12 [No changes] Data transfer functions 334------------------------------------------- 335 3363.5.13 [No changes] Transactional memory copies 337----------------------------------------------- 338 3393.5.14 Transactional versions of memmove 340---------------------------------------- 341 342If either the source or destination memory region is to be accessed 343nontransactionally, then source and destination regions must not be 344overlapping. The respective '_ITM_memmove' functions are still 345available but a fatal runtime error will be raised if such regions do 346overlap. To support this functionality, the ABI would have to specify 347how the intersection of the regions has to be accessed (i.e., 348transactionally or nontransactionally). 349 3503.5.15 [No changes] Transactional versions of memset 351---------------------------------------------------- 352 3533.5.16 [No changes] Logging functions 354------------------------------------- 355 3563.5.17 User-registered commit and undo actions 357---------------------------------------------- 358 359Commit actions will get executed in the same order in which the 360respective calls to '_ITM_addUserCommitAction' happened. Only 361'_ITM_noTransactionId' is allowed as value for the 362'resumingTransactionId' argument. Commit actions get executed after 363privatization safety has been ensured. 364 365 Undo actions will get executed in reverse order compared to the order 366in which the respective calls to '_ITM_addUserUndoAction' happened. The 367ordering of undo actions w.r.t. the roll-back of other actions (e.g., 368data transfers or memory allocations) is undefined. 369 370 '_ITM_getThreadnum' is not supported currently because its only 371purpose is to provide a thread ID that matches some assumed performance 372tuning output, but this output is not part of the ABI nor further 373defined by it. 374 375 '_ITM_dropReferences' is not supported currently because its 376semantics and the intention behind it is not entirely clear. The 377specification suggests that this function is necessary because of 378certain orderings of data transfer undos and the releasing of memory 379regions (i.e., privatization). However, this ordering is never defined, 380nor is the ordering of dropping references w.r.t. other events. 381 3823.5.18 [New] Transactional indirect calls 383----------------------------------------- 384 385Indirect calls (i.e., calls through a function pointer) within 386transactions should execute the transactional clone of the original 387function (i.e., a clone of the original that has been fully instrumented 388to use the TM runtime), if such a clone is available. The runtime 389provides two functions to register/deregister clone tables: 390 391 struct clone_entry 392 { 393 void *orig, *clone; 394 }; 395 396 void _ITM_registerTMCloneTable (clone_entry *table, size_t entries); 397 void _ITM_deregisterTMCloneTable (clone_entry *table); 398 399 Registered tables must be writable by the TM runtime, and must be 400live throughout the life-time of the TM runtime. 401 402 *TODO* The intention was always to drop the registration functions 403entirely, and create a new ELF Phdr describing the linker-sorted table. 404Much like what currently happens for 'PT_GNU_EH_FRAME'. This work kept 405getting bogged down in how to represent the N different code generation 406variants. We clearly needed at least two--SW and HW transactional 407clones--but there was always a suggestion of more variants for different 408TM assumptions/invariants. 409 410 The compiler can then use two TM runtime functions to perform 411indirect calls in transactions: 412 void *_ITM_getTMCloneOrIrrevocable (void *function) ITM_REGPARM; 413 void *_ITM_getTMCloneSafe (void *function) ITM_REGPARM; 414 415 If there is a registered clone for supplied function, both will 416return a pointer to the clone. If not, the first runtime function will 417attempt to switch to serial-irrevocable mode and return the original 418pointer, whereas the second will raise a fatal runtime error. 419 4203.5.19 [New] Transactional dynamic memory management 421---------------------------------------------------- 422 423 void *_ITM_malloc (size_t) 424 __attribute__((__malloc__)) ITM_PURE; 425 void *_ITM_calloc (size_t, size_t) 426 __attribute__((__malloc__)) ITM_PURE; 427 void _ITM_free (void *) ITM_PURE; 428 429 These functions are essentially transactional wrappers for 'malloc', 430'calloc', and 'free'. Within transactions, the compiler should replace 431calls to the original functions with calls to the wrapper functions. 432 433 libitm also provides transactional clones of C++ memory management 434functions such as global operator new and delete. They are part of 435libitm for historic reasons but do not need to be part of this ABI. 436 4373.6 [No changes] Future Enhancements to the ABI 438=============================================== 439 4403.7 Sample code 441=============== 442 443The code examples might not be correct w.r.t. the current version of 444the ABI, especially everything related to exception handling. 445 4463.8 [New] Memory model 447====================== 448 449The ABI should define a memory model and the ordering that is guaranteed 450for data transfers and commit/undo actions, or at least refer to another 451memory model that needs to be preserved. Without that, the compiler 452cannot ensure the memory model specified on the level of the programming 453language (e.g., by the C++ TM specification). 454 455 For example, if a transactional load is ordered before another 456load/store, then the TM runtime must also ensure this ordering when 457accessing shared state. If not, this might break the kind of 458publication safety used in the C++ TM specification. Likewise, the TM 459runtime must ensure privatization safety. 460 461 462File: libitm.info, Node: Internals, Next: GNU Free Documentation License, Prev: The libitm ABI, Up: Top 463 4644 Internals 465*********** 466 4674.1 TM methods and method groups 468================================ 469 470libitm supports several ways of synchronizing transactions with each 471other. These TM methods (or TM algorithms) are implemented in the form 472of subclasses of 'abi_dispatch', which provide methods for transactional 473loads and stores as well as callbacks for rollback and commit. All 474methods that are compatible with each other (i.e., that let concurrently 475running transactions still synchronize correctly even if different 476methods are used) belong to the same TM method group. Pointers to TM 477methods can be obtained using the factory methods prefixed with 478'dispatch_' in 'libitm_i.h'. There are two special methods, 479'dispatch_serial' and 'dispatch_serialirr', that are compatible with all 480methods because they run transactions completely in serial mode. 481 4824.1.1 TM method life cycle 483-------------------------- 484 485The state of TM methods does not change after construction, but they do 486alter the state of transactions that use this method. However, because 487per-transaction data gets used by several methods, 'gtm_thread' is 488responsible for setting an initial state that is useful for all methods. 489After that, methods are responsible for resetting/clearing this state on 490each rollback or commit (of outermost transactions), so that the 491transaction executed next is not affected by the previous transaction. 492 493 There is also global state associated with each method group, which 494is initialized and shut down ('method_group::init()' and 'fini()') when 495switching between method groups (see 'retry.cc'). 496 4974.1.2 Selecting the default method 498---------------------------------- 499 500The default method that libitm uses for freshly started transactions 501(but not necessarily for restarted transactions) can be set via an 502environment variable ('ITM_DEFAULT_METHOD'), whose value should be equal 503to the name of one of the factory methods returning abi_dispatch 504subclasses but without the "dispatch_" prefix (e.g., "serialirr" instead 505of 'GTM::dispatch_serialirr()'). 506 507 Note that this environment variable is only a hint for libitm and 508might not be supported in the future. 509 5104.2 Nesting: flat vs. closed 511============================ 512 513We support two different kinds of nesting of transactions. In the case 514of _flat nesting_, the nesting structure is flattened and all nested 515transactions are subsumed by the enclosing transaction. In contrast, 516with _closed nesting_, nested transactions that have not yet committed 517can be rolled back separately from the enclosing transactions; when they 518commit, they are subsumed by the enclosing transaction, and their 519effects will be finally committed when the outermost transaction 520commits. _Open nesting_ (where nested transactions can commit 521independently of the enclosing transactions) are not supported. 522 523 Flat nesting is the default nesting mode, but closed nesting is 524supported and used when transactions contain user-controlled aborts 525('__transaction_cancel' statements). We assume that user-controlled 526aborts are rare in typical code and used mostly in exceptional 527situations. Thus, it makes more sense to use flat nesting by default to 528avoid the performance overhead of the additional checkpoints required 529for closed nesting. User-controlled aborts will correctly abort the 530innermost enclosing transaction, whereas the whole (i.e., outermost) 531transaction will be restarted otherwise (e.g., when a transaction 532encounters data conflicts during optimistic execution). 533 5344.3 Locking conventions 535======================= 536 537This section documents the locking scheme and rules for all uses of 538locking in libitm. We have to support serial(-irrevocable) mode, which 539is implemented using a global lock as explained next (called the _serial 540lock_). To simplify the overall design, we use the same lock as 541catch-all locking mechanism for other infrequent tasks such as 542(de)registering clone tables or threads. Besides the serial lock, there 543are _per-method-group locks_ that are managed by specific method groups 544(i.e., groups of similar TM concurrency control algorithms), and 545lock-like constructs for quiescence-based operations such as ensuring 546privatization safety. 547 548 Thus, the actions that participate in the libitm-internal locking are 549either _active transactions_ that do not run in serial mode, _serial 550transactions_ (which (are about to) run in serial mode), and management 551tasks that do not execute within a transaction but have acquired the 552serial mode like a serial transaction would do (e.g., to be able to 553register threads with libitm). Transactions become active as soon as 554they have successfully used the serial lock to announce this globally 555(*note Serial lock implementation: serial-lock-impl.). Likewise, 556transactions become serial transactions as soon as they have acquired 557the exclusive rights provided by the serial lock (i.e., serial mode, 558which also means that there are no other concurrent active or serial 559transactions). Note that active transactions can become serial 560transactions when they enter serial mode during the runtime of the 561transaction. 562 5634.3.1 State-to-lock mapping 564--------------------------- 565 566Application data is protected by the serial lock if there is a serial 567transaction and no concurrently running active transaction (i.e., 568non-serial). Otherwise, application data is protected by the currently 569selected method group, which might use per-method-group locks or other 570mechanisms. Also note that application data that is about to be 571privatized might not be allowed to be accessed by nontransactional code 572until privatization safety has been ensured; the details of this are 573handled by the current method group. 574 575 libitm-internal state is either protected by the serial lock or 576accessed through custom concurrent code. The latter applies to the 577public/shared part of a transaction object and most typical 578method-group-specific state. 579 580 The former category (protected by the serial lock) includes: 581 * The list of active threads that have used transactions. 582 * The tables that map functions to their transactional clones. 583 * The current selection of which method group to use. 584 * Some method-group-specific data, or invariants of this data. For 585 example, resetting a method group to its initial state is handled 586 by switching to the same method group, so the serial lock protects 587 such resetting as well. 588 In general, such state is immutable whenever there exists an active 589(non-serial) transaction. If there is no active transaction, a serial 590transaction (or a thread that is not currently executing a transaction 591but has acquired the serial lock) is allowed to modify this state (but 592must of course be careful to not surprise the current method group's 593implementation with such modifications). 594 5954.3.2 Lock acquisition order 596---------------------------- 597 598To prevent deadlocks, locks acquisition must happen in a globally 599agreed-upon order. Note that this applies to other forms of blocking 600too, but does not necessarily apply to lock acquisitions that do not 601block (e.g., trylock() calls that do not get retried forever). Note 602that serial transactions are never return back to active transactions 603until the transaction has committed. Likewise, active transactions stay 604active until they have committed. Per-method-group locks are typically 605also not released before commit. 606 607 Lock acquisition / blocking rules: 608 609 * Transactions must become active or serial before they are allowed 610 to use method-group-specific locks or blocking (i.e., the serial 611 lock must be acquired before those other locks, either in serial or 612 nonserial mode). 613 614 * Any number of threads that do not currently run active transactions 615 can block while trying to get the serial lock in exclusive mode. 616 Note that active transactions must not block when trying to upgrade 617 to serial mode unless there is no other transaction that is trying 618 that (the latter is ensured by the serial lock implementation. 619 620 * Method groups must prevent deadlocks on their locks. In 621 particular, they must also be prepared for another active 622 transaction that has acquired method-group-specific locks but is 623 blocked during an attempt to upgrade to being a serial transaction. 624 See below for details. 625 626 * Serial transactions can acquire method-group-specific locks because 627 there will be no other active nor serial transaction. 628 629 There is no single rule for per-method-group blocking because this 630depends on when a TM method might acquire locks. If no active 631transaction can upgrade to being a serial transaction after it has 632acquired per-method-group locks (e.g., when those locks are only 633acquired during an attempt to commit), then the TM method does not need 634to consider a potential deadlock due to serial mode. 635 636 If there can be upgrades to serial mode after the acquisition of 637per-method-group locks, then TM methods need to avoid those deadlocks: 638 * When upgrading to a serial transaction, after acquiring exclusive 639 rights to the serial lock but before waiting for concurrent active 640 transactions to finish (*note Serial lock implementation: 641 serial-lock-impl. for details), we have to wake up all active 642 transactions waiting on the upgrader's per-method-group locks. 643 * Active transactions blocking on per-method-group locks need to 644 check the serial lock and abort if there is a pending serial 645 transaction. 646 * Lost wake-ups have to be prevented (e.g., by changing a bit in each 647 per-method-group lock before doing the wake-up, and only blocking 648 on this lock using a futex if this bit is not group). 649 650 *TODO*: Can reuse serial lock for gl-*? And if we can, does it make 651sense to introduce further complexity in the serial lock? For gl-*, we 652can really only avoid an abort if we do -wb and -vbv. 653 6544.3.3 Serial lock implementation 655-------------------------------- 656 657The serial lock implementation is optimized towards assuming that serial 658transactions are infrequent and not the common case. However, the 659performance of entering serial mode can matter because when only few 660transactions are run concurrently or if there are few threads, then it 661can be efficient to run transactions serially. 662 663 The serial lock is similar to a multi-reader-single-writer lock in 664that there can be several active transactions but only one serial 665transaction. However, we do want to avoid contention (in the lock 666implementation) between active transactions, so we split up the reader 667side of the lock into per-transaction flags that are true iff the 668transaction is active. The exclusive writer side remains a shared 669single flag, which is acquired using a CAS, for example. On the 670fast-path, the serial lock then works similar to Dekker's algorithm but 671with several reader flags that a serial transaction would have to check. 672A serial transaction thus requires a list of all threads with 673potentially active transactions; we can use the serial lock itself to 674protect this list (i.e., only threads that have acquired the serial lock 675can modify this list). 676 677 We want starvation-freedom for the serial lock to allow for using it 678to ensure progress for potentially starved transactions (*note Progress 679Guarantees: progress-guarantees. for details). However, this is 680currently not enforced by the implementation of the serial lock. 681 682 Here is pseudo-code for the read/write fast paths of acquiring the 683serial lock (read-to-write upgrade is similar to write_lock: 684 // read_lock: 685 tx->shared_state |= active; 686 __sync_synchronize(); // or STLD membar, or C++0x seq-cst fence 687 while (!serial_lock.exclusive) 688 if (spinning_for_too_long) goto slowpath; 689 690 // write_lock: 691 if (CAS(&serial_lock.exclusive, 0, this) != 0) 692 goto slowpath; // writer-writer contention 693 // need a membar here, but CAS already has full membar semantics 694 bool need_blocking = false; 695 for (t: all txns) 696 { 697 for (;t->shared_state & active;) 698 if (spinning_for_too_long) { need_blocking = true; break; } 699 } 700 if (need_blocking) goto slowpath; 701 702 Releasing a lock in this spin-lock version then just consists of 703resetting 'tx->shared_state' to inactive or clearing 704'serial_lock.exclusive'. 705 706 However, we can't rely on a pure spinlock because we need to get the 707OS involved at some time (e.g., when there are more threads than CPUs to 708run on). Therefore, the real implementation falls back to a blocking 709slow path, either based on pthread mutexes or Linux futexes. 710 7114.3.4 Reentrancy 712---------------- 713 714libitm has to consider the following cases of reentrancy: 715 716 * Transaction calls unsafe code that starts a new transaction: The 717 outer transaction will become a serial transaction before executing 718 unsafe code. Therefore, nesting within serial transactions must 719 work, even if the nested transaction is called from within 720 uninstrumented code. 721 722 * Transaction calls either a transactional wrapper or safe code, 723 which in turn starts a new transaction: It is not yet defined in 724 the specification whether this is allowed. Thus, it is undefined 725 whether libitm supports this. 726 727 * Code that starts new transactions might be called from within any 728 part of libitm: This kind of reentrancy would likely be rather 729 complex and can probably be avoided. Therefore, it is not 730 supported. 731 7324.3.5 Privatization safety 733-------------------------- 734 735Privatization safety is ensured by libitm using a quiescence-based 736approach. Basically, a privatizing transaction waits until all 737concurrent active transactions will either have finished (are not active 738anymore) or operate on a sufficiently recent snapshot to not access the 739privatized data anymore. This happens after the privatizing transaction 740has stopped being an active transaction, so waiting for quiescence does 741not contribute to deadlocks. 742 743 In method groups that need to ensure publication safety explicitly, 744active transactions maintain a flag or timestamp in the public/shared 745part of the transaction descriptor. Before blocking, privatizers need 746to let the other transactions know that they should wake up the 747privatizer. 748 749 *TODO* Ho to implement the waiters? Should those flags be 750per-transaction or at a central place? We want to avoid one wake/wait 751call per active transactions, so we might want to use either a tree or 752combining to reduce the syscall overhead, or rather spin for a long 753amount of time instead of doing blocking. Also, it would be good if 754only the last transaction that the privatizer waits for would do the 755wake-up. 756 7574.3.6 Progress guarantees 758------------------------- 759 760Transactions that do not make progress when using the current TM method 761will eventually try to execute in serial mode. Thus, the serial lock's 762progress guarantees determine the progress guarantees of the whole TM. 763Obviously, we at least need deadlock-freedom for the serial lock, but it 764would also be good to provide starvation-freedom (informally, all 765threads will finish executing a transaction eventually iff they get 766enough cycles). 767 768 However, the scheduling of transactions (e.g., thread scheduling by 769the OS) also affects the handling of progress guarantees by the TM. 770First, the TM can only guarantee deadlock-freedom if threads do not get 771stopped. Likewise, low-priority threads can starve if they do not get 772scheduled when other high-priority threads get those cycles instead. 773 774 If all threads get scheduled eventually, correct lock implementations 775will provide deadlock-freedom, but might not provide starvation-freedom. 776We can either enforce the latter in the TM's lock implementation, or 777assume that the scheduling is sufficiently random to yield a 778probabilistic guarantee that no thread will starve (because eventually, 779a transaction will encounter a scheduling that will allow it to run). 780This can indeed work well in practice but is not necessarily guaranteed 781to work (e.g., simple spin locks can be pretty efficient). 782 783 Because enforcing stronger progress guarantees in the TM has a higher 784runtime overhead, we focus on deadlock-freedom right now and assume that 785the threads will get scheduled eventually by the OS (but don't consider 786threads with different priorities). We should support 787starvation-freedom for serial transactions in the future. Everything 788beyond that is highly related to proper contention management across all 789of the TM (including with TM method to choose), and is future work. 790 791 *TODO* Handling thread priorities: We want to avoid priority 792inversion but it's unclear how often that actually matters in practice. 793Workloads that have threads with different priorities will likely also 794require lower latency or higher throughput for high-priority threads. 795Therefore, it probably makes not that much sense (except for eventual 796progress guarantees) to use priority inheritance until the TM has 797priority-aware contention management. 798 799 800File: libitm.info, Node: GNU Free Documentation License, Next: Library Index, Prev: Internals, Up: Top 801 802GNU Free Documentation License 803****************************** 804 805 Version 1.3, 3 November 2008 806 807 Copyright (C) 2000, 2001, 2002, 2007, 2008 Free Software Foundation, Inc. 808 <http://fsf.org/> 809 810 Everyone is permitted to copy and distribute verbatim copies 811 of this license document, but changing it is not allowed. 812 813 0. PREAMBLE 814 815 The purpose of this License is to make a manual, textbook, or other 816 functional and useful document "free" in the sense of freedom: to 817 assure everyone the effective freedom to copy and redistribute it, 818 with or without modifying it, either commercially or 819 noncommercially. Secondarily, this License preserves for the 820 author and publisher a way to get credit for their work, while not 821 being considered responsible for modifications made by others. 822 823 This License is a kind of "copyleft", which means that derivative 824 works of the document must themselves be free in the same sense. 825 It complements the GNU General Public License, which is a copyleft 826 license designed for free software. 827 828 We have designed this License in order to use it for manuals for 829 free software, because free software needs free documentation: a 830 free program should come with manuals providing the same freedoms 831 that the software does. But this License is not limited to 832 software manuals; it can be used for any textual work, regardless 833 of subject matter or whether it is published as a printed book. We 834 recommend this License principally for works whose purpose is 835 instruction or reference. 836 837 1. APPLICABILITY AND DEFINITIONS 838 839 This License applies to any manual or other work, in any medium, 840 that contains a notice placed by the copyright holder saying it can 841 be distributed under the terms of this License. Such a notice 842 grants a world-wide, royalty-free license, unlimited in duration, 843 to use that work under the conditions stated herein. The 844 "Document", below, refers to any such manual or work. Any member 845 of the public is a licensee, and is addressed as "you". You accept 846 the license if you copy, modify or distribute the work in a way 847 requiring permission under copyright law. 848 849 A "Modified Version" of the Document means any work containing the 850 Document or a portion of it, either copied verbatim, or with 851 modifications and/or translated into another language. 852 853 A "Secondary Section" is a named appendix or a front-matter section 854 of the Document that deals exclusively with the relationship of the 855 publishers or authors of the Document to the Document's overall 856 subject (or to related matters) and contains nothing that could 857 fall directly within that overall subject. (Thus, if the Document 858 is in part a textbook of mathematics, a Secondary Section may not 859 explain any mathematics.) The relationship could be a matter of 860 historical connection with the subject or with related matters, or 861 of legal, commercial, philosophical, ethical or political position 862 regarding them. 863 864 The "Invariant Sections" are certain Secondary Sections whose 865 titles are designated, as being those of Invariant Sections, in the 866 notice that says that the Document is released under this License. 867 If a section does not fit the above definition of Secondary then it 868 is not allowed to be designated as Invariant. The Document may 869 contain zero Invariant Sections. If the Document does not identify 870 any Invariant Sections then there are none. 871 872 The "Cover Texts" are certain short passages of text that are 873 listed, as Front-Cover Texts or Back-Cover Texts, in the notice 874 that says that the Document is released under this License. A 875 Front-Cover Text may be at most 5 words, and a Back-Cover Text may 876 be at most 25 words. 877 878 A "Transparent" copy of the Document means a machine-readable copy, 879 represented in a format whose specification is available to the 880 general public, that is suitable for revising the document 881 straightforwardly with generic text editors or (for images composed 882 of pixels) generic paint programs or (for drawings) some widely 883 available drawing editor, and that is suitable for input to text 884 formatters or for automatic translation to a variety of formats 885 suitable for input to text formatters. A copy made in an otherwise 886 Transparent file format whose markup, or absence of markup, has 887 been arranged to thwart or discourage subsequent modification by 888 readers is not Transparent. An image format is not Transparent if 889 used for any substantial amount of text. A copy that is not 890 "Transparent" is called "Opaque". 891 892 Examples of suitable formats for Transparent copies include plain 893 ASCII without markup, Texinfo input format, LaTeX input format, 894 SGML or XML using a publicly available DTD, and standard-conforming 895 simple HTML, PostScript or PDF designed for human modification. 896 Examples of transparent image formats include PNG, XCF and JPG. 897 Opaque formats include proprietary formats that can be read and 898 edited only by proprietary word processors, SGML or XML for which 899 the DTD and/or processing tools are not generally available, and 900 the machine-generated HTML, PostScript or PDF produced by some word 901 processors for output purposes only. 902 903 The "Title Page" means, for a printed book, the title page itself, 904 plus such following pages as are needed to hold, legibly, the 905 material this License requires to appear in the title page. For 906 works in formats which do not have any title page as such, "Title 907 Page" means the text near the most prominent appearance of the 908 work's title, preceding the beginning of the body of the text. 909 910 The "publisher" means any person or entity that distributes copies 911 of the Document to the public. 912 913 A section "Entitled XYZ" means a named subunit of the Document 914 whose title either is precisely XYZ or contains XYZ in parentheses 915 following text that translates XYZ in another language. (Here XYZ 916 stands for a specific section name mentioned below, such as 917 "Acknowledgements", "Dedications", "Endorsements", or "History".) 918 To "Preserve the Title" of such a section when you modify the 919 Document means that it remains a section "Entitled XYZ" according 920 to this definition. 921 922 The Document may include Warranty Disclaimers next to the notice 923 which states that this License applies to the Document. These 924 Warranty Disclaimers are considered to be included by reference in 925 this License, but only as regards disclaiming warranties: any other 926 implication that these Warranty Disclaimers may have is void and 927 has no effect on the meaning of this License. 928 929 2. VERBATIM COPYING 930 931 You may copy and distribute the Document in any medium, either 932 commercially or noncommercially, provided that this License, the 933 copyright notices, and the license notice saying this License 934 applies to the Document are reproduced in all copies, and that you 935 add no other conditions whatsoever to those of this License. You 936 may not use technical measures to obstruct or control the reading 937 or further copying of the copies you make or distribute. However, 938 you may accept compensation in exchange for copies. If you 939 distribute a large enough number of copies you must also follow the 940 conditions in section 3. 941 942 You may also lend copies, under the same conditions stated above, 943 and you may publicly display copies. 944 945 3. COPYING IN QUANTITY 946 947 If you publish printed copies (or copies in media that commonly 948 have printed covers) of the Document, numbering more than 100, and 949 the Document's license notice requires Cover Texts, you must 950 enclose the copies in covers that carry, clearly and legibly, all 951 these Cover Texts: Front-Cover Texts on the front cover, and 952 Back-Cover Texts on the back cover. Both covers must also clearly 953 and legibly identify you as the publisher of these copies. The 954 front cover must present the full title with all words of the title 955 equally prominent and visible. You may add other material on the 956 covers in addition. Copying with changes limited to the covers, as 957 long as they preserve the title of the Document and satisfy these 958 conditions, can be treated as verbatim copying in other respects. 959 960 If the required texts for either cover are too voluminous to fit 961 legibly, you should put the first ones listed (as many as fit 962 reasonably) on the actual cover, and continue the rest onto 963 adjacent pages. 964 965 If you publish or distribute Opaque copies of the Document 966 numbering more than 100, you must either include a machine-readable 967 Transparent copy along with each Opaque copy, or state in or with 968 each Opaque copy a computer-network location from which the general 969 network-using public has access to download using public-standard 970 network protocols a complete Transparent copy of the Document, free 971 of added material. If you use the latter option, you must take 972 reasonably prudent steps, when you begin distribution of Opaque 973 copies in quantity, to ensure that this Transparent copy will 974 remain thus accessible at the stated location until at least one 975 year after the last time you distribute an Opaque copy (directly or 976 through your agents or retailers) of that edition to the public. 977 978 It is requested, but not required, that you contact the authors of 979 the Document well before redistributing any large number of copies, 980 to give them a chance to provide you with an updated version of the 981 Document. 982 983 4. MODIFICATIONS 984 985 You may copy and distribute a Modified Version of the Document 986 under the conditions of sections 2 and 3 above, provided that you 987 release the Modified Version under precisely this License, with the 988 Modified Version filling the role of the Document, thus licensing 989 distribution and modification of the Modified Version to whoever 990 possesses a copy of it. In addition, you must do these things in 991 the Modified Version: 992 993 A. Use in the Title Page (and on the covers, if any) a title 994 distinct from that of the Document, and from those of previous 995 versions (which should, if there were any, be listed in the 996 History section of the Document). You may use the same title 997 as a previous version if the original publisher of that 998 version gives permission. 999 1000 B. List on the Title Page, as authors, one or more persons or 1001 entities responsible for authorship of the modifications in 1002 the Modified Version, together with at least five of the 1003 principal authors of the Document (all of its principal 1004 authors, if it has fewer than five), unless they release you 1005 from this requirement. 1006 1007 C. State on the Title page the name of the publisher of the 1008 Modified Version, as the publisher. 1009 1010 D. Preserve all the copyright notices of the Document. 1011 1012 E. Add an appropriate copyright notice for your modifications 1013 adjacent to the other copyright notices. 1014 1015 F. Include, immediately after the copyright notices, a license 1016 notice giving the public permission to use the Modified 1017 Version under the terms of this License, in the form shown in 1018 the Addendum below. 1019 1020 G. Preserve in that license notice the full lists of Invariant 1021 Sections and required Cover Texts given in the Document's 1022 license notice. 1023 1024 H. Include an unaltered copy of this License. 1025 1026 I. Preserve the section Entitled "History", Preserve its Title, 1027 and add to it an item stating at least the title, year, new 1028 authors, and publisher of the Modified Version as given on the 1029 Title Page. If there is no section Entitled "History" in the 1030 Document, create one stating the title, year, authors, and 1031 publisher of the Document as given on its Title Page, then add 1032 an item describing the Modified Version as stated in the 1033 previous sentence. 1034 1035 J. Preserve the network location, if any, given in the Document 1036 for public access to a Transparent copy of the Document, and 1037 likewise the network locations given in the Document for 1038 previous versions it was based on. These may be placed in the 1039 "History" section. You may omit a network location for a work 1040 that was published at least four years before the Document 1041 itself, or if the original publisher of the version it refers 1042 to gives permission. 1043 1044 K. For any section Entitled "Acknowledgements" or "Dedications", 1045 Preserve the Title of the section, and preserve in the section 1046 all the substance and tone of each of the contributor 1047 acknowledgements and/or dedications given therein. 1048 1049 L. Preserve all the Invariant Sections of the Document, unaltered 1050 in their text and in their titles. Section numbers or the 1051 equivalent are not considered part of the section titles. 1052 1053 M. Delete any section Entitled "Endorsements". Such a section 1054 may not be included in the Modified Version. 1055 1056 N. Do not retitle any existing section to be Entitled 1057 "Endorsements" or to conflict in title with any Invariant 1058 Section. 1059 1060 O. Preserve any Warranty Disclaimers. 1061 1062 If the Modified Version includes new front-matter sections or 1063 appendices that qualify as Secondary Sections and contain no 1064 material copied from the Document, you may at your option designate 1065 some or all of these sections as invariant. To do this, add their 1066 titles to the list of Invariant Sections in the Modified Version's 1067 license notice. These titles must be distinct from any other 1068 section titles. 1069 1070 You may add a section Entitled "Endorsements", provided it contains 1071 nothing but endorsements of your Modified Version by various 1072 parties--for example, statements of peer review or that the text 1073 has been approved by an organization as the authoritative 1074 definition of a standard. 1075 1076 You may add a passage of up to five words as a Front-Cover Text, 1077 and a passage of up to 25 words as a Back-Cover Text, to the end of 1078 the list of Cover Texts in the Modified Version. Only one passage 1079 of Front-Cover Text and one of Back-Cover Text may be added by (or 1080 through arrangements made by) any one entity. If the Document 1081 already includes a cover text for the same cover, previously added 1082 by you or by arrangement made by the same entity you are acting on 1083 behalf of, you may not add another; but you may replace the old 1084 one, on explicit permission from the previous publisher that added 1085 the old one. 1086 1087 The author(s) and publisher(s) of the Document do not by this 1088 License give permission to use their names for publicity for or to 1089 assert or imply endorsement of any Modified Version. 1090 1091 5. COMBINING DOCUMENTS 1092 1093 You may combine the Document with other documents released under 1094 this License, under the terms defined in section 4 above for 1095 modified versions, provided that you include in the combination all 1096 of the Invariant Sections of all of the original documents, 1097 unmodified, and list them all as Invariant Sections of your 1098 combined work in its license notice, and that you preserve all 1099 their Warranty Disclaimers. 1100 1101 The combined work need only contain one copy of this License, and 1102 multiple identical Invariant Sections may be replaced with a single 1103 copy. If there are multiple Invariant Sections with the same name 1104 but different contents, make the title of each such section unique 1105 by adding at the end of it, in parentheses, the name of the 1106 original author or publisher of that section if known, or else a 1107 unique number. Make the same adjustment to the section titles in 1108 the list of Invariant Sections in the license notice of the 1109 combined work. 1110 1111 In the combination, you must combine any sections Entitled 1112 "History" in the various original documents, forming one section 1113 Entitled "History"; likewise combine any sections Entitled 1114 "Acknowledgements", and any sections Entitled "Dedications". You 1115 must delete all sections Entitled "Endorsements." 1116 1117 6. COLLECTIONS OF DOCUMENTS 1118 1119 You may make a collection consisting of the Document and other 1120 documents released under this License, and replace the individual 1121 copies of this License in the various documents with a single copy 1122 that is included in the collection, provided that you follow the 1123 rules of this License for verbatim copying of each of the documents 1124 in all other respects. 1125 1126 You may extract a single document from such a collection, and 1127 distribute it individually under this License, provided you insert 1128 a copy of this License into the extracted document, and follow this 1129 License in all other respects regarding verbatim copying of that 1130 document. 1131 1132 7. AGGREGATION WITH INDEPENDENT WORKS 1133 1134 A compilation of the Document or its derivatives with other 1135 separate and independent documents or works, in or on a volume of a 1136 storage or distribution medium, is called an "aggregate" if the 1137 copyright resulting from the compilation is not used to limit the 1138 legal rights of the compilation's users beyond what the individual 1139 works permit. When the Document is included in an aggregate, this 1140 License does not apply to the other works in the aggregate which 1141 are not themselves derivative works of the Document. 1142 1143 If the Cover Text requirement of section 3 is applicable to these 1144 copies of the Document, then if the Document is less than one half 1145 of the entire aggregate, the Document's Cover Texts may be placed 1146 on covers that bracket the Document within the aggregate, or the 1147 electronic equivalent of covers if the Document is in electronic 1148 form. Otherwise they must appear on printed covers that bracket 1149 the whole aggregate. 1150 1151 8. TRANSLATION 1152 1153 Translation is considered a kind of modification, so you may 1154 distribute translations of the Document under the terms of section 1155 4. Replacing Invariant Sections with translations requires special 1156 permission from their copyright holders, but you may include 1157 translations of some or all Invariant Sections in addition to the 1158 original versions of these Invariant Sections. You may include a 1159 translation of this License, and all the license notices in the 1160 Document, and any Warranty Disclaimers, provided that you also 1161 include the original English version of this License and the 1162 original versions of those notices and disclaimers. In case of a 1163 disagreement between the translation and the original version of 1164 this License or a notice or disclaimer, the original version will 1165 prevail. 1166 1167 If a section in the Document is Entitled "Acknowledgements", 1168 "Dedications", or "History", the requirement (section 4) to 1169 Preserve its Title (section 1) will typically require changing the 1170 actual title. 1171 1172 9. TERMINATION 1173 1174 You may not copy, modify, sublicense, or distribute the Document 1175 except as expressly provided under this License. Any attempt 1176 otherwise to copy, modify, sublicense, or distribute it is void, 1177 and will automatically terminate your rights under this License. 1178 1179 However, if you cease all violation of this License, then your 1180 license from a particular copyright holder is reinstated (a) 1181 provisionally, unless and until the copyright holder explicitly and 1182 finally terminates your license, and (b) permanently, if the 1183 copyright holder fails to notify you of the violation by some 1184 reasonable means prior to 60 days after the cessation. 1185 1186 Moreover, your license from a particular copyright holder is 1187 reinstated permanently if the copyright holder notifies you of the 1188 violation by some reasonable means, this is the first time you have 1189 received notice of violation of this License (for any work) from 1190 that copyright holder, and you cure the violation prior to 30 days 1191 after your receipt of the notice. 1192 1193 Termination of your rights under this section does not terminate 1194 the licenses of parties who have received copies or rights from you 1195 under this License. If your rights have been terminated and not 1196 permanently reinstated, receipt of a copy of some or all of the 1197 same material does not give you any rights to use it. 1198 1199 10. FUTURE REVISIONS OF THIS LICENSE 1200 1201 The Free Software Foundation may publish new, revised versions of 1202 the GNU Free Documentation License from time to time. Such new 1203 versions will be similar in spirit to the present version, but may 1204 differ in detail to address new problems or concerns. See 1205 <http://www.gnu.org/copyleft/>. 1206 1207 Each version of the License is given a distinguishing version 1208 number. If the Document specifies that a particular numbered 1209 version of this License "or any later version" applies to it, you 1210 have the option of following the terms and conditions either of 1211 that specified version or of any later version that has been 1212 published (not as a draft) by the Free Software Foundation. If the 1213 Document does not specify a version number of this License, you may 1214 choose any version ever published (not as a draft) by the Free 1215 Software Foundation. If the Document specifies that a proxy can 1216 decide which future versions of this License can be used, that 1217 proxy's public statement of acceptance of a version permanently 1218 authorizes you to choose that version for the Document. 1219 1220 11. RELICENSING 1221 1222 "Massive Multiauthor Collaboration Site" (or "MMC Site") means any 1223 World Wide Web server that publishes copyrightable works and also 1224 provides prominent facilities for anybody to edit those works. A 1225 public wiki that anybody can edit is an example of such a server. 1226 A "Massive Multiauthor Collaboration" (or "MMC") contained in the 1227 site means any set of copyrightable works thus published on the MMC 1228 site. 1229 1230 "CC-BY-SA" means the Creative Commons Attribution-Share Alike 3.0 1231 license published by Creative Commons Corporation, a not-for-profit 1232 corporation with a principal place of business in San Francisco, 1233 California, as well as future copyleft versions of that license 1234 published by that same organization. 1235 1236 "Incorporate" means to publish or republish a Document, in whole or 1237 in part, as part of another Document. 1238 1239 An MMC is "eligible for relicensing" if it is licensed under this 1240 License, and if all works that were first published under this 1241 License somewhere other than this MMC, and subsequently 1242 incorporated in whole or in part into the MMC, (1) had no cover 1243 texts or invariant sections, and (2) were thus incorporated prior 1244 to November 1, 2008. 1245 1246 The operator of an MMC Site may republish an MMC contained in the 1247 site under CC-BY-SA on the same site at any time before August 1, 1248 2009, provided the MMC is eligible for relicensing. 1249 1250ADDENDUM: How to use this License for your documents 1251==================================================== 1252 1253To use this License in a document you have written, include a copy of 1254the License in the document and put the following copyright and license 1255notices just after the title page: 1256 1257 Copyright (C) YEAR YOUR NAME. 1258 Permission is granted to copy, distribute and/or modify this document 1259 under the terms of the GNU Free Documentation License, Version 1.3 1260 or any later version published by the Free Software Foundation; 1261 with no Invariant Sections, no Front-Cover Texts, and no Back-Cover 1262 Texts. A copy of the license is included in the section entitled ``GNU 1263 Free Documentation License''. 1264 1265 If you have Invariant Sections, Front-Cover Texts and Back-Cover 1266Texts, replace the "with...Texts." line with this: 1267 1268 with the Invariant Sections being LIST THEIR TITLES, with 1269 the Front-Cover Texts being LIST, and with the Back-Cover Texts 1270 being LIST. 1271 1272 If you have Invariant Sections without Cover Texts, or some other 1273combination of the three, merge those two alternatives to suit the 1274situation. 1275 1276 If your document contains nontrivial examples of program code, we 1277recommend releasing these examples in parallel under your choice of free 1278software license, such as the GNU General Public License, to permit 1279their use in free software. 1280 1281 1282File: libitm.info, Node: Library Index, Prev: GNU Free Documentation License, Up: Top 1283 1284Library Index 1285************* 1286 1287�[index�] 1288* Menu: 1289 1290* FDL, GNU Free Documentation License: GNU Free Documentation License. 1291 (line 6) 1292* Introduction: Top. (line 6) 1293 1294 1295 1296Tag Table: 1297Node: Top1141 1298Node: Enabling libitm2045 1299Node: C/C++ Language Constructs for TM2440 1300Node: The libitm ABI3923 1301Ref: txn-code-properties7721 1302Node: Internals18814 1303Ref: serial-lock-impl28852 1304Ref: progress-guarantees33613 1305Node: GNU Free Documentation License35891 1306Node: Library Index61020 1307 1308End Tag Table 1309