begriffs open source - ai-pg/blob - full-docs/txt/generic-wal.txt

   1
   2 64.1. Generic WAL Records #
   3
   4    Although all built-in WAL-logged modules have their own types of WAL
   5    records, there is also a generic WAL record type, which describes
   6    changes to pages in a generic way.
   7
   8 Note
   9
  10    Generic WAL records are ignored during Logical Decoding. If logical
  11    decoding is required for your extension, consider a Custom WAL Resource
  12    Manager.
  13
  14    The API for constructing generic WAL records is defined in
  15    access/generic_xlog.h and implemented in access/transam/generic_xlog.c.
  16
  17    To perform a WAL-logged data update using the generic WAL record
  18    facility, follow these steps:
  19     1. state = GenericXLogStart(relation) — start construction of a
  20        generic WAL record for the given relation.
  21     2. page = GenericXLogRegisterBuffer(state, buffer, flags) — register a
  22        buffer to be modified within the current generic WAL record. This
  23        function returns a pointer to a temporary copy of the buffer's
  24        page, where modifications should be made. (Do not modify the
  25        buffer's contents directly.) The third argument is a bit mask of
  26        flags applicable to the operation. Currently the only such flag is
  27        GENERIC_XLOG_FULL_IMAGE, which indicates that a full-page image
  28        rather than a delta update should be included in the WAL record.
  29        Typically this flag would be set if the page is new or has been
  30        rewritten completely. GenericXLogRegisterBuffer can be repeated if
  31        the WAL-logged action needs to modify multiple pages.
  32     3. Apply modifications to the page images obtained in the previous
  33        step.
  34     4. GenericXLogFinish(state) — apply the changes to the buffers and
  35        emit the generic WAL record.
  36
  37    WAL record construction can be canceled between any of the above steps
  38    by calling GenericXLogAbort(state). This will discard all changes to
  39    the page image copies.
  40
  41    Please note the following points when using the generic WAL record
  42    facility:
  43      * No direct modifications of buffers are allowed! All modifications
  44        must be done in copies acquired from GenericXLogRegisterBuffer().
  45        In other words, code that makes generic WAL records should never
  46        call BufferGetPage() for itself. However, it remains the caller's
  47        responsibility to pin/unpin and lock/unlock the buffers at
  48        appropriate times. Exclusive lock must be held on each target
  49        buffer from before GenericXLogRegisterBuffer() until after
  50        GenericXLogFinish().
  51      * Registrations of buffers (step 2) and modifications of page images
  52        (step 3) can be mixed freely, i.e., both steps may be repeated in
  53        any sequence. Keep in mind that buffers should be registered in the
  54        same order in which locks are to be obtained on them during replay.
  55      * The maximum number of buffers that can be registered for a generic
  56        WAL record is MAX_GENERIC_XLOG_PAGES. An error will be thrown if
  57        this limit is exceeded.
  58      * Generic WAL assumes that the pages to be modified have standard
  59        layout, and in particular that there is no useful data between
  60        pd_lower and pd_upper.
  61      * Since you are modifying copies of buffer pages, GenericXLogStart()
  62        does not start a critical section. Thus, you can safely do memory
  63        allocation, error throwing, etc. between GenericXLogStart() and
  64        GenericXLogFinish(). The only actual critical section is present
  65        inside GenericXLogFinish(). There is no need to worry about calling
  66        GenericXLogAbort() during an error exit, either.
  67      * GenericXLogFinish() takes care of marking buffers dirty and setting
  68        their LSNs. You do not need to do this explicitly.
  69      * For unlogged relations, everything works the same except that no
  70        actual WAL record is emitted. Thus, you typically do not need to do
  71        any explicit checks for unlogged relations.
  72      * The generic WAL redo function will acquire exclusive locks to
  73        buffers in the same order as they were registered. After redoing
  74        all changes, the locks will be released in the same order.
  75      * If GENERIC_XLOG_FULL_IMAGE is not specified for a registered
  76        buffer, the generic WAL record contains a delta between the old and
  77        the new page images. This delta is based on byte-by-byte
  78        comparison. This is not very compact for the case of moving data
  79        within a page, and might be improved in the future.