[persistence] interface overview
A while ago, I proposed a persistence library and there was some interest. Since then, the prototype has evolved into a feature-complete, reasonably optimized, implementation. Here's a quick recap of what the library is supposed to do: --------- int main(){ ... shared_ptr<A> shared(new A); db_ptr<A> db(new A); ... } // "shared" is destroyed, "db" is saved to disk to ensure data consistency, there are transactions introduced: transaction tx; //change_objects tx.commit(); if change_objects throws an exception, causing tx to be destroyed without commit() being called, all changes are undone. --------- there is no complete documentation yet, but I've written an overview of the library interface, which can be found here: http://www.boostpro.com/vault/index.php?action=downloadfile&filename=overview.html&directory=persistence& I'd appreciate your comments. please note the "open issues" section.
on 23.08.2009 at 14:53 Stefan Strasser wrote :
A while ago, I proposed a persistence library and there was some interest.
Since then, the prototype has evolved into a feature-complete, reasonably optimized, implementation. Here's a quick recap of what the library is supposed to do: [text here] --------- there is no complete documentation yet, but I've written an overview of the library interface, which can be found here: http://www.boostpro.com/vault/index.php?action=downloadfile&filename=overview.html&directory=persistence& next time try documenting code you are writnig in a 'special' way so an autogeneration tool can 'write' docs for you (e.g. doxygen) believe me, your effort of learning to write comments in a bit special way will cover all the effort of (re)writng docs every time the code changes besides the code becomes fully selfdocumented just try it, i think you won't regret it anyway
-- Pavel
-----Original Message----- From: boost-bounces@lists.boost.org [mailto:boost-bounces@lists.boost.org] On Behalf Of DE Sent: Sunday, August 23, 2009 1:07 PM To: Stefan Strasser Subject: Re: [boost] [persistence] interface overview
there is no complete documentation yet, but I've written an overview of the library interface, which can be found here:
http://www.boostpro.com/vault/index.php?action=downloadfile&filename=overview.ht ml&d
irectory=persistence& next time try documenting code you are writnig in a 'special' way so an autogeneration tool can 'write' docs for you (e.g. doxygen) believe me, your effort of learning to write comments in a bit special way will cover all the effort of (re)writng docs every time the code changes besides the code becomes fully selfdocumented just try it, i think you won't regret it anyway
Well I think you will regret it at first - setup is a pig - but the results are really, really worth it! You need to make sure you can re-build one of the Boost libraries that use Doxygen and indexing too. We need a template for people to work from - I have it part done but I still need more help with B(*£%$^) jam! Good luck Paul
Am Monday 24 August 2009 10:37:55 schrieb Paul A. Bristow:
there is no complete documentation yet, but I've written an overview of the library interface, which can be found here:
http://www.boostpro.com/vault/index.php?action=downloadfile&filename=overvi ew.ht ml&d
irectory=persistence& next time try documenting code you are writnig in a 'special' way so an autogeneration tool can 'write' docs for you (e.g. doxygen) believe me, your effort of learning to write comments in a bit special way will cover all the effort of (re)writng docs every time the code changes besides the code becomes fully selfdocumented just try it, i think you won't regret it anyway
Well I think you will regret it at first - setup is a pig - but the results are really, really worth it!
You need to make sure you can re-build one of the Boost libraries that use Doxygen and indexing too.
thanks for the suggestions, but right now there are no comments in any format, suitable for automatic documentation or not. so when I add documentation I'll think about adding it into the source code. but that's besides the point of my mail. I'd appreciate comments and suggestions about the library interface itself (link above).
Hi, in the documentation you say, "Objects can be read outside of transactions, but no object can be created or changed outside of transactions. " So how do you manage with conflicts between reads outside transactions and writes inside transactions? Maybe you can clarify this on the documentation. As db_ptr is a shared_ptr why not name it shared_db_ptr (note that you have already a weak_db_ptr) or even better, why don't name them shared_ptr and weak_ptr but on the namespace db? Do you think that it will be possible to manage db pointers that are not managed, so it will be up to the user to create/remove them explicitly? About commit_transaction, in TBoost.STM we have defined a macro atomic so you can do the following atomic(_) { book->friends.push_back(...); } Of course the corrct boost name will be BOOST_STM_ATOMIC. Maybe you can take a look at this macro. It avoids to force defining a specific function and pass it as parameter to the commit_transaction function. Related to "Improving performance", what hapens if in a transaction we access a db_ptr using the read function, then we modify it in a neested function/transaction and then we re-read this shared_ptr. Will the readen pointer corresponds to the written one? transaction tx; shared_ptr<T> shptr(dbptr.read()); // do something with shptr // in a nested call to f dbptr is written f(); // will the use of shptr contains the modifications done by f? ----- Original Message ----- From: "Stefan Strasser" <strasser@uni-bremen.de> To: <boost@lists.boost.org> Sent: Sunday, August 23, 2009 12:53 PM Subject: [boost] [persistence] interface overview
A while ago, I proposed a persistence library and there was some interest.
Since then, the prototype has evolved into a feature-complete, reasonably optimized, implementation. Here's a quick recap of what the library is supposed to do:
--------- int main(){ ... shared_ptr<A> shared(new A); db_ptr<A> db(new A); ... } // "shared" is destroyed, "db" is saved to disk
to ensure data consistency, there are transactions introduced:
transaction tx; //change_objects tx.commit();
if change_objects throws an exception, causing tx to be destroyed without commit() being called, all changes are undone. ---------
there is no complete documentation yet, but I've written an overview of the library interface, which can be found here: http://www.boostpro.com/vault/index.php?action=downloadfile&filename=overview.html&directory=persistence&
I'd appreciate your comments. please note the "open issues" section. _______________________________________________ Unsubscribe & other changes: http://lists.boost.org/mailman/listinfo.cgi/boost
Am Sunday 23 August 2009 14:54:23 schrieb vicente.botet:
in the documentation you say,
"Objects can be read outside of transactions, but no object can be created or changed outside of transactions. "
So how do you manage with conflicts between reads outside transactions and writes inside transactions? Maybe you can clarify this on the documentation.
ok. a read outside of a transaction returns the committed state of that object at the time. (consistent state within the object.) if you need an atomic read across more than one object, you can use a transaction.
As db_ptr is a shared_ptr why not name it shared_db_ptr (note that you have already a weak_db_ptr) or even better, why don't name them shared_ptr and weak_ptr but on the namespace db?
db_ptr is not a shared_ptr, think of it more like an "object id". it does not keep the referenced object in memory, see pitfalls -> object lifetime for that. the name "db_ptr" is certainly imperfect and might depend on if the whole library stays with its name (robert ramey suggested a name change). the namespace currently is persistence.
Do you think that it will be possible to manage db pointers that are not managed, so it will be up to the user to create/remove them explicitly?
I'm not sure if I understand that question correctly...do you mean objects that are not reference counted and must be added and removed explicitely?
About commit_transaction, in TBoost.STM we have defined a macro atomic so you can do the following
atomic(_) { book->friends.push_back(...); }
thanks, I did look at it. how is the catch-block added? do you have to use another define after {}? though you could stop commit() from throwing and just let it return false to indicate that the transaction failed and avoid a catch block. I need to think that through though because not only commit() can throw isolation_exception, it can be thrown much earlier. but your macros still have a "try" at the end, I wonder what that's for?
Related to "Improving performance", what hapens if in a transaction we access a db_ptr using the read function, then we modify it in a neested function/transaction and then we re-read this shared_ptr. Will the readen pointer corresponds to the written one?
no. that is addressed in the documentation in pitfalls->transaction boundaries. maybe one could describe that more clearly and prominently in the final documentation. so objects should always be accessed through their db_ptr's. thanks for your comments. which version of the db_ptr interface do you prefer? (at the end of overview.html)
participants (4)
-
DE -
Paul A. Bristow -
Stefan Strasser -
vicente.botet