Refine the guidelines for rmgrdesc authors.

Clarify the goals of the recently added guidelines for rmgrdesc authors:
to avoid gratuitous inconsistencies across resource managers, and to
make it reasonably easy to write a reusable custom parser.

Beyond that, the guidelines leave rmgrdesc authors with a significant
amount of leeway.  This even includes the leeway to invent custom
conventions (in cases where it's warranted).

Follow-up to commit 7d8219a4.

Author: Peter Geoghegan <pg@bowt.ie>
Reviewed-By: Melanie Plageman <melanieplageman@gmail.com>
Discussion: https://postgr.es/m/CAH2-WzkbYuvwYKm-Y-72QEh6SPMQcAo9uONv+mR3bMGcu9E_Cg@mail.gmail.com
This commit is contained in:
Peter Geoghegan 2023-04-11 15:26:24 -07:00
parent 96149a180d
commit c03c2eae0a
2 changed files with 44 additions and 20 deletions

View File

@ -16,26 +16,6 @@
#include "access/rmgrdesc_utils.h"
#include "storage/off.h"
/*
* Guidelines for formatting desc functions:
*
* member1_name: member1_value, member2_name: member2_value
*
* If the value is a list, please use:
*
* member3_name: [ member3_list_value1, member3_list_value2 ]
*
* The first item appended to the string should not be prepended by any spaces
* or comma, however all subsequent appends to the string are responsible for
* prepending themselves with a comma followed by a space.
*
* Flags should be in ALL CAPS.
*
* For lists/arrays of items, the number of those items should be listed at
* the beginning with all of the other numbers.
*
* Composite objects in a list should be surrounded with { }.
*/
void
array_desc(StringInfo buf, void *array, size_t elem_size, int count,
void (*elem_desc) (StringInfo buf, void *elem, void *data),

View File

@ -12,6 +12,50 @@
#ifndef RMGRDESC_UTILS_H_
#define RMGRDESC_UTILS_H_
/*
* Guidelines for rmgrdesc routine authors:
*
* The goal of these guidelines is to avoid gratuitous inconsistencies across
* each rmgr, and to allow users to parse desc output strings without too much
* difficulty. This is not an API specification or an interchange format.
* (Only heapam and nbtree desc routines follow these guidelines at present,
* in any case.)
*
* Record descriptions are similar to JSON style key/value objects. However,
* there is no explicit "string" type/string escaping. Top-level { } brackets
* should be omitted. For example:
*
* snapshotConflictHorizon: 0, flags: 0x03
*
* Record descriptions may contain variable-length arrays. For example:
*
* nunused: 5, unused: [1, 2, 3, 4, 5]
*
* Nested objects are supported via { } brackets. They generally appear
* inside variable-length arrays. For example:
*
* ndeleted: 0, nupdated: 1, deleted: [], updated: [{ off: 45, nptids: 1, ptids: [0] }]
*
* Try to output things in an order that faithfully represents the order of
* fields from the underlying physical WAL record struct. Key names should be
* unique (at the same nesting level) to make parsing easy. It's a good idea
* if the number of items in the array appears before the array.
*
* It's okay for individual WAL record types to invent their own conventions.
* For example, Heap2's PRUNE record descriptions use a custom array format
* for the record's "redirected" field:
*
* ... redirected: [1->4, 5->9], dead: [10, 11], unused: [3, 7, 8]
*
* Arguably the desc routine should be using object notation for this instead.
* However, there is value in using a custom format when it conveys useful
* information about the underlying physical data structures.
*
* This ad-hoc format has the advantage of being close to the format used for
* the "dead" and "unused" arrays (which follow the standard desc convention
* for page offset number arrays). It suggests that the "redirected" elements
* shown are just pairs of page offset numbers (which is how it really works).
*/
extern void array_desc(StringInfo buf, void *array, size_t elem_size, int count,
void (*elem_desc) (StringInfo buf, void *elem, void *data),
void *data);