From 8bff37e6db02ba014afadf8060a809a6e7cb5911 Mon Sep 17 00:00:00 2001 From: Boris Kolpackov Date: Wed, 9 Nov 2011 10:32:26 +0200 Subject: Proofreading fixes for optimistic concurrency documentation --- doc/manual.xhtml | 68 ++++++++++++++++++++++++++++---------------------------- 1 file changed, 34 insertions(+), 34 deletions(-) diff --git a/doc/manual.xhtml b/doc/manual.xhtml index f7bea75..110a39d 100644 --- a/doc/manual.xhtml +++ b/doc/manual.xhtml @@ -2938,7 +2938,7 @@ t.commit ();

The first special property of reload() compared to the load() function is that it - does not interact with the session object cache + does not interact with the session's object cache (Section 10.1, "Object Cache"). That is, if the object being reloaded is already in the cache, then it will remain there after reload() returns. Similarly, if the @@ -2946,7 +2946,7 @@ t.commit (); put it there either.

The second special property of the reload() function - only manifests itself when operating on object with optimistic + only manifests itself when operating on an object with the optimistic concurrency model. In this case, if the states of the object in the application memory and in the database are the same, then no reloading will occur. For more information on optimistic @@ -3062,8 +3062,8 @@ t.commit ();

If any of the update() functions are operating on a - persistent class with optimistic concurrency model, then they will throw - the odb::object_changed exception if the state of the + persistent class with the optimistic concurrency model, then they will + throw the odb::object_changed exception if the state of the object in the database has changed since it was last loaded into the application memory. Furthermore, for such classes, update() no longer throws the object_not_persistent exception if @@ -3148,8 +3148,8 @@ db.erase<person> (joe_id); t.commit (); -

If any of the erase() functions except the last - one are operating on a persistent class with optimistic concurrency +

If any of the erase() functions except the last one are + operating on a persistent class with the optimistic concurrency model, then they will throw the odb::object_changed exception if the state of the object in the database has changed since it was last loaded into the application memory. Furthermore, for such @@ -3623,7 +3623,7 @@ namespace odb

The object_changed exception is thrown by the update() database function and certain erase() database functions when - operating on objects with optimistic concurrency model. See + operating on objects with the optimistic concurrency model. See Chapter 11, "Optimistic Concurrency" for details.

The result_not_cached exception is thrown by @@ -7628,8 +7628,8 @@ unsigned long id2 (save (db, p2)); // p2 is cached in s as non-const. application-specific functionality. The term database transaction refers to the set of database operations performed between the ODB begin() and commit() - calls. Up until now we treated application transactions and database - transactions as essentially the same thing.

+ calls. Up until now we have treated application transactions and + database transactions as essentially the same thing.

While this model is easy to understand and straightforward to use, it may not be suitable for applications that have long application @@ -7642,7 +7642,7 @@ unsigned long id2 (save (db, p2)); // p2 is cached in s as non-const.

The solution to this problem is to break up the long-lived application transaction into several short-lived database - transaction. In our example that would mean loading the object + transactions. In our example that would mean loading the object in one database transaction, waiting for user input, and then updating the object in another database transaction. For example:

@@ -7668,7 +7668,7 @@ p.age (age); } -

This approach works well if we have only one process/thread that can ever +

This approach works well if we only have one process/thread that can ever update the object. However, if we have multiple processes/threads modifying the same object, then this approach does not guarantee consistency anymore. Consider what happens in the above example if @@ -7685,7 +7685,7 @@ p.age (age); concurrency, that allows applications to detect and potentially recover from such inconsistencies.

-

In essence, optimistic concurrency model detects mismatches +

In essence, the optimistic concurrency model detects mismatches between the current object state in the database and the state when it was loaded into the application memory. Such a mismatch would mean that the object was changed by another process or @@ -7693,8 +7693,8 @@ p.age (age); detection. Currently, ODB uses object versioning while other methods, such as timestamps, may be supported in the future.

-

To declare a persistent class with optimistic concurrency model we use - the optimistic pragma (Section 12.1.5, +

To declare a persistent class with the optimistic concurrency model we + use the optimistic pragma (Section 12.1.5, "optimistic"). We also use the version pragma (Section 12.4.12, "version") to specify which data member will store the object version. For @@ -7711,7 +7711,7 @@ class person }; -

The version data members is managed by ODB. It is initialized to +

The version data member is managed by ODB. It is initialized to 1 when the object is made persistent and incremented by 1 with each update. The 0 version value is not used by ODB and the application can use it as a special value, @@ -7736,14 +7736,14 @@ class person

When we call the database::update() function (Section 3.9, "Updating Persistent Objects") and pass - an object that has outdated state, the odb::object_changed + an object that has an outdated state, the odb::object_changed exception is thrown. At this point the application has two recovery options: it can abort and potentially restart the application transaction or it can reload the new object state from the database, re-apply or merge the changes, and call update() again. Note that aborting an application transaction that performs updates in multiple database transactions - may requires reverting changes that has already been committed to + may require reverting changes that have already been committed to the database. As a result, this strategy works best if all the updates are performed in the last database transaction of the application transaction. This way the changes can be reverted @@ -7829,7 +7829,7 @@ if (answer == "yes")

Consider again what happens if another process or thread updates the object by changing the person's age while we are waiting for the user input. In this case, the user makes the decision based on - certain age while we may delete (or not delete) an object that has + a certain age while we may delete (or not delete) an object that has a completely different age. Here is how we can fix this problem using optimistic concurrency:

@@ -7874,9 +7874,9 @@ for (bool done (false); !done; ) } -

Note that the state mismatch detection is performed only if we delete +

Note that state mismatch detection is performed only if we delete an object by passing the object instance to the erase() - function. If we want to delete an object with optimistic concurrency + function. If we want to delete an object with the optimistic concurrency model regardless of its state, then we need to use the erase() function that deletes an object given its id, for example:

@@ -7888,8 +7888,8 @@ for (bool done (false); !done; ) } -

Finally note that for persistent classes with optimistic concurrency - model both the update() function and the +

Finally, note that for persistent classes with the optimistic concurrency + model both the update() function as well as the erase() function that accepts an object instance as its argument no longer throw the object_not_persistent exception if there is no such object in the database. Instead, @@ -8112,7 +8112,7 @@ class person optimistic - persistent class with optimistic concurrency model + persistent class with the optimistic concurrency model 12.1.5 @@ -8261,9 +8261,9 @@ class person

12.1.5 optimistic

The optimistic specifier specifies that the persistent class - has optimistic concurrency model. A class with optimistic concurrency - model must also specify the data member that is used to store the - object version using the version pragma + has the optimistic concurrency model. A class with the optimistic + concurrency model must also specify the data member that is used to + store the object version using the version pragma (Section 12.4.12, "version"). For example:

@@ -8278,8 +8278,8 @@ class person }; -

If a base class has optimistic concurrency model then all its derived - classes will automatically have optimistic concurrency model. The +

If a base class has the optimistic concurrency model, then all its derived + classes will automatically have the optimistic concurrency model. The current implementation also requires that in any given inheritance hierarchy the object id and the version data members reside in the same class.

@@ -9804,12 +9804,12 @@ class person

12.4.12 version

-

The version specifier specifies that the data member - stores the object version used to support optimistic concurrency. - If a class has a version data member then it must also be declared - as having optimistic concurrency model using the optimistic - pragma (Section 12.1.5, "optimistic"). - For example:

+

The version specifier specifies that the data member stores + the object version used to support optimistic concurrency. If a class + has a version data member, then it must also be declared as having the + optimistic concurrency model using the optimistic pragma + (Section 12.1.5, "optimistic"). For + example:

 #pragma db object optimistic
-- 
cgit v1.1