Improve code documentation about "magnetic disk" storage manager.

The modern incarnation of md.c is by no means specific to magnetic disk
technology, but every so often we hear from someone who's misled by the
label.  Try to clarify that it will work for anything that supports
standard filesystem operations.  Per suggestion from Andrew Dunstan.

diff --git a/src/backend/storage/smgr/README b/src/backend/storage/smgr/README
index 44e93022dfcedcfe8fdd583b60c5c682606ffbd4..12df42a094bd6b06a173e5816495f079c7ada696 100644 (file)
--- a/src/backend/storage/smgr/README
+++ b/src/backend/storage/smgr/README
@@ -1,38 +1,45 @@
 src/backend/storage/smgr/README
 
-Storage Manager
-===============
+Storage Managers
+================
 
 In the original Berkeley Postgres system, there were several storage managers,
 of which only the "magnetic disk" manager remains.  (At Berkeley there were
 also managers for the Sony WORM optical disk jukebox and persistent main
 memory, but these were never supported in any externally released Postgres,
-nor in any version of PostgreSQL.)  However, we retain the notion of a storage
-manager switch in case anyone wants to reintroduce other kinds of storage
-managers.
+nor in any version of PostgreSQL.)  The "magnetic disk" manager is itself
+seriously misnamed, because actually it supports any kind of device for
+which the operating system provides standard filesystem operations; which
+these days is pretty much everything of interest.  However, we retain the
+notion of a storage manager switch in case anyone ever wants to reintroduce
+other kinds of storage managers.  Removing the switch layer would save
+nothing noticeable anyway, since storage-access operations are surely far
+more expensive than one extra layer of C function calls.
 
 In Berkeley Postgres each relation was tagged with the ID of the storage
-manager to use for it.  This is gone.  It would be more reasonable to
-associate storage managers with tablespaces (a feature not present as this
-text is being written, but one likely to emerge soon).
+manager to use for it.  This is gone.  It would be probably more reasonable
+to associate storage managers with tablespaces, should we ever re-introduce
+multiple storage managers into the system catalogs.
 
 The files in this directory, and their contents, are
 
+    smgr.c     The storage manager switch dispatch code.  The routines in
+               this file call the appropriate storage manager to do storage
+               accesses requested by higher-level code.  smgr.c also manages
+               the file handle cache (SMgrRelation table).
+
+    md.c       The "magnetic disk" storage manager, which is really just
+               an interface to the kernel's filesystem operations.
+
     smgrtype.c Storage manager type -- maps string names to storage manager
                IDs and provides simple comparison operators.  This is the
-               regproc support for type 'smgr' in the system catalogs.
+               regproc support for type "smgr" in the system catalogs.
                (This is vestigial since no columns of type smgr exist
                in the catalogs anymore.)
 
-    smgr.c     The storage manager switch dispatch code.  The routines in
-               this file call the appropriate storage manager to do hardware
-               accesses requested by the backend.  smgr.c also manages the
-               file handle cache (SMgrRelation table).
-
-    md.c       The magnetic disk storage manager.
-
 Note that md.c in turn relies on src/backend/storage/file/fd.c.
 
+
 Relation Forks
 ==============
 

diff --git a/src/backend/storage/smgr/md.c b/src/backend/storage/smgr/md.c
index 7d567ae1103968eaa4b530c8345259e8adbc4c60..e62918195ead064f3622f5fada66092837132e33 100644 (file)
--- a/src/backend/storage/smgr/md.c
+++ b/src/backend/storage/smgr/md.c
@@ -3,6 +3,13 @@
  * md.c
  *       This code manages relations that reside on magnetic disk.
  *
+ * Or at least, that was what the Berkeley folk had in mind when they named
+ * this file.  In reality, what this code provides is an interface from
+ * the smgr API to Unix-like filesystem APIs, so it will work with any type
+ * of device for which the operating system provides filesystem support.
+ * It doesn't matter whether the bits are on spinning rust or some other
+ * storage technology.
+ *
  * Portions Copyright (c) 1996-2013, PostgreSQL Global Development Group
  * Portions Copyright (c) 1994, Regents of the University of California
  *