BIND 10 #2461: clarify thread consideration for DataSourceClient

[BIND 10 Development]

#2461: clarify thread consideration for DataSourceClient
-------------------------------------+-------------------------------------
            Reporter:  jinmei        |                        Owner:
                Type:  task          |                       Status:  new
            Priority:  medium        |                    Milestone:  New
           Component:  data source   |  Tasks
           Sensitive:  0             |                     Keywords:
         Sub-Project:  DNS           |              Defect Severity:  N/A
Estimated Difficulty:  0             |  Feature Depending on Ticket:
         Total Hours:  0             |          Add Hours to Ticket:  0
                                     |                    Internal?:  0
-------------------------------------+-------------------------------------
 This is a related topic of #2459, at a bit higher level.

 Even the issue of #2459 aside, b10-auth now breaks a design assumption
 of `DataSourceClient`:
 {{{#!cpp
 /// If the application uses multiple threads, each thread will need to
 /// create and use a separate DataSourceClient.  This is because some
 /// database backend doesn't allow multiple threads to share the same
 /// connection to the database.
 }}}
 because it shared the same client object by multiple threads through
 `ConfigurableClientList`.

 But, actually, the above note may be a bit too strong.  Due to the
 introduction of `DatabaseAccessor::clone() and the use of it in many
 of its methods (of its database version of derived class)
 `DataSourceClient` should now be pretty thread safe except for
 findZone().  (As noted in #2460, based on the assumption that
 `DatabaseAccessor::clone()` is thread safe).

 Considering these facts, I think we should revise the thread
 consideration.  My basic suggestion is:

 - The derived class implementation must ensure all methods are thread
   safe except for findZone() (and subsequent use of `ZoneFinder`)
 - If `DataSourceClient` is shared by multiple threads, the application
   is responsible for protecting calls to findZone() (and subsequent
   use of `ZoneFinder`) by multiple threads.

 On top of this, we might also make some extensions:
 - introduce a thread-safe mode to findZone().  It will internally
   clone() the accessor (in the case of the DB-based version).
 - on the other hand, introduce a share-mode to other methods.  For
   example, DDNS would probably like to keep the same connection for
   updating zones; it would be expensive if it needs to open a new DB
   connection for every update message.  It would apply to xfrin, too,
   (although probably less critical, assuming xfr-in events are less
   frequent).

 In this ticket I suggest just making documentation clarification as
 suggested above.  doc for `ConfigurableClientList` should also be updated.

-- 
Ticket URL: <http://bind10.isc.org/ticket/2461>
BIND 10 Development <http://bind10.isc.org>
BIND 10 Development