datahandle.h 4.57 KB
Newer Older
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
// ================================================================================================
// 
// This file is part of the TUMVis Visualization Framework.
// 
// If not explicitly stated otherwise: Copyright (C) 2012, all rights reserved,
//      Christian Schulte zu Berge (christian.szb@in.tum.de)
//      Chair for Computer Aided Medical Procedures
//      Technische Universität München
//      Boltzmannstr. 3, 85748 Garching b. München, Germany
// 
// The licensing of this softare is not yet resolved. Until then, redistribution in source or
// binary forms outside the CAMP chair is not permitted, unless explicitly stated in legal form.
// However, the names of the original authors and the above copyright notice must retain in its
// original state in any case.
// 
// Legal disclaimer provided by the BSD license:
// THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR
// IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY 
// AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR 
// CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR 
// CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR 
// SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY 
// THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR 
// OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
// POSSIBILITY OF SUCH DAMAGE.
// 
// ================================================================================================

schultezub's avatar
schultezub committed
29
30
31
#ifndef datahandle_h__
#define datahandle_h__

32
33
#include <ctime>

schultezub's avatar
schultezub committed
34
namespace TUMVis {
35
    class AbstractData;
schultezub's avatar
schultezub committed
36
37
38

    /**
     * A DataHandle is responsible to manage the lifetime of an AbstractData instance.
39
     * Therefore, it implements a reference counting technique in cooperation with AbstractData.
40
41
42
43
44
     * 
     * This class can be considered as thread safe under the following conditions:
     *  * A single DataHandle instance must not be accessed from different threads.
     *  * Concurrent access to the same AbstractData instance via different DataHandles is safe.
     * 
45
     * \note    For clarity: An AbstractData instance can be referenced by multiple DataHandles. As soon 
46
     *          as it is afterwards reference by 0 DataHandles, the AbstractData instance will be destroyed.
47
48
49
50
     *          Also remember that a DataHandle takes ownership of the given AbstractData instance. So do
     *          not delete it once it has been assigned to a DataHandle (respectively DataContainer) or mess
     *          with its reference counting!
     * \note    Reference counting implementation inspired from Scott Meyers: More Effective C++, Item 29
schultezub's avatar
schultezub committed
51
52
53
54
     */
    class DataHandle {
    public:
        /**
55
56
57
58
         * Creates a new DataHandle for the given data.
         * \note    By passing the data to DataHandle you will transfer its ownership to the reference
         *          counting mechanism. Make sure not to interfere with it or delete \a data yourself!
         * \param   data    Data for the DataHandle
schultezub's avatar
schultezub committed
59
         */
60
        DataHandle(AbstractData* data);
schultezub's avatar
schultezub committed
61
62

        /**
63
64
65
         * Copy-constructor
         * \note    If \a rhs is not shareable, this implies a copy of the data!
         * \param   rhs     Source DataHandle
schultezub's avatar
schultezub committed
66
         */
67
        DataHandle(const DataHandle& rhs);
schultezub's avatar
schultezub committed
68
69

        /**
70
71
72
73
         * Assignment operator
         * \note    If \a rhs is not shareable, this implies a copy of the data!
         * \param   rhs     source DataHandle
         * \return  *this
schultezub's avatar
schultezub committed
74
         */
75
        DataHandle& operator=(const DataHandle& rhs);
76

schultezub's avatar
schultezub committed
77
        /**
schultezub's avatar
schultezub committed
78
         * Destructor, decrease the reference count of the managed AbstractData.
schultezub's avatar
schultezub committed
79
         */
80
        virtual ~DataHandle();
schultezub's avatar
schultezub committed
81
82

        /**
83
84
         * Grants const access to the managed AbstractData instance.
         * \return  _data;
schultezub's avatar
schultezub committed
85
         */
86
        const AbstractData* getData() const;
schultezub's avatar
schultezub committed
87

88
89
90
91
92
93
        /**
         * Gets the timestamp when this data has been created.
         * \return _timestamp
         */
        clock_t getTimestamp() const;

schultezub's avatar
schultezub committed
94

95
    private:
schultezub's avatar
schultezub committed
96
        /**
97
         * Initializes the reference counting for the data.
schultezub's avatar
schultezub committed
98
         */
99
        void init();
schultezub's avatar
schultezub committed
100

101
102
        AbstractData* _data;                    ///< managed data
        clock_t _timestamp;                     ///< Timestamp when this data has been created
schultezub's avatar
schultezub committed
103
104
105
106
107
    };

}

#endif // datahandle_h__