From 4e228447aa42c3d74ad513a11d1d00c1997fd116 Mon Sep 17 00:00:00 2001 From: Bruce Momjian Date: Thu, 20 Mar 2008 17:55:15 +0000 Subject: [PATCH] Make source code READMEs more consistent. Add CVS tags to all README files. --- src/backend/access/gin/README | 2 ++ src/backend/access/gist/README | 11 ++++++++--- src/backend/access/hash/README | 15 +++++++++------ src/backend/access/nbtree/README | 19 +++++++++++-------- src/backend/access/transam/README | 10 +++++----- src/backend/catalog/README | 5 ++++- src/backend/executor/README | 4 ++-- src/backend/nodes/README | 27 +++++++++++++-------------- src/backend/optimizer/README | 10 ++++++---- src/backend/optimizer/plan/README | 8 ++++++-- src/backend/parser/README | 5 +++++ src/backend/port/darwin/README | 5 +++++ src/backend/snowball/README | 4 +++- src/backend/storage/buffer/README | 12 ++++++------ src/backend/storage/ipc/README | 7 ++++--- src/backend/storage/lmgr/README | 21 +++++++++++++-------- src/backend/storage/smgr/README | 5 ++++- src/backend/utils/fmgr/README | 23 ++++++++++++++--------- src/backend/utils/mb/README | 5 +++++ src/backend/utils/misc/README | 15 +++++++++------ src/backend/utils/mmgr/README | 24 ++++++++++++------------ src/backend/utils/resowner/README | 6 +++--- 22 files changed, 149 insertions(+), 94 deletions(-) diff --git a/src/backend/access/gin/README b/src/backend/access/gin/README index c914759aa8..cc3856f9a8 100644 --- a/src/backend/access/gin/README +++ b/src/backend/access/gin/README @@ -1,3 +1,5 @@ +$PostgreSQL: pgsql/src/backend/access/gin/README,v 1.5 2008/03/20 17:55:14 momjian Exp $ + Gin for PostgreSQL ================== diff --git a/src/backend/access/gist/README b/src/backend/access/gist/README index 1d828b30ff..aaa6c2abbf 100644 --- a/src/backend/access/gist/README +++ b/src/backend/access/gist/README @@ -1,4 +1,7 @@ -$PostgreSQL: pgsql/src/backend/access/gist/README,v 1.3 2005/09/16 14:40:54 teodor Exp $ +$PostgreSQL: pgsql/src/backend/access/gist/README,v 1.4 2008/03/20 17:55:14 momjian Exp $ + +GiST Indexing +============= This directory contains an implementation of GiST indexing for Postgres. @@ -48,7 +51,8 @@ core and PostgreSQL WAL system. Moreover, we encountered (and solved) a problem of uncompleted insertions when recovering after crash, which was not touched in the paper. -SEARCH ALGORITHM +Search Algorithm +---------------- Function gettuple finds a tuple which satisfies the search predicate. It store their state and returns next tuple under @@ -92,7 +96,8 @@ gettuple(search-pred) end -INSERT ALGORITHM +Insert Algorithm +---------------- INSERT guarantees that the GiST tree remains balanced. User defined key method Penalty is used for choosing a subtree to insert; method PickSplit is used for diff --git a/src/backend/access/hash/README b/src/backend/access/hash/README index 9f34fd73c4..ca23920648 100644 --- a/src/backend/access/hash/README +++ b/src/backend/access/hash/README @@ -1,4 +1,7 @@ -$PostgreSQL: pgsql/src/backend/access/hash/README,v 1.7 2008/03/15 20:46:31 tgl Exp $ +$PostgreSQL: pgsql/src/backend/access/hash/README,v 1.8 2008/03/20 17:55:14 momjian Exp $ + +Hash Indexing +============= This directory contains an implementation of hash indexing for Postgres. Most of the core ideas are taken from Margo Seltzer and Ozan Yigit, A New Hashing @@ -30,7 +33,7 @@ in other buckets, but we never give them back to the operating system. There is no provision for reducing the number of buckets, either. -Page addressing +Page Addressing --------------- There are four kinds of pages in a hash index: the meta page (page zero), @@ -111,7 +114,7 @@ first bitmap page, which is allocated during index creation just after all the initially created buckets. -Lock definitions +Lock Definitions ---------------- We use both lmgr locks ("heavyweight" locks) and buffer context locks @@ -166,7 +169,7 @@ be held at a time by any one process. (The third restriction is probably stronger than necessary, but it makes the proof of no deadlock obvious.) -Pseudocode algorithms +Pseudocode Algorithms --------------------- The operations we need to support are: readers scanning the index for @@ -324,7 +327,7 @@ The exclusive lock request could deadlock in some strange scenarios, but we can just error out without any great harm being done. -Free space management +Free Space Management --------------------- (Question: why is this so complicated? Why not just have a linked list @@ -429,7 +432,7 @@ All the freespace operations should be called while holding no buffer locks. Since they need no lmgr locks, deadlock is not possible. -Other notes +Other Notes ----------- All the shenanigans with locking prevent a split occurring while *another* diff --git a/src/backend/access/nbtree/README b/src/backend/access/nbtree/README index af19525cdc..f32174191c 100644 --- a/src/backend/access/nbtree/README +++ b/src/backend/access/nbtree/README @@ -1,4 +1,7 @@ -$PostgreSQL: pgsql/src/backend/access/nbtree/README,v 1.18 2007/09/12 22:10:26 tgl Exp $ +$PostgreSQL: pgsql/src/backend/access/nbtree/README,v 1.19 2008/03/20 17:55:14 momjian Exp $ + +Btree Indexing +-------------- This directory contains a correct implementation of Lehman and Yao's high-concurrency B-tree management algorithm (P. Lehman and S. Yao, @@ -8,7 +11,7 @@ use a simplified version of the deletion logic described in Lanin and Shasha (V. Lanin and D. Shasha, A Symmetric Concurrent B-Tree Algorithm, Proceedings of 1986 Fall Joint Computer Conference, pp 380-389). -The Lehman and Yao algorithm and insertions +The Lehman and Yao Algorithm and Insertions ------------------------------------------- We have made the following changes in order to incorporate the L&Y algorithm @@ -125,7 +128,7 @@ each of the resulting pages. Note we must include the incoming item in this calculation, otherwise it is possible to find that the incoming item doesn't fit on the split page where it needs to go! -The deletion algorithm +The Deletion Algorithm ---------------------- Before deleting a leaf item, we get a super-exclusive lock on the target @@ -320,7 +323,7 @@ positives, so long as it never gives a false negative. This makes it possible to implement the test with a small counter value stored on each index page. -On-the-fly deletion of index tuples +On-the-Fly Deletion Of Index Tuples ----------------------------------- If a process visits a heap tuple and finds that it's dead and removable @@ -357,7 +360,7 @@ and so cannot remove the heap tuple. This is another reason why btbulkdelete has to get super-exclusive lock on every leaf page, not only the ones where it actually sees items to delete. -WAL considerations +WAL Considerations ------------------ The insertion and deletion algorithms in themselves don't guarantee btree @@ -398,7 +401,7 @@ of the WAL entry.) If the parent page becomes half-dead but is not immediately deleted due to a subsequent crash, there is no loss of consistency, and the empty page will be picked up by the next VACUUM. -Other things that are handy to know +Other Things That Are Handy to Know ----------------------------------- Page zero of every btree is a meta-data page. This page stores the @@ -443,7 +446,7 @@ original search scankey is consulted as each index entry is sequentially scanned to decide whether to return the entry and whether the scan can stop (see _bt_checkkeys()). -Notes about data representation +Notes About Data Representation ------------------------------- The right-sibling link required by L&Y is kept in the page "opaque @@ -477,7 +480,7 @@ item is irrelevant, and need not be stored at all. This arrangement corresponds to the fact that an L&Y non-leaf page has one more pointer than key. -Notes to operator class implementors +Notes to Operator Class Implementors ------------------------------------ With this implementation, we require each supported combination of diff --git a/src/backend/access/transam/README b/src/backend/access/transam/README index f0f27af1c3..5439869ee5 100644 --- a/src/backend/access/transam/README +++ b/src/backend/access/transam/README @@ -1,4 +1,4 @@ -$PostgreSQL: pgsql/src/backend/access/transam/README,v 1.9 2007/09/08 20:31:14 tgl Exp $ +$PostgreSQL: pgsql/src/backend/access/transam/README,v 1.10 2008/03/20 17:55:14 momjian Exp $ The Transaction System ---------------------- @@ -145,7 +145,7 @@ finishing of transactions and subtransactions. For example, AtStart_Memory takes care of initializing the memory subsystem at main transaction start. -Subtransaction handling +Subtransaction Handling ----------------------- Subtransactions are implemented using a stack of TransactionState structures, @@ -187,7 +187,7 @@ Another difference is that BeginInternalSubtransaction is allowed when no explicit transaction block has been established, while DefineSavepoint is not. -Transaction and subtransaction numbering +Transaction and Subtransaction Numbering ---------------------------------------- Transactions and subtransactions are assigned permanent XIDs only when/if @@ -221,7 +221,7 @@ InvalidSubTransactionId.) Note that subtransactions do not have their own VXIDs; they use the parent top transaction's VXID. -Interlocking transaction begin, transaction end, and snapshots +Interlocking Transaction Begin, Transaction End, and Snapshots -------------------------------------------------------------- We try hard to minimize the amount of overhead and lock contention involved @@ -375,7 +375,7 @@ for pg_clog are implemented in transam.c, while the low-level functions are in clog.c. pg_subtrans is contained completely in subtrans.c. -Write-Ahead Log coding +Write-Ahead Log Coding ---------------------- The WAL subsystem (also called XLOG in the code) exists to guarantee crash diff --git a/src/backend/catalog/README b/src/backend/catalog/README index 89c6e0305a..9e3a9af47f 100644 --- a/src/backend/catalog/README +++ b/src/backend/catalog/README @@ -1,4 +1,7 @@ -$PostgreSQL: pgsql/src/backend/catalog/README,v 1.11 2007/05/11 17:57:11 tgl Exp $ +$PostgreSQL: pgsql/src/backend/catalog/README,v 1.12 2008/03/20 17:55:14 momjian Exp $ + +System Catalog +-------------- This directory contains .c files that manipulate the system catalogs; src/include/catalog contains the .h files that define the structure diff --git a/src/backend/executor/README b/src/backend/executor/README index 00e503744e..2ebe168b38 100644 --- a/src/backend/executor/README +++ b/src/backend/executor/README @@ -1,4 +1,4 @@ -$PostgreSQL: pgsql/src/backend/executor/README,v 1.5 2005/04/28 21:47:12 tgl Exp $ +$PostgreSQL: pgsql/src/backend/executor/README,v 1.6 2008/03/20 17:55:14 momjian Exp $ The Postgres Executor --------------------- @@ -137,7 +137,7 @@ be hidden inside function calls). This case has a flow of control like (a separate FreeExprContext call is not necessary) -EvalPlanQual (READ COMMITTED update checking) +EvalPlanQual (READ COMMITTED Update Checking) --------------------------------------------- For simple SELECTs, the executor need only pay attention to tuples that are diff --git a/src/backend/nodes/README b/src/backend/nodes/README index 499aefbe97..b1b95ffcde 100644 --- a/src/backend/nodes/README +++ b/src/backend/nodes/README @@ -1,15 +1,12 @@ -******************************************************************************* -* * -* EXPLANATION OF THE NODE STRUCTURES * -* - Andrew Yu (11/94) * -* * -* Copyright (c) 1994, Regents of the University of California * -* * -* $PostgreSQL: pgsql/src/backend/nodes/README,v 1.2 2003/11/29 22:39:45 pgsql Exp $ -* * -******************************************************************************* - -INTRODUCTION +$PostgreSQL: pgsql/src/backend/nodes/README,v 1.3 2008/03/20 17:55:14 momjian Exp $ + +Node Structures +=============== + +Andrew Yu (11/94) + +Introduction +------------ The current node structures are plain old C structures. "Inheritance" is achieved by convention. No additional functions will be generated. Functions @@ -36,7 +33,8 @@ FILES IN THIS DIRECTORY memnodes.h - memory nodes -STEPS TO ADD A NODE +Steps to Add a Node +------------------- Suppose you wana define a node Foo: @@ -51,7 +49,8 @@ Suppose you wana define a node Foo: bother writing a creator function in makefuncs.c) -HISTORICAL NOTE +Historical Note +--------------- Prior to the current simple C structure definitions, the Node structures uses a pseudo-inheritance system which automatically generates creator and diff --git a/src/backend/optimizer/README b/src/backend/optimizer/README index a0df388993..43f99d7fba 100644 --- a/src/backend/optimizer/README +++ b/src/backend/optimizer/README @@ -1,5 +1,7 @@ -Summary -------- +$PostgreSQL: pgsql/src/backend/optimizer/README,v 1.42 2008/03/20 17:55:14 momjian Exp $ + +Optimizer +--------- These directories take the Query structure returned by the parser, and generate a plan used by the executor. The /plan directory generates the @@ -180,7 +182,7 @@ to see which join style should be applied for a valid join, ie, JOIN_INNER, JOIN_LEFT, etc.) -Valid OUTER JOIN optimizations +Valid OUTER JOIN Optimizations ------------------------------ The planner's treatment of outer join reordering is based on the following @@ -236,7 +238,7 @@ set must be expanded to include the whole of the lower OJ, thereby preventing it from being formed before the lower OJ is.) -Pulling up subqueries +Pulling Up Subqueries --------------------- As we described above, a subquery appearing in the range table is planned diff --git a/src/backend/optimizer/plan/README b/src/backend/optimizer/plan/README index d3a516834c..10c32b6460 100644 --- a/src/backend/optimizer/plan/README +++ b/src/backend/optimizer/plan/README @@ -1,12 +1,16 @@ -Subselect notes from Vadim. +$PostgreSQL: pgsql/src/backend/optimizer/plan/README,v 1.2 2008/03/20 17:55:14 momjian Exp $ +Subselects +---------- + +Vadim B. Mikheev From owner-pgsql-hackers@hub.org Fri Feb 13 09:01:19 1998 Received: from renoir.op.net (root@renoir.op.net [209.152.193.4]) by candle.pha.pa.us (8.8.5/8.8.5) with ESMTP id JAA11576 for ; Fri, 13 Feb 1998 09:01:17 -0500 (EST) -Received: from hub.org (hub.org [209.47.148.200]) by renoir.op.net (o1/$Revision: 1.1 $) with ESMTP id IAA09761 for ; Fri, 13 Feb 1998 08:41:22 -0500 (EST) +Received: from hub.org (hub.org [209.47.148.200]) by renoir.op.net (o1/$Revision: 1.2 $) with ESMTP id IAA09761 for ; Fri, 13 Feb 1998 08:41:22 -0500 (EST) Received: from localhost (majordom@localhost) by hub.org (8.8.8/8.7.5) with SMTP id IAA08135; Fri, 13 Feb 1998 08:40:17 -0500 (EST) Received: by hub.org (TLB v0.10a (1.23 tibbs 1997/01/09 00:29:32)); Fri, 13 Feb 1998 08:38:42 -0500 (EST) Received: (from majordom@localhost) by hub.org (8.8.8/8.7.5) id IAA06646 for pgsql-hackers-outgoing; Fri, 13 Feb 1998 08:38:35 -0500 (EST) diff --git a/src/backend/parser/README b/src/backend/parser/README index 35a7a68763..bc48a457e3 100644 --- a/src/backend/parser/README +++ b/src/backend/parser/README @@ -1,3 +1,8 @@ +$PostgreSQL: pgsql/src/backend/parser/README,v 1.6 2008/03/20 17:55:14 momjian Exp $ + +Parser +------ + This directory does more than tokenize and parse SQL queries. It also creates Query structures for the various complex queries that are passed to the optimizer and then executor. diff --git a/src/backend/port/darwin/README b/src/backend/port/darwin/README index 0f0a9166ab..fcee2b28c4 100644 --- a/src/backend/port/darwin/README +++ b/src/backend/port/darwin/README @@ -1,3 +1,8 @@ +$PostgreSQL: pgsql/src/backend/port/darwin/README,v 1.4 2008/03/20 17:55:14 momjian Exp $ + +Darwin +------ + The file system.c included herein is taken directly from Apple's Darwin open-source CVS archives, and is redistributed under the BSD copyright notice it bears. (According to Apple's CVS logs, their version is diff --git a/src/backend/snowball/README b/src/backend/snowball/README index 099925ad8f..3a9f18f9cd 100644 --- a/src/backend/snowball/README +++ b/src/backend/snowball/README @@ -1,4 +1,6 @@ -Snowball-based stemming +$PostgreSQL: pgsql/src/backend/snowball/README,v 1.2 2008/03/20 17:55:14 momjian Exp $ + +Snowball-Based Stemming ----------------------- This module uses the word stemming code developed by the Snowball project, diff --git a/src/backend/storage/buffer/README b/src/backend/storage/buffer/README index f6327f875e..2f4741f870 100644 --- a/src/backend/storage/buffer/README +++ b/src/backend/storage/buffer/README @@ -1,6 +1,6 @@ -$PostgreSQL: pgsql/src/backend/storage/buffer/README,v 1.12 2007/05/30 20:11:58 tgl Exp $ +$PostgreSQL: pgsql/src/backend/storage/buffer/README,v 1.13 2008/03/20 17:55:15 momjian Exp $ -Notes about shared buffer access rules +Notes About Shared Buffer Access Rules -------------------------------------- There are two separate access control mechanisms for shared disk buffers: @@ -92,7 +92,7 @@ for VACUUM's use, since we don't allow multiple VACUUMs concurrently on a single relation anyway. -Buffer manager's internal locking +Buffer Manager's Internal Locking --------------------------------- Before PostgreSQL 8.1, all operations of the shared buffer manager itself @@ -152,7 +152,7 @@ we could use per-backend LWLocks instead (a buffer header would then contain a field to show which backend is doing its I/O). -Normal buffer replacement strategy +Normal Buffer Replacement Strategy ---------------------------------- There is a "free list" of buffers that are prime candidates for replacement. @@ -201,7 +201,7 @@ have to give up and try another buffer. This however is not a concern of the basic select-a-victim-buffer algorithm.) -Buffer ring replacement strategy +Buffer Ring Replacement Strategy --------------------------------- When running a query that needs to access a large number of pages just once, @@ -236,7 +236,7 @@ buffer, resulting in excessive WAL flushing. Allowing VACUUM to update 256KB between WAL flushes should be more efficient. -Background writer's processing +Background Writer's Processing ------------------------------ The background writer is designed to write out pages that are likely to be diff --git a/src/backend/storage/ipc/README b/src/backend/storage/ipc/README index 303bc4895f..fc33fb6070 100644 --- a/src/backend/storage/ipc/README +++ b/src/backend/storage/ipc/README @@ -1,9 +1,10 @@ -$PostgreSQL: pgsql/src/backend/storage/ipc/README,v 1.4 2003/11/29 19:51:56 pgsql Exp $ -Mon Jul 18 11:09:22 PDT 1988 W.KLAS +$PostgreSQL: pgsql/src/backend/storage/ipc/README,v 1.5 2008/03/20 17:55:15 momjian Exp $ -Cache invalidation synchronization routines: +Cache Invalidation Synchronization Routines =========================================== +Mon Jul 18 11:09:22 PDT 1988 W.KLAS + The cache synchronization is done using a message queue. Every backend can register a message which then has to be read by all backends. A message read by all backends is removed from the diff --git a/src/backend/storage/lmgr/README b/src/backend/storage/lmgr/README index 5abef17116..b93452d025 100644 --- a/src/backend/storage/lmgr/README +++ b/src/backend/storage/lmgr/README @@ -1,7 +1,7 @@ -$PostgreSQL: pgsql/src/backend/storage/lmgr/README,v 1.22 2007/10/26 20:45:10 alvherre Exp $ +$PostgreSQL: pgsql/src/backend/storage/lmgr/README,v 1.23 2008/03/20 17:55:15 momjian Exp $ - -LOCKING OVERVIEW +Locking Overview +---------------- Postgres uses three types of interprocess locks: @@ -45,7 +45,8 @@ when the wait time might exceed a few seconds. The rest of this README file discusses the regular lock manager in detail. -LOCK DATA STRUCTURES +Lock Data Structures +-------------------- Lock methods describe the overall locking behavior. Currently there are two lock methods: DEFAULT and USER. @@ -187,7 +188,8 @@ procLink - --------------------------------------------------------------------------- -LOCK MANAGER INTERNAL LOCKING +Lock Manager Internal Locking +----------------------------- Before PostgreSQL 8.2, all of the shared-memory data structures used by the lock manager were protected by a single LWLock, the LockMgrLock; @@ -246,7 +248,8 @@ tradeoff: we could instead recalculate the partition number from the LOCKTAG when needed. -THE DEADLOCK DETECTION ALGORITHM +The Deadlock Detection Algorithm +-------------------------------- Since we allow user transactions to request locks in any order, deadlock is possible. We use a deadlock detection/breaking algorithm that is @@ -445,7 +448,8 @@ eventually lead to the discovery of the additional constraint B before C.) Got that? -Miscellaneous notes: +Miscellaneous Notes +------------------- 1. It is easily proven that no deadlock will be missed due to our asynchronous invocation of deadlock checking. A deadlock cycle in the WFG @@ -495,7 +499,8 @@ The caller can then send a cancellation signal. This implements the principle that autovacuum has a low locking priority (eg it must not block DDL on the table). -USER LOCKS +User Locks +---------- User locks are handled totally on the application side as long term cooperative locks which extend beyond the normal transaction boundaries. diff --git a/src/backend/storage/smgr/README b/src/backend/storage/smgr/README index 124d5bcdff..493d53da90 100644 --- a/src/backend/storage/smgr/README +++ b/src/backend/storage/smgr/README @@ -1,4 +1,7 @@ -# $PostgreSQL: pgsql/src/backend/storage/smgr/README,v 1.3 2004/02/10 01:55:26 tgl Exp $ +# $PostgreSQL: pgsql/src/backend/storage/smgr/README,v 1.4 2008/03/20 17:55:15 momjian Exp $ + +Storage Manager +--------------- In the original Berkeley Postgres system, there were several storage managers, of which only the "magnetic disk" manager remains. (At Berkeley there were diff --git a/src/backend/utils/fmgr/README b/src/backend/utils/fmgr/README index 87044787e8..3fd3a158ea 100644 --- a/src/backend/utils/fmgr/README +++ b/src/backend/utils/fmgr/README @@ -1,4 +1,9 @@ -Proposal for function-manager redesign 19-Nov-2000 +$PostgreSQL: pgsql/src/backend/utils/fmgr/README,v 1.10 2008/03/20 17:55:15 momjian Exp $ + +Function Manager +================ + +Proposal For Function-Manager Redesign 19-Nov-2000 -------------------------------------- We know that the existing mechanism for calling Postgres functions needs @@ -25,7 +30,7 @@ written in the old style can be left in place indefinitely, to provide backward compatibility for user-written C functions. -Changes in pg_proc (system data about a function) +Changes In pg_proc (System Data About a Function) ------------------------------------------------- A new column "proisstrict" will be added to the system pg_proc table. @@ -45,7 +50,7 @@ more useful case for functions expressed in SQL or a PL language, but am open to arguments for the other choice. -The new function-manager interface +The New Function-Manager Interface ---------------------------------- The core of the new design is revised data structures for representing @@ -165,7 +170,7 @@ through a function pointer declared with exactly that signature, we should have no portability or optimization problems. -Function coding conventions +Function Coding Conventions --------------------------- As an example, int4 addition goes from old-style @@ -277,7 +282,7 @@ fields of FunctionCallInfo, it should just do it. I doubt that providing syntactic-sugar macros for these cases is useful. -Call-site coding conventions +Call-Site Coding Conventions ---------------------------- There are many places in the system that call either a specific function @@ -339,7 +344,7 @@ have to change in the first step of implementation, but they can continue to support the same external appearance. -Support for TOAST-able data types +Support for TOAST-Able Data Types --------------------------------- For TOAST-able data types, the PG_GETARG macro will deliver a de-TOASTed @@ -372,7 +377,7 @@ context. When and if the value is actually stored into a tuple, the tuple toaster will decide whether toasting is needed. -Functions accepting or returning sets +Functions Accepting or Returning Sets ------------------------------------- [ this section revised 29-Aug-2002 for 7.3 ] @@ -436,7 +441,7 @@ There is no support for functions accepting sets; instead, the function will be called multiple times, once for each element of the input set. -Notes about function handlers +Notes About Function Handlers ----------------------------- Handlers for classes of functions should find life much easier and @@ -458,7 +463,7 @@ in any case it is required to be a context at least as long-lived as the FmgrInfo itself. -Telling the difference between old- and new-style functions +Telling the Difference Between Old- and New-Style Functions ----------------------------------------------------------- During the conversion process, we carried two different pg_language diff --git a/src/backend/utils/mb/README b/src/backend/utils/mb/README index d106b3120b..8afb41bfc7 100644 --- a/src/backend/utils/mb/README +++ b/src/backend/utils/mb/README @@ -1,3 +1,8 @@ +$PostgreSQL: pgsql/src/backend/utils/mb/README,v 1.6 2008/03/20 17:55:15 momjian Exp $ + +Encodings +--------- + encnames.c: public functions for both the backend and the frontend. conv.c: static functions and a public table for code conversion wchar.c: mostly static functions and a public table for mb string and diff --git a/src/backend/utils/misc/README b/src/backend/utils/misc/README index 3113218853..e2ae67afd9 100644 --- a/src/backend/utils/misc/README +++ b/src/backend/utils/misc/README @@ -1,7 +1,7 @@ -$PostgreSQL: pgsql/src/backend/utils/misc/README,v 1.9 2008/03/16 16:42:44 mha Exp $ +$PostgreSQL: pgsql/src/backend/utils/misc/README,v 1.10 2008/03/20 17:55:15 momjian Exp $ - -GUC IMPLEMENTATION NOTES +Guc Implementation Notes +======================== The GUC (Grand Unified Configuration) module implements configuration variables of multiple types (currently boolean, enum, int, float, and string). @@ -9,7 +9,8 @@ Variable settings can come from various places, with a priority ordering determining which setting is used. -PER-VARIABLE HOOKS +Per-Variable Hooks +------------------ Each variable known to GUC can optionally have an assign_hook and/or a show_hook to provide customized behavior. Assign hooks are used to @@ -69,7 +70,8 @@ This hook allows variable-specific computation of the value displayed by SHOW. -SAVING/RESTORING GUC VARIABLE VALUES +Saving/Restoring Guc Variable Values +------------------------------------ Prior values of configuration variables must be remembered in order to deal with several special cases: RESET (a/k/a SET TO DEFAULT), rollback of SET @@ -208,7 +210,8 @@ with doit = false so that the value is validated, but no derived state is changed. -STRING MEMORY HANDLING +String Memory Handling +---------------------- String option values are allocated with strdup, not with the pstrdup/palloc mechanisms. We would need to keep them in a permanent diff --git a/src/backend/utils/mmgr/README b/src/backend/utils/mmgr/README index 92ffbd407c..b681f9ce50 100644 --- a/src/backend/utils/mmgr/README +++ b/src/backend/utils/mmgr/README @@ -1,7 +1,7 @@ -$PostgreSQL: pgsql/src/backend/utils/mmgr/README,v 1.11 2007/05/29 04:19:35 neilc Exp $ +$PostgreSQL: pgsql/src/backend/utils/mmgr/README,v 1.12 2008/03/20 17:55:15 momjian Exp $ -Notes about memory allocation redesign --------------------------------------- +Notes About Memory Allocation Redesign +====================================== Up through version 7.0, Postgres had serious problems with memory leakage during large queries that process a lot of pass-by-reference data. There @@ -53,7 +53,7 @@ that can be reset or deleted at strategic times within a query, such as after each tuple. -Some notes about the palloc API versus standard C library +Some Notes About the palloc API Versus Standard C Library --------------------------------------------------------- The behavior of palloc and friends is similar to the standard C library's @@ -73,7 +73,7 @@ Similarly, repalloc allows realloc'ing to zero size. * pfree and repalloc do not accept a NULL pointer. This is intentional. -pfree/repalloc no longer depend on CurrentMemoryContext +pfree/repalloc No Longer Depend On CurrentMemoryContext ------------------------------------------------------- In this proposal, pfree() and repalloc() can be applied to any chunk @@ -101,7 +101,7 @@ do". So there'd still need to be a global variable specifying a suitable temporary-allocation context. That might as well be CurrentMemoryContext. -Additions to the memory-context mechanism +Additions to the Memory-Context Mechanism ----------------------------------------- If we are going to have more contexts, we need more mechanism for keeping @@ -130,7 +130,7 @@ children of a given context, but don't reset or delete that context itself". -Globally known contexts +Globally Known Contexts ----------------------- There will be several widely-known contexts that will typically be @@ -214,7 +214,7 @@ if the backend has run out of memory otherwise. This allows out-of-memory to be treated as a normal ERROR condition, not a FATAL error. -Contexts for prepared statements and portals +Contexts For Prepared Statements And Portals -------------------------------------------- A prepared-statement object has an associated private context, in which @@ -230,7 +230,7 @@ from prepared statements simply reference the prepared statements' trees, and won't actually need any storage allocated in their private contexts. -Transient contexts during execution +Transient Contexts During Execution ----------------------------------- When creating a prepared statement, the parse and plan trees will be built @@ -318,7 +318,7 @@ processing. (Eventually we might have an even better solution from nested transactions, but this'll do fine for now.) -Mechanisms to allow multiple types of contexts +Mechanisms to Allow Multiple Types of Contexts ---------------------------------------------- We may want several different types of memory contexts with different @@ -389,7 +389,7 @@ compared to the existing code, so I think we're doing fine without squeezing out that last little bit ... -More control over aset.c behavior +More Control Over aset.c Behavior --------------------------------- Currently, aset.c allocates an 8K block upon the first allocation in @@ -417,7 +417,7 @@ back to malloc() during reset, but just cleared. This avoids malloc thrashing. -Other notes +Other Notes ----------- The original version of this proposal suggested that functions returning diff --git a/src/backend/utils/resowner/README b/src/backend/utils/resowner/README index 57be840dc1..fd4f279ba4 100644 --- a/src/backend/utils/resowner/README +++ b/src/backend/utils/resowner/README @@ -1,6 +1,6 @@ -$PostgreSQL: pgsql/src/backend/utils/resowner/README,v 1.5 2007/03/13 00:33:42 tgl Exp $ +$PostgreSQL: pgsql/src/backend/utils/resowner/README,v 1.6 2008/03/20 17:55:15 momjian Exp $ -Notes about resource owners +Notes About Resource Owners --------------------------- ResourceOwner objects are a concept invented to simplify management of @@ -39,7 +39,7 @@ because transactions may initiate operations that require resources (such as query parsing) when no associated Portal exists yet. -API overview +API Overview ------------ The basic operations on a ResourceOwner are: -- 2.40.0