From 0b8ace8d773257fffeaceda196ed94877c2b74df Mon Sep 17 00:00:00 2001 From: Peter Eisentraut <peter@eisentraut.org> Date: Fri, 19 May 2023 10:52:04 +0200 Subject: [PATCH] Reindent some comments Most (older) comments in md.c and smgr.c are indented with a leading tab on all lines, which isn't the current style and makes updating the comments a bit annoying. This reindents all these lines with a single space, as is the normal style. This issue exists in various shapes throughout the code but it's pretty consistent here, and since there is a patch pending to refresh some of the comments in these files, it seems sensible to clean this up here separately. Discussion: https://www.postgresql.org/message-id/flat/22fed8ba-01c3-2008-a256-4ea912d68fab%40enterprisedb.com --- src/backend/storage/smgr/md.c | 128 ++++++++++++------------- src/backend/storage/smgr/smgr.c | 162 ++++++++++++++++---------------- 2 files changed, 145 insertions(+), 145 deletions(-) diff --git a/src/backend/storage/smgr/md.c b/src/backend/storage/smgr/md.c index e982a8dd7f7..3d955aa72b3 100644 --- a/src/backend/storage/smgr/md.c +++ b/src/backend/storage/smgr/md.c @@ -42,41 +42,41 @@ #include "utils/memutils.h" /* - * The magnetic disk storage manager keeps track of open file - * descriptors in its own descriptor pool. This is done to make it - * easier to support relations that are larger than the operating - * system's file size limit (often 2GBytes). In order to do that, - * we break relations up into "segment" files that are each shorter than - * the OS file size limit. The segment size is set by the RELSEG_SIZE - * configuration constant in pg_config.h. + * The magnetic disk storage manager keeps track of open file + * descriptors in its own descriptor pool. This is done to make it + * easier to support relations that are larger than the operating + * system's file size limit (often 2GBytes). In order to do that, + * we break relations up into "segment" files that are each shorter than + * the OS file size limit. The segment size is set by the RELSEG_SIZE + * configuration constant in pg_config.h. * - * On disk, a relation must consist of consecutively numbered segment - * files in the pattern - * -- Zero or more full segments of exactly RELSEG_SIZE blocks each - * -- Exactly one partial segment of size 0 <= size < RELSEG_SIZE blocks - * -- Optionally, any number of inactive segments of size 0 blocks. - * The full and partial segments are collectively the "active" segments. - * Inactive segments are those that once contained data but are currently - * not needed because of an mdtruncate() operation. The reason for leaving - * them present at size zero, rather than unlinking them, is that other - * backends and/or the checkpointer might be holding open file references to - * such segments. If the relation expands again after mdtruncate(), such - * that a deactivated segment becomes active again, it is important that - * such file references still be valid --- else data might get written - * out to an unlinked old copy of a segment file that will eventually - * disappear. + * On disk, a relation must consist of consecutively numbered segment + * files in the pattern + * -- Zero or more full segments of exactly RELSEG_SIZE blocks each + * -- Exactly one partial segment of size 0 <= size < RELSEG_SIZE blocks + * -- Optionally, any number of inactive segments of size 0 blocks. + * The full and partial segments are collectively the "active" segments. + * Inactive segments are those that once contained data but are currently + * not needed because of an mdtruncate() operation. The reason for leaving + * them present at size zero, rather than unlinking them, is that other + * backends and/or the checkpointer might be holding open file references to + * such segments. If the relation expands again after mdtruncate(), such + * that a deactivated segment becomes active again, it is important that + * such file references still be valid --- else data might get written + * out to an unlinked old copy of a segment file that will eventually + * disappear. * - * File descriptors are stored in the per-fork md_seg_fds arrays inside - * SMgrRelation. The length of these arrays is stored in md_num_open_segs. - * Note that a fork's md_num_open_segs having a specific value does not - * necessarily mean the relation doesn't have additional segments; we may - * just not have opened the next segment yet. (We could not have "all - * segments are in the array" as an invariant anyway, since another backend - * could extend the relation while we aren't looking.) We do not have - * entries for inactive segments, however; as soon as we find a partial - * segment, we assume that any subsequent segments are inactive. + * File descriptors are stored in the per-fork md_seg_fds arrays inside + * SMgrRelation. The length of these arrays is stored in md_num_open_segs. + * Note that a fork's md_num_open_segs having a specific value does not + * necessarily mean the relation doesn't have additional segments; we may + * just not have opened the next segment yet. (We could not have "all + * segments are in the array" as an invariant anyway, since another backend + * could extend the relation while we aren't looking.) We do not have + * entries for inactive segments, however; as soon as we find a partial + * segment, we assume that any subsequent segments are inactive. * - * The entire MdfdVec array is palloc'd in the MdCxt memory context. + * The entire MdfdVec array is palloc'd in the MdCxt memory context. */ typedef struct _MdfdVec @@ -154,7 +154,7 @@ _mdfd_open_flags(void) } /* - * mdinit() -- Initialize private state for magnetic disk storage manager. + * mdinit() -- Initialize private state for magnetic disk storage manager. */ void mdinit(void) @@ -165,7 +165,7 @@ mdinit(void) } /* - * mdexists() -- Does the physical file exist? + * mdexists() -- Does the physical file exist? * * Note: this will return true for lingering files, with pending deletions */ @@ -184,7 +184,7 @@ mdexists(SMgrRelation reln, ForkNumber forknum) } /* - * mdcreate() -- Create a new relation on magnetic disk. + * mdcreate() -- Create a new relation on magnetic disk. * * If isRedo is true, it's okay for the relation to exist already. */ @@ -242,7 +242,7 @@ mdcreate(SMgrRelation reln, ForkNumber forknum, bool isRedo) } /* - * mdunlink() -- Unlink a relation. + * mdunlink() -- Unlink a relation. * * Note that we're passed a RelFileLocatorBackend --- by the time this is called, * there won't be an SMgrRelation hashtable entry anymore. @@ -447,13 +447,13 @@ mdunlinkfork(RelFileLocatorBackend rlocator, ForkNumber forknum, bool isRedo) } /* - * mdextend() -- Add a block to the specified relation. + * mdextend() -- Add a block to the specified relation. * - * The semantics are nearly the same as mdwrite(): write at the - * specified position. However, this is to be used for the case of - * extending a relation (i.e., blocknum is at or beyond the current - * EOF). Note that we assume writing a block beyond current EOF - * causes intervening file space to become filled with zeroes. + * The semantics are nearly the same as mdwrite(): write at the + * specified position. However, this is to be used for the case of + * extending a relation (i.e., blocknum is at or beyond the current + * EOF). Note that we assume writing a block beyond current EOF + * causes intervening file space to become filled with zeroes. */ void mdextend(SMgrRelation reln, ForkNumber forknum, BlockNumber blocknum, @@ -515,10 +515,10 @@ mdextend(SMgrRelation reln, ForkNumber forknum, BlockNumber blocknum, } /* - * mdzeroextend() -- Add new zeroed out blocks to the specified relation. + * mdzeroextend() -- Add new zeroed out blocks to the specified relation. * - * Similar to mdextend(), except the relation can be extended by multiple - * blocks at once and the added blocks will be filled with zeroes. + * Similar to mdextend(), except the relation can be extended by multiple + * blocks at once and the added blocks will be filled with zeroes. */ void mdzeroextend(SMgrRelation reln, ForkNumber forknum, @@ -623,7 +623,7 @@ mdzeroextend(SMgrRelation reln, ForkNumber forknum, } /* - * mdopenfork() -- Open one fork of the specified relation. + * mdopenfork() -- Open one fork of the specified relation. * * Note we only open the first segment, when there are multiple segments. * @@ -673,7 +673,7 @@ mdopenfork(SMgrRelation reln, ForkNumber forknum, int behavior) } /* - * mdopen() -- Initialize newly-opened relation. + * mdopen() -- Initialize newly-opened relation. */ void mdopen(SMgrRelation reln) @@ -684,7 +684,7 @@ mdopen(SMgrRelation reln) } /* - * mdclose() -- Close the specified relation, if it isn't closed already. + * mdclose() -- Close the specified relation, if it isn't closed already. */ void mdclose(SMgrRelation reln, ForkNumber forknum) @@ -707,7 +707,7 @@ mdclose(SMgrRelation reln, ForkNumber forknum) } /* - * mdprefetch() -- Initiate asynchronous read of the specified block of a relation + * mdprefetch() -- Initiate asynchronous read of the specified block of a relation */ bool mdprefetch(SMgrRelation reln, ForkNumber forknum, BlockNumber blocknum) @@ -791,7 +791,7 @@ mdwriteback(SMgrRelation reln, ForkNumber forknum, } /* - * mdread() -- Read the specified block from a relation. + * mdread() -- Read the specified block from a relation. */ void mdread(SMgrRelation reln, ForkNumber forknum, BlockNumber blocknum, @@ -856,11 +856,11 @@ mdread(SMgrRelation reln, ForkNumber forknum, BlockNumber blocknum, } /* - * mdwrite() -- Write the supplied block at the appropriate location. + * mdwrite() -- Write the supplied block at the appropriate location. * - * This is to be used only for updating already-existing blocks of a - * relation (ie, those before the current EOF). To extend a relation, - * use mdextend(). + * This is to be used only for updating already-existing blocks of a + * relation (ie, those before the current EOF). To extend a relation, + * use mdextend(). */ void mdwrite(SMgrRelation reln, ForkNumber forknum, BlockNumber blocknum, @@ -924,12 +924,12 @@ mdwrite(SMgrRelation reln, ForkNumber forknum, BlockNumber blocknum, } /* - * mdnblocks() -- Get the number of blocks stored in a relation. + * mdnblocks() -- Get the number of blocks stored in a relation. * - * Important side effect: all active segments of the relation are opened - * and added to the md_seg_fds array. If this routine has not been - * called, then only segments up to the last one actually touched - * are present in the array. + * Important side effect: all active segments of the relation are opened + * and added to the md_seg_fds array. If this routine has not been + * called, then only segments up to the last one actually touched + * are present in the array. */ BlockNumber mdnblocks(SMgrRelation reln, ForkNumber forknum) @@ -986,7 +986,7 @@ mdnblocks(SMgrRelation reln, ForkNumber forknum) } /* - * mdtruncate() -- Truncate relation to specified number of blocks. + * mdtruncate() -- Truncate relation to specified number of blocks. */ void mdtruncate(SMgrRelation reln, ForkNumber forknum, BlockNumber nblocks) @@ -1080,7 +1080,7 @@ mdtruncate(SMgrRelation reln, ForkNumber forknum, BlockNumber nblocks) } /* - * mdimmedsync() -- Immediately sync a relation to stable storage. + * mdimmedsync() -- Immediately sync a relation to stable storage. * * Note that only writes already issued are synced; this routine knows * nothing of dirty buffers that may exist inside the buffer manager. We @@ -1275,7 +1275,7 @@ DropRelationFiles(RelFileLocator *delrels, int ndelrels, bool isRedo) /* - * _fdvec_resize() -- Resize the fork's open segments array + * _fdvec_resize() -- Resize the fork's open segments array */ static void _fdvec_resize(SMgrRelation reln, @@ -1376,8 +1376,8 @@ _mdfd_openseg(SMgrRelation reln, ForkNumber forknum, BlockNumber segno, } /* - * _mdfd_getseg() -- Find the segment of the relation holding the - * specified block. + * _mdfd_getseg() -- Find the segment of the relation holding the + * specified block. * * If the segment doesn't exist, we ereport, return NULL, or create the * segment, according to "behavior". Note: skipFsync is only used in the diff --git a/src/backend/storage/smgr/smgr.c b/src/backend/storage/smgr/smgr.c index 70d0d570b1a..8a11090944a 100644 --- a/src/backend/storage/smgr/smgr.c +++ b/src/backend/storage/smgr/smgr.c @@ -104,8 +104,8 @@ static void smgrshutdown(int code, Datum arg); /* - * smgrinit(), smgrshutdown() -- Initialize or shut down storage - * managers. + * smgrinit(), smgrshutdown() -- Initialize or shut down storage + * managers. * * Note: smgrinit is called during backend startup (normal or standalone * case), *not* during postmaster start. Therefore, any resources created @@ -142,9 +142,9 @@ smgrshutdown(int code, Datum arg) } /* - * smgropen() -- Return an SMgrRelation object, creating it if need be. + * smgropen() -- Return an SMgrRelation object, creating it if need be. * - * This does not attempt to actually open the underlying file. + * This does not attempt to actually open the underlying file. */ SMgrRelation smgropen(RelFileLocator rlocator, BackendId backend) @@ -245,7 +245,7 @@ smgrclearowner(SMgrRelation *owner, SMgrRelation reln) } /* - * smgrexists() -- Does the underlying file for a fork exist? + * smgrexists() -- Does the underlying file for a fork exist? */ bool smgrexists(SMgrRelation reln, ForkNumber forknum) @@ -254,7 +254,7 @@ smgrexists(SMgrRelation reln, ForkNumber forknum) } /* - * smgrclose() -- Close and delete an SMgrRelation object. + * smgrclose() -- Close and delete an SMgrRelation object. */ void smgrclose(SMgrRelation reln) @@ -284,9 +284,9 @@ smgrclose(SMgrRelation reln) } /* - * smgrrelease() -- Release all resources used by this object. + * smgrrelease() -- Release all resources used by this object. * - * The object remains valid. + * The object remains valid. */ void smgrrelease(SMgrRelation reln) @@ -299,9 +299,9 @@ smgrrelease(SMgrRelation reln) } /* - * smgrreleaseall() -- Release resources used by all objects. + * smgrreleaseall() -- Release resources used by all objects. * - * This is called for PROCSIGNAL_BARRIER_SMGRRELEASE. + * This is called for PROCSIGNAL_BARRIER_SMGRRELEASE. */ void smgrreleaseall(void) @@ -320,7 +320,7 @@ smgrreleaseall(void) } /* - * smgrcloseall() -- Close all existing SMgrRelation objects. + * smgrcloseall() -- Close all existing SMgrRelation objects. */ void smgrcloseall(void) @@ -339,8 +339,8 @@ smgrcloseall(void) } /* - * smgrcloserellocator() -- Close SMgrRelation object for given RelFileLocator, - * if one exists. + * smgrcloserellocator() -- Close SMgrRelation object for given RelFileLocator, + * if one exists. * * This has the same effects as smgrclose(smgropen(rlocator)), but it avoids * uselessly creating a hashtable entry only to drop it again when no @@ -363,11 +363,11 @@ smgrcloserellocator(RelFileLocatorBackend rlocator) } /* - * smgrcreate() -- Create a new relation. + * smgrcreate() -- Create a new relation. * - * Given an already-created (but presumably unused) SMgrRelation, - * cause the underlying disk file or other storage for the fork - * to be created. + * Given an already-created (but presumably unused) SMgrRelation, + * cause the underlying disk file or other storage for the fork + * to be created. */ void smgrcreate(SMgrRelation reln, ForkNumber forknum, bool isRedo) @@ -376,13 +376,13 @@ smgrcreate(SMgrRelation reln, ForkNumber forknum, bool isRedo) } /* - * smgrdosyncall() -- Immediately sync all forks of all given relations + * smgrdosyncall() -- Immediately sync all forks of all given relations * - * All forks of all given relations are synced out to the store. + * All forks of all given relations are synced out to the store. * - * This is equivalent to FlushRelationBuffers() for each smgr relation, - * then calling smgrimmedsync() for all forks of each relation, but it's - * significantly quicker so should be preferred when possible. + * This is equivalent to FlushRelationBuffers() for each smgr relation, + * then calling smgrimmedsync() for all forks of each relation, but it's + * significantly quicker so should be preferred when possible. */ void smgrdosyncall(SMgrRelation *rels, int nrels) @@ -411,14 +411,14 @@ smgrdosyncall(SMgrRelation *rels, int nrels) } /* - * smgrdounlinkall() -- Immediately unlink all forks of all given relations + * smgrdounlinkall() -- Immediately unlink all forks of all given relations * - * All forks of all given relations are removed from the store. This - * should not be used during transactional operations, since it can't be - * undone. + * All forks of all given relations are removed from the store. This + * should not be used during transactional operations, since it can't be + * undone. * - * If isRedo is true, it is okay for the underlying file(s) to be gone - * already. + * If isRedo is true, it is okay for the underlying file(s) to be gone + * already. */ void smgrdounlinkall(SMgrRelation *rels, int nrels, bool isRedo) @@ -485,13 +485,13 @@ smgrdounlinkall(SMgrRelation *rels, int nrels, bool isRedo) /* - * smgrextend() -- Add a new block to a file. + * smgrextend() -- Add a new block to a file. * - * The semantics are nearly the same as smgrwrite(): write at the - * specified position. However, this is to be used for the case of - * extending a relation (i.e., blocknum is at or beyond the current - * EOF). Note that we assume writing a block beyond current EOF - * causes intervening file space to become filled with zeroes. + * The semantics are nearly the same as smgrwrite(): write at the + * specified position. However, this is to be used for the case of + * extending a relation (i.e., blocknum is at or beyond the current + * EOF). Note that we assume writing a block beyond current EOF + * causes intervening file space to become filled with zeroes. */ void smgrextend(SMgrRelation reln, ForkNumber forknum, BlockNumber blocknum, @@ -512,11 +512,11 @@ smgrextend(SMgrRelation reln, ForkNumber forknum, BlockNumber blocknum, } /* - * smgrzeroextend() -- Add new zeroed out blocks to a file. + * smgrzeroextend() -- Add new zeroed out blocks to a file. * - * Similar to smgrextend(), except the relation can be extended by - * multiple blocks at once and the added blocks will be filled with - * zeroes. + * Similar to smgrextend(), except the relation can be extended by + * multiple blocks at once and the added blocks will be filled with + * zeroes. */ void smgrzeroextend(SMgrRelation reln, ForkNumber forknum, BlockNumber blocknum, @@ -537,11 +537,11 @@ smgrzeroextend(SMgrRelation reln, ForkNumber forknum, BlockNumber blocknum, } /* - * smgrprefetch() -- Initiate asynchronous read of the specified block of a relation. + * smgrprefetch() -- Initiate asynchronous read of the specified block of a relation. * - * In recovery only, this can return false to indicate that a file - * doesn't exist (presumably it has been dropped by a later WAL - * record). + * In recovery only, this can return false to indicate that a file + * doesn't exist (presumably it has been dropped by a later WAL + * record). */ bool smgrprefetch(SMgrRelation reln, ForkNumber forknum, BlockNumber blocknum) @@ -550,12 +550,12 @@ smgrprefetch(SMgrRelation reln, ForkNumber forknum, BlockNumber blocknum) } /* - * smgrread() -- read a particular block from a relation into the supplied - * buffer. + * smgrread() -- read a particular block from a relation into the supplied + * buffer. * - * This routine is called from the buffer manager in order to - * instantiate pages in the shared buffer cache. All storage managers - * return pages in the format that POSTGRES expects. + * This routine is called from the buffer manager in order to + * instantiate pages in the shared buffer cache. All storage managers + * return pages in the format that POSTGRES expects. */ void smgrread(SMgrRelation reln, ForkNumber forknum, BlockNumber blocknum, @@ -565,19 +565,19 @@ smgrread(SMgrRelation reln, ForkNumber forknum, BlockNumber blocknum, } /* - * smgrwrite() -- Write the supplied buffer out. + * smgrwrite() -- Write the supplied buffer out. * - * This is to be used only for updating already-existing blocks of a - * relation (ie, those before the current EOF). To extend a relation, - * use smgrextend(). + * This is to be used only for updating already-existing blocks of a + * relation (ie, those before the current EOF). To extend a relation, + * use smgrextend(). * - * This is not a synchronous write -- the block is not necessarily - * on disk at return, only dumped out to the kernel. However, - * provisions will be made to fsync the write before the next checkpoint. + * This is not a synchronous write -- the block is not necessarily + * on disk at return, only dumped out to the kernel. However, + * provisions will be made to fsync the write before the next checkpoint. * - * skipFsync indicates that the caller will make other provisions to - * fsync the relation, so we needn't bother. Temporary relations also - * do not require fsync. + * skipFsync indicates that the caller will make other provisions to + * fsync the relation, so we needn't bother. Temporary relations also + * do not require fsync. */ void smgrwrite(SMgrRelation reln, ForkNumber forknum, BlockNumber blocknum, @@ -589,7 +589,7 @@ smgrwrite(SMgrRelation reln, ForkNumber forknum, BlockNumber blocknum, /* - * smgrwriteback() -- Trigger kernel writeback for the supplied range of + * smgrwriteback() -- Trigger kernel writeback for the supplied range of * blocks. */ void @@ -601,8 +601,8 @@ smgrwriteback(SMgrRelation reln, ForkNumber forknum, BlockNumber blocknum, } /* - * smgrnblocks() -- Calculate the number of blocks in the - * supplied relation. + * smgrnblocks() -- Calculate the number of blocks in the + * supplied relation. */ BlockNumber smgrnblocks(SMgrRelation reln, ForkNumber forknum) @@ -622,8 +622,8 @@ smgrnblocks(SMgrRelation reln, ForkNumber forknum) } /* - * smgrnblocks_cached() -- Get the cached number of blocks in the supplied - * relation. + * smgrnblocks_cached() -- Get the cached number of blocks in the supplied + * relation. * * Returns an InvalidBlockNumber when not in recovery and when the relation * fork size is not cached. @@ -642,8 +642,8 @@ smgrnblocks_cached(SMgrRelation reln, ForkNumber forknum) } /* - * smgrtruncate() -- Truncate the given forks of supplied relation to - * each specified numbers of blocks + * smgrtruncate() -- Truncate the given forks of supplied relation to + * each specified numbers of blocks * * The truncation is done immediately, so this can't be rolled back. * @@ -694,27 +694,27 @@ smgrtruncate(SMgrRelation reln, ForkNumber *forknum, int nforks, BlockNumber *nb } /* - * smgrimmedsync() -- Force the specified relation to stable storage. + * smgrimmedsync() -- Force the specified relation to stable storage. * - * Synchronously force all previous writes to the specified relation - * down to disk. + * Synchronously force all previous writes to the specified relation + * down to disk. * - * This is useful for building completely new relations (eg, new - * indexes). Instead of incrementally WAL-logging the index build - * steps, we can just write completed index pages to disk with smgrwrite - * or smgrextend, and then fsync the completed index file before - * committing the transaction. (This is sufficient for purposes of - * crash recovery, since it effectively duplicates forcing a checkpoint - * for the completed index. But it is *not* sufficient if one wishes - * to use the WAL log for PITR or replication purposes: in that case - * we have to make WAL entries as well.) + * This is useful for building completely new relations (eg, new + * indexes). Instead of incrementally WAL-logging the index build + * steps, we can just write completed index pages to disk with smgrwrite + * or smgrextend, and then fsync the completed index file before + * committing the transaction. (This is sufficient for purposes of + * crash recovery, since it effectively duplicates forcing a checkpoint + * for the completed index. But it is *not* sufficient if one wishes + * to use the WAL log for PITR or replication purposes: in that case + * we have to make WAL entries as well.) * - * The preceding writes should specify skipFsync = true to avoid - * duplicative fsyncs. + * The preceding writes should specify skipFsync = true to avoid + * duplicative fsyncs. * - * Note that you need to do FlushRelationBuffers() first if there is - * any possibility that there are dirty buffers for the relation; - * otherwise the sync is not very meaningful. + * Note that you need to do FlushRelationBuffers() first if there is + * any possibility that there are dirty buffers for the relation; + * otherwise the sync is not very meaningful. */ void smgrimmedsync(SMgrRelation reln, ForkNumber forknum)