codekingpro/portable-devtools

1/*-------------------------------------------------------------------------2 *3 * rmgrdesc_utils.h4 *	  Support functions for rmgrdesc routines5 *6 * Copyright (c) 2023, PostgreSQL Global Development Group7 *8 * src/include/access/rmgrdesc_utils.h9 *10 *-------------------------------------------------------------------------11 */12#ifndef RMGRDESC_UTILS_H_13#define RMGRDESC_UTILS_H_14 15/*16 * Guidelines for rmgrdesc routine authors:17 *18 * The goal of these guidelines is to avoid gratuitous inconsistencies across19 * each rmgr, and to allow users to parse desc output strings without too much20 * difficulty.  This is not an API specification or an interchange format.21 * (Only heapam and nbtree desc routines follow these guidelines at present,22 * in any case.)23 *24 * Record descriptions are similar to JSON style key/value objects.  However,25 * there is no explicit "string" type/string escaping.  Top-level { } brackets26 * should be omitted.  For example:27 *28 * snapshotConflictHorizon: 0, flags: 0x0329 *30 * Record descriptions may contain variable-length arrays.  For example:31 *32 * nunused: 5, unused: [1, 2, 3, 4, 5]33 *34 * Nested objects are supported via { } brackets.  They generally appear35 * inside variable-length arrays.  For example:36 *37 * ndeleted: 0, nupdated: 1, deleted: [], updated: [{ off: 45, nptids: 1, ptids: [0] }]38 *39 * Try to output things in an order that faithfully represents the order of40 * fields from the underlying physical WAL record struct.  Key names should be41 * unique (at the same nesting level) to make parsing easy.  It's a good idea42 * if the number of items in the array appears before the array.43 *44 * It's okay for individual WAL record types to invent their own conventions.45 * For example, Heap2's PRUNE record descriptions use a custom array format46 * for the record's "redirected" field:47 *48 * ... redirected: [1->4, 5->9], dead: [10, 11], unused: [3, 7, 8]49 *50 * Arguably the desc routine should be using object notation for this instead.51 * However, there is value in using a custom format when it conveys useful52 * information about the underlying physical data structures.53 *54 * This ad-hoc format has the advantage of being close to the format used for55 * the "dead" and "unused" arrays (which follow the standard desc convention56 * for page offset number arrays).  It suggests that the "redirected" elements57 * shown are just pairs of page offset numbers (which is how it really works).58 */59extern void array_desc(StringInfo buf, void *array, size_t elem_size, int count,60					   void (*elem_desc) (StringInfo buf, void *elem, void *data),61					   void *data);62extern void offset_elem_desc(StringInfo buf, void *offset, void *data);63extern void redirect_elem_desc(StringInfo buf, void *offset, void *data);64extern void oid_elem_desc(StringInfo buf, void *relid, void *data);65 66#endif							/* RMGRDESC_UTILS_H_ */67