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-2022, 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 
19 #include "storage/sharedfileset.h"
20 
21 /*
22  * LogicalTapeSet and LogicalTape are opaque types whose details are not
23  * known outside logtape.c.
24  */
25 typedef struct LogicalTapeSet LogicalTapeSet;
26 typedef 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  */
48 typedef 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 
61 extern LogicalTapeSet *LogicalTapeSetCreate(bool preallocate,
62  SharedFileSet *fileset, int worker);
63 extern void LogicalTapeClose(LogicalTape *lt);
64 extern void LogicalTapeSetClose(LogicalTapeSet *lts);
66 extern LogicalTape *LogicalTapeImport(LogicalTapeSet *lts, int worker, TapeShare *shared);
68 extern size_t LogicalTapeRead(LogicalTape *lt, void *ptr, size_t size);
69 extern void LogicalTapeWrite(LogicalTape *lt, void *ptr, size_t size);
70 extern void LogicalTapeRewindForRead(LogicalTape *lt, size_t buffer_size);
71 extern void LogicalTapeFreeze(LogicalTape *lt, TapeShare *share);
72 extern size_t LogicalTapeBackspace(LogicalTape *lt, size_t size);
73 extern void LogicalTapeSeek(LogicalTape *lt, long blocknum, int offset);
74 extern void LogicalTapeTell(LogicalTape *lt, long *blocknum, int *offset);
75 extern long LogicalTapeSetBlocks(LogicalTapeSet *lts);
76 
77 #endif /* LOGTAPE_H */
LogicalTape * LogicalTapeCreate(LogicalTapeSet *lts)
Definition: logtape.c:681
void LogicalTapeRewindForRead(LogicalTape *lt, size_t buffer_size)
Definition: logtape.c:847
void LogicalTapeSetForgetFreeSpace(LogicalTapeSet *lts)
Definition: logtape.c:751
size_t LogicalTapeBackspace(LogicalTape *lt, size_t size)
Definition: logtape.c:1063
size_t LogicalTapeRead(LogicalTape *lt, void *ptr, size_t size)
Definition: logtape.c:929
void LogicalTapeClose(LogicalTape *lt)
Definition: logtape.c:734
void LogicalTapeSetClose(LogicalTapeSet *lts)
Definition: logtape.c:668
void LogicalTapeWrite(LogicalTape *lt, void *ptr, size_t size)
Definition: logtape.c:762
void LogicalTapeTell(LogicalTape *lt, long *blocknum, int *offset)
Definition: logtape.c:1163
struct TapeShare TapeShare
void LogicalTapeSeek(LogicalTape *lt, long blocknum, int offset)
Definition: logtape.c:1134
LogicalTapeSet * LogicalTapeSetCreate(bool preallocate, SharedFileSet *fileset, int worker)
Definition: logtape.c:557
long LogicalTapeSetBlocks(LogicalTapeSet *lts)
Definition: logtape.c:1184
void LogicalTapeFreeze(LogicalTape *lt, TapeShare *share)
Definition: logtape.c:982
LogicalTape * LogicalTapeImport(LogicalTapeSet *lts, int worker, TapeShare *shared)
Definition: logtape.c:610
long firstblocknumber
Definition: logtape.h:54