1/*-------------------------------------------------------------------------
2 *
3 * shm_mq.h
4 * single-reader, single-writer shared memory message queue
5 *
6 * Portions Copyright (c) 1996-2019, 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. */
21struct shm_mq;
22typedef struct shm_mq shm_mq;
23
24/* Backend-private state. */
25struct shm_mq_handle;
26typedef struct shm_mq_handle shm_mq_handle;
27
28/* Descriptors for a single write spanning multiple locations. */
29typedef struct
30{
31 const char *data;
32 Size len;
33} shm_mq_iovec;
34
35/* Possible results of a send or receive operation. */
36typedef 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 */
50extern shm_mq *shm_mq_create(void *address, Size size);
51extern void shm_mq_set_receiver(shm_mq *mq, PGPROC *);
52extern void shm_mq_set_sender(shm_mq *mq, PGPROC *);
53
54/* Accessor methods for sender and receiver. */
55extern PGPROC *shm_mq_get_receiver(shm_mq *);
56extern PGPROC *shm_mq_get_sender(shm_mq *);
57
58/* Set up backend-local queue state. */
59extern shm_mq_handle *shm_mq_attach(shm_mq *mq, dsm_segment *seg,
60 BackgroundWorkerHandle *handle);
61
62/* Associate worker handle with shm_mq. */
63extern void shm_mq_set_handle(shm_mq_handle *, BackgroundWorkerHandle *);
64
65/* Break connection, release handle resources. */
66extern void shm_mq_detach(shm_mq_handle *mqh);
67
68/* Get the shm_mq from handle. */
69extern shm_mq *shm_mq_get_queue(shm_mq_handle *mqh);
70
71/* Send or receive messages. */
72extern shm_mq_result shm_mq_send(shm_mq_handle *mqh,
73 Size nbytes, const void *data, bool nowait);
74extern shm_mq_result shm_mq_sendv(shm_mq_handle *mqh,
75 shm_mq_iovec *iov, int iovcnt, bool nowait);
76extern shm_mq_result shm_mq_receive(shm_mq_handle *mqh,
77 Size *nbytesp, void **datap, bool nowait);
78
79/* Wait for our counterparty to attach to the queue. */
80extern shm_mq_result shm_mq_wait_for_attach(shm_mq_handle *mqh);
81
82/* Smallest possible queue. */
83extern PGDLLIMPORT const Size shm_mq_minimum_size;
84
85#endif /* SHM_MQ_H */
86