Ticket #1215: 0001-ticket-1215-fix-thread-safety-in-rasodmg.patch

File 0001-ticket-1215-fix-thread-safety-in-rasodmg.patch, 8.0 KB (added by Dimitar Misev, 5 years ago)

  • 08_dev-guide-cpp.rst 

    From f5c682f6ef87231ae358f233d16aeba640cfd0c6 Mon Sep 17 00:00:00 2001
From: Dimitar Misev <misev@rasdaman.com>
Date: Sun, 2 Dec 2018 18:50:27 +0100
Subject: [PATCH] ticket:1215 - fix thread-safety in rasodmg

---
 08_dev-guide-cpp.rst | 58 +++++++++++++++++++++++++-------------------
 1 file changed, 33 insertions(+), 25 deletions(-)

diff --git a/08_dev-guide-cpp.rst b/08_dev-guide-cpp.rst
index c59cf10..76c8082 100644
    a b access is concerned):  
    105105   other data like images or image sets ::
    106106
    107107       r_Database database;
    108        r_Transaction transaction;
     108       r_Transaction transaction{&database};
    109109
    110110-  Set the server name using the default port 7001. ::
    111111
    … … zero, and the second one by way of some assumed initialization function.  
    160160     ::
    161161
    162162         r_Database database;
    163          r_Transaction transaction;
     163         r_Transaction transaction{&database};
    164164         r_Minterval domain;
    165165         r_Ref< r_Marray<r_ULong> > image;
    166166         r_Ref< r_Set< r_Ref< r_Marray<r_ULong> > > > image_set;
    … … zero, and the second one by way of some assumed initialization function.  
    192192     ::
    193193
    194194         image_set = new( &database, "ULongSet" )
    195                      r_Set< r_Ref< r_Marray<r_ULong> > >;
     195                     r_Set< r_Ref< r_Marray<r_ULong> > >(&transaction);
    196196
    197197(6)  To give a name to the set for later retrieval, a ``set_object_name``
    198198     message is sent to the database object. ::
    … … zero, and the second one by way of some assumed initialization function.  
    220220     ::
    221221
    222222         image = new( &database, "ULongImage" )
    223                  r_Marray<r_ULong>( domain, 0ul );
     223                 r_Marray<r_ULong>( domain, 0ul, &transaction );
    224224
    225225(9)  The image created in (7) is now inserted into the set. From now on,
    226226     the persistent object is accessible via the collection. ::
    … … zero, and the second one by way of some assumed initialization function.  
    238238     ::
    239239
    240240         image = new( &database, "ULongImage" )
    241                  r_Marray<r_ULong>( domain, &initWithCoordinates );
     241                 r_Marray<r_ULong>( domain, &initWithCoordinates, &transaction );
    242242
    243243(11) The image created in (9) is inserted into the set.
    244244
    … … elements and iteration through the retrieved result set using raslib.  
    286286    ::
    287287
    288288        r_Database database;
    289         r_Transaction transaction;
     289        r_Transaction transaction{&database};
    290290        r_Ref< r_Set< r_Ref< r_GMarray > > > image_set;
    291291        r_Ref< r_GMarray > image;
    292292        r_Iterator< r_Ref< r_GMarray > > iter;
    … … the raslib classes:  
    358358        r_ULong threshold_value = 10;
    359359
    360360        r_Database database;
    361         r_Transaction transaction;
     361        r_Transaction transaction{&database};
    362362        r_Set< r_Ref< r_GMarray > > image_set;
    363363        r_Ref< r_GMarray > image;
    364364        r_Iterator< r_Ref< r_GMarray > > iter;
    … … the raslib classes:  
    408408
    409409    ::
    410410
    411         r_oql_execute( query, image_set );
     411        r_oql_execute( query, image_set, &transaction );
    412412        iter = image_set.create_iterator();
    413413        for( iter.reset(); iter.not_done(); iter++ )
    414414        {
    … … The template class ``r_Marray<T>`` represents an MDD object over cell type  
    618618``T``. Class ``r_GMarray`` is more generic in that it is able to represent MDD
    619619objects of any base type. This is necessary, firstly, for having a
    620620generic class for query results where the base type is not known at
    621 compile time and, secondly, for usage in the API where the final base
    622 types are not known in advance either.
     621compile time and, secondly, for composite (multi-band) types.
    623622
    624623The template class ``r_Marray<T>`` for specific base types inherits from
    625624``r_GMarray``; the constructor ``r_Marray<T>( r_GMarray& )`` is provided for
    … … Class ``r_Transaction``  
    750749-----------------------
    751750
    752751To use a transaction, an object of type ``r_Transaction`` has to be
    753 in­stantiated. Transactions can be started either in read/write or
     752in­stantiated with an ``r_Database`` object as an argument.
     753Transactions can be started either in read/write or
    754754read-only mode, committed, aborted, and checkpointed. It is important to
    755755note that all access, creation, modification, and deletion of persistent
    756756objects must be done within a transaction. In order to achieve maximal
    757757performance, read-only transactions should be used when­ever possible,
    758758i.e., when no update operations occur within this trans­action. Right
    759 now, only one transaction can be active at a time and no checkpointing
    760 is supported.
     759now checkpointing is not supported.
    761760
    762761::
    763762
    … … memory yet, it is retrieved from the server.  
    780779The class ``r_Ref_Any`` is defined to support a reference to any type. Its
    781780primary purpose is to handle generic references and allow conversions of
    782781``r_Ref<T>`` in the type hierarchy. A ``r_Ref_Any`` object can be used as an
    783 intermediary between any two types ``r_Ref<X>`` and ``r_Ref<Y>`` where ``X`` and ``Y``
    784 are different types. A ``r_Ref<T>`` can always be converted to a
     782intermediary between any two types ``r_Ref<X>`` and ``r_Ref<Y>`` where ``X``
     783and ``Y`` are different types. A ``r_Ref<T>`` can always be converted to a
    785784``r_Ref_Any``; there is a function to perform the conversion in the
    786785``r_Ref<T>`` template. Each ``r_Ref<T>`` class has a constructor and
    787786assignment operator that takes a reference to a ``r_Ref_Any``.
    … … and so on. If any of the ``$i`` is not followed by a parameter at the point  
    817816
    818817A query is executed against an open database through invocation of the
    819818freestanding function ``r_oql_execute()``. This overloaded function exists
    820 in three variants:
     819in four variants:
    821820
    822821::
    823822
    824     void r_oql_execute( r_OQL_Query & query )
     823    void r_oql_execute( r_OQL_Query & query,
     824                        r_Transaction* transaction )
    825825
    826     void r_oql_execute( r_OQL_Query & query, r_Set<r_Ref<r_GMarray>> & result_set )
     826    void r_oql_execute( r_OQL_Query & query, r_Set<r_Ref_Any>& result, int dummy,
     827                        r_Transaction* transaction);
    827828
    828     void r_oql_execute( r_OQL_Query & query, r_Set<r_Ref<r_Any>> & result_set )
     829    void r_oql_execute( r_OQL_Query & query, r_Set<r_Ref<r_GMarray>> & result_set,
     830                        r_Transaction* transaction )
    829831
    830 The first version is used for ``insert``, ``update``, and ``delete`` statements
    831 where no result is passed back. The second version is used for ``select``
     832    void r_oql_execute( r_OQL_Query & query, r_Set<r_Ref<r_Any>> & result_set,
     833                        r_Transaction* transaction )
     834
     835The first version is used for ``insert`` (until v9.1), ``update``, and ``delete``
     836statements where no result is passed back. The second version is used for
     837``insert`` queries, where the result contains the unique OID of the inserted
     838object; the third parameter has no function and is there to distinguish this
     839from the next two versions. The third version is for executing ``select``
    832840statements where an MDD is returned; in this case, the second parameter
    833 receives the query result. The third case is for general query results
     841receives the query result. The final case is for general query results
    834842which may also contain non-MDD return values, e.g., resulting from
    835843``select oid(...)`` or ``select sdom(...)`` statements. This version will also be
    836844used when the result type of a query is not known in advance (i.e., at
    … … Class ``r_Interest_Tiling``  
    12521260The class ``r_Interest_Tiling`` implements the *areas of interest tiling*
    12531261algorithm. The user specifies which areas are of interest (areas which
    12541262are accessed very often) and tiling is performed accordingly, in order
    1255 to optimize access to those areas. 
     1263to optimize access to those areas.
    12561264
    12571265.. figure:: media/dev-guide-c++/image12.png
    12581266   :align: center
    … … error situations:  
    15121520   rasdaman Error Classes
    15131521
    15141522
    1515 Class r_Error
    1516 --------------
     1523Class ``r_Error``
     1524-----------------
    15171525
    15181526This class implements the relevant part of the ODMG C++ binding's
    15191527``r_Error`` class. It extends exception handling through deriving special