LCOV - code coverage report
Current view: top level - lib - node_lock.cpp (source / functions) Hit Total Coverage
Test: coverage.info Lines: 28 28 100.0 %
Date: 2014-11-22 Functions: 9 9 100.0 %
Legend: Lines: hit not hit

          Line data    Source code
       1             : /* node_lock.cpp -- written by Alexis WILKE for Made to Order Software Corp. (c) 2005-2014 */
       2             : 
       3             : /*
       4             : 
       5             : Copyright (c) 2005-2014 Made to Order Software Corp.
       6             : 
       7             : http://snapwebsites.org/project/as2js
       8             : 
       9             : Permission is hereby granted, free of charge, to any
      10             : person obtaining a copy of this software and
      11             : associated documentation files (the "Software"), to
      12             : deal in the Software without restriction, including
      13             : without limitation the rights to use, copy, modify,
      14             : merge, publish, distribute, sublicense, and/or sell
      15             : copies of the Software, and to permit persons to whom
      16             : the Software is furnished to do so, subject to the
      17             : following conditions:
      18             : 
      19             : The above copyright notice and this permission notice
      20             : shall be included in all copies or substantial
      21             : portions of the Software.
      22             : 
      23             : THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF
      24             : ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT
      25             : LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
      26             : FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO
      27             : EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
      28             : LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
      29             : WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE,
      30             : ARISING FROM, OUT OF OR IN CONNECTION WITH THE
      31             : SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
      32             : SOFTWARE.
      33             : 
      34             : */
      35             : 
      36             : #include    "as2js/node.h"
      37             : 
      38             : #include    "as2js/exceptions.h"
      39             : 
      40             : 
      41             : /** \file
      42             :  * \brief Manage a node lock.
      43             :  *
      44             :  * This file defines the implementation of the node lock. At some point
      45             :  * in the compiler, a set of node cannot be modified or it could crash
      46             :  * or invalidate the current work being done. (i.e. if you assume you
      47             :  * have a node of type NODE_INT64 and someone changes it to NODE_FLOAT64
      48             :  * under your feet, then calling get_int64() will fail with an exception.
      49             :  * However, the real problem would not be the call to the get_int64(),
      50             :  * but the earlier call to the to_float64() function.)
      51             :  *
      52             :  * The lock allows you to mark a node as being read-only for a while.
      53             :  *
      54             :  * The NodeLock class allows you to use a scoped lock (the destructor
      55             :  * automatically unlocks the node.)
      56             :  */
      57             : 
      58             : 
      59             : namespace as2js
      60             : {
      61             : 
      62             : 
      63             : /**********************************************************************/
      64             : /**********************************************************************/
      65             : /***  NODE LOCK  ******************************************************/
      66             : /**********************************************************************/
      67             : /**********************************************************************/
      68             : 
      69             : 
      70             : /** \brief Test whether the node can be modified.
      71             :  *
      72             :  * This function verifies whether the node can be modified. Nodes that were
      73             :  * locked cannot be modified. It can be very difficult to determine what
      74             :  * is happening on the tree when working with a very large tree.
      75             :  * This parameter ensures that nodes we are looping over while doing work
      76             :  * do not get modify at the wrong time.
      77             :  *
      78             :  * To avoid the exception that this function generates, you may instead
      79             :  * call the is_locked() function.
      80             :  *
      81             :  * \note
      82             :  * This function is expected to be called BEFORE your function attemps
      83             :  * any modification of the node.
      84             :  *
      85             :  * \exception exception_locked_node
      86             :  * If the function detects a lock on this node (i.e. the node should not
      87             :  * get modified,) then it raises this exception.
      88             :  *
      89             :  * \sa lock()
      90             :  * \sa unlock()
      91             :  * \sa is_locked()
      92             :  */
      93    48778387 : void Node::modifying() const
      94             : {
      95    48778387 :     if(is_locked())
      96             :     {
      97        2042 :         throw exception_locked_node("trying to modify a locked node.");
      98             :     }
      99    48776345 : }
     100             : 
     101             : 
     102             : /** \brief Check whether a node is locked.
     103             :  *
     104             :  * This function returns true if the specified node is currently locked.
     105             :  * False otherwise.
     106             :  *
     107             :  * \return true if the node is locked.
     108             :  *
     109             :  * \sa lock()
     110             :  * \sa unlock()
     111             :  * \sa modifying()
     112             :  */
     113    49487402 : bool Node::is_locked() const
     114             : {
     115    49487402 :     return f_lock != 0;
     116             : }
     117             : 
     118             : 
     119             : /** \brief Lock this node.
     120             :  *
     121             :  * This function locks this node. A node can be locked multiple times. The
     122             :  * unlock() function needs to be called the same number of times the
     123             :  * lock() function was called.
     124             :  *
     125             :  * It is strongly recommended that you use the NodeLock object in order
     126             :  * to lock your nodes. That way they automatically get unlocked when you
     127             :  * exit your scope, even if an exception occurs.
     128             :  *
     129             :  * \code
     130             :  *  {
     131             :  *      NodeLock lock(my_node);
     132             :  *
     133             :  *      ...do work...
     134             :  *  } // auto-unlock here
     135             :  * \endcode
     136             :  *
     137             :  * \note
     138             :  * This library is NOT multi-thread safe. This lock has nothing to do
     139             :  * with protecting a node from multiple accesses via multiple threads.
     140             :  *
     141             :  * \warning
     142             :  * The f_parent makes use of a weak pointer, and thus you will see
     143             :  * a call to a lock() function. This is the lock of the smart pointer
     144             :  * and not the lock of the node:
     145             :  *
     146             :  * \code
     147             :  *      p = f_parent.lock();   // return a shared_ptr
     148             :  *
     149             :  *      f_parent->lock();      // lock the parent node (call this function)
     150             :  * \endcode
     151             :  *
     152             :  * \bug
     153             :  * This function does not verify that the lock counter does not go
     154             :  * over the limit. However, the limit is 2 billion and if you reach
     155             :  * such, you probably have an enormous stack... which is rather
     156             :  * unlikely. More or less, technically, it just should not ever
     157             :  * overflow.
     158             :  *
     159             :  * \sa is_locked()
     160             :  * \sa unlock()
     161             :  * \sa modifying()
     162             :  */
     163       26790 : void Node::lock()
     164             : {
     165       26790 :     ++f_lock;
     166       26790 : }
     167             : 
     168             : 
     169             : /** \brief Unlock a node that was previously locked.
     170             :  *
     171             :  * This function unlocks a node that was previously called with a call
     172             :  * to the lock() function.
     173             :  *
     174             :  * It cannot be called on a node that was not previously locked.
     175             :  *
     176             :  * To make it safe, you should look into using the NodeLock object to
     177             :  * lock your nodes, especially because the NodeLock is exception safe.
     178             :  *
     179             :  * \code
     180             :  *  {
     181             :  *      NodeLock lock(my_node);
     182             :  *
     183             :  *      ...do work...
     184             :  *  } // auto-unlock here
     185             :  * \endcode
     186             :  *
     187             :  * \note
     188             :  * This library is NOT multi-thread safe. This lock has nothing to do
     189             :  * with protecting a node from multiple accesses via multiple threads.
     190             :  *
     191             :  * \exception exception_internal_error
     192             :  * This exception is raised if the unlock() function is called more times
     193             :  * than the lock() function was called. It is considered an internal error
     194             :  * since it should never happen, especially if you make sure to use the
     195             :  * NodeLock object.
     196             :  *
     197             :  * \sa lock()
     198             :  * \sa is_locked()
     199             :  * \sa modifying()
     200             :  */
     201       26790 : void Node::unlock()
     202             : {
     203       26790 :     if(f_lock <= 0)
     204             :     {
     205           1 :         throw exception_internal_error("somehow the Node::unlock() function was called when the lock counter is zero");
     206             :     }
     207             : 
     208       26789 :     --f_lock;
     209       26789 : }
     210             : 
     211             : 
     212             : /** \brief Safely lock a node.
     213             :  *
     214             :  * This constructor is used to lock a node within a scope.
     215             :  *
     216             :  * \code
     217             :  *     {
     218             :  *         NodeLock lock(my_node);
     219             :  *         ...code...
     220             :  *     } // auto-unlock here
     221             :  * \endcode
     222             :  *
     223             :  * Note that the unlock() function can be used to prematuraly unlock
     224             :  * a node. It is very important to use the unlock() function of the
     225             :  * NodeLock() otherwise it will attempt to unlock the node again
     226             :  * when it gets out of scope (although that bug will be caught).
     227             :  *
     228             :  * \code
     229             :  *     {
     230             :  *         NodeLock lock(my_node);
     231             :  *         ...code...
     232             :  *         lock.unlock();
     233             :  *         ...code...
     234             :  *     } // already unlocked...
     235             :  * \endcode
     236             :  *
     237             :  * The function accepts a null pointer as parameter. This is useful
     238             :  * in many situation where we do not know whether the node is null
     239             :  * and it would make it complicated to have to check.
     240             :  *
     241             :  * \param[in] node  The node to be locked.
     242             :  *
     243             :  * \sa Node::lock()
     244             :  * \sa unlock()
     245             :  */
     246       26791 : NodeLock::NodeLock(Node::pointer_t node)
     247       26791 :     : f_node(node)
     248             : {
     249       26791 :     if(f_node)
     250             :     {
     251       26789 :         f_node->lock();
     252             :     }
     253       26791 : }
     254             : 
     255             : 
     256             : /** \brief Destroy the NodeLock object.
     257             :  *
     258             :  * The destructor of the NodeLock object ensures that the node passed
     259             :  * as a parameter to the constructor gets unlocked.
     260             :  *
     261             :  * If the pointer was null or the unlock() function was called early,
     262             :  * nothing happens.
     263             :  *
     264             :  * \sa unlock()
     265             :  */
     266       53582 : NodeLock::~NodeLock()
     267             : {
     268       26791 :     unlock();
     269       26791 : }
     270             : 
     271             : 
     272             : /** \brief Prematurely unlock the node.
     273             :  *
     274             :  * This function can be used to unlock a node before the end of a
     275             :  * scope is reached. There are cases where that may be necessary.
     276             :  *
     277             :  * Note that this function is also called by the destructor. To
     278             :  * avoid a double unlock on a node, the function sets the node
     279             :  * pointer to null before returning. This means this function
     280             :  * can safely be called any number of times and the lock counter
     281             :  * of the node will remain valid.
     282             :  *
     283             :  * \sa Node::unlock()
     284             :  */
     285       26793 : void NodeLock::unlock()
     286             : {
     287       26793 :     if(f_node)
     288             :     {
     289       26789 :         f_node->unlock();
     290       26789 :         f_node.reset();
     291             :     }
     292       26793 : }
     293             : 
     294          63 : }
     295             : // namespace as2js
     296             : 
     297             : // vim: ts=4 sw=4 et

Generated by: LCOV version 1.10