PostgreSQL Source Code git master
logtape.h
Go to the documentation of this file.
1/*-------------------------------------------------------------------------
2 *
3 * logtape.h
4 * Management of "logical tapes" within temporary files.
5 *
6 * See logtape.c for explanations.
7 *
8 * Portions Copyright (c) 1996-2025, PostgreSQL Global Development Group
9 * Portions Copyright (c) 1994, Regents of the University of California
10 *
11 * src/include/utils/logtape.h
12 *
13 *-------------------------------------------------------------------------
14 */
15
16#ifndef LOGTAPE_H
17#define LOGTAPE_H
18
20
21/*
22 * LogicalTapeSet and LogicalTape are opaque types whose details are not
23 * known outside logtape.c.
24 */
26typedef struct LogicalTape LogicalTape;
27
28
29/*
30 * The approach tuplesort.c takes to parallel external sorts is that workers,
31 * whose state is almost the same as independent serial sorts, are made to
32 * produce a final materialized tape of sorted output in all cases. This is
33 * frozen, just like any case requiring a final materialized tape. However,
34 * there is one difference, which is that freezing will also export an
35 * underlying shared fileset BufFile for sharing. Freezing produces TapeShare
36 * metadata for the worker when this happens, which is passed along through
37 * shared memory to leader.
38 *
39 * The leader process can then pass an array of TapeShare metadata (one per
40 * worker participant) to LogicalTapeSetCreate(), alongside a handle to a
41 * shared fileset, which is sufficient to construct a new logical tapeset that
42 * consists of each of the tapes materialized by workers.
43 *
44 * Note that while logtape.c does create an empty leader tape at the end of the
45 * tapeset in the leader case, it can never be written to due to a restriction
46 * in the shared buffile infrastructure.
47 */
48typedef struct TapeShare
49{
50 /*
51 * Currently, all the leader process needs is the location of the
52 * materialized tape's first block.
53 */
56
57/*
58 * prototypes for functions in logtape.c
59 */
60
61extern LogicalTapeSet *LogicalTapeSetCreate(bool preallocate,
62 SharedFileSet *fileset, int worker);
63extern void LogicalTapeClose(LogicalTape *lt);
64extern void LogicalTapeSetClose(LogicalTapeSet *lts);
66extern LogicalTape *LogicalTapeImport(LogicalTapeSet *lts, int worker, TapeShare *shared);
68extern size_t LogicalTapeRead(LogicalTape *lt, void *ptr, size_t size);
69extern void LogicalTapeWrite(LogicalTape *lt, const void *ptr, size_t size);
70extern void LogicalTapeRewindForRead(LogicalTape *lt, size_t buffer_size);
71extern void LogicalTapeFreeze(LogicalTape *lt, TapeShare *share);
72extern size_t LogicalTapeBackspace(LogicalTape *lt, size_t size);
73extern void LogicalTapeSeek(LogicalTape *lt, int64 blocknum, int offset);
74extern void LogicalTapeTell(LogicalTape *lt, int64 *blocknum, int *offset);
76
77#endif /* LOGTAPE_H */
int64_t int64
Definition: c.h:499
void LogicalTapeRewindForRead(LogicalTape *lt, size_t buffer_size)
Definition: logtape.c:846
void LogicalTapeSetForgetFreeSpace(LogicalTapeSet *lts)
Definition: logtape.c:750
size_t LogicalTapeBackspace(LogicalTape *lt, size_t size)
Definition: logtape.c:1062
size_t LogicalTapeRead(LogicalTape *lt, void *ptr, size_t size)
Definition: logtape.c:928
int64 LogicalTapeSetBlocks(LogicalTapeSet *lts)
Definition: logtape.c:1181
void LogicalTapeClose(LogicalTape *lt)
Definition: logtape.c:733
void LogicalTapeSetClose(LogicalTapeSet *lts)
Definition: logtape.c:667
void LogicalTapeSeek(LogicalTape *lt, int64 blocknum, int offset)
Definition: logtape.c:1133
LogicalTapeSet * LogicalTapeSetCreate(bool preallocate, SharedFileSet *fileset, int worker)
Definition: logtape.c:556
void LogicalTapeTell(LogicalTape *lt, int64 *blocknum, int *offset)
Definition: logtape.c:1162
struct TapeShare TapeShare
void LogicalTapeWrite(LogicalTape *lt, const void *ptr, size_t size)
Definition: logtape.c:761
LogicalTape * LogicalTapeCreate(LogicalTapeSet *lts)
Definition: logtape.c:680
void LogicalTapeFreeze(LogicalTape *lt, TapeShare *share)
Definition: logtape.c:981
LogicalTape * LogicalTapeImport(LogicalTapeSet *lts, int worker, TapeShare *shared)
Definition: logtape.c:609
int64 firstblocknumber
Definition: logtape.h:54