======
LISTEN
======


.. container:: refentry
   :name: SQL-LISTEN

   .. container:: titlepage

   .. container:: refnamediv

      .. rubric:: LISTEN
         :name: listen

      LISTEN — 监听一个通知

   .. container:: refsynopsisdiv

      .. rubric:: 大纲
         :name: 大纲

      .. code:: synopsis

         LISTEN channel

   .. container:: refsect1
      :name: id-1.9.3.153.5

      .. rubric:: 描述
         :name: 描述

      ``LISTEN``\ 在名为\ *``channel``*\ 的通知频道上将当前会话注册为一个监听者。如果当前会话已经被注册为这个通知频道的一个监听者，则什么也不会发生。

      只要命令\ ``NOTIFY channel``\ 被调用（不管是在这个会话还是在另一个连接到同一数据库的会话中），所有当前正在该通知频道上监听的会话都会被通知，并且每一个会话将会接着通知连接到它的客户端应用。

      可以使用\ ``UNLISTEN``\ 命令在一个给定通知频道上反注册一个会话。当会话结束时，它的监听注册会被自动清除。

      一个客户端应用检测通知事件的必用方法取决于它使用的PostgreSQL应用编程接口。如果使用libpq库，应用会将\ ``LISTEN``\ 作为一个普通
      SQL
      命令发出，并且接着必须周期性地调用函数\ ``PQnotifies``\ 来查看是否接收到通知事件。其他诸如libpgtcl的接口提供了更高层次上的处理通知事件的方法。事实上，通过使用libpgtcl应用程序员甚至不必直接发出\ ``LISTEN``\ 或\ ``UNLISTEN``\ 。更多细节可参阅所使用的接口的文档。

      `NOTIFY <sql-notify.html>`__\ 包含了使用\ ``LISTEN``\ 和\ ``NOTIFY``\ 的更广泛的讨论。

   .. container:: refsect1
      :name: id-1.9.3.153.6

      .. rubric:: 参数
         :name: 参数

      .. container:: variablelist

         *``channel``*
            一个通知频道的名称（任意标识符）。

   .. container:: refsect1
      :name: id-1.9.3.153.7

      .. rubric:: 注解
         :name: 注解

      ``LISTEN``\ 在事务提交时生效。如果在一个后来被回滚的事务中执行了\ ``LISTEN``\ 或\ ``UNLISTEN``\ ，被监听的通知频道集合不会变化。

      一个已经执行了\ ``LISTEN``\ 的事务不能为两阶段提交做准备。

   .. container:: refsect1
      :name: id-1.9.3.153.8

      .. rubric:: 例子
         :name: 例子

      从psql中配置并执行一个监听/通知序列

      .. code:: programlisting

         LISTEN virtual;
         NOTIFY virtual;
         Asynchronous notification "virtual" received from server process with PID 8448.

   .. container:: refsect1
      :name: id-1.9.3.153.9

      .. rubric:: 兼容性
         :name: 兼容性

      在 SQL 标准中没有\ ``LISTEN``\ 语句。

   .. container:: refsect1
      :name: id-1.9.3.153.10

      .. rubric:: 参见
         :name: 参见

      `NOTIFY <sql-notify.html>`__, `UNLISTEN <sql-unlisten.html>`__