2025年9月25日: PostgreSQL 18 釋出!
支援的版本:當前 (18) / 17 / 16 / 15 / 14 / 13
開發版本:devel
不支援的版本:12 / 11 / 10 / 9.6 / 9.5 / 9.4 / 9.3 / 9.2 / 9.1 / 9.0 / 8.4

32.14. 事件系統 #

libpq 的事件系統旨在通知已註冊的事件處理程式有關 libpq 的重要事件,例如 PGconnPGresult 物件的建立或銷燬。主要用例是,這允許應用程式將自己的資料與 PGconnPGresult 關聯起來,並確保在適當的時間釋放這些資料。

每個已註冊的事件處理程式都與兩部分資料相關聯,在 libpq 中僅作為不透明的 void * 指標。有一個“傳遞”(pass-through)指標,在將事件處理程式註冊到 PGconn 時由應用程式提供。此傳遞指標在 PGconn 的整個生命週期及其生成的所有 PGresult 中都不會改變;因此,如果使用,它必須指向長期存在的資料。此外,還有一個“例項資料”(instance data)指標,在每個 PGconnPGresult 中初始值為 NULL。此指標可以使用 PQinstanceDataPQsetInstanceDataPQresultInstanceDataPQresultSetInstanceData 函式進行操作。請注意,與傳遞指標不同,由 PGconn 建立的 PGresult 不會自動繼承 PGconn 的例項資料。 libpq 不知道傳遞指標和例項資料指標(如果它們指向任何東西)指向何處,也不會嘗試釋放它們——這由事件處理程式負責。

32.14.1. 事件型別 #

列舉 PGEventId 命名了事件系統處理的事件型別。它的所有值都以 PGEVT 開頭。對於每種事件型別,都有一個相應的事件資訊結構,它攜帶傳遞給事件處理程式的引數。事件型別是:

PGEVT_REGISTER #

當呼叫 PQregisterEventProc 時會發生註冊事件。這是初始化事件過程可能需要的任何 instanceData 的理想時機。每個連線每個事件處理程式只觸發一次註冊事件。如果事件過程失敗(返回零),則註冊將被取消。

typedef struct
{
    PGconn *conn;
} PGEventRegister;

收到 PGEVT_REGISTER 事件時,應將 evtInfo 指標強制轉換為 PGEventRegister *。此結構包含一個 PGconn,它應該處於 CONNECTION_OK 狀態;如果呼叫 PQregisterEventProc 緊接著獲得一個有效的 PGconn,則可以保證這一點。返回失敗程式碼時,必須執行所有清理工作,因為不會發送 PGEVT_CONNDESTROY 事件。

PGEVT_CONNRESET #

連線重置事件在 PQresetPQresetPoll 完成時觸發。在這兩種情況下,只有在重置成功時才會觸發事件。在 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_RESULTCOPYPGEVT_RESULTDESTROY 事件。

PGEVT_RESULTCOPY #

結果複製事件在響應 PQcopyResult 時觸發。此事件僅在複製完成後觸發。只有成功處理了源結果的 PGEVT_RESULTCREATEPGEVT_RESULTCOPY 事件的事件過程才會收到 PGEVT_RESULTCOPY 事件。

typedef struct
{
    const PGresult *src;
    PGresult *dest;
} PGEventResultCopy;

收到 PGEVT_RESULTCOPY 事件時,應將 evtInfo 指標強制轉換為 PGEventResultCopy *src 結果是被複制的源,而 dest 結果是複製的目標。此事件可用於提供 instanceData 的深度複製,因為 PQcopyResult 無法做到這一點。如果事件過程失敗(返回零),則該事件過程在新結果的剩餘生命週期中將被忽略;也就是說,它不會收到該結果或從中複製的結果的 PGEVT_RESULTCOPYPGEVT_RESULTDESTROY 事件。

PGEVT_RESULTDESTROY #

結果銷燬事件在響應 PQclear 時觸發。事件過程負責正確清理其事件資料,因為 libpq 沒有管理此記憶體的能力。未能清理將導致記憶體洩漏。

typedef struct
{
    PGresult *result;
} PGEventResultDestroy;

收到 PGEVT_RESULTDESTROY 事件時,應將 evtInfo 指標強制轉換為 PGEventResultDestroy *。此事件在 PQclear 執行任何其他清理之前觸發。事件過程的返回值將被忽略,因為無法從 PQclear 指示失敗。此外,事件過程的失敗不應中止清理不需要記憶體的過程。

32.14.2. 事件回撥過程 #

PGEventProc #

PGEventProc 是事件過程指標的 typedef,即接收 libpq 事件的使用者回撥函式。事件過程的簽名必須是:

int eventproc(PGEventId evtId, void *evtInfo, void *passThrough)

evtId 引數指示發生了哪個 PGEVT 事件。evtInfo 指標必須強制轉換為適當的結構型別,以獲取有關事件的進一步資訊。passThrough 引數是在註冊事件過程時傳遞給 PQregisterEventProc 的指標。如果函式成功,則應返回一個非零值,如果失敗,則返回零。

一個特定的事件過程只能在一個 PGconn 中註冊一次。這是因為過程的地址用作查詢鍵來標識關聯的例項資料。

注意

在 Windows 上,函式可以有兩個不同的地址:一個在 DLL 外部可見,另一個在 DLL 內部可見。應謹慎確保只有一個地址與 libpq 的事件過程函式一起使用,否則會導致混淆。要編寫可行的程式碼,最簡單的規則是確保事件過程宣告為 static。如果過程的地址必須在原始檔外部可用,請公開一個單獨的函式來返回該地址。

32.14.3. 事件支援函式 #

PQregisterEventProc #

將事件回撥過程註冊到 libpq。

int PQregisterEventProc(PGconn *conn, PGEventProc proc,
                        const char *name, void *passThrough);

每個要接收事件的 PGconn 都必須註冊一次事件過程。可以註冊到連線的事件過程數量沒有限制,除了記憶體限制。如果成功,函式將返回一個非零值,如果失敗,則返回零。

proc 引數將在 libpq 事件觸發時被呼叫。其記憶體地址也用於查詢 instanceDataname 引數用於在錯誤訊息中引用事件過程。此值不能為空 NULL 或零長度字串。名稱字串會被複制到 PGconn 中,因此傳遞的值不必是長期存在的。passThrough 指標在事件發生時會傳遞給 proc。此引數可以是 NULL

PQsetInstanceData #

將連線 conninstanceData 對於過程 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);

32.14.4. 事件示例 #

這是一個管理與 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 */
}

提交更正

如果您在文件中發現任何不正確之處、與您對特定功能的實際體驗不符或需要進一步澄清的地方,請使用 此表格 報告文件問題。