datahandle.h 4.67 KB
Newer Older
1
2
// ================================================================================================
// 
schultezub's avatar
schultezub committed
3
// This file is part of the CAMPVis Software Framework.
4
5
// 
// If not explicitly stated otherwise: Copyright (C) 2012, all rights reserved,
schultezub's avatar
schultezub committed
6
//      Christian Schulte zu Berge <christian.szb@in.tum.de>
7
8
9
//      Chair for Computer Aided Medical Procedures
//      Technische Universität München
//      Boltzmannstr. 3, 85748 Garching b. München, Germany
schultezub's avatar
schultezub committed
10
// For a full list of authors and contributors, please refer to the file "AUTHORS.txt".
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
// 
// 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
30
31
32
#ifndef datahandle_h__
#define datahandle_h__

33
34
#include <ctime>

schultezub's avatar
schultezub committed
35
namespace campvis {
36
    class AbstractData;
schultezub's avatar
schultezub committed
37
38
39

    /**
     * A DataHandle is responsible to manage the lifetime of an AbstractData instance.
40
     * Therefore, it implements a reference counting technique in cooperation with AbstractData.
41
42
43
44
45
     * 
     * 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.
     * 
46
     * \note    For clarity: An AbstractData instance can be referenced by multiple DataHandles. As soon 
47
     *          as it is afterwards reference by 0 DataHandles, the AbstractData instance will be destroyed.
48
49
50
51
     *          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
52
53
54
55
     */
    class DataHandle {
    public:
        /**
56
57
58
59
         * 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
60
         */
61
        explicit DataHandle(AbstractData* data = 0);
schultezub's avatar
schultezub committed
62
63

        /**
64
65
66
         * 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
67
         */
68
        DataHandle(const DataHandle& rhs);
schultezub's avatar
schultezub committed
69
70

        /**
71
72
73
74
         * 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
75
         */
76
        DataHandle& operator=(const DataHandle& rhs);
77

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

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

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

schultezub's avatar
schultezub committed
95

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

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

}

#endif // datahandle_h__