使用單一管線的快取訊息

Singleton Pipe 是 DBMS_PIPE 套裝程式的新增功能，可讓您快取和擷取自訂訊息，並以並行讀取的方式跨多個資料庫階段作業共用訊息。

關於使用單一管線快取訊息

DBMS_PIPE 套裝軟體在 Autonomous AI Database 上具有擴充功能，可支援單一管道。

DBMS_PIPE 中的單一管道：

使用單一管線訊息提供自訂資料的記憶體內快取。
支援快取和擷取最多 32,767 個位元組的自訂訊息。
支援在多個資料庫階段作業之間使用並行讀取共用快取訊息。這可提供高傳輸量，並支援跨資料庫階段作業並行讀取訊息。
支援唯讀和讀寫資料庫。
支援數種快取無效化方法：
- 由使用者控制的明確快取無效驗證。
- 使用者指定的時間間隔 (秒) 之後的快取無效驗證。此無效驗證方法是由訊息寄件者使用 shelflife 參數控制，而不是由訊息讀取者控制。這可避免常見的陷阱，因為讀取器快取的使用不正確。

關於標準管和單一管

DBMS_PIPE 套裝程式允許兩個或多個資料庫階段作業使用記憶體內訊息進行通訊。管線功能具有數個應用程式，例如外部服務介面、除錯、獨立交易及警示。請參閱 Oracle Database 19c PL/SQL Packages and Types Reference 中的 DBMS_PIPE 或 Oracle Database 26ai PL/SQL Packages and Types Reference ，瞭解詳細資訊。

database-pipe-messages-singleton-pipes.png 圖解描述

「單一管線」可以是任何一種支援的 DBMS_PIPE 類型：

隱含管：使用 DBMS_PIPE.SEND_MESSAGE 函數以不明的管路名稱傳送訊息時，會自動建立。
明確管線：使用 DBMS_PIPE.CREATE_PIPE 函數與使用者指定的管線名稱建立。
公用管線：任何具備 DBMS_PIPE 套裝程式之 EXECUTE 權限的使用者都可以存取。
專用管線：具有與管線建立者相同之使用者的階段作業可以存取。

Singleton Pipes 可讓您在自治式 AI 資料庫執行處理的記憶體中快取單一訊息。

以下顯示使用單一管的一般工作流程。

singleton-pipe-workflow.png 圖解描述

Singleton 管線概述和功能

單一訊息
- Singleton Pipe 可以快取管中的一個訊息，因此名稱為 "singleton"。
- 「單一管線」中的訊息可由多個欄位組成，最多可包含 32,767 個位元組的訊息大小總計。
- DBMS_PIPE 支援使用 DBMS_PIPE.PACK_MESSAGE 程序在訊息中封裝多個屬性的功能。
- 對於「公用單一管線」，任何具有 DBMS_PIPE 套裝程式執行權限的資料庫階段作業都可以接收訊息。
- 若為「專用單一管線」，階段作業可以接收與「單一管線」建立者相同之使用者的訊息。
讀取的訊息處理量上限
- Singleton Pipes 會快取管中的訊息，直到訊息失效或清除為止。資料庫階段作業可以同時從「單一管線」讀取訊息。
- 從單一管道接收訊息是非封鎖作業。
快取訊息
- 訊息使用 DBMS_PIPE.SEND_MESSAGE 快取至單一管中。
- 如果「單一管線」中已有快取訊息，則 DBMS_PIPE.SEND_MESSAGE 會覆寫上一則訊息，以在「單一管線」中僅保留一則訊息。
訊息無效化
- 明確無效化：使用 DBMS_PIPE.PURGE 程序清除管路，或使用 DBMS_PIPE.SEND_MESSAGE 覆寫訊息。
- 自動失效：訊息可以在經過指定的 shelflife 時間之後自動失效。
沒有從資料庫記憶體收回
- Oracle Database 記憶體無法收回 Singleton Pipes。
- 「明確單一管線」會繼續位於資料庫記憶體中，直到使用 DBMS_PIPE.REMOVE_PIPE 移除，或直到資料庫重新啟動為止。
- 「隱含單一管線」會保留在資料庫記憶體中，直到管線中有一個快取訊息為止。

Singleton 管線作業

操作	DBMS_PIPE 功能或過程
建立明確單一管線	CREATE_PIPE 函數
在 Singleton Pipe 中快取訊息	Oracle Database 19c PL/SQL Packages and Types Reference 或 Oracle Database 26ai PL/SQL Packages and Types Reference 中的 PACK_MESSAGE Procedures SEND_MESSAGE 函數
讀取 Singleton Pipe 的快取訊息	Oracle Database 19c PL/SQL Packages and Types Reference 或 Oracle Database 26ai PL/SQL Packages and Types Reference 中的 RECEIVE_MESSAGE 函數、 UNPACK_MESSAGE 程序
刪除 Singleton Pipe 中的訊息	Oracle Database 19c PL/SQL Packages and Types Reference 或 Oracle Database 26ai PL/SQL Packages and Types Reference 中的 PURGE Procedure
移除明確的單一管線	Oracle Database 19c PL/SQL Packages and Types Reference 或 Oracle Database 26ai PL/SQL Packages and Types Reference 中的 REMOVE_PIPE 函數

使用快取函數自動重新整理快取訊息

DBMS_PIPE 套裝程式可讓您使用使用者定義的快取功能，自動產生「單一管」訊息。

依照預設，使用 Singleton Pipe 明確或隱含無效驗證讓訊息變成無效之後，後續的 DBMS_PIPE.RECEIVE_MESSAGE 便不會收到任何訊息。若要將新訊息新增至管道，必須透過呼叫 DBMS_PIPE.SEND_MESSAGE 來明確快取訊息。若要避免此情況發生，當您從單一管路讀取時沒有訊息，您可以定義快取功能。定義快取函數後，當您收到下列情況的訊息時，會自動呼叫快取函數：

單一管線空白時。
當「單一管線」中的訊息因 shelflife 時間而無效時。

若要使用快取函式，請定義快取函式，並包含 cache_func 參數與 DBMS_PIPE.RECEIVE_MESSAGE。使用者定義的快取函式提供下列各項：

使用 DBMS_PIPE.RECEIVE_MESSAGE 從單一管路讀取訊息時，可以指定快取函數。
當「單一管線」中沒有訊息時，DBMS_PIPE.RECEIVE_MESSAGE 會呼叫快取功能。
訊息 shelflife 時間經過時，資料庫會自動在「單一管線」中填入新訊息。

使用快取函數可簡化使用單一管路。您不需要處理從空白管道接收訊息的失敗案例。此外，快取功能可確保從單一管路讀取訊息時不會遺漏快取記憶體，提供快取訊息的最大使用量。

autom-cache-refresh-cache-function.eps 的描述如下

autom-cache-refresh-cache-function.png 圖解描述

定義快取函數時，函數名稱必須與擁有者綱要完全合格：

OWNER.FUNCTION_NAME
OWNER.PACKAGE.FUNCTION_NAME

使用下列簽章定義快取函數：

CREATE OR REPLACE FUNCTION *cache_function_name*(
       pipename  IN VARCHAR2
) RETURN INTEGER;

快取函數內的一般作業為：

使用 DBMS_PIPE.CREATE_PIPE 建立「明確管線」的「單一管線」。
在「單一管線」中建立要快取的訊息。
將訊息傳送至快取函數中指定的管道，選擇性地為隱含訊息指定 shelflife。

若要使用快取功能，呼叫 DBMS_PIPE.RECEIVE_MESSAGE 的目前階段作業使用者必須具有執行快取功能的必要權限。

請參閱 RECIEVE_MESSAGE 函數，瞭解有關定義快取函數的詳細資訊。

建立明確單一管線

說明以指定管道名稱 (明確單一管道) 建立單一管道的步驟。

首先，在此範例中建立 receive_message 協助程式函數，以重複呼叫 DBMS_PIPE.RECEIVE_MESSAGE。這可讓您測試單一管路功能。

CREATE OR REPLACE FUNCTION msg_types AS
       TYPE t_rcv_row IS RECORD (c1 VARCHAR2(32767), c2 NUMBER);
       TYPE t_rcv_tab IS TABLE OF t_rcv_row;
END;


CREATE OR REPLACE FUNCTION receive_message(
      pipename    IN VARCHAR2,
      rcv_count   IN NUMBER DEFAULT 1,
      cache_func  IN VARCHAR2 DEFAULT NULL)
   RETURN msg_types.t_rcv_tab pipelined
    AS
       l_msg    VARCHAR2(32767);
       l_status NUMBER;
 BEGIN
      FOR i IN 1..rcv_count LOOP
           l_status := DBMS_PIPE.RECEIVE_MESSAGE(
            pipename   => pipename,
            cache_func => cache_func,
            timeout    => 1);
         IF l_status != 0 THEN
              raise_application_error(-20000,
             'Message not received for attempt: ' || to_char(i) || ' status: ' ||
            l_status);
         END IF;

         DBMS_PIPE.UNPACK_MESSAGE(l_msg);
             pipe row(msg_types.t_rcv_row(l_msg));
     END LOOP;
 RETURN;
 END;

建立名為 PIPE_TEST 的明確單一管道，並將 shelflife 參數設為 3600 (秒)。

   DECLARE
   l_status INTEGER;
   BEGIN
   l_status := DBMS_PIPE.CREATE_PIPE(
                 pipename => 'MY_PIPE1',
                 private => TRUE,
                 singleton => TRUE,
                 shelflife => 3600);
   END;
   /

請參閱 CREATE_PIPE 函數瞭解詳細資訊。

確認已建立單一管道。

 SELECT name, singleton, type
      FROM v$db_pipes WHERE name= '&pipename' ORDER BY 1;

 NAME                 SINGLETON  TYPE

 -------------------- ---------- -------
 PIPE_TEST            YES        PRIVATE

以單獨管道包裝並傳送訊息。
```
 EXEC DBMS_PIPE.PACK_MESSAGE('This is a real message that you can get multiple times');

 SELECT DBMS_PIPE.SEND_MESSAGE(pipename => '&pipename') status FROM DUAL;
```
```
 STATUS

 ----------
 0
```
請參閱 Oracle Database 19c PL/SQL Packages and Types Reference 中的 PACK_MESSAGE Procedures 或 Oracle Database 26ai PL/SQL Packages and Types Reference 和 SEND_MESSAGE Function 以瞭解詳細資訊。

從單一管道接收訊息。

 SELECT * FROM receive_message(
     pipename => '&pipename',
     rcv_count => 2);

 MESSAGE

 --------------------------------------------------------------------------------
 This is a real message that you can get multiple times
 This is a real message that you can get multiple times

receive_message 函數是呼叫 DBMS_PIPE.RECEIVE_MESSAGE 的協助程式函數。

清除訊息並移除管道。

 EXEC DBMS_PIPE.PURGE('&pipename');
 SELECT DBMS_PIPE.REMOVE_PIPE('&pipename') status FROM DUAL;

使用快取函數建立明確的單一管線

說明建立具有指定管道名稱、明確單一管道以及提供快取功能的單一管道的步驟。快取功能可讓您在單一管道中自動植入訊息。

建立單一管道的快取功能 test_cache_message。

 CREATE OR REPLACE FUNCTION test_cache_message(
      pipename IN VARCHAR2) return NUMBER

 AS
    l_status NUMBER;
    l_data VARCHAR2(4000);
 BEGIN
    l_status := DBMS_PIPE.CREATE_PIPE(
           pipename => pipename,
           private => TRUE,
           singleton => true,
           shelflife => 600);
    IF l_status != 0 THEN RETURN l_status;
    END IF;

    DBMS_PIPE.PACK_MESSAGE('This is a placeholder cache message for an empty pipe');
    l_status := DBMS_PIPE.SEND_MESSAGE(pipename => pipename);
    RETURN l_status;
  END;
 /

注意：呼叫 DBMS_PIPE.RECEIVE_MESSAGE 的目前階段作業使用者必須具有必要的權限，才能執行快取功能。

接收快取功能並確認訊息植入管道中。管線必須以在快取功能中建立的專用管形式存在。
```
 SELECT * FROM receive_message(
      pipename => '&pipename',
      rcv_count => 1,
      cache_func => 'TEST_CACHE_MESSAGE');
```
```
 MESSAGE

 ---------------
 This is a placeholder cache message for an empty pipe
```
receive_message 函數是呼叫 DBMS_PIPE.RECEIVE_MESSAGE 的協助程式函數。請參閱建立明確單一管線以取得 receive_message 定義。

請參閱 CREATE_PIPE 函數瞭解詳細資訊。
不使用快取功能接收，以確認訊息保留在管道中。
```
 SELECT * FROM receive_message(
      pipename => '&pipename',
      rcv_count => 2);
```
```
 MESSAGE

 ---------------
 This is a placeholder cache message for an empty pipe
 This is a placeholder cache message for an empty pipe
```
receive_message 函數是呼叫 DBMS_PIPE.RECEIVE_MESSAGE 的協助程式函數。請參閱建立明確單一管線以取得 receive_message 定義。

請參閱 CREATE_PIPE 函數瞭解詳細資訊。