src/include/storage/shm_mq.h

   1 /*-------------------------------------------------------------------------
   2  *
   3  * shm_mq.h
   4  *        single-reader, single-writer shared memory message queue
   5  *
   6  * Portions Copyright (c) 1996-2024, PostgreSQL Global Development Group
   7  * Portions Copyright (c) 1994, Regents of the University of California
   8  *
   9  * src/include/storage/shm_mq.h
  10  *
  11  *-------------------------------------------------------------------------
  12  */
  13 #ifndef SHM_MQ_H
  14 #define SHM_MQ_H
  15
  16 #include "postmaster/bgworker.h"
  17 #include "storage/dsm.h"
  18 #include "storage/proc.h"
  19
  20 /* The queue itself, in shared memory. */
  21 struct shm_mq;
  22 typedef struct shm_mq shm_mq;
  23
  24 /* Backend-private state. */
  25 struct shm_mq_handle;
  26 typedef struct shm_mq_handle shm_mq_handle;
  27
  28 /* Descriptors for a single write spanning multiple locations. */
  29 typedef struct
  30 {
  31         const char *data;
  32         Size            len;
  33 } shm_mq_iovec;
  34
  35 /* Possible results of a send or receive operation. */
  36 typedef enum
  37 {
  38         SHM_MQ_SUCCESS,                         /* Sent or received a message. */
  39         SHM_MQ_WOULD_BLOCK,                     /* Not completed; retry later. */
  40         SHM_MQ_DETACHED,                        /* Other process has detached queue. */
  41 } shm_mq_result;
  42
  43 /*
  44  * Primitives to create a queue and set the sender and receiver.
  45  *
  46  * Both the sender and the receiver must be set before any messages are read
  47  * or written, but they need not be set by the same process.  Each must be
  48  * set exactly once.
  49  */
  50 extern shm_mq *shm_mq_create(void *address, Size size);
  51 extern void shm_mq_set_receiver(shm_mq *mq, PGPROC *);
  52 extern void shm_mq_set_sender(shm_mq *mq, PGPROC *);
  53
  54 /* Accessor methods for sender and receiver. */
  55 extern PGPROC *shm_mq_get_receiver(shm_mq *);
  56 extern PGPROC *shm_mq_get_sender(shm_mq *);
  57
  58 /* Set up backend-local queue state. */
  59 extern shm_mq_handle *shm_mq_attach(shm_mq *mq, dsm_segment *seg,
  60                                                                         BackgroundWorkerHandle *handle);
  61
  62 /* Associate worker handle with shm_mq. */
  63 extern void shm_mq_set_handle(shm_mq_handle *, BackgroundWorkerHandle *);
  64
  65 /* Break connection, release handle resources. */
  66 extern void shm_mq_detach(shm_mq_handle *mqh);
  67
  68 /* Get the shm_mq from handle. */
  69 extern shm_mq *shm_mq_get_queue(shm_mq_handle *mqh);
  70
  71 /* Send or receive messages. */
  72 extern shm_mq_result shm_mq_send(shm_mq_handle *mqh,
  73                                                                  Size nbytes, const void *data, bool nowait,
  74                                                                  bool force_flush);
  75 extern shm_mq_result shm_mq_sendv(shm_mq_handle *mqh, shm_mq_iovec *iov,
  76                                                                   int iovcnt, bool nowait, bool force_flush);
  77 extern shm_mq_result shm_mq_receive(shm_mq_handle *mqh,
  78                                                                         Size *nbytesp, void **datap, bool nowait);
  79
  80 /* Wait for our counterparty to attach to the queue. */
  81 extern shm_mq_result shm_mq_wait_for_attach(shm_mq_handle *mqh);
  82
  83 /* Smallest possible queue. */
  84 extern PGDLLIMPORT const Size shm_mq_minimum_size;
  85
  86 #endif                                                  /* SHM_MQ_H */