1src/backend/utils/resowner/README 2 3Notes About Resource Owners 4=========================== 5 6ResourceOwner objects are a concept invented to simplify management of 7query-related resources, such as buffer pins and table locks. These 8resources need to be tracked in a reliable way to ensure that they will 9be released at query end, even if the query fails due to an error. 10Rather than expecting the entire executor to have bulletproof data 11structures, we localize the tracking of such resources into a single 12module. 13 14The design of the ResourceOwner API is modeled on our MemoryContext API, 15which has proven very flexible and successful in preventing memory leaks. 16In particular we allow ResourceOwners to have child ResourceOwner objects 17so that there can be forests of the things; releasing a parent 18ResourceOwner acts on all its direct and indirect children as well. 19 20(It is tempting to consider unifying ResourceOwners and MemoryContexts 21into a single object type, but their usage patterns are sufficiently 22different that this is probably not really a helpful thing to do.) 23 24We create a ResourceOwner for each transaction or subtransaction as 25well as one for each Portal. During execution of a Portal, the global 26variable CurrentResourceOwner points to the Portal's ResourceOwner. 27This causes operations such as ReadBuffer and LockAcquire to record 28ownership of the acquired resources in that ResourceOwner object. 29 30When a Portal is closed, any remaining resources (typically only locks) 31become the responsibility of the current transaction. This is represented 32by making the Portal's ResourceOwner a child of the current transaction's 33ResourceOwner. resowner.c automatically transfers the resources to the 34parent object when releasing the child. Similarly, subtransaction 35ResourceOwners are children of their immediate parent. 36 37We need transaction-related ResourceOwners as well as Portal-related ones 38because transactions may initiate operations that require resources (such 39as query parsing) when no associated Portal exists yet. 40 41 42API Overview 43------------ 44 45The basic operations on a ResourceOwner are: 46 47* create a ResourceOwner 48 49* associate or deassociate some resource with a ResourceOwner 50 51* release a ResourceOwner's assets (free all owned resources, but not the 52 owner object itself) 53 54* delete a ResourceOwner (including child owner objects); all resources 55 must have been released beforehand 56 57Locks are handled specially because in non-error situations a lock should 58be held until end of transaction, even if it was originally taken by a 59subtransaction or portal. Therefore, the "release" operation on a child 60ResourceOwner transfers lock ownership to the parent instead of actually 61releasing the lock, if isCommit is true. 62 63Currently, ResourceOwners contain direct support for recording ownership of 64buffer pins, lmgr locks, and catcache, relcache, plancache, tupdesc, and 65snapshot references. Other objects can be associated with a ResourceOwner by 66recording the address of the owning ResourceOwner in such an object. There is 67an API for other modules to get control during ResourceOwner release, so that 68they can scan their own data structures to find the objects that need to be 69deleted. 70 71Whenever we are inside a transaction, the global variable 72CurrentResourceOwner shows which resource owner should be assigned 73ownership of acquired resources. Note however that CurrentResourceOwner 74is NULL when not inside any transaction (or when inside a failed 75transaction). In this case it is not valid to acquire query-lifespan 76resources. 77 78When unpinning a buffer or releasing a lock or cache reference, 79CurrentResourceOwner must point to the same resource owner that was current 80when the buffer, lock, or cache reference was acquired. It would be possible 81to relax this restriction given additional bookkeeping effort, but at present 82there seems no need. 83 84Code that transiently changes CurrentResourceOwner should generally use a 85PG_TRY construct to ensure that the previous value of CurrentResourceOwner 86is restored if control is lost during an error exit. 87