dest.h 5.8 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144
  1. /*-------------------------------------------------------------------------
  2. *
  3. * dest.h
  4. * support for communication destinations
  5. *
  6. * Whenever the backend executes a query that returns tuples, the results
  7. * have to go someplace. For example:
  8. *
  9. * - stdout is the destination only when we are running a
  10. * standalone backend (no postmaster) and are returning results
  11. * back to an interactive user.
  12. *
  13. * - a remote process is the destination when we are
  14. * running a backend with a frontend and the frontend executes
  15. * PQexec() or PQfn(). In this case, the results are sent
  16. * to the frontend via the functions in backend/libpq.
  17. *
  18. * - DestNone is the destination when the system executes
  19. * a query internally. The results are discarded.
  20. *
  21. * dest.c defines three functions that implement destination management:
  22. *
  23. * BeginCommand: initialize the destination at start of command.
  24. * CreateDestReceiver: return a pointer to a struct of destination-specific
  25. * receiver functions.
  26. * EndCommand: clean up the destination at end of command.
  27. *
  28. * BeginCommand/EndCommand are executed once per received SQL query.
  29. *
  30. * CreateDestReceiver returns a receiver object appropriate to the specified
  31. * destination. The executor, as well as utility statements that can return
  32. * tuples, are passed the resulting DestReceiver* pointer. Each executor run
  33. * or utility execution calls the receiver's rStartup method, then the
  34. * receiveSlot method (zero or more times), then the rShutdown method.
  35. * The same receiver object may be re-used multiple times; eventually it is
  36. * destroyed by calling its rDestroy method.
  37. *
  38. * In some cases, receiver objects require additional parameters that must
  39. * be passed to them after calling CreateDestReceiver. Since the set of
  40. * parameters varies for different receiver types, this is not handled by
  41. * this module, but by direct calls from the calling code to receiver type
  42. * specific functions.
  43. *
  44. * The DestReceiver object returned by CreateDestReceiver may be a statically
  45. * allocated object (for destination types that require no local state),
  46. * in which case rDestroy is a no-op. Alternatively it can be a palloc'd
  47. * object that has DestReceiver as its first field and contains additional
  48. * fields (see printtup.c for an example). These additional fields are then
  49. * accessible to the DestReceiver functions by casting the DestReceiver*
  50. * pointer passed to them. The palloc'd object is pfree'd by the rDestroy
  51. * method. Note that the caller of CreateDestReceiver should take care to
  52. * do so in a memory context that is long-lived enough for the receiver
  53. * object not to disappear while still needed.
  54. *
  55. * Special provision: None_Receiver is a permanently available receiver
  56. * object for the DestNone destination. This avoids useless creation/destroy
  57. * calls in portal and cursor manipulations.
  58. *
  59. *
  60. * Portions Copyright (c) 1996-2016, PostgreSQL Global Development Group
  61. * Portions Copyright (c) 1994, Regents of the University of California
  62. *
  63. * src/include/tcop/dest.h
  64. *
  65. *-------------------------------------------------------------------------
  66. */
  67. #ifndef DEST_H
  68. #define DEST_H
  69. #include "executor/tuptable.h"
  70. /* buffer size to use for command completion tags */
  71. #define COMPLETION_TAG_BUFSIZE 64
  72. /* ----------------
  73. * CommandDest is a simplistic means of identifying the desired
  74. * destination. Someday this will probably need to be improved.
  75. *
  76. * Note: only the values DestNone, DestDebug, DestRemote are legal for the
  77. * global variable whereToSendOutput. The other values may be used
  78. * as the destination for individual commands.
  79. * ----------------
  80. */
  81. typedef enum
  82. {
  83. DestNone, /* results are discarded */
  84. DestDebug, /* results go to debugging output */
  85. DestRemote, /* results sent to frontend process */
  86. DestRemoteExecute, /* sent to frontend, in Execute command */
  87. DestSPI, /* results sent to SPI manager */
  88. DestTuplestore, /* results sent to Tuplestore */
  89. DestIntoRel, /* results sent to relation (SELECT INTO) */
  90. DestCopyOut, /* results sent to COPY TO code */
  91. DestSQLFunction, /* results sent to SQL-language func mgr */
  92. DestTransientRel, /* results sent to transient relation */
  93. DestTupleQueue /* results sent to tuple queue */
  94. } CommandDest;
  95. /* ----------------
  96. * DestReceiver is a base type for destination-specific local state.
  97. * In the simplest cases, there is no state info, just the function
  98. * pointers that the executor must call.
  99. *
  100. * Note: the receiveSlot routine must be passed a slot containing a TupleDesc
  101. * identical to the one given to the rStartup routine. It returns bool where
  102. * a "true" value means "continue processing" and a "false" value means
  103. * "stop early, just as if we'd reached the end of the scan".
  104. * ----------------
  105. */
  106. typedef struct _DestReceiver DestReceiver;
  107. struct _DestReceiver
  108. {
  109. /* Called for each tuple to be output: */
  110. bool (*receiveSlot) (TupleTableSlot *slot,
  111. DestReceiver *self);
  112. /* Per-executor-run initialization and shutdown: */
  113. void (*rStartup) (DestReceiver *self,
  114. int operation,
  115. TupleDesc typeinfo);
  116. void (*rShutdown) (DestReceiver *self);
  117. /* Destroy the receiver object itself (if dynamically allocated) */
  118. void (*rDestroy) (DestReceiver *self);
  119. /* CommandDest code for this receiver */
  120. CommandDest mydest;
  121. /* Private fields might appear beyond this point... */
  122. };
  123. extern DestReceiver *None_Receiver; /* permanent receiver for DestNone */
  124. /* The primary destination management functions */
  125. extern void BeginCommand(const char *commandTag, CommandDest dest);
  126. extern DestReceiver *CreateDestReceiver(CommandDest dest);
  127. extern void EndCommand(const char *commandTag, CommandDest dest);
  128. /* Additional functions that go with destination management, more or less. */
  129. extern void NullCommand(CommandDest dest);
  130. extern void ReadyForQuery(CommandDest dest);
  131. #endif /* DEST_H */