+$PostgreSQL: pgsql/src/backend/access/gin/README,v 1.5 2008/03/20 17:55:14 momjian Exp $
+
Gin for PostgreSQL
==================
-$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.
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
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
-$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
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),
the initially created buckets.
-Lock definitions
+Lock Definitions
----------------
We use both lmgr locks ("heavyweight" locks) and buffer context locks
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
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
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*
-$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,
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
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
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
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
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
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
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
-$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
----------------------
takes care of initializing the memory subsystem at main transaction start.
-Subtransaction handling
+Subtransaction Handling
-----------------------
Subtransactions are implemented using a stack of TransactionState structures,
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
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
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
-$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
-$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
---------------------
(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
-*******************************************************************************
-* *
-* 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
memnodes.h - memory nodes
-STEPS TO ADD A NODE
+Steps to Add a Node
+-------------------
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
-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
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
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
-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 <maillist@candle.pha.pa.us>; 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 <maillist@candle.pha.pa.us>; 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 <maillist@candle.pha.pa.us>; 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)
+$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.
+$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
-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,
-$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:
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
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.
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,
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
-$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
-$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:
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.
---------------------------------------------------------------------------
-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;
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
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
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.
-# $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
-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
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.
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
should have no portability or optimization problems.
-Function coding conventions
+Function Coding Conventions
---------------------------
As an example, int4 addition goes from old-style
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
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
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 ]
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
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
+$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
-$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).
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
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
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
-$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
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
* 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
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
itself".
-Globally known contexts
+Globally Known Contexts
-----------------------
There will be several widely-known contexts that will typically be
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
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
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
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
thrashing.
-Other notes
+Other Notes
-----------
The original version of this proposal suggested that functions returning
-$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
as query parsing) when no associated Portal exists yet.
-API overview
+API Overview
------------
The basic operations on a ResourceOwner are:
projects / postgresql.git / commitdiff