aio: Rename pgaio_io_prep_* to pgaio_io_start_*

anarazel · anarazel · commit 9469d7fdd2bc · 2025-03-26T16:10:29.000-04:00
The old naming pattern (mirroring liburing's naming) was inconsistent with the (not yet introduced) callers. It seems better to get rid of the inconsistency now than to grow more users of the odd naming. Reported-by: Noah Misch <noah@leadboat.com> Discussion: https://postgr.es/m/20250326001915.bc.nmisch@google.com
diff --git a/src/backend/storage/aio/aio.c b/src/backend/storage/aio/aio.c
@@ -127,25 +127,25 @@ static PgAioHandle *pgaio_inj_cur_handle;
  * To react to the completion of the IO as soon as it is known to have
  * completed, callbacks can be registered with pgaio_io_register_callbacks().
  *
- * To actually execute IO using the returned handle, the pgaio_io_prep_*()
- * family of functions is used. In many cases the pgaio_io_prep_*() call will
+ * To actually execute IO using the returned handle, the pgaio_io_start_*()
+ * family of functions is used. In many cases the pgaio_io_start_*() call will
  * not be done directly by code that acquired the handle, but by lower level
  * code that gets passed the handle. E.g. if code in bufmgr.c wants to perform
  * AIO, it typically will pass the handle to smgr.c, which will pass it on to
- * md.c, on to fd.c, which then finally calls pgaio_io_prep_*().  This
+ * md.c, on to fd.c, which then finally calls pgaio_io_start_*().  This
  * forwarding allows the various layers to react to the IO's completion by
  * registering callbacks. These callbacks in turn can translate a lower
  * layer's result into a result understandable by a higher layer.
  *
- * During pgaio_io_prep_*() the IO is staged (i.e. prepared for execution but
+ * During pgaio_io_start_*() the IO is staged (i.e. prepared for execution but
  * not submitted to the kernel). Unless in batchmode
  * (c.f. pgaio_enter_batchmode()), the IO will also get submitted for
  * execution. Note that, whether in batchmode or not, the IO might even
  * complete before the functions return.
  *
- * After pgaio_io_prep_*() the AioHandle is "consumed" and may not be
+ * After pgaio_io_start_*() the AioHandle is "consumed" and may not be
  * referenced by the IO issuing code. To e.g. wait for IO, references to the
- * IO can be established with pgaio_io_get_wref() *before* pgaio_io_prep_*()
+ * IO can be established with pgaio_io_get_wref() *before* pgaio_io_start_*()
  * is called.  pgaio_wref_wait() can be used to wait for the IO to complete.
  *
  *
@@ -391,7 +391,7 @@ pgaio_io_resowner_register(PgAioHandle *ioh)
 /*
  * Stage IO for execution and, if appropriate, submit it immediately.
  *
- * Should only be called from pgaio_io_prep_*().
+ * Should only be called from pgaio_io_start_*().
  */
 void
 pgaio_io_stage(PgAioHandle *ioh, PgAioOp op)
@@ -421,7 +421,7 @@ pgaio_io_stage(PgAioHandle *ioh, PgAioOp op)
 	needs_synchronous = pgaio_io_needs_synchronous_execution(ioh);
 
 	pgaio_debug_io(DEBUG3, ioh,
-				   "prepared (synchronous: %d, in_batch: %d)",
+				   "staged (synchronous: %d, in_batch: %d)",
 				   needs_synchronous, pgaio_my_backend->in_batchmode);
 
 	if (!needs_synchronous)
diff --git a/src/backend/storage/aio/aio_callback.c b/src/backend/storage/aio/aio_callback.c
@@ -54,7 +54,7 @@ static const PgAioHandleCallbacksEntry aio_handle_cbs[] = {
  * registered for each IO.
  *
  * Callbacks need to be registered before [indirectly] calling
- * pgaio_io_prep_*(), as the IO may be executed immediately.
+ * pgaio_io_start_*(), as the IO may be executed immediately.
  *
  * A callback can be passed a small bit of data, e.g. to indicate whether to
  * zero a buffer if it is invalid.
diff --git a/src/backend/storage/aio/aio_io.c b/src/backend/storage/aio/aio_io.c
@@ -25,7 +25,7 @@
 #include "utils/wait_event.h"
 
 
-static void pgaio_io_before_prep(PgAioHandle *ioh);
+static void pgaio_io_before_start(PgAioHandle *ioh);
 
 
 
@@ -63,22 +63,22 @@ pgaio_io_get_op_data(PgAioHandle *ioh)
 
 
 /* --------------------------------------------------------------------------------
- * "Preparation" routines for individual IO operations
+ * "Start" routines for individual IO operations
  *
  * These are called by the code actually initiating an IO, to associate the IO
  * specific data with an AIO handle.
  *
- * Each of the preparation routines first needs to call
- * pgaio_io_before_prep(), then fill IO specific fields in the handle and then
- * finally call pgaio_io_stage().
+ * Each of the "start" routines first needs to call pgaio_io_before_start(),
+ * then fill IO specific fields in the handle and then finally call
+ * pgaio_io_stage().
  * --------------------------------------------------------------------------------
  */
 
 void
-pgaio_io_prep_readv(PgAioHandle *ioh,
-					int fd, int iovcnt, uint64 offset)
+pgaio_io_start_readv(PgAioHandle *ioh,
+					 int fd, int iovcnt, uint64 offset)
 {
-	pgaio_io_before_prep(ioh);
+	pgaio_io_before_start(ioh);
 
 	ioh->op_data.read.fd = fd;
 	ioh->op_data.read.offset = offset;
@@ -88,10 +88,10 @@ pgaio_io_prep_readv(PgAioHandle *ioh,
 }
 
 void
-pgaio_io_prep_writev(PgAioHandle *ioh,
-					 int fd, int iovcnt, uint64 offset)
+pgaio_io_start_writev(PgAioHandle *ioh,
+					  int fd, int iovcnt, uint64 offset)
 {
-	pgaio_io_before_prep(ioh);
+	pgaio_io_before_start(ioh);
 
 	ioh->op_data.write.fd = fd;
 	ioh->op_data.write.offset = offset;
@@ -153,7 +153,7 @@ pgaio_io_perform_synchronously(PgAioHandle *ioh)
  * any data in the handle is set.  Mostly to centralize assertions.
  */
 static void
-pgaio_io_before_prep(PgAioHandle *ioh)
+pgaio_io_before_start(PgAioHandle *ioh)
 {
 	Assert(ioh->state == PGAIO_HS_HANDED_OUT);
 	Assert(pgaio_my_backend->handed_out_io == ioh);
diff --git a/src/backend/storage/aio/aio_target.c b/src/backend/storage/aio/aio_target.c
@@ -55,7 +55,7 @@ pgaio_io_get_target_name(PgAioHandle *ioh)
 /*
  * Assign a target to the IO.
  *
- * This has to be called exactly once before pgaio_io_prep_*() is called.
+ * This has to be called exactly once before pgaio_io_start_*() is called.
  */
 void
 pgaio_io_set_target(PgAioHandle *ioh, PgAioTargetID targetid)
@@ -101,7 +101,7 @@ pgaio_io_can_reopen(PgAioHandle *ioh)
 
 /*
  * Internal: Before executing an IO outside of the context of the process the
- * IO has been prepared in, the file descriptor has to be reopened - any FD
+ * IO has been staged in, the file descriptor has to be reopened - any FD
  * referenced in the IO itself, won't be valid in the separate process.
  */
 void
diff --git a/src/include/storage/aio.h b/src/include/storage/aio.h
@@ -277,10 +277,10 @@ extern int	pgaio_io_get_iovec(PgAioHandle *ioh, struct iovec **iov);
 extern PgAioOp pgaio_io_get_op(PgAioHandle *ioh);
 extern PgAioOpData *pgaio_io_get_op_data(PgAioHandle *ioh);
 
-extern void pgaio_io_prep_readv(PgAioHandle *ioh,
-								int fd, int iovcnt, uint64 offset);
-extern void pgaio_io_prep_writev(PgAioHandle *ioh,
+extern void pgaio_io_start_readv(PgAioHandle *ioh,
 								 int fd, int iovcnt, uint64 offset);
+extern void pgaio_io_start_writev(PgAioHandle *ioh,
+								  int fd, int iovcnt, uint64 offset);
 
 /* functions in aio_target.c */
 extern void pgaio_io_set_target(PgAioHandle *ioh, PgAioTargetID targetid);
diff --git a/src/include/storage/aio_internal.h b/src/include/storage/aio_internal.h
@@ -42,13 +42,13 @@ typedef enum PgAioHandleState
 
 	/*
 	 * Returned by pgaio_io_acquire(). The next state is either DEFINED (if
-	 * pgaio_io_prep_*() is called), or IDLE (if pgaio_io_release() is
+	 * pgaio_io_start_*() is called), or IDLE (if pgaio_io_release() is
 	 * called).
 	 */
 	PGAIO_HS_HANDED_OUT,
 
 	/*
-	 * pgaio_io_prep_*() has been called, but IO is not yet staged. At this
+	 * pgaio_io_start_*() has been called, but IO is not yet staged. At this
 	 * point the handle has all the information for the IO to be executed.
 	 */
 	PGAIO_HS_DEFINED,

Original file line number	Diff line number	Diff line change
`@@ -54,7 +54,7 @@ static const PgAioHandleCallbacksEntry aio_handle_cbs[] = {`
`54`	`54`	`* registered for each IO.`
`55`	`55`	`*`
`56`	`56`	`* Callbacks need to be registered before [indirectly] calling`
`57`		`- * pgaio_io_prep_*(), as the IO may be executed immediately.`
	`57`	`+ * pgaio_io_start_*(), as the IO may be executed immediately.`
`58`	`58`	`*`
`59`	`59`	`* A callback can be passed a small bit of data, e.g. to indicate whether to`
`60`	`60`	`* zero a buffer if it is invalid.`