PostgreSQL Source Code  git master
pg_prewarm.c
Go to the documentation of this file.
1 /*-------------------------------------------------------------------------
2  *
3  * pg_prewarm.c
4  * prewarming utilities
5  *
6  * Copyright (c) 2010-2024, PostgreSQL Global Development Group
7  *
8  * IDENTIFICATION
9  * contrib/pg_prewarm/pg_prewarm.c
10  *
11  *-------------------------------------------------------------------------
12  */
13 #include "postgres.h"
14 
15 #include <sys/stat.h>
16 #include <unistd.h>
17 
18 #include "access/relation.h"
19 #include "fmgr.h"
20 #include "miscadmin.h"
21 #include "storage/bufmgr.h"
22 #include "storage/read_stream.h"
23 #include "storage/smgr.h"
24 #include "utils/acl.h"
25 #include "utils/builtins.h"
26 #include "utils/lsyscache.h"
27 #include "utils/rel.h"
28 
30 
32 
33 typedef enum
34 {
38 } PrewarmType;
39 
41 
43 {
45  int64 last_block;
46 };
47 
48 static BlockNumber
50  void *callback_private_data,
51  void *per_buffer_data)
52 {
53  struct pg_prewarm_read_stream_private *p = callback_private_data;
54 
55  if (p->blocknum <= p->last_block)
56  return p->blocknum++;
57 
58  return InvalidBlockNumber;
59 }
60 
61 /*
62  * pg_prewarm(regclass, mode text, fork text,
63  * first_block int8, last_block int8)
64  *
65  * The first argument is the relation to be prewarmed; the second controls
66  * how prewarming is done; legal options are 'prefetch', 'read', and 'buffer'.
67  * The third is the name of the relation fork to be prewarmed. The fourth
68  * and fifth arguments specify the first and last block to be prewarmed.
69  * If the fourth argument is NULL, it will be taken as 0; if the fifth argument
70  * is NULL, it will be taken as the number of blocks in the relation. The
71  * return value is the number of blocks successfully prewarmed.
72  */
73 Datum
75 {
76  Oid relOid;
77  text *forkName;
78  text *type;
79  int64 first_block;
80  int64 last_block;
81  int64 nblocks;
82  int64 blocks_done = 0;
83  int64 block;
84  Relation rel;
85  ForkNumber forkNumber;
86  char *forkString;
87  char *ttype;
88  PrewarmType ptype;
89  AclResult aclresult;
90 
91  /* Basic sanity checking. */
92  if (PG_ARGISNULL(0))
93  ereport(ERROR,
94  (errcode(ERRCODE_INVALID_PARAMETER_VALUE),
95  errmsg("relation cannot be null")));
96  relOid = PG_GETARG_OID(0);
97  if (PG_ARGISNULL(1))
98  ereport(ERROR,
99  (errcode(ERRCODE_INVALID_PARAMETER_VALUE),
100  errmsg("prewarm type cannot be null")));
101  type = PG_GETARG_TEXT_PP(1);
102  ttype = text_to_cstring(type);
103  if (strcmp(ttype, "prefetch") == 0)
104  ptype = PREWARM_PREFETCH;
105  else if (strcmp(ttype, "read") == 0)
106  ptype = PREWARM_READ;
107  else if (strcmp(ttype, "buffer") == 0)
108  ptype = PREWARM_BUFFER;
109  else
110  {
111  ereport(ERROR,
112  (errcode(ERRCODE_INVALID_PARAMETER_VALUE),
113  errmsg("invalid prewarm type"),
114  errhint("Valid prewarm types are \"prefetch\", \"read\", and \"buffer\".")));
115  PG_RETURN_INT64(0); /* Placate compiler. */
116  }
117  if (PG_ARGISNULL(2))
118  ereport(ERROR,
119  (errcode(ERRCODE_INVALID_PARAMETER_VALUE),
120  errmsg("relation fork cannot be null")));
121  forkName = PG_GETARG_TEXT_PP(2);
122  forkString = text_to_cstring(forkName);
123  forkNumber = forkname_to_number(forkString);
124 
125  /* Open relation and check privileges. */
126  rel = relation_open(relOid, AccessShareLock);
127  aclresult = pg_class_aclcheck(relOid, GetUserId(), ACL_SELECT);
128  if (aclresult != ACLCHECK_OK)
129  aclcheck_error(aclresult, get_relkind_objtype(rel->rd_rel->relkind), get_rel_name(relOid));
130 
131  /* Check that the fork exists. */
132  if (!smgrexists(RelationGetSmgr(rel), forkNumber))
133  ereport(ERROR,
134  (errcode(ERRCODE_INVALID_PARAMETER_VALUE),
135  errmsg("fork \"%s\" does not exist for this relation",
136  forkString)));
137 
138  /* Validate block numbers, or handle nulls. */
139  nblocks = RelationGetNumberOfBlocksInFork(rel, forkNumber);
140  if (PG_ARGISNULL(3))
141  first_block = 0;
142  else
143  {
144  first_block = PG_GETARG_INT64(3);
145  if (first_block < 0 || first_block >= nblocks)
146  ereport(ERROR,
147  (errcode(ERRCODE_INVALID_PARAMETER_VALUE),
148  errmsg("starting block number must be between 0 and %lld",
149  (long long) (nblocks - 1))));
150  }
151  if (PG_ARGISNULL(4))
152  last_block = nblocks - 1;
153  else
154  {
156  if (last_block < 0 || last_block >= nblocks)
157  ereport(ERROR,
158  (errcode(ERRCODE_INVALID_PARAMETER_VALUE),
159  errmsg("ending block number must be between 0 and %lld",
160  (long long) (nblocks - 1))));
161  }
162 
163  /* Now we're ready to do the real work. */
164  if (ptype == PREWARM_PREFETCH)
165  {
166 #ifdef USE_PREFETCH
167 
168  /*
169  * In prefetch mode, we just hint the OS to read the blocks, but we
170  * don't know whether it really does it, and we don't wait for it to
171  * finish.
172  *
173  * It would probably be better to pass our prefetch requests in chunks
174  * of a megabyte or maybe even a whole segment at a time, but there's
175  * no practical way to do that at present without a gross modularity
176  * violation, so we just do this.
177  */
178  for (block = first_block; block <= last_block; ++block)
179  {
181  PrefetchBuffer(rel, forkNumber, block);
182  ++blocks_done;
183  }
184 #else
185  ereport(ERROR,
186  (errcode(ERRCODE_FEATURE_NOT_SUPPORTED),
187  errmsg("prefetch is not supported by this build")));
188 #endif
189  }
190  else if (ptype == PREWARM_READ)
191  {
192  /*
193  * In read mode, we actually read the blocks, but not into shared
194  * buffers. This is more portable than prefetch mode (it works
195  * everywhere) and is synchronous.
196  */
197  for (block = first_block; block <= last_block; ++block)
198  {
200  smgrread(RelationGetSmgr(rel), forkNumber, block, blockbuffer.data);
201  ++blocks_done;
202  }
203  }
204  else if (ptype == PREWARM_BUFFER)
205  {
207  ReadStream *stream;
208 
209  /*
210  * In buffer mode, we actually pull the data into shared_buffers.
211  */
212 
213  /* Set up the private state for our streaming buffer read callback. */
214  p.blocknum = first_block;
216 
218  NULL,
219  rel,
220  forkNumber,
222  &p,
223  0);
224 
225  for (block = first_block; block <= last_block; ++block)
226  {
227  Buffer buf;
228 
230  buf = read_stream_next_buffer(stream, NULL);
232  ++blocks_done;
233  }
234  Assert(read_stream_next_buffer(stream, NULL) == InvalidBuffer);
235  read_stream_end(stream);
236  }
237 
238  /* Close relation, release lock. */
240 
241  PG_RETURN_INT64(blocks_done);
242 }
AclResult
Definition: acl.h:182
@ ACLCHECK_OK
Definition: acl.h:183
void aclcheck_error(AclResult aclerr, ObjectType objtype, const char *objectname)
Definition: aclchk.c:2702
AclResult pg_class_aclcheck(Oid table_oid, Oid roleid, AclMode mode)
Definition: aclchk.c:4093
uint32 BlockNumber
Definition: block.h:31
#define InvalidBlockNumber
Definition: block.h:33
int Buffer
Definition: buf.h:23
#define InvalidBuffer
Definition: buf.h:25
PrefetchBufferResult PrefetchBuffer(Relation reln, ForkNumber forkNum, BlockNumber blockNum)
Definition: bufmgr.c:638
BlockNumber RelationGetNumberOfBlocksInFork(Relation relation, ForkNumber forkNum)
Definition: bufmgr.c:3912
void ReleaseBuffer(Buffer buffer)
Definition: bufmgr.c:4896
#define Assert(condition)
Definition: c.h:858
int errhint(const char *fmt,...)
Definition: elog.c:1317
int errcode(int sqlerrcode)
Definition: elog.c:857
int errmsg(const char *fmt,...)
Definition: elog.c:1070
#define ERROR
Definition: elog.h:39
#define ereport(elevel,...)
Definition: elog.h:149
#define PG_GETARG_OID(n)
Definition: fmgr.h:275
#define PG_GETARG_TEXT_PP(n)
Definition: fmgr.h:309
#define PG_ARGISNULL(n)
Definition: fmgr.h:209
#define PG_RETURN_INT64(x)
Definition: fmgr.h:368
#define PG_GETARG_INT64(n)
Definition: fmgr.h:283
#define PG_FUNCTION_ARGS
Definition: fmgr.h:193
#define AccessShareLock
Definition: lockdefs.h:36
char * get_rel_name(Oid relid)
Definition: lsyscache.c:1928
#define CHECK_FOR_INTERRUPTS()
Definition: miscadmin.h:122
Oid GetUserId(void)
Definition: miscinit.c:514
ObjectType get_relkind_objtype(char relkind)
#define ACL_SELECT
Definition: parsenodes.h:77
PG_FUNCTION_INFO_V1(pg_prewarm)
PG_MODULE_MAGIC
Definition: pg_prewarm.c:29
PrewarmType
Definition: pg_prewarm.c:34
@ PREWARM_PREFETCH
Definition: pg_prewarm.c:35
@ PREWARM_READ
Definition: pg_prewarm.c:36
@ PREWARM_BUFFER
Definition: pg_prewarm.c:37
static PGIOAlignedBlock blockbuffer
Definition: pg_prewarm.c:40
Datum pg_prewarm(PG_FUNCTION_ARGS)
Definition: pg_prewarm.c:74
static BlockNumber pg_prewarm_read_stream_next_block(ReadStream *stream, void *callback_private_data, void *per_buffer_data)
Definition: pg_prewarm.c:49
static char * buf
Definition: pg_test_fsync.c:73
uintptr_t Datum
Definition: postgres.h:64
unsigned int Oid
Definition: postgres_ext.h:31
ReadStream * read_stream_begin_relation(int flags, BufferAccessStrategy strategy, Relation rel, ForkNumber forknum, ReadStreamBlockNumberCB callback, void *callback_private_data, size_t per_buffer_data_size)
Definition: read_stream.c:410
Buffer read_stream_next_buffer(ReadStream *stream, void **per_buffer_data)
Definition: read_stream.c:572
void read_stream_end(ReadStream *stream)
Definition: read_stream.c:802
#define READ_STREAM_FULL
Definition: read_stream.h:42
static SMgrRelation RelationGetSmgr(Relation rel)
Definition: rel.h:567
ForkNumber forkname_to_number(const char *forkName)
Definition: relpath.c:50
ForkNumber
Definition: relpath.h:48
bool smgrexists(SMgrRelation reln, ForkNumber forknum)
Definition: smgr.c:398
static void smgrread(SMgrRelation reln, ForkNumber forknum, BlockNumber blocknum, void *buffer)
Definition: smgr.h:114
void relation_close(Relation relation, LOCKMODE lockmode)
Definition: relation.c:205
Relation relation_open(Oid relationId, LOCKMODE lockmode)
Definition: relation.c:47
Form_pg_class rd_rel
Definition: rel.h:111
Definition: c.h:687
char data[BLCKSZ]
Definition: c.h:1137
char * text_to_cstring(const text *t)
Definition: varlena.c:217
const char * type