Movatterモバイル変換

[0]ホーム
URL:

Skip to content

Navigation Menu

Sign in
Appearance settings

Search code, repositories, users, issues, pull requests...

Provide feedback

We read every piece of feedback, and take your input very seriously.

Saved searches

Use saved searches to filter your results more quickly

 Sign up
Appearance settings

Commitc03c2ea

Browse files
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 tomake it reasonably easy to write a reusable custom parser.Beyond that, the guidelines leave rmgrdesc authors with a significantamount of leeway. This even includes the leeway to invent customconventions (in cases where it's warranted).Follow-up to commit7d8219a.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
1 parent96149a1 commitc03c2ea

File tree

2 files changed

+44
-20
lines changed

2 files changed

+44
-20
lines changed

‎src/backend/access/rmgrdesc/rmgrdesc_utils.c

Lines changed: 0 additions & 20 deletions
Original file line numberDiff line numberDiff line change
@@ -16,26 +16,6 @@
1616
#include"access/rmgrdesc_utils.h"
1717
#include"storage/off.h"
1818

19-
/*
20-
* Guidelines for formatting desc functions:
21-
*
22-
* member1_name: member1_value, member2_name: member2_value
23-
*
24-
* If the value is a list, please use:
25-
*
26-
* member3_name: [ member3_list_value1, member3_list_value2 ]
27-
*
28-
* The first item appended to the string should not be prepended by any spaces
29-
* or comma, however all subsequent appends to the string are responsible for
30-
* prepending themselves with a comma followed by a space.
31-
*
32-
* Flags should be in ALL CAPS.
33-
*
34-
* For lists/arrays of items, the number of those items should be listed at
35-
* the beginning with all of the other numbers.
36-
*
37-
* Composite objects in a list should be surrounded with { }.
38-
*/
3919
void
4020
array_desc(StringInfobuf,void*array,size_telem_size,intcount,
4121
void (*elem_desc) (StringInfobuf,void*elem,void*data),

‎src/include/access/rmgrdesc_utils.h

Lines changed: 44 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -12,6 +12,50 @@
1212
#ifndefRMGRDESC_UTILS_H_
1313
#defineRMGRDESC_UTILS_H_
1414

15+
/*
16+
* Guidelines for rmgrdesc routine authors:
17+
*
18+
* The goal of these guidelines is to avoid gratuitous inconsistencies across
19+
* each rmgr, and to allow users to parse desc output strings without too much
20+
* 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 { } brackets
26+
* should be omitted. For example:
27+
*
28+
* snapshotConflictHorizon: 0, flags: 0x03
29+
*
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 appear
35+
* 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 of
40+
* fields from the underlying physical WAL record struct. Key names should be
41+
* unique (at the same nesting level) to make parsing easy. It's a good idea
42+
* 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 format
46+
* 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 useful
52+
* information about the underlying physical data structures.
53+
*
54+
* This ad-hoc format has the advantage of being close to the format used for
55+
* the "dead" and "unused" arrays (which follow the standard desc convention
56+
* for page offset number arrays). It suggests that the "redirected" elements
57+
* shown are just pairs of page offset numbers (which is how it really works).
58+
*/
1559
externvoidarray_desc(StringInfobuf,void*array,size_telem_size,intcount,
1660
void (*elem_desc) (StringInfobuf,void*elem,void*data),
1761
void*data);

0 commit comments

Comments
 (0)
[8]ページ先頭
©2009-2025 Movatter.jp