VirtualBox

source: vbox/trunk/src/VBox/Main/include/objectslist.h@ 43618

Last change on this file since 43618 was 33540, checked in by vboxsync, 14 years ago

*: spelling fixes, thanks Timeless!

  • Property svn:eol-style set to native
  • Property svn:keywords set to Author Date Id Revision
File size: 4.8 KB
Line 
1/** @file
2 *
3 * List of COM objects
4 */
5
6/*
7 * Copyright (C) 2009 Oracle Corporation
8 *
9 * This file is part of VirtualBox Open Source Edition (OSE), as
10 * available from http://www.virtualbox.org. This file is free software;
11 * you can redistribute it and/or modify it under the terms of the GNU
12 * General Public License (GPL) as published by the Free Software
13 * Foundation, in version 2 as it comes in the "COPYING" file of the
14 * VirtualBox OSE distribution. VirtualBox OSE is distributed in the
15 * hope that it will be useful, but WITHOUT ANY WARRANTY of any kind.
16 */
17
18#ifndef ____H_OBJECTSLIST
19#define ____H_OBJECTSLIST
20
21#include <list>
22#include <VBox/com/ptr.h>
23
24/**
25 * Implements a "flat" objects list with a lock. Since each such list
26 * has its own lock it is not a good idea to implement trees with this.
27 *
28 * ObjectList<T> is designed to behave as if it were a std::list of
29 * COM pointers of class T; in other words,
30 * ObjectList<Medium> behaves like std::list< ComObjPtr<Medium> > but
31 * it's less typing. Iterators, front(), size(), begin() and end()
32 * are implemented.
33 *
34 * In addition it automatically includes an RWLockHandle which can be
35 * accessed with getLockHandle().
36 *
37 * If you need the raw std::list for some reason you can access it with
38 * getList().
39 *
40 * The destructor automatically calls uninit() on every contained
41 * COM object. If this is not desired, clear the member list before
42 * deleting the list object.
43 */
44template<typename T>
45class ObjectsList
46{
47public:
48 typedef ComObjPtr<T> MyType;
49 typedef std::list<MyType> MyList;
50
51 typedef typename MyList::iterator iterator;
52 typedef typename MyList::const_iterator const_iterator;
53 // typename is necessary to disambiguate "::iterator" in templates; see
54 // the "this might hurt your head" part in
55 // http://www.parashift.com/c++-faq-lite/templates.html#faq-35.18
56
57 ObjectsList(RWLockHandle &lockHandle)
58 : m_lock(lockHandle)
59 { }
60
61 ~ObjectsList()
62 {
63 uninitAll();
64 }
65
66private:
67 // prohibit copying and assignment
68 ObjectsList(const ObjectsList &d);
69 ObjectsList& operator=(const ObjectsList &d);
70
71public:
72
73 /**
74 * Returns the lock handle which protects this list, for use with
75 * AutoReadLock or AutoWriteLock.
76 */
77 RWLockHandle& getLockHandle()
78 {
79 return m_lock;
80 }
81
82 /**
83 * Calls m_ll.push_back(p) with locking.
84 * @param p
85 */
86 void addChild(MyType p)
87 {
88 AutoWriteLock al(m_lock COMMA_LOCKVAL_SRC_POS);
89 m_ll.push_back(p);
90 }
91
92 /**
93 * Calls m_ll.remove(p) with locking. Does NOT call uninit()
94 * on the contained object.
95 * @param p
96 */
97 void removeChild(MyType p)
98 {
99 AutoWriteLock al(m_lock COMMA_LOCKVAL_SRC_POS);
100 m_ll.remove(p);
101 }
102
103 /**
104 * Appends all objects from another list to the member list.
105 * Locks the other list for reading but does not lock "this"
106 * (because it might be on the caller's stack and needs no
107 * locking).
108 * @param ll
109 */
110 void appendOtherList(ObjectsList<T> &ll)
111 {
112 AutoReadLock alr(ll.getLockHandle() COMMA_LOCKVAL_SRC_POS);
113 for (const_iterator it = ll.begin();
114 it != ll.end();
115 ++it)
116 {
117 m_ll.push_back(*it);
118 }
119 }
120
121 /**
122 * Calls uninit() on every COM object on the list and then
123 * clears the list, with locking.
124 */
125 void uninitAll()
126 {
127 AutoWriteLock al(m_lock COMMA_LOCKVAL_SRC_POS);
128 for (iterator it = m_ll.begin();
129 it != m_ll.end();
130 ++it)
131 {
132 MyType &q = *it;
133 q->uninit();
134 }
135 m_ll.clear();
136 }
137
138 /**
139 * Returns the no. of objects on the list (std::list compatibility)
140 * with locking.
141 */
142 size_t size()
143 {
144 AutoReadLock al(m_lock COMMA_LOCKVAL_SRC_POS);
145 return m_ll.size();
146 }
147
148 /**
149 * Returns a raw pointer to the member list of objects.
150 * Does not lock!
151 * @return
152 */
153 MyList& getList()
154 {
155 return m_ll;
156 }
157
158 /**
159 * Returns the first object on the list (std::list compatibility)
160 * with locking.
161 */
162 MyType front()
163 {
164 AutoReadLock al(m_lock COMMA_LOCKVAL_SRC_POS);
165 return m_ll.front();
166 }
167
168 /**
169 * Returns the begin iterator from the list (std::list compatibility).
170 * Does not lock!
171 * @return
172 */
173 iterator begin()
174 {
175 return m_ll.begin();
176 }
177
178 /**
179 * Returns the end iterator from the list (std::list compatibility).
180 * Does not lock!
181 */
182 iterator end()
183 {
184 return m_ll.end();
185 }
186
187 void insert(iterator it, MyType &p)
188 {
189 m_ll.insert(it, p);
190 }
191
192 void erase(iterator it)
193 {
194 m_ll.erase(it);
195 }
196
197private:
198 MyList m_ll;
199 RWLockHandle &m_lock;
200};
201
202#endif
Note: See TracBrowser for help on using the repository browser.

© 2024 Oracle Support Privacy / Do Not Sell My Info Terms of Use Trademark Policy Automated Access Etiquette