libpq 的事件系统旨在通知已注册的事件处理程序有关 libpq 的重要事件，例如 PGconn 和 PGresult 对象的创建或销毁。主要用例是，这允许应用程序将自己的数据与 PGconn 或 PGresult 关联起来，并确保在适当的时间释放这些数据。
每个已注册的事件处理程序都与两部分数据相关联，在 libpq 中仅作为不透明的 void * 指针。有一个“传递”（pass-through）指针，在将事件处理程序注册到 PGconn 时由应用程序提供。此传递指针在 PGconn 的整个生命周期及其生成的所有 PGresult 中都不会改变；因此，如果使用，它必须指向长期存在的数据。此外，还有一个“实例数据”（instance data）指针，在每个 PGconn 和 PGresult 中初始值为 NULL。此指针可以使用 PQinstanceData、PQsetInstanceData、PQresultInstanceData 和 PQresultSetInstanceData 函数进行操作。请注意，与传递指针不同，由 PGconn 创建的 PGresult 不会自动继承 PGconn 的实例数据。 libpq 不知道传递指针和实例数据指针（如果它们指向任何东西）指向何处，也不会尝试释放它们——这由事件处理程序负责。
枚举 PGEventId 命名了事件系统处理的事件类型。它的所有值都以 PGEVT 开头。对于每种事件类型，都有一个相应的事件信息结构，它携带传递给事件处理程序的参数。事件类型是：
PGEVT_REGISTER #当调用 PQregisterEventProc 时会发生注册事件。这是初始化事件过程可能需要的任何 instanceData 的理想时机。每个连接每个事件处理程序只触发一次注册事件。如果事件过程失败（返回零），则注册将被取消。
typedef struct
{
PGconn *conn;
} PGEventRegister;
收到 PGEVT_REGISTER 事件时，应将 evtInfo 指针强制转换为 PGEventRegister *。此结构包含一个 PGconn，它应该处于 CONNECTION_OK 状态；如果调用 PQregisterEventProc 紧接着获得一个有效的 PGconn，则可以保证这一点。返回失败代码时，必须执行所有清理工作，因为不会发送 PGEVT_CONNDESTROY 事件。
PGEVT_CONNRESET #连接重置事件在 PQreset 或 PQresetPoll 完成时触发。在这两种情况下，只有在重置成功时才会触发事件。在 PostgreSQL v15 及更高版本中，事件过程的返回值将被忽略。然而，在早期版本中，返回成功（非零）很重要，否则连接将被中止。
typedef struct
{
PGconn *conn;
} PGEventConnReset;
收到 PGEVT_CONNRESET 事件时，应将 evtInfo 指针强制转换为 PGEventConnReset *。尽管包含的 PGconn 刚刚被重置，但所有事件数据都保持不变。此事件应用于重置/重新加载/重新查询任何关联的 instanceData。请注意，即使事件过程未能处理 PGEVT_CONNRESET，当连接关闭时，它仍然会收到 PGEVT_CONNDESTROY 事件。
PGEVT_CONNDESTROY #连接销毁事件在响应 PQfinish 时触发。事件过程负责正确清理其事件数据，因为 libpq 没有管理此内存的能力。未能清理将导致内存泄漏。
typedef struct
{
PGconn *conn;
} PGEventConnDestroy;
收到 PGEVT_CONNDESTROY 事件时，应将 evtInfo 指针强制转换为 PGEventConnDestroy *。此事件在 PQfinish 执行任何其他清理之前触发。事件过程的返回值将被忽略，因为无法从 PQfinish 指示失败。此外，事件过程的失败不应中止清理不需要内存的过程。
PGEVT_RESULTCREATE #结果创建事件在响应任何生成结果的查询执行函数（包括 PQgetResult）时触发。此事件仅在结果成功创建后触发。
typedef struct
{
PGconn *conn;
PGresult *result;
} PGEventResultCreate;
收到 PGEVT_RESULTCREATE 事件时，应将 evtInfo 指针强制转换为 PGEventResultCreate *。conn 是用于生成结果的连接。这是初始化需要与结果关联的任何 instanceData 的理想位置。如果事件过程失败（返回零），则该事件过程在结果的剩余生命周期中将被忽略；也就是说，它不会收到此结果或从中复制的结果的 PGEVT_RESULTCOPY 或 PGEVT_RESULTDESTROY 事件。
PGEVT_RESULTCOPY #结果复制事件在响应 PQcopyResult 时触发。此事件仅在复制完成后触发。只有成功处理了源结果的 PGEVT_RESULTCREATE 或 PGEVT_RESULTCOPY 事件的事件过程才会收到 PGEVT_RESULTCOPY 事件。
typedef struct
{
const PGresult *src;
PGresult *dest;
} PGEventResultCopy;
收到 PGEVT_RESULTCOPY 事件时，应将 evtInfo 指针强制转换为 PGEventResultCopy *。src 结果是被复制的源，而 dest 结果是复制的目标。此事件可用于提供 instanceData 的深度复制，因为 PQcopyResult 无法做到这一点。如果事件过程失败（返回零），则该事件过程在新结果的剩余生命周期中将被忽略；也就是说，它不会收到该结果或从中复制的结果的 PGEVT_RESULTCOPY 或 PGEVT_RESULTDESTROY 事件。
PGEVT_RESULTDESTROY #结果销毁事件在响应 PQclear 时触发。事件过程负责正确清理其事件数据，因为 libpq 没有管理此内存的能力。未能清理将导致内存泄漏。
typedef struct
{
PGresult *result;
} PGEventResultDestroy;
收到 PGEVT_RESULTDESTROY 事件时，应将 evtInfo 指针强制转换为 PGEventResultDestroy *。此事件在 PQclear 执行任何其他清理之前触发。事件过程的返回值将被忽略，因为无法从 PQclear 指示失败。此外，事件过程的失败不应中止清理不需要内存的过程。
PGEventProc #PGEventProc 是事件过程指针的 typedef，即接收 libpq 事件的用户回调函数。事件过程的签名必须是：
int eventproc(PGEventId evtId, void *evtInfo, void *passThrough)
evtId 参数指示发生了哪个 PGEVT 事件。evtInfo 指针必须强制转换为适当的结构类型，以获取有关事件的进一步信息。passThrough 参数是在注册事件过程时传递给 PQregisterEventProc 的指针。如果函数成功，则应返回一个非零值，如果失败，则返回零。
一个特定的事件过程只能在一个 PGconn 中注册一次。这是因为过程的地址用作查找键来标识关联的实例数据。
在 Windows 上，函数可以有两个不同的地址：一个在 DLL 外部可见，另一个在 DLL 内部可见。应谨慎确保只有一个地址与 libpq 的事件过程函数一起使用，否则会导致混淆。要编写可行的代码，最简单的规则是确保事件过程声明为 static。如果过程的地址必须在源文件外部可用，请公开一个单独的函数来返回该地址。
PQregisterEventProc #将事件回调过程注册到 libpq。
int PQregisterEventProc(PGconn *conn, PGEventProc proc,
const char *name, void *passThrough);
每个要接收事件的 PGconn 都必须注册一次事件过程。可以注册到连接的事件过程数量没有限制，除了内存限制。如果成功，函数将返回一个非零值，如果失败，则返回零。
proc 参数将在 libpq 事件触发时被调用。其内存地址也用于查找 instanceData。name 参数用于在错误消息中引用事件过程。此值不能为空 NULL 或零长度字符串。名称字符串会被复制到 PGconn 中，因此传递的值不必是长期存在的。passThrough 指针在事件发生时会传递给 proc。此参数可以是 NULL。
PQsetInstanceData #将连接 conn 的 instanceData 对于过程 proc 设置为 data。此函数返回非零表示成功，零表示失败。（只有当 proc 未能在 conn 中正确注册时才可能失败。）
int PQsetInstanceData(PGconn *conn, PGEventProc proc, void *data);
PQinstanceData #返回连接 conn 的与过程 proc 关联的 instanceData，如果没有则返回 NULL。
void *PQinstanceData(const PGconn *conn, PGEventProc proc);
PQresultSetInstanceData #将结果的 instanceData 对于 proc 设置为 data。此函数返回非零表示成功，零表示失败。（只有当 proc 未能在结果中正确注册时才可能失败。）
int PQresultSetInstanceData(PGresult *res, PGEventProc proc, void *data);
请注意，data 所代表的任何存储都不会被 PQresultMemorySize 统计，除非它是使用 PQresultAlloc 分配的。（这样做是推荐的，因为它消除了在结果销毁时显式释放此类存储的需要。）
PQresultInstanceData #返回结果的与 proc 关联的 instanceData，如果没有则返回 NULL。
void *PQresultInstanceData(const PGresult *res, PGEventProc proc);
这是一个管理与 libpq 连接和结果关联的私有数据的骨架示例。
/* required header for libpq events (note: includes libpq-fe.h) */
#include <libpq-events.h>
/* The instanceData */
typedef struct
{
int n;
char *str;
} mydata;
/* PGEventProc */
static int myEventProc(PGEventId evtId, void *evtInfo, void *passThrough);
int
main(void)
{
mydata *data;
PGresult *res;
PGconn *conn =
PQconnectdb("dbname=postgres options=-csearch_path=");
if (PQstatus(conn) != CONNECTION_OK)
{
/* PQerrorMessage's result includes a trailing newline */
fprintf(stderr, "%s", PQerrorMessage(conn));
PQfinish(conn);
return 1;
}
/* called once on any connection that should receive events.
* Sends a PGEVT_REGISTER to myEventProc.
*/
if (!PQregisterEventProc(conn, myEventProc, "mydata_proc", NULL))
{
fprintf(stderr, "Cannot register PGEventProc\n");
PQfinish(conn);
return 1;
}
/* conn instanceData is available */
data = PQinstanceData(conn, myEventProc);
/* Sends a PGEVT_RESULTCREATE to myEventProc */
res = PQexec(conn, "SELECT 1 + 1");
/* result instanceData is available */
data = PQresultInstanceData(res, myEventProc);
/* If PG_COPYRES_EVENTS is used, sends a PGEVT_RESULTCOPY to myEventProc */
res_copy = PQcopyResult(res, PG_COPYRES_TUPLES | PG_COPYRES_EVENTS);
/* result instanceData is available if PG_COPYRES_EVENTS was
* used during the PQcopyResult call.
*/
data = PQresultInstanceData(res_copy, myEventProc);
/* Both clears send a PGEVT_RESULTDESTROY to myEventProc */
PQclear(res);
PQclear(res_copy);
/* Sends a PGEVT_CONNDESTROY to myEventProc */
PQfinish(conn);
return 0;
}
static int
myEventProc(PGEventId evtId, void *evtInfo, void *passThrough)
{
switch (evtId)
{
case PGEVT_REGISTER:
{
PGEventRegister *e = (PGEventRegister *)evtInfo;
mydata *data = get_mydata(e->conn);
/* associate app specific data with connection */
PQsetInstanceData(e->conn, myEventProc, data);
break;
}
case PGEVT_CONNRESET:
{
PGEventConnReset *e = (PGEventConnReset *)evtInfo;
mydata *data = PQinstanceData(e->conn, myEventProc);
if (data)
memset(data, 0, sizeof(mydata));
break;
}
case PGEVT_CONNDESTROY:
{
PGEventConnDestroy *e = (PGEventConnDestroy *)evtInfo;
mydata *data = PQinstanceData(e->conn, myEventProc);
/* free instance data because the conn is being destroyed */
if (data)
free_mydata(data);
break;
}
case PGEVT_RESULTCREATE:
{
PGEventResultCreate *e = (PGEventResultCreate *)evtInfo;
mydata *conn_data = PQinstanceData(e->conn, myEventProc);
mydata *res_data = dup_mydata(conn_data);
/* associate app specific data with result (copy it from conn) */
PQresultSetInstanceData(e->result, myEventProc, res_data);
break;
}
case PGEVT_RESULTCOPY:
{
PGEventResultCopy *e = (PGEventResultCopy *)evtInfo;
mydata *src_data = PQresultInstanceData(e->src, myEventProc);
mydata *dest_data = dup_mydata(src_data);
/* associate app specific data with result (copy it from a result) */
PQresultSetInstanceData(e->dest, myEventProc, dest_data);
break;
}
case PGEVT_RESULTDESTROY:
{
PGEventResultDestroy *e = (PGEventResultDestroy *)evtInfo;
mydata *data = PQresultInstanceData(e->result, myEventProc);
/* free instance data because the result is being destroyed */
if (data)
free_mydata(data);
break;
}
/* unknown event ID, just return true. */
default:
break;
}
return true; /* event processing succeeded */
}
如果您在文档中发现任何不正确之处、与您对特定功能的实际体验不符或需要进一步澄清的地方，请使用 此表格 报告文档问题。