Document callback const-ness change

2 files changed, 29 insertions, 16 deletions

diff --git a/NEWS b/NEWS
index da2d3ed..8302f3b 100644
--- a/NEWS
+++ b/NEWS
@@ -45,11 +45,6 @@ Version 1.9.0
     namespace. For more information, refer to Section 12.5.1, "pointer" and
     Section 12.5.2, "table" in the ODB manual.
 
-  * New exception, odb::session_required, is thrown when ODB detects that
-    correctly loading a bidirectional object relationship requires a session
-    but one is not used. For more information, refer to Section 6.2,
-    "Bidirectional Relationships" in the ODB manual.
-
   * Session support is now optional and is disabled by default. This is a
     backwards-incompatible change. Session support can be enabled on the
     per object basis or at the namespace level using the new session pragma.
@@ -58,10 +53,22 @@ Version 1.9.0
     where all the objects were session-enabled, simply add --generate-session
     to your ODB compiler command line.
 
+  * The semantics of the callback functions with respect to object const-ness
+    has changed. This is a backwards-incompatible change. Now, the callback
+    function for the *_persist, *_update, and *_erase events is always called
+    on the constant object reference while for the *_load events -- always on
+    the unrestricted reference. For more information, refer to Section 12.1.7,
+    "Callback" in the ODB manual.
+
   * New function, transaction::reset(), allows the reuse of the same
     transaction instance to complete several database transactions. For more
     information, refer to Section 3.4, "Transactions" in the ODB manual.
 
+  * New exception, odb::session_required, is thrown when ODB detects that
+    correctly loading a bidirectional object relationship requires a session
+    but one is not used. For more information, refer to Section 6.2,
+    "Bidirectional Relationships" in the ODB manual.
+
 Version 1.8.0
 
   * Support for the Microsoft SQL Server database. The provided connection
diff --git a/doc/manual.xhtml b/doc/manual.xhtml
index a969f7f..dd7c649 100644
--- a/doc/manual.xhtml
+++ b/doc/manual.xhtml
@@ -9354,19 +9354,25 @@ namespace odb
 
   <p>The second argument to the callback function is the database
      on which the operation is about to be performed or has just
-     been performed.</p>
+     been performed. A callback function can be inline or virtual.</p>
+
+  <p>The callback function for the <code>*_persist</code>,
+     <code>*_update</code>, and <code>*_erase</code> events is always
+     called on the constant object reference while for the <code>*_load</code>
+     events &mdash; always on the unrestricted reference.</p>
 
   <p>If only the non-<code>const</code> version of the callback function
-     is provided, then only database operations that are performed on
-     unrestricted objects will trigger callback calls. If only the
-     <code>const</code> version is provided, then the database
-     operations on both constant and unrestricted objects will trigger
-     callback calls but the object will always be passed as constant.
-     Finally, if both versions are provided, then the <code>const</code>
-     overload will be called for constant objects and the non-<code>const</code>
-     overload for unrestricted objects. These rules are modeled after
-     the standard C++ overload resolution rules. A callback function can
-     be inline or virtual.</p>
+     is provided, then only the <code>*_load</code> events will be delivered.
+     If only the <code>const</code> version is provided, then all the
+     events will be delivered to this function. Finally, if both versions
+     are provided, then the <code>*_load</code> events will be delivered
+     to the non-<code>const</code> version while all others &mdash; to the
+     <code>const</code> version. If you need to modify the object in one
+     of the "<code>const</code>" events, then you can safely cast away
+     <code>const</code>-ness using the <code>const_cast</code> operator if
+     you know that none of the objects will be created const. Alternatively,
+     if you cannot make this assumption, then you can declare the data
+     members you wish to modify as <code>mutable</code>.</p>
 
   <p>A database operations callback can be used to implement object-specific
      pre and post initializations, registrations, and cleanups. As an example,