mirror of
https://github.com/berkeleydb/libdb.git
synced 2024-11-17 01:26:25 +00:00
494 lines
26 KiB
HTML
494 lines
26 KiB
HTML
<?xml version="1.0" encoding="UTF-8" standalone="no"?>
|
||
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
|
||
<html xmlns="http://www.w3.org/1999/xhtml">
|
||
<head>
|
||
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
|
||
<title>DbEnv::set_event_notify()</title>
|
||
<link rel="stylesheet" href="apiReference.css" type="text/css" />
|
||
<meta name="generator" content="DocBook XSL Stylesheets V1.73.2" />
|
||
<link rel="start" href="index.html" title="Berkeley DB C++ API Reference" />
|
||
<link rel="up" href="env.html" title="Chapter 5. The DbEnv Handle" />
|
||
<link rel="prev" href="envset_encrypt.html" title="DbEnv::set_encrypt()" />
|
||
<link rel="next" href="envset_errcall.html" title="DbEnv::set_errcall()" />
|
||
</head>
|
||
<body>
|
||
<div xmlns="" class="navheader">
|
||
<div class="libver">
|
||
<p>Library Version 11.2.5.2</p>
|
||
</div>
|
||
<table width="100%" summary="Navigation header">
|
||
<tr>
|
||
<th colspan="3" align="center">DbEnv::set_event_notify()</th>
|
||
</tr>
|
||
<tr>
|
||
<td width="20%" align="left"><a accesskey="p" href="envset_encrypt.html">Prev</a> </td>
|
||
<th width="60%" align="center">Chapter 5.
|
||
The DbEnv Handle
|
||
</th>
|
||
<td width="20%" align="right"> <a accesskey="n" href="envset_errcall.html">Next</a></td>
|
||
</tr>
|
||
</table>
|
||
<hr />
|
||
</div>
|
||
<div class="sect1" lang="en" xml:lang="en">
|
||
<div class="titlepage">
|
||
<div>
|
||
<div>
|
||
<h2 class="title" style="clear: both"><a id="envevent_notify"></a>DbEnv::set_event_notify()</h2>
|
||
</div>
|
||
</div>
|
||
</div>
|
||
<pre class="programlisting">#include <db_cxx.h>
|
||
|
||
int
|
||
DbEnv::set_event_notify(
|
||
void (*db_event_fcn)(DB_ENV *dbenv, u_int32_t event,
|
||
void *event_info));</pre>
|
||
<p>
|
||
The <code class="methodname">DbEnv::set_event_notify()</code> method
|
||
configures a callback function which is called to notify the
|
||
process of specific Berkeley DB events.
|
||
</p>
|
||
<div class="note" style="margin-left: 0.5in; margin-right: 0.5in;">
|
||
<h3 class="title">Note</h3>
|
||
<p>
|
||
Berkeley DB is not re-entrant. Callback functions should
|
||
not attempt to make library calls (for example, to release
|
||
locks or close open handles). Re-entering Berkeley DB is
|
||
not guaranteed to work correctly, and the results are
|
||
undefined.
|
||
</p>
|
||
</div>
|
||
<p>
|
||
The <code class="methodname">DbEnv::set_event_notify()</code> method
|
||
configures operations performed using the specified
|
||
<a class="link" href="env.html" title="Chapter 5. The DbEnv Handle">DbEnv</a> handle, not all operations
|
||
performed on the underlying database environment.
|
||
</p>
|
||
<p>
|
||
The <code class="methodname">DbEnv::set_event_notify()</code> method may
|
||
be called at any time during the life of the application.
|
||
</p>
|
||
<p>
|
||
The <code class="methodname">DbEnv::set_event_notify()</code> <span>
|
||
|
||
<span>
|
||
method either returns a non-zero error value or throws an
|
||
exception that encapsulates a non-zero error value on
|
||
failure, and returns 0 on success.
|
||
</span>
|
||
</span>
|
||
</p>
|
||
<div class="sect2" lang="en" xml:lang="en">
|
||
<div class="titlepage">
|
||
<div>
|
||
<div>
|
||
<h3 class="title"><a id="id3601084"></a>Parameters</h3>
|
||
</div>
|
||
</div>
|
||
</div>
|
||
<div class="sect3" lang="en" xml:lang="en">
|
||
<div class="titlepage">
|
||
<div>
|
||
<div>
|
||
<h4 class="title"><a id="id3601110"></a>db_event_fcn</h4>
|
||
</div>
|
||
</div>
|
||
</div>
|
||
<p>
|
||
The <span class="bold"><strong>db_event_fcn</strong></span> parameter is the
|
||
application's event notification function. The function takes three
|
||
parameters:
|
||
</p>
|
||
<div class="itemizedlist">
|
||
<ul type="disc">
|
||
<li>
|
||
<p>
|
||
<code class="literal">dbenv</code>
|
||
</p>
|
||
<p>
|
||
The <span class="bold"><strong>dbenv</strong></span>
|
||
parameter is the enclosing database environment
|
||
handle.
|
||
</p>
|
||
</li>
|
||
<li>
|
||
<p>
|
||
<code class="literal">event</code>
|
||
</p>
|
||
<p>
|
||
The <span class="bold"><strong>event</strong></span> parameter is one of the
|
||
following values:
|
||
</p>
|
||
<div class="itemizedlist">
|
||
<ul type="circle">
|
||
<li>
|
||
<p><a id="event_notify_DB_EVENT_PANIC"></a>
|
||
<code class="literal">DB_EVENT_PANIC</code>
|
||
</p>
|
||
<p>
|
||
Errors can occur in the Berkeley DB library where the only solution
|
||
is to shut down the application and run recovery (for example, if
|
||
Berkeley DB is unable to allocate heap memory). In such cases, the
|
||
Berkeley DB methods will return
|
||
<a href="../../programmer_reference/program_errorret.html#program_errorret.DB_RUNRECOVERY" class="olink">DB_RUNRECOVERY</a>.
|
||
It is often easier to simply exit the application when such errors
|
||
occur rather than gracefully return up the stack.
|
||
</p>
|
||
<p>
|
||
When <span class="bold"><strong>event</strong></span> is set to
|
||
<code class="literal">DB_EVENT_PANIC</code>, the database environment has
|
||
failed. All threads of control in the database environment should
|
||
exit the environment, and recovery should be run.
|
||
</p>
|
||
</li>
|
||
<li>
|
||
<p><a id="event_notify_DB_EVENT_REG_ALIVE"></a>
|
||
<code class="literal">DB_EVENT_REG_ALIVE</code>
|
||
</p>
|
||
<p>
|
||
Recovery is needed in an environment where the
|
||
<a class="link" href="envopen.html#envopen_DB_REGISTER">DB_REGISTER</a>
|
||
flag was specified on the
|
||
<a class="xref" href="envopen.html" title="DbEnv::open()">DbEnv::open()</a> method and there is
|
||
a process attached to the environment. The callback function is triggered
|
||
once for each process attached.
|
||
</p>
|
||
<p>
|
||
The <span class="bold"><strong>event_info</strong></span> parameter points to a pid_t value
|
||
containing the process identifier (pid) of the process the Berkeley DB library
|
||
detects is attached to the environment.
|
||
</p>
|
||
</li>
|
||
<li>
|
||
<p><a id="event_notify_DB_EVENT_REG_PANIC"></a>
|
||
<code class="literal">DB_EVENT_REG_PANIC</code>
|
||
</p>
|
||
<p>
|
||
Recovery is needed in an environment where the
|
||
<a class="link" href="envopen.html#envopen_DB_REGISTER">DB_REGISTER</a>
|
||
flag was specified
|
||
on the <a class="xref" href="envopen.html" title="DbEnv::open()">DbEnv::open()</a> method. All threads
|
||
of control in the database environment should exit the environment.
|
||
</p>
|
||
<p>
|
||
This event is different than the <code class="literal">DB_EVENT_PANIC</code> event
|
||
because it can only be triggered when <code class="literal">DB_REGISTER</code> was
|
||
specified. It can be used to distinguish between the case when a process
|
||
dies in the environment and recovery is initiated versus the case when an
|
||
error happened (for example, if Berkeley DB is unable to allocate heap
|
||
memory)
|
||
</p>
|
||
</li>
|
||
<li>
|
||
<p><a id="event_notify_DB_EVENT_REP_CLIENT"></a>
|
||
<code class="literal">DB_EVENT_REP_CLIENT</code>
|
||
</p>
|
||
<p>
|
||
The local site is now a replication client.
|
||
</p>
|
||
<p>
|
||
This event is generated when the replication role changes to client,
|
||
either from master or from being unset. The role is unset when an
|
||
environment is first created and after an environment is recovered.
|
||
This event is not generated when restarting replication in an
|
||
environment that was previously a client and was opened without
|
||
recovery.
|
||
</p>
|
||
</li>
|
||
<li>
|
||
<p><a id="event_notify_DB_EVENT_REP_CONNECT_BROKEN"></a>
|
||
<code class="literal">DB_EVENT_REP_CONNECT_BROKEN</code>
|
||
</p>
|
||
<p>
|
||
A previously established replication message connection between the
|
||
local site and a remote site has been broken. This event supplies
|
||
the EID of the remote site, and an integer error code that
|
||
identifies the reason the connection was broken.
|
||
</p>
|
||
</li>
|
||
<li>
|
||
<p><a id="event_notify_DB_EVENT_REP_CONNECT_ESTD"></a>
|
||
<code class="literal">DB_EVENT_REP_CONNECT_ESTD</code>
|
||
</p>
|
||
<p>
|
||
A replication message connection has been established between the
|
||
local site and a remote site. This event supplied the EID of the
|
||
remote site.
|
||
</p>
|
||
</li>
|
||
<li>
|
||
<p><a id="event_notify_DB_EVENT_REP_CONNECT_TRY_FAILED"></a>
|
||
<code class="literal">DB_EVENT_REP_CONNECT_TRY_FAILED</code>
|
||
</p>
|
||
<p>
|
||
An attempt to establish a connection between the local site and a
|
||
remote site has failed. This event supplies the EID of the remote
|
||
site, and an integer error code that identifies the reason the
|
||
connection attempt failed.
|
||
</p>
|
||
</li>
|
||
<li>
|
||
<p><a id="event_notify_DB_EVENT_REP_DUPMASTER"></a>
|
||
<code class="literal">DB_EVENT_REP_DUPMASTER</code>
|
||
</p>
|
||
<p>
|
||
Replication Manager has detected a duplicate master situation, and
|
||
has changed the local site to the client role as a result. If the
|
||
<a class="link" href="repconfig.html#config_DB_REPMGR_CONF_ELECTIONS">DB_REPMGR_CONF_ELECTIONS</a>
|
||
configuration parameter has been turned off, the application should
|
||
now choose and assign the correct master site. If
|
||
<code class="literal">DB_REPMGR_CONF_ELECTIONS</code> is turned on, the
|
||
application may ignore this event.
|
||
</p>
|
||
<p>
|
||
The <code class="literal">DB_EVENT_REP_DUPMASTER</code> event is provided
|
||
only to applications configured for the replication manager.
|
||
</p>
|
||
</li>
|
||
<li>
|
||
<p><a id="event_notify_DB_EVENT_REP_ELECTED"></a>
|
||
<code class="literal">DB_EVENT_REP_ELECTED</code>
|
||
</p>
|
||
<p>
|
||
The local replication site has just won an election. An application
|
||
using the Base replication API should arrange for a call to the
|
||
<a class="xref" href="repstart.html" title="DbEnv::rep_start()">DbEnv::rep_start()</a> method
|
||
after receiving this event, to reconfigure the local environment as a
|
||
replication master.
|
||
</p>
|
||
<p>
|
||
Replication Manager applications may safely ignore this event. The
|
||
Replication Manager calls <a class="xref" href="repstart.html" title="DbEnv::rep_start()">DbEnv::rep_start()</a>
|
||
automatically on behalf of the application when appropriate (resulting
|
||
in firing of the DB_EVENT_REP_MASTER event).
|
||
</p>
|
||
</li>
|
||
<li>
|
||
<p><a id="event_notify_DB_EVENT_REP_ELECTION_FAILED"></a>
|
||
<code class="literal">DB_EVENT_REP_ELECTION_FAILED</code>
|
||
</p>
|
||
<p>
|
||
Replication Manager tried to run an election to choose a master
|
||
site, but the election failed due to lack of timely participation by
|
||
a sufficient number of other sites. Replication Manager will
|
||
automatically retry the election later. This event is for
|
||
information only.
|
||
</p>
|
||
<p>
|
||
The <code class="literal">DB_EVENT_REP_ELECTION_FAILED</code> event is
|
||
provided only to applications configured for the replication
|
||
manager.
|
||
</p>
|
||
</li>
|
||
<li>
|
||
<p><a id="event_notify_DB_EVENT_REP_ELECTION_STARTED"></a>
|
||
<code class="literal">DB_EVENT_REP_ELECTION_STARTED</code>
|
||
</p>
|
||
<p>
|
||
Replication Manager has started an election
|
||
to choose a master site.
|
||
</p>
|
||
</li>
|
||
<li>
|
||
<p><a id="event_notify_DB_EVENT_REP_INIT_DONE"></a>
|
||
<code class="literal">DB_EVENT_REP_INIT_DONE</code>
|
||
</p>
|
||
<p>
|
||
Replication Manager has completed an
|
||
internal initialization procedure.
|
||
</p>
|
||
</li>
|
||
<li>
|
||
<p><a id="event_notify_DB_EVENT_REP_JOIN_FAILURE"></a>
|
||
<code class="literal">DB_EVENT_REP_JOIN_FAILURE</code>
|
||
</p>
|
||
<p>
|
||
The local client site is unable to synchronize with a new master,
|
||
possibly because the client has turned off automatic internal
|
||
initialization by setting the
|
||
<a class="link" href="repconfig.html#config_DB_REP_CONF_AUTOINIT">DB_REP_CONF_AUTOINIT</a>
|
||
flag to <code class="literal">0</code>.
|
||
</p>
|
||
</li>
|
||
<li>
|
||
<p><a id="event_notify_DB_EVENT_REP_LOCAL_SITE_REMOVED"></a>
|
||
<code class="literal">DB_EVENT_REP_LOCAL_SITE_REMOVED</code>
|
||
</p>
|
||
<p>
|
||
The local site has been
|
||
removed from the replication group.
|
||
</p>
|
||
</li>
|
||
<li>
|
||
<p><a id="event_notify_DB_EVENT_REP_MASTER"></a>
|
||
<code class="literal">DB_EVENT_REP_MASTER</code>
|
||
</p>
|
||
<p>
|
||
The local site is now the master site of its replication group. It is
|
||
the application's responsibility to begin acting as the master
|
||
environment.
|
||
</p>
|
||
<p>
|
||
This event is generated when the replication role changes to master,
|
||
either from client or from being unset. The role is unset when an
|
||
environment is first created and after an environment is recovered.
|
||
This event is not generated when restarting replication in an
|
||
environment that was previously a master and was opened without
|
||
recovery.
|
||
</p>
|
||
</li>
|
||
<li>
|
||
<p><a id="event_notify_DB_EVENT_REP_MASTER_FAILURE"></a>
|
||
<code class="literal">DB_EVENT_REP_MASTER_FAILURE</code>
|
||
</p>
|
||
<p>
|
||
A Replication Manager client site has detected the loss of
|
||
connection to the master site. If the
|
||
<a class="link" href="repconfig.html#config_DB_REPMGR_CONF_ELECTIONS">DB_REPMGR_CONF_ELECTIONS</a>
|
||
configuration parameter is turned on, Replication Manager will
|
||
automatically start an election in order to choose a new master. In
|
||
this case, this event may be ignored.
|
||
</p>
|
||
<p>
|
||
When <code class="literal">DB_REPMGR_CONF_ELECTIONS</code> is turned off, the
|
||
application should choose and assign a new master. Failure to do so
|
||
means that your replication group has no master, and so it cannot
|
||
service write requests.
|
||
</p>
|
||
<p>
|
||
The <code class="literal">DB_EVENT_REP_MASTER_FAILURE</code> event is provided
|
||
only to applications configured for the replication manager.
|
||
</p>
|
||
</li>
|
||
<li>
|
||
<p><a id="event_notify_DB_EVENT_REP_NEWMASTER"></a>
|
||
<code class="literal">DB_EVENT_REP_NEWMASTER</code>
|
||
</p>
|
||
<p>
|
||
The replication group of which this site is a member has just
|
||
established a new master; the local site is not the new master. The
|
||
<span class="bold"><strong>event_info</strong></span> parameter points to an
|
||
integer containing the environment ID of the new master.
|
||
</p>
|
||
</li>
|
||
<li>
|
||
<p><a id="event_notify_DB_EVENT_REP_PERM_FAILED"></a>
|
||
<code class="literal">DB_EVENT_REP_PERM_FAILED</code>
|
||
</p>
|
||
<p>
|
||
The replication manager did not receive enough acknowledgements (based
|
||
on the acknowledgement policy configured with
|
||
<a class="xref" href="repmgrset_ack_policy.html" title="DbEnv::repmgr_set_ack_policy()">DbEnv::repmgr_set_ack_policy()</a> )
|
||
to ensure a transaction's durability within the replication group.
|
||
The transaction will be flushed to the master's local disk storage for
|
||
durability.
|
||
</p>
|
||
<p>
|
||
The <code class="literal">DB_EVENT_REP_PERM_FAILED</code> event is provided
|
||
only to applications configured for the replication manager.
|
||
</p>
|
||
</li>
|
||
<li>
|
||
<p><a id="event_notify_DB_EVENT_REP_SITE_ADDED"></a>
|
||
<code class="literal">DB_EVENT_REP_SITE_ADDED</code>
|
||
</p>
|
||
<p>
|
||
A new site has joined the group.
|
||
The
|
||
<span class="bold"><strong>event_info</strong></span> parameter points to an
|
||
integer containing the environment ID of the new site.
|
||
</p>
|
||
</li>
|
||
<li>
|
||
<p><a id="event_notify_DB_EVENT_REP_SITE_REMOVED"></a>
|
||
<code class="literal">DB_EVENT_REP_SITE_REMOVED</code>
|
||
</p>
|
||
<p>
|
||
An existing remote site has been removed from the group. The
|
||
<span class="bold"><strong>event_info</strong></span> parameter points to an
|
||
integer containing the environment ID of the site that was removed.
|
||
</p>
|
||
</li>
|
||
<li>
|
||
<p><a id="event_notify_DB_EVENT_REP_STARTUPDONE"></a>
|
||
<code class="literal">DB_EVENT_REP_STARTUPDONE</code>
|
||
</p>
|
||
<p>
|
||
The client has completed startup synchronization and is now processing
|
||
live log records received from the master.
|
||
</p>
|
||
</li>
|
||
<li>
|
||
<p><a id="event_notify_DB_EVENT_WRITE_FAILED"></a>
|
||
<code class="literal">DB_EVENT_WRITE_FAILED</code>
|
||
</p>
|
||
<p>
|
||
A Berkeley DB write to stable storage failed.
|
||
</p>
|
||
</li>
|
||
</ul>
|
||
</div>
|
||
</li>
|
||
<li>
|
||
<p>
|
||
<code class="literal">event_info</code>
|
||
</p>
|
||
<p>
|
||
The <span class="bold"><strong>event_info</strong></span> parameter may
|
||
reference memory which contains additional information describing an
|
||
event. By default, <span class="bold"><strong>event_info</strong></span> is
|
||
NULL; specific events may pass non-NULL values, in which case the
|
||
event will also describe the memory's structure.
|
||
</p>
|
||
</li>
|
||
</ul>
|
||
</div>
|
||
</div>
|
||
</div>
|
||
<div class="sect2" lang="en" xml:lang="en">
|
||
<div class="titlepage">
|
||
<div>
|
||
<div>
|
||
<h3 class="title"><a id="id3601599"></a>Class</h3>
|
||
</div>
|
||
</div>
|
||
</div>
|
||
<p>
|
||
<a class="link" href="env.html" title="Chapter 5. The DbEnv Handle">DbEnv</a>
|
||
</p>
|
||
</div>
|
||
<div class="sect2" lang="en" xml:lang="en">
|
||
<div class="titlepage">
|
||
<div>
|
||
<div>
|
||
<h3 class="title"><a id="id3601162"></a>See Also</h3>
|
||
</div>
|
||
</div>
|
||
</div>
|
||
<p>
|
||
<a class="xref" href="env.html#envlist" title="Database Environments and Related Methods">Database Environments and Related Methods</a>
|
||
</p>
|
||
</div>
|
||
</div>
|
||
<div class="navfooter">
|
||
<hr />
|
||
<table width="100%" summary="Navigation footer">
|
||
<tr>
|
||
<td width="40%" align="left"><a accesskey="p" href="envset_encrypt.html">Prev</a> </td>
|
||
<td width="20%" align="center">
|
||
<a accesskey="u" href="env.html">Up</a>
|
||
</td>
|
||
<td width="40%" align="right"> <a accesskey="n" href="envset_errcall.html">Next</a></td>
|
||
</tr>
|
||
<tr>
|
||
<td width="40%" align="left" valign="top">DbEnv::set_encrypt() </td>
|
||
<td width="20%" align="center">
|
||
<a accesskey="h" href="index.html">Home</a>
|
||
</td>
|
||
<td width="40%" align="right" valign="top"> DbEnv::set_errcall()</td>
|
||
</tr>
|
||
</table>
|
||
</div>
|
||
</body>
|
||
</html>
|