begriffs open source - ai-pg/blob - full-docs/txt/libpq-fastpath.txt

   1
   2 32.8. The Fast-Path Interface #
   3
   4    PostgreSQL provides a fast-path interface to send simple function calls
   5    to the server.
   6
   7 Tip
   8
   9    This interface is somewhat obsolete, as one can achieve similar
  10    performance and greater functionality by setting up a prepared
  11    statement to define the function call. Then, executing the statement
  12    with binary transmission of parameters and results substitutes for a
  13    fast-path function call.
  14
  15    The function PQfn requests execution of a server function via the
  16    fast-path interface:
  17 PGresult *PQfn(PGconn *conn,
  18                int fnid,
  19                int *result_buf,
  20                int *result_len,
  21                int result_is_int,
  22                const PQArgBlock *args,
  23                int nargs);
  24
  25 typedef struct
  26 {
  27     int len;
  28     int isint;
  29     union
  30     {
  31         int *ptr;
  32         int integer;
  33     } u;
  34 } PQArgBlock;
  35
  36    The fnid argument is the OID of the function to be executed. args and
  37    nargs define the parameters to be passed to the function; they must
  38    match the declared function argument list. When the isint field of a
  39    parameter structure is true, the u.integer value is sent to the server
  40    as an integer of the indicated length (this must be 2 or 4 bytes);
  41    proper byte-swapping occurs. When isint is false, the indicated number
  42    of bytes at *u.ptr are sent with no processing; the data must be in the
  43    format expected by the server for binary transmission of the function's
  44    argument data type. (The declaration of u.ptr as being of type int * is
  45    historical; it would be better to consider it void *.) result_buf
  46    points to the buffer in which to place the function's return value. The
  47    caller must have allocated sufficient space to store the return value.
  48    (There is no check!) The actual result length in bytes will be returned
  49    in the integer pointed to by result_len. If a 2- or 4-byte integer
  50    result is expected, set result_is_int to 1, otherwise set it to 0.
  51    Setting result_is_int to 1 causes libpq to byte-swap the value if
  52    necessary, so that it is delivered as a proper int value for the client
  53    machine; note that a 4-byte integer is delivered into *result_buf for
  54    either allowed result size. When result_is_int is 0, the binary-format
  55    byte string sent by the server is returned unmodified. (In this case
  56    it's better to consider result_buf as being of type void *.)
  57
  58    PQfn always returns a valid PGresult pointer, with status
  59    PGRES_COMMAND_OK for success or PGRES_FATAL_ERROR if some problem was
  60    encountered. The result status should be checked before the result is
  61    used. The caller is responsible for freeing the PGresult with PQclear
  62    when it is no longer needed.
  63
  64    To pass a NULL argument to the function, set the len field of that
  65    parameter structure to -1; the isint and u fields are then irrelevant.
  66
  67    If the function returns NULL, *result_len is set to -1, and *result_buf
  68    is not modified.
  69
  70    Note that it is not possible to handle set-valued results when using
  71    this interface. Also, the function must be a plain function, not an
  72    aggregate, window function, or procedure.