Age Owner Branch data TLA Line data Source code
1 : : /*-------------------------------------------------------------------------
2 : : *
3 : : * basebackup_sink.h
4 : : * API for filtering or sending to a final destination the archives
5 : : * produced by the base backup process
6 : : *
7 : : * Taking a base backup produces one archive per tablespace directory,
8 : : * plus a backup manifest unless that feature has been disabled. The
9 : : * goal of the backup process is to put those archives and that manifest
10 : : * someplace, possibly after postprocessing them in some way. A 'bbsink'
11 : : * is an object to which those archives, and the manifest if present,
12 : : * can be sent.
13 : : *
14 : : * In practice, there will be a chain of 'bbsink' objects rather than
15 : : * just one, with callbacks being forwarded from one to the next,
16 : : * possibly with modification. Each object is responsible for a
17 : : * single task e.g. command progress reporting, throttling, or
18 : : * communication with the client.
19 : : *
20 : : * Portions Copyright (c) 2010-2026, PostgreSQL Global Development Group
21 : : *
22 : : * src/include/backup/basebackup_sink.h
23 : : *
24 : : *-------------------------------------------------------------------------
25 : : */
26 : : #ifndef BASEBACKUP_SINK_H
27 : : #define BASEBACKUP_SINK_H
28 : :
29 : : #include "access/xlogdefs.h"
30 : : #include "common/compression.h"
31 : : #include "nodes/pg_list.h"
32 : :
33 : : /* Forward declarations. */
34 : : struct bbsink;
35 : : struct bbsink_ops;
36 : : typedef struct bbsink bbsink;
37 : : typedef struct bbsink_ops bbsink_ops;
38 : :
39 : : /*
40 : : * Overall backup state shared by all bbsink objects for a backup.
41 : : *
42 : : * Before calling bbstate_begin_backup, caller must initiate a bbsink_state
43 : : * object which will last for the lifetime of the backup, and must thereafter
44 : : * update it as required before each new call to a bbsink method. The bbsink
45 : : * will retain a pointer to the state object and will consult it to understand
46 : : * the progress of the backup.
47 : : *
48 : : * 'tablespaces' is a list of tablespaceinfo objects. It must be set before
49 : : * calling bbstate_begin_backup() and must not be modified thereafter.
50 : : *
51 : : * 'tablespace_num' is the index of the current tablespace within the list
52 : : * stored in 'tablespaces'.
53 : : *
54 : : * 'bytes_done' is the number of bytes of archive data generated so far. This
55 : : * is counted before any server-side compression.
56 : : *
57 : : * 'bytes_total' is the total number of bytes of archive data estimated to be
58 : : * generated, if we have estimated this. The estimate is for data before any
59 : : * server-side compression.
60 : : *
61 : : * 'bytes_total_is_valid' is true if and only if a proper estimate has been
62 : : * stored into 'bytes_total'.
63 : : *
64 : : * 'startptr' and 'starttli' identify the point in the WAL stream at which
65 : : * the backup began. They must be set before calling bbstate_begin_backup()
66 : : * and must not be modified thereafter.
67 : : */
68 : : typedef struct bbsink_state
69 : : {
70 : : List *tablespaces;
71 : : int tablespace_num;
72 : : uint64 bytes_done;
73 : : uint64 bytes_total;
74 : : bool bytes_total_is_valid;
75 : : XLogRecPtr startptr;
76 : : TimeLineID starttli;
77 : : } bbsink_state;
78 : :
79 : : /*
80 : : * Common data for any type of basebackup sink.
81 : : *
82 : : * 'bbs_ops' is the relevant callback table.
83 : : *
84 : : * 'bbs_buffer' is the buffer into which data destined for the bbsink
85 : : * should be stored. It must be a multiple of BLCKSZ.
86 : : *
87 : : * 'bbs_buffer_length' is the allocated length of the buffer.
88 : : *
89 : : * 'bbs_next' is a pointer to another bbsink to which this bbsink is
90 : : * forwarding some or all operations.
91 : : *
92 : : * 'bbs_state' is a pointer to the bbsink_state object for this backup.
93 : : * Every bbsink associated with this backup should point to the same
94 : : * underlying state object.
95 : : *
96 : : * In general it is expected that the values of these fields are set when
97 : : * a bbsink is created and that they do not change thereafter. It's OK
98 : : * to modify the data to which bbs_buffer or bbs_state point, but no changes
99 : : * should be made to the contents of this struct.
100 : : */
101 : : struct bbsink
102 : : {
103 : : const bbsink_ops *bbs_ops;
104 : : char *bbs_buffer;
105 : : size_t bbs_buffer_length;
106 : : bbsink *bbs_next;
107 : : bbsink_state *bbs_state;
108 : : };
109 : :
110 : : /*
111 : : * Callbacks for a base backup sink.
112 : : *
113 : : * All of these callbacks are required. If a particular callback just needs to
114 : : * forward the call to sink->bbs_next, use bbsink_forward_<callback_name> as
115 : : * the callback.
116 : : *
117 : : * Callers should always invoke these callbacks via the bbsink_* inline
118 : : * functions rather than calling them directly.
119 : : */
120 : : struct bbsink_ops
121 : : {
122 : : /*
123 : : * This callback is invoked just once, at the very start of the backup. It
124 : : * must set bbs_buffer to point to a chunk of storage where at least
125 : : * bbs_buffer_length bytes of data can be written.
126 : : */
127 : : void (*begin_backup) (bbsink *sink);
128 : :
129 : : /*
130 : : * For each archive transmitted to a bbsink, there will be one call to the
131 : : * begin_archive() callback, some number of calls to the
132 : : * archive_contents() callback, and then one call to the end_archive()
133 : : * callback.
134 : : *
135 : : * Before invoking the archive_contents() callback, the caller should copy
136 : : * a number of bytes equal to what will be passed as len into bbs_buffer,
137 : : * but not more than bbs_buffer_length.
138 : : *
139 : : * It's generally good if the buffer is as full as possible before the
140 : : * archive_contents() callback is invoked, but it's not worth expending
141 : : * extra cycles to make sure it's absolutely 100% full.
142 : : */
143 : : void (*begin_archive) (bbsink *sink, const char *archive_name);
144 : : void (*archive_contents) (bbsink *sink, size_t len);
145 : : void (*end_archive) (bbsink *sink);
146 : :
147 : : /*
148 : : * If a backup manifest is to be transmitted to a bbsink, there will be
149 : : * one call to the begin_manifest() callback, some number of calls to the
150 : : * manifest_contents() callback, and then one call to the end_manifest()
151 : : * callback. These calls will occur after all archives are transmitted.
152 : : *
153 : : * The rules for invoking the manifest_contents() callback are the same as
154 : : * for the archive_contents() callback above.
155 : : */
156 : : void (*begin_manifest) (bbsink *sink);
157 : : void (*manifest_contents) (bbsink *sink, size_t len);
158 : : void (*end_manifest) (bbsink *sink);
159 : :
160 : : /*
161 : : * This callback is invoked just once, after all archives and the manifest
162 : : * have been sent.
163 : : */
164 : : void (*end_backup) (bbsink *sink, XLogRecPtr endptr, TimeLineID endtli);
165 : :
166 : : /*
167 : : * If a backup is aborted by an error, this callback is invoked before the
168 : : * bbsink object is destroyed, so that it can release any resources that
169 : : * would not be released automatically. If no error occurs, this callback
170 : : * is invoked after the end_backup callback.
171 : : */
172 : : void (*cleanup) (bbsink *sink);
173 : : };
174 : :
175 : : /* Begin a backup. */
176 : : static inline void
1826 rhaas@postgresql.org 177 :CBC 406 : bbsink_begin_backup(bbsink *sink, bbsink_state *state, int buffer_length)
178 : : {
179 [ - + ]: 406 : Assert(sink != NULL);
180 : :
181 [ - + ]: 406 : Assert(buffer_length > 0);
182 : :
183 : 406 : sink->bbs_state = state;
184 : 406 : sink->bbs_buffer_length = buffer_length;
185 : 406 : sink->bbs_ops->begin_backup(sink);
186 : :
187 [ - + ]: 406 : Assert(sink->bbs_buffer != NULL);
188 [ - + ]: 406 : Assert((sink->bbs_buffer_length % BLCKSZ) == 0);
189 : 406 : }
190 : :
191 : : /* Begin an archive. */
192 : : static inline void
193 : 489 : bbsink_begin_archive(bbsink *sink, const char *archive_name)
194 : : {
195 [ - + ]: 489 : Assert(sink != NULL);
196 : :
197 : 489 : sink->bbs_ops->begin_archive(sink, archive_name);
198 : 489 : }
199 : :
200 : : /* Process some of the contents of an archive. */
201 : : static inline void
202 : 903053 : bbsink_archive_contents(bbsink *sink, size_t len)
203 : : {
204 [ - + ]: 903053 : Assert(sink != NULL);
205 : :
206 : : /*
207 : : * The caller should make a reasonable attempt to fill the buffer before
208 : : * calling this function, so it shouldn't be completely empty. Nor should
209 : : * it be filled beyond capacity.
210 : : */
211 [ + - - + ]: 903053 : Assert(len > 0 && len <= sink->bbs_buffer_length);
212 : :
213 : 903053 : sink->bbs_ops->archive_contents(sink, len);
214 : 903053 : }
215 : :
216 : : /* Finish an archive. */
217 : : static inline void
218 : 478 : bbsink_end_archive(bbsink *sink)
219 : : {
220 [ - + ]: 478 : Assert(sink != NULL);
221 : :
222 : 478 : sink->bbs_ops->end_archive(sink);
223 : 478 : }
224 : :
225 : : /* Begin the backup manifest. */
226 : : static inline void
227 : 393 : bbsink_begin_manifest(bbsink *sink)
228 : : {
229 [ - + ]: 393 : Assert(sink != NULL);
230 : :
231 : 393 : sink->bbs_ops->begin_manifest(sink);
232 : 393 : }
233 : :
234 : : /* Process some of the manifest contents. */
235 : : static inline void
236 : 2021 : bbsink_manifest_contents(bbsink *sink, size_t len)
237 : : {
238 [ - + ]: 2021 : Assert(sink != NULL);
239 : :
240 : : /* See comments in bbsink_archive_contents. */
241 [ + - - + ]: 2021 : Assert(len > 0 && len <= sink->bbs_buffer_length);
242 : :
243 : 2021 : sink->bbs_ops->manifest_contents(sink, len);
244 : 2021 : }
245 : :
246 : : /* Finish the backup manifest. */
247 : : static inline void
248 : 393 : bbsink_end_manifest(bbsink *sink)
249 : : {
250 [ - + ]: 393 : Assert(sink != NULL);
251 : :
252 : 393 : sink->bbs_ops->end_manifest(sink);
253 : 393 : }
254 : :
255 : : /* Finish a backup. */
256 : : static inline void
257 : 395 : bbsink_end_backup(bbsink *sink, XLogRecPtr endptr, TimeLineID endtli)
258 : : {
259 [ - + ]: 395 : Assert(sink != NULL);
260 [ - + ]: 395 : Assert(sink->bbs_state->tablespace_num == list_length(sink->bbs_state->tablespaces));
261 : :
262 : 395 : sink->bbs_ops->end_backup(sink, endptr, endtli);
263 : 395 : }
264 : :
265 : : /* Release resources before destruction. */
266 : : static inline void
267 : 391 : bbsink_cleanup(bbsink *sink)
268 : : {
269 [ - + ]: 391 : Assert(sink != NULL);
270 : :
271 : 391 : sink->bbs_ops->cleanup(sink);
272 : 391 : }
273 : :
274 : : /* Forwarding callbacks. Use these to pass operations through to next sink. */
275 : : extern void bbsink_forward_begin_backup(bbsink *sink);
276 : : extern void bbsink_forward_begin_archive(bbsink *sink,
277 : : const char *archive_name);
278 : : extern void bbsink_forward_archive_contents(bbsink *sink, size_t len);
279 : : extern void bbsink_forward_end_archive(bbsink *sink);
280 : : extern void bbsink_forward_begin_manifest(bbsink *sink);
281 : : extern void bbsink_forward_manifest_contents(bbsink *sink, size_t len);
282 : : extern void bbsink_forward_end_manifest(bbsink *sink);
283 : : extern void bbsink_forward_end_backup(bbsink *sink, XLogRecPtr endptr,
284 : : TimeLineID endtli);
285 : : extern void bbsink_forward_cleanup(bbsink *sink);
286 : :
287 : : /* Constructors for various types of sinks. */
288 : : extern bbsink *bbsink_copystream_new(bool send_to_client);
289 : : extern bbsink *bbsink_gzip_new(bbsink *next, pg_compress_specification *);
290 : : extern bbsink *bbsink_lz4_new(bbsink *next, pg_compress_specification *);
291 : : extern bbsink *bbsink_zstd_new(bbsink *next, pg_compress_specification *);
292 : : extern bbsink *bbsink_progress_new(bbsink *next, bool estimate_backup_size,
293 : : bool incremental);
294 : : extern bbsink *bbsink_server_new(bbsink *next, char *pathname);
295 : : extern bbsink *bbsink_throttle_new(bbsink *next, uint32 maxrate);
296 : :
297 : : /* Extra interface functions for progress reporting. */
298 : : extern void basebackup_progress_wait_checkpoint(void);
299 : : extern void basebackup_progress_estimate_backup_size(void);
300 : : extern void basebackup_progress_wait_wal_archive(bbsink_state *);
301 : : extern void basebackup_progress_transfer_wal(void);
302 : :
303 : : #endif
|
