database/postgres
1
0
Fork 0
mirror of https://github.com/postgres/postgres.git synced 2025-07-30 11:03:19 +03:00
Code Activity

Replace the pg_listener-based LISTEN/NOTIFY mechanism with an in-memory queue.

Browse Source 
In addition, add support for a "payload" string to be passed along with
each notify event.

This implementation should be significantly more efficient than the old one,
and is also more compatible with Hot Standby usage.  There is not yet any
facility for HS slaves to receive notifications generated on the master,
although such a thing is possible in future.

Joachim Wieland, reviewed by Jeff Davis; also hacked on by me.
This commit is contained in:
Tom Lane
2010-02-16 22:34:57 +00:00
parent fc5173ad51
commit d1e027221d
37 changed files with 1831 additions and 744 deletions
Download Patch File Download Diff File Expand all files Collapse all files

69
doc/src/sgml/catalogs.sgml
View File

@ -1,4 +1,4 @@
<!-- $PostgreSQL: pgsql/doc/src/sgml/catalogs.sgml,v 2.221 2010/02/07 20:48:09 tgl Exp $ -->
<!-- $PostgreSQL: pgsql/doc/src/sgml/catalogs.sgml,v 2.222 2010/02/16 22:34:41 tgl Exp $ -->
<!--
Documentation of the system catalogs, directed toward PostgreSQL developers
-->
@ -168,11 +168,6 @@
<entry>metadata for large objects</entry>
</row>
<row>
<entry><link linkend="catalog-pg-listener"><structname>pg_listener</structname></link></entry>
<entry>asynchronous notification support</entry>
</row>
<row>
<entry><link linkend="catalog-pg-namespace"><structname>pg_namespace</structname></link></entry>
<entry>schemas</entry>
@ -3253,68 +3248,6 @@
</table>
</sect1>
<sect1 id="catalog-pg-listener">
<title><structname>pg_listener</structname></title>
<indexterm zone="catalog-pg-listener">
<primary>pg_listener</primary>
</indexterm>
<para>
The catalog <structname>pg_listener</structname> supports the
<xref linkend="sql-listen" endterm="sql-listen-title"> and
<xref linkend="sql-notify" endterm="sql-notify-title">
commands. A listener creates an entry in
<structname>pg_listener</structname> for each notification name
it is listening for. A notifier scans <structname>pg_listener</structname>
and updates each matching entry to show that a notification has occurred.
The notifier also sends a signal (using the PID recorded in the table)
to awaken the listener from sleep.
</para>
<table>
<title><structname>pg_listener</> Columns</title>
<tgroup cols="3">
<thead>
<row>
<entry>Name</entry>
<entry>Type</entry>
<entry>Description</entry>
</row>
</thead>
<tbody>
<row>
<entry><structfield>relname</structfield></entry>
<entry><type>name</type></entry>
<entry>
Notify condition name. (The name need not match any actual
relation in the database; the name <structfield>relname</> is historical.)
</entry>
</row>
<row>
<entry><structfield>listenerpid</structfield></entry>
<entry><type>int4</type></entry>
<entry>PID of the server process that created this entry</entry>
</row>
<row>
<entry><structfield>notification</structfield></entry>
<entry><type>int4</type></entry>
<entry>
Zero if no event is pending for this listener. If an event is
pending, the PID of the server process that sent the notification
</entry>
</row>
</tbody>
</tgroup>
</table>
</sect1>
<sect1 id="catalog-pg-namespace">
<title><structname>pg_namespace</structname></title>

18
doc/src/sgml/func.sgml
View File

@ -1,4 +1,4 @@
<!-- $PostgreSQL: pgsql/doc/src/sgml/func.sgml,v 1.503 2010/02/16 21:18:01 momjian Exp $ -->
<!-- $PostgreSQL: pgsql/doc/src/sgml/func.sgml,v 1.504 2010/02/16 22:34:42 tgl Exp $ -->
<chapter id="functions">
<title>Functions and Operators</title>
@ -11529,6 +11529,12 @@ postgres=# select * from unnest2(array[[1,2],[3,4]]);
</entry>
</row>
<row>
<entry><literal><function>pg_listening_channels</function>()</literal></entry>
<entry><type>setof text</type></entry>
<entry>channel names that the session is currently listening on</entry>
</row>
<row>
<entry><literal><function>inet_client_addr</function>()</literal></entry>
<entry><type>inet</type></entry>
@ -11674,6 +11680,16 @@ SET search_path TO <replaceable>schema</> <optional>, <replaceable>schema</>, ..
</para>
</note>
<indexterm>
<primary>pg_listening_channels</primary>
</indexterm>
<para>
<function>pg_listening_channels</function> returns a set of names of
channels that the current session is listening to. See <xref
linkend="sql-listen" endterm="sql-listen-title"> for more information.
</para>
<indexterm>
<primary>inet_client_addr</primary>
</indexterm>

52
doc/src/sgml/libpq.sgml
View File

@ -1,4 +1,4 @@
<!-- $PostgreSQL: pgsql/doc/src/sgml/libpq.sgml,v 1.298 2010/02/16 20:58:13 momjian Exp $ -->
<!-- $PostgreSQL: pgsql/doc/src/sgml/libpq.sgml,v 1.299 2010/02/16 22:34:42 tgl Exp $ -->
<chapter id="libpq">
<title><application>libpq</application> - C Library</title>
@ -307,28 +307,28 @@
<entry>Description</entry>
</row>
</thead>
<tbody>
<row>
<entry><literal>disable</></entry>
<entry>only try a non-<acronym>SSL</> connection</entry>
</row>
<row>
<entry><literal>allow</></entry>
<entry>first try a non-<acronym>SSL</>
connection; if that fails, try an <acronym>SSL</>
connection</entry>
</row>
<row>
<entry><literal>prefer</> (default)</entry>
<entry>first try an <acronym>SSL</> connection; if
that fails, try a non-<acronym>SSL</>
connection</entry>
</row>
<row>
<entry><literal>require</></entry>
<entry>only try an <acronym>SSL</> connection</entry>
@ -481,7 +481,7 @@
</para>
<para>
If <literal>expand_dbname</literal> is non-zero and
If <literal>expand_dbname</literal> is non-zero and
<parameter>dbname</parameter> contains an <symbol>=</symbol> sign, it
is taken as a <parameter>conninfo</parameter> string in exactly the same way as
if it had been passed to <function>PQconnectdb</function>(see below). Previously
@ -4111,50 +4111,48 @@ typedef struct {
<productname>PostgreSQL</productname> offers asynchronous notification
via the <command>LISTEN</command> and <command>NOTIFY</command>
commands. A client session registers its interest in a particular
notification condition with the <command>LISTEN</command> command (and
notification channel with the <command>LISTEN</command> command (and
can stop listening with the <command>UNLISTEN</command> command). All
sessions listening on a particular condition will be notified
sessions listening on a particular channel will be notified
asynchronously when a <command>NOTIFY</command> command with that
condition name is executed by any session. No additional information
is passed from the notifier to the listener. Thus, typically, any
actual data that needs to be communicated is transferred through a
database table. Commonly, the condition name is the same as the
associated table, but it is not necessary for there to be any associated
table.
channel name is executed by any session. A <quote>payload</> string can
be passed to communicate additional data to the listeners.
</para>
<para>
<application>libpq</application> applications submit
<command>LISTEN</command> and <command>UNLISTEN</command> commands as
<command>LISTEN</command>, <command>UNLISTEN</command>,
and <command>NOTIFY</command> commands as
ordinary SQL commands. The arrival of <command>NOTIFY</command>
messages can subsequently be detected by calling
<function>PQnotifies</function>.<indexterm><primary>PQnotifies</></>
</para>
<para>
The function <function>PQnotifies</function>
returns the next notification from a list of unhandled
notification messages received from the server. It returns a null pointer if
there are no pending notifications. Once a notification is
returned from <function>PQnotifies</>, it is considered handled and will be
removed from the list of notifications.
The function <function>PQnotifies</function> returns the next notification
from a list of unhandled notification messages received from the server.
It returns a null pointer if there are no pending notifications. Once a
notification is returned from <function>PQnotifies</>, it is considered
handled and will be removed from the list of notifications.
<synopsis>
PGnotify *PQnotifies(PGconn *conn);
typedef struct pgNotify {
char *relname; /* notification condition name */
char *relname; /* notification channel name */
int be_pid; /* process ID of notifying server process */
char *extra; /* notification parameter */
char *extra; /* notification payload string */
} PGnotify;
</synopsis>
After processing a <structname>PGnotify</structname> object returned
by <function>PQnotifies</function>, be sure to free it with
<function>PQfreemem</function>. It is sufficient to free the
<structname>PGnotify</structname> pointer; the
<structfield>relname</structfield> and <structfield>extra</structfield>
fields do not represent separate allocations. (At present, the
<structfield>extra</structfield> field is unused and will always point
to an empty string.)
fields do not represent separate allocations. (The names of these fields
are historical; in particular, channel names need not have anything to
do with relation names.)
</para>
<para>

23
doc/src/sgml/protocol.sgml
View File

@ -1,4 +1,4 @@
<!-- $PostgreSQL: pgsql/doc/src/sgml/protocol.sgml,v 1.80 2010/02/16 20:58:14 momjian Exp $ -->
<!-- $PostgreSQL: pgsql/doc/src/sgml/protocol.sgml,v 1.81 2010/02/16 22:34:43 tgl Exp $ -->
<chapter id="protocol">
<title>Frontend/Backend Protocol</title>
@ -354,7 +354,7 @@
<para>
This message contains the response data from the previous step
of GSSAPI or SSPI negotiation (AuthenticationGSS, AuthenticationSSPI
or a previous AuthenticationGSSContinue). If the GSSAPI
or a previous AuthenticationGSSContinue). If the GSSAPI
or SSPI data in this message
indicates more data is needed to complete the authentication,
the frontend must send that data as another PasswordMessage. If
@ -992,7 +992,7 @@
<para>
In the event of a backend-detected error during copy-in mode (including
receipt of a CopyFail message), the backend will issue an ErrorResponse
receipt of a CopyFail message), the backend will issue an ErrorResponse
message. If the <command>COPY</> command was issued via an extended-query
message, the backend will now discard frontend messages until a Sync
message is received, then it will issue ReadyForQuery and return to normal
@ -1117,7 +1117,7 @@
backend will send a NotificationResponse message (not to be
confused with NoticeResponse!) whenever a
<command>NOTIFY</command> command is executed for the same
notification name.
channel name.
</para>
<note>
@ -1340,7 +1340,7 @@ This section describes the base data types used in messages.
value that will appear, otherwise the value is variable.
Eg. String, String("user").
</para>
<note>
<para>
<emphasis>There is no predefined limit</emphasis> on the length of a string
@ -1951,7 +1951,7 @@ Bind (F)
(denoted <replaceable>R</> below).
This can be zero to indicate that there are no result columns
or that the result columns should all use the default format
(text);
(text);
or one, in which case the specified format code is applied
to all result columns (if any); or it can equal the actual
number of result columns of the query.
@ -2500,7 +2500,7 @@ CopyOutResponse (B)
separated by separator characters, etc). 1 indicates
the overall copy format is binary (similar to DataRow
format). See <xref linkend="sql-copy"
endterm="sql-copy-title"> for more information.
endterm="sql-copy-title"> for more information.
</para>
</listitem>
</varlistentry>
@ -3187,7 +3187,7 @@ NotificationResponse (B)
</term>
<listitem>
<para>
The name of the condition that the notify has been raised on.
The name of the channel that the notify has been raised on.
</para>
</listitem>
</varlistentry>
@ -3197,9 +3197,7 @@ NotificationResponse (B)
</term>
<listitem>
<para>
Additional information passed from the notifying process.
(Currently, this feature is unimplemented so the field
is always an empty string.)
The <quote>payload</> string passed from the notifying process.
</para>
</listitem>
</varlistentry>
@ -4353,7 +4351,7 @@ the backend.
<para>
The NotificationResponse ('<literal>A</>') message has an additional string
field, which is presently empty but might someday carry additional data passed
field, which can carry a <quote>payload</> string passed
from the <command>NOTIFY</command> event sender.
</para>
@ -4364,5 +4362,4 @@ string parameter; this has been removed.
</sect1>
</chapter>

38
doc/src/sgml/ref/listen.sgml
View File

@ -1,5 +1,5 @@
<!--
$PostgreSQL: pgsql/doc/src/sgml/ref/listen.sgml,v 1.23 2008/11/14 10:22:47 petere Exp $
$PostgreSQL: pgsql/doc/src/sgml/ref/listen.sgml,v 1.24 2010/02/16 22:34:43 tgl Exp $
PostgreSQL documentation
-->
@ -21,7 +21,7 @@ PostgreSQL documentation
<refsynopsisdiv>
<synopsis>
LISTEN <replaceable class="PARAMETER">name</replaceable>
LISTEN <replaceable class="PARAMETER">channel</replaceable>
</synopsis>
</refsynopsisdiv>
@ -30,24 +30,23 @@ LISTEN <replaceable class="PARAMETER">name</replaceable>
<para>
<command>LISTEN</command> registers the current session as a
listener on the notification condition <replaceable
class="PARAMETER">name</replaceable>.
listener on the notification channel named <replaceable
class="PARAMETER">channel</replaceable>.
If the current session is already registered as a listener for
this notification condition, nothing is done.
this notification channel, nothing is done.
</para>
<para>
Whenever the command <command>NOTIFY <replaceable
class="PARAMETER">name</replaceable></command> is invoked, either
class="PARAMETER">channel</replaceable></command> is invoked, either
by this session or another one connected to the same database, all
the sessions currently listening on that notification condition are
the sessions currently listening on that notification channel are
notified, and each will in turn notify its connected client
application. See the discussion of <command>NOTIFY</command> for
more information.
application.
</para>
<para>
A session can be unregistered for a given notify condition with the
A session can be unregistered for a given notification channel with the
<command>UNLISTEN</command> command. A session's listen
registrations are automatically cleared when the session ends.
</para>
@ -78,16 +77,31 @@ LISTEN <replaceable class="PARAMETER">name</replaceable>
<variablelist>
<varlistentry>
<term><replaceable class="PARAMETER">name</replaceable></term>
<term><replaceable class="PARAMETER">channel</replaceable></term>
<listitem>
<para>
Name of a notify condition (any identifier).
Name of a notification channel (any identifier).
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1>
<title>Notes</title>
<para>
<command>LISTEN</command> takes effect at transaction commit.
If <command>LISTEN</command> or <command>UNLISTEN</command> is executed
within a transaction that later rolls back, the set of notification
channels being listened to is unchanged.
</para>
<para>
A transaction that has executed <command>LISTEN</command> cannot be
prepared for two-phase commit.
</para>
</refsect1>
<refsect1>
<title>Examples</title>

121
doc/src/sgml/ref/notify.sgml
View File

@ -1,5 +1,5 @@
<!--
$PostgreSQL: pgsql/doc/src/sgml/ref/notify.sgml,v 1.31 2008/11/14 10:22:47 petere Exp $
$PostgreSQL: pgsql/doc/src/sgml/ref/notify.sgml,v 1.32 2010/02/16 22:34:43 tgl Exp $
PostgreSQL documentation
-->
@ -21,7 +21,7 @@ PostgreSQL documentation
<refsynopsisdiv>
<synopsis>
NOTIFY <replaceable class="PARAMETER">name</replaceable>
NOTIFY <replaceable class="PARAMETER">channel</replaceable> [ , <replaceable class="PARAMETER">payload</replaceable> ]
</synopsis>
</refsynopsisdiv>
@ -29,35 +29,39 @@ NOTIFY <replaceable class="PARAMETER">name</replaceable>
<title>Description</title>
<para>
The <command>NOTIFY</command> command sends a notification event to each
client application that has previously executed
<command>LISTEN <replaceable class="parameter">name</replaceable></command>
for the specified notification name in the current database.
The <command>NOTIFY</command> command sends a notification event together
with an optional <quote>payload</> string to each client application that
has previously executed
<command>LISTEN <replaceable class="parameter">channel</></command>
for the specified channel name in the current database.
</para>
<para>
<command>NOTIFY</command> provides a simple form of signal or
<command>NOTIFY</command> provides a simple
interprocess communication mechanism for a collection of processes
accessing the same <productname>PostgreSQL</productname> database.
Higher-level mechanisms can be built by using tables in the database to
pass additional data (beyond a mere notification name) from notifier to
listener(s).
A payload string can be sent along with the notification, and
higher-level mechanisms for passing structured data can be built by using
tables in the database to pass additional data from notifier to listener(s).
</para>
<para>
The information passed to the client for a notification event includes the notification
name and the notifying session's server process <acronym>PID</>. It is up to the
database designer to define the notification names that will be used in a given
database and what each one means.
The information passed to the client for a notification event includes the
notification channel
name, the notifying session's server process <acronym>PID</>, and the
payload string, which is an empty string if it has not been specified.
</para>
<para>
Commonly, the notification name is the same as the name of some table in
It is up to the database designer to define the channel names that will
be used in a given database and what each one means.
Commonly, the channel name is the same as the name of some table in
the database, and the notify event essentially means, <quote>I changed this table,
take a look at it to see what's new</quote>. But no such association is enforced by
the <command>NOTIFY</command> and <command>LISTEN</command> commands. For
example, a database designer could use several different notification names
to signal different sorts of changes to a single table.
example, a database designer could use several different channel names
to signal different sorts of changes to a single table. Alternatively,
the payload string could be used to differentiate various cases.
</para>
<para>
@ -89,19 +93,22 @@ NOTIFY <replaceable class="PARAMETER">name</replaceable>
</para>
<para>
<command>NOTIFY</command> behaves like Unix signals in one important
respect: if the same notification name is signaled multiple times in quick
succession, recipients might get only one notification event for several executions
of <command>NOTIFY</command>. So it is a bad idea to depend on the number
of notifications received. Instead, use <command>NOTIFY</command> to wake up
applications that need to pay attention to something, and use a database
object (such as a sequence) to keep track of what happened or how many times
it happened.
If the same channel name is signaled multiple times from the same
transaction with identical payload strings, the
database server can decide to deliver a single notification only.
On the other hand, notifications with distinct payload strings will
always be delivered as distinct notifications. Similarly, notifications from
different transactions will never get folded into one notification.
Except for dropping later instances of duplicate notifications,
<command>NOTIFY</command> guarantees that notifications from the same
transaction get delivered in the order they were sent. It is also
guaranteed that messages from different transactions are delivered in
the order in which the transactions committed.
</para>
<para>
It is common for a client that executes <command>NOTIFY</command>
to be listening on the same notification name itself. In that case
to be listening on the same notification channel itself. In that case
it will get back a notification event, just like all the other
listening sessions. Depending on the application logic, this could
result in useless work, for example, reading a database table to
@ -111,12 +118,7 @@ NOTIFY <replaceable class="PARAMETER">name</replaceable>
notification event message) is the same as one's own session's
<acronym>PID</> (available from <application>libpq</>). When they
are the same, the notification event is one's own work bouncing
back, and can be ignored. (Despite what was said in the preceding
paragraph, this is a safe technique.
<productname>PostgreSQL</productname> keeps self-notifications
separate from notifications arriving from other sessions, so you
cannot miss an outside notification by ignoring your own
notifications.)
back, and can be ignored.
</para>
</refsect1>
@ -125,16 +127,61 @@ NOTIFY <replaceable class="PARAMETER">name</replaceable>
<variablelist>
<varlistentry>
<term><replaceable class="PARAMETER">name</replaceable></term>
<term><replaceable class="PARAMETER">channel</replaceable></term>
<listitem>
<para>
Name of the notification to be signaled (any identifier).
Name of the notification channel to be signaled (any identifier).
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><replaceable class="PARAMETER">payload</replaceable></term>
<listitem>
<para>
The <quote>payload</> string to be communicated along with the
notification. This string must be shorter than 8000 bytes, and
is treated as text.
(If binary data or large amounts of information need to be communicated,
it's best to put it in a database table and send the key of the record.)
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1>
<title>Notes</title>
<indexterm>
<primary>pg_notify</primary>
</indexterm>
<para>
To send a notification you can also use the function
<literal><function>pg_notify</function>(<type>text</type>,
<type>text</type>)</literal>. The function takes the channel name as the
first argument and the payload as the second. The function is much easier
to use than the <command>NOTIFY</command> command if you need to work with
non-constant channel names and payloads.
</para>
<para>
There is a queue that holds notifications that have been sent but not
yet processed by all listening sessions. If this queue becomes full,
transactions calling <command>NOTIFY</command> will fail at commit.
The queue is quite large (8GB in a standard installation) and should be
sufficiently sized for almost every use case. However, no cleanup can take
place if a session executes <command>LISTEN</command> and then enters a
transaction for a very long time. Once the queue is half full you will see
warnings in the log file pointing you to the session that is preventing
cleanup. In this case you should make sure that this session ends its
current transaction so that cleanup can proceed.
</para>
<para>
A transaction that has executed <command>NOTIFY</command> cannot be
prepared for two-phase commit.
</para>
</refsect1>
<refsect1>
<title>Examples</title>
@ -146,6 +193,12 @@ NOTIFY <replaceable class="PARAMETER">name</replaceable>
LISTEN virtual;
NOTIFY virtual;
Asynchronous notification "virtual" received from server process with PID 8448.
NOTIFY virtual, 'This is the payload';
Asynchronous notification "virtual" with payload "This is the payload" received from server process with PID 8448.
LISTEN foo;
SELECT pg_notify('fo' || 'o', 'pay' || 'load');
Asynchronous notification "foo" with payload "payload" received from server process with PID 14728.
</programlisting>
</para>
</refsect1>

19
doc/src/sgml/ref/unlisten.sgml
View File

@ -1,5 +1,5 @@
<!--
$PostgreSQL: pgsql/doc/src/sgml/ref/unlisten.sgml,v 1.30 2008/11/14 10:22:47 petere Exp $
$PostgreSQL: pgsql/doc/src/sgml/ref/unlisten.sgml,v 1.31 2010/02/16 22:34:43 tgl Exp $
PostgreSQL documentation
-->
@ -21,7 +21,7 @@ PostgreSQL documentation
<refsynopsisdiv>
<synopsis>
UNLISTEN { <replaceable class="PARAMETER">name</replaceable> | * }
UNLISTEN { <replaceable class="PARAMETER">channel</replaceable> | * }
</synopsis>
</refsynopsisdiv>
@ -33,8 +33,8 @@ UNLISTEN { <replaceable class="PARAMETER">name</replaceable> | * }
registration for <command>NOTIFY</command> events.
<command>UNLISTEN</command> cancels any existing registration of
the current <productname>PostgreSQL</productname> session as a
listener on the notification <replaceable
class="PARAMETER">name</replaceable>. The special wildcard
listener on the notification channel named <replaceable
class="PARAMETER">channel</replaceable>. The special wildcard
<literal>*</literal> cancels all listener registrations for the
current session.
</para>
@ -52,10 +52,10 @@ UNLISTEN { <replaceable class="PARAMETER">name</replaceable> | * }
<variablelist>
<varlistentry>
<term><replaceable class="PARAMETER">name</replaceable></term>
<term><replaceable class="PARAMETER">channel</replaceable></term>
<listitem>
<para>
Name of a notification (any identifier).
Name of a notification channel (any identifier).
</para>
</listitem>
</varlistentry>
@ -83,6 +83,11 @@ UNLISTEN { <replaceable class="PARAMETER">name</replaceable> | * }
At the end of each session, <command>UNLISTEN *</command> is
automatically executed.
</para>
<para>
A transaction that has executed <command>UNLISTEN</command> cannot be
prepared for two-phase commit.
</para>
</refsect1>
<refsect1>
@ -100,7 +105,7 @@ Asynchronous notification "virtual" received from server process with PID 8448.
<para>
Once <command>UNLISTEN</> has been executed, further <command>NOTIFY</>
commands will be ignored:
messages will be ignored:
<programlisting>
UNLISTEN virtual;

7
doc/src/sgml/storage.sgml
View File

@ -1,4 +1,4 @@
<!-- $PostgreSQL: pgsql/doc/src/sgml/storage.sgml,v 1.31 2010/02/07 20:48:09 tgl Exp $ -->
<!-- $PostgreSQL: pgsql/doc/src/sgml/storage.sgml,v 1.32 2010/02/16 22:34:43 tgl Exp $ -->
<chapter id="storage">
@ -77,6 +77,11 @@ Item
(used for shared row locks)</entry>
</row>
<row>
<entry><filename>pg_notify</></entry>
<entry>Subdirectory containing LISTEN/NOTIFY status data</entry>
</row>
<row>
<entry><filename>pg_stat_tmp</></entry>
<entry>Subdirectory containing temporary files for the statistics