From c03c2eae0acbb82db8e626f71f367ef4b043d27d Mon Sep 17 00:00:00 2001 From: Peter Geoghegan Date: Tue, 11 Apr 2023 15:26:24 -0700 Subject: [PATCH] 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 Reviewed-By: Melanie Plageman Discussion: https://postgr.es/m/CAH2-WzkbYuvwYKm-Y-72QEh6SPMQcAo9uONv+mR3bMGcu9E_Cg@mail.gmail.com --- src/backend/access/rmgrdesc/rmgrdesc_utils.c | 20 --------- src/include/access/rmgrdesc_utils.h | 44 ++++++++++++++++++++ 2 files changed, 44 insertions(+), 20 deletions(-) diff --git a/src/backend/access/rmgrdesc/rmgrdesc_utils.c b/src/backend/access/rmgrdesc/rmgrdesc_utils.c index 3d16b1fcba..90051f0df9 100644 --- a/src/backend/access/rmgrdesc/rmgrdesc_utils.c +++ b/src/backend/access/rmgrdesc/rmgrdesc_utils.c @@ -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), diff --git a/src/include/access/rmgrdesc_utils.h b/src/include/access/rmgrdesc_utils.h index 00e6146490..e09b112674 100644 --- a/src/include/access/rmgrdesc_utils.h +++ b/src/include/access/rmgrdesc_utils.h @@ -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);