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
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
|
.TH ACE_Weak_Bound_Ptr 3 "1 Dec 2001" "ACE" \" -*- nroff -*-
.ad l
.nh
.SH NAME
ACE_Weak_Bound_Ptr \- This class implements support for a weak pointer that complements \fBACE_Strong_Bound_Ptr\fR. Unlike \fBACE_Strong_Bound_Ptr\fR, assigning or copying instances of an ACE_Weak_Bound_Ptr will not automatically increment the reference count of the underlying object. What ACE_Weak_Bound_Ptr does is preserve the knowledge that the object is in fact reference counted, and thus provides an alternative to raw pointers where non-ownership associations must be maintained. When the last instance of an \fBACE_Strong_Bound_Ptr\fR that references a particular object is destroyed or overwritten, the corresponding ACE_Weak_Bound_Ptr instances are set to null.
.SH SYNOPSIS
.br
.PP
\fC#include <Bound_Ptr.h>\fR
.PP
.SS Public Methods
.in +1c
.ti -1c
.RI "ACE_EXPLICIT \fBACE_Weak_Bound_Ptr\fR (X *p = 0)"
.br
.RI "\fIConstructor that initializes an ACE_Weak_Bound_Ptr to point to the object
.PP
immediately.\fR"
.ti -1c
.RI "\fBACE_Weak_Bound_Ptr\fR (const ACE_Weak_Bound_Ptr<X, ACE_LOCK> &r)"
.br
.RI "\fICopy constructor binds <this> and <r> to the same object.\fR"
.ti -1c
.RI "\fBACE_Weak_Bound_Ptr\fR (const \fBACE_Strong_Bound_Ptr\fR<X, ACE_LOCK> &r)"
.br
.RI "\fIConstructor binds <this> and <r> to the same object.\fR"
.ti -1c
.RI "\fB~ACE_Weak_Bound_Ptr\fR (void)"
.br
.RI "\fIDestructor.\fR"
.ti -1c
.RI "void \fBoperator=\fR (const ACE_Weak_Bound_Ptr<X, ACE_LOCK> &r)"
.br
.RI "\fIAssignment operator that binds <this> and <r> to the same object.\fR"
.ti -1c
.RI "void \fBoperator=\fR (const \fBACE_Strong_Bound_Ptr\fR<X, ACE_LOCK> &r)"
.br
.RI "\fIAssignment operator that binds <this> and <r> to the same object.\fR"
.ti -1c
.RI "int \fBoperator==\fR (const ACE_Weak_Bound_Ptr<X, ACE_LOCK> &r) const"
.br
.RI "\fIEquality operator that returns 1 if both ACE_Weak_Bound_Ptr objects point to the same underlying object. Attention: It also returns 1 if both objects have just been instantiated and not used yet.\fR"
.ti -1c
.RI "int \fBoperator==\fR (const \fBACE_Strong_Bound_Ptr\fR<X, ACE_LOCK> &r) const"
.br
.RI "\fIEquality operator that returns 1 if the ACE_Weak_Bound_Ptr and \fBACE_Strong_Bound_Ptr\fR objects point to the same underlying object. Attention: It also returns 1 if both objects have just been instantiated and not used yet.\fR"
.ti -1c
.RI "int \fBoperator==\fR (X *p) const"
.br
.RI "\fIEquality operator that returns 1 if the ACE_Weak_Bound_Ptr and the raw pointer point to the same underlying object.\fR"
.ti -1c
.RI "int \fBoperator!=\fR (const ACE_Weak_Bound_Ptr<X, ACE_LOCK> &r) const"
.br
.RI "\fIInequality operator, which is the opposite of equality.\fR"
.ti -1c
.RI "int \fBoperator!=\fR (const \fBACE_Strong_Bound_Ptr\fR<X, ACE_LOCK> &r) const"
.br
.RI "\fIInequality operator, which is the opposite of equality.\fR"
.ti -1c
.RI "int \fBoperator!=\fR (X *p) const"
.br
.RI "\fIInequality operator, which is the opposite of equality.\fR"
.ti -1c
.RI "\fBACE_Strong_Bound_Ptr\fR<X, ACE_LOCK> \fBoperator->\fR (void) const"
.br
.RI "\fIRedirection operator. It returns a temporary strong pointer and makes use of the chaining properties of operator-> to ensure that the underlying object does not disappear while you are using it. If you are certain of the lifetimes of the object, and do not want to incur the locking overhead, then use the unsafe_get method instead.\fR"
.ti -1c
.RI "\fBACE_Strong_Bound_Ptr\fR<X, ACE_LOCK> \fBstrong\fR (void) const"
.br
.RI "\fIObtain a strong pointer corresponding to this weak pointer. This function is useful to create a temporary strong pointer for conversion to a reference.\fR"
.ti -1c
.RI "X* \fBunsafe_get\fR (void) const"
.br
.RI "\fIGet the pointer value. Warning: this does not affect the reference count of the underlying object, so it may disappear on you while you are using it if you are not careful.\fR"
.ti -1c
.RI "void \fBreset\fR (X *p = 0)"
.br
.RI "\fIResets the ACE_Weak_Bound_Ptr to refer to a different underlying object.\fR"
.ti -1c
.RI "int \fBadd_ref\fR (void)"
.br
.RI "\fIIncrement the reference count on the underlying object. Returns the new reference count on the object. This function may be used to integrate the bound pointers into an external reference counting mechanism such as those used by COM or CORBA servants.\fR"
.ti -1c
.RI "int \fBremove_ref\fR (void)"
.br
.RI "\fIDecrement the reference count on the underlying object, which is deleted if the count has reached zero. Returns the new reference count on the object. This function may be used to integrate the bound pointers into an external reference counting mechanism such as those used by COM or CORBA servants.\fR"
.ti -1c
.RI "int \fBnull\fR (void) const"
.br
.RI "\fIAllows us to check for NULL on all ACE_Weak_Bound_Ptr objects.\fR"
.in -1c
.SS Public Attributes
.in +1c
.ti -1c
.RI "\fBACE_ALLOC_HOOK_DECLARE\fR"
.br
.RI "\fIDeclare the dynamic allocation hooks.\fR"
.in -1c
.SS Private Types
.in +1c
.ti -1c
.RI "typedef \fBACE_Bound_Ptr_Counter\fR<ACE_LOCK> \fBCOUNTER\fR"
.br
.RI "\fIThe \fBACE_Bound_Ptr_Counter\fR type.\fR"
.in -1c
.SS Private Attributes
.in +1c
.ti -1c
.RI "\fBCOUNTER\fR* \fBcounter_\fR"
.br
.RI "\fIThe reference counter.\fR"
.ti -1c
.RI "X* \fBptr_\fR"
.br
.RI "\fIThe underlying object.\fR"
.in -1c
.SS Friends
.in +1c
.ti -1c
.RI "class \fBACE_Strong_Bound_Ptr< X,ACE_LOCK >\fR"
.br
.in -1c
.SH DETAILED DESCRIPTION
.PP
.SS template<class X, class ACE_LOCK> template class ACE_Weak_Bound_Ptr
This class implements support for a weak pointer that complements \fBACE_Strong_Bound_Ptr\fR. Unlike \fBACE_Strong_Bound_Ptr\fR, assigning or copying instances of an ACE_Weak_Bound_Ptr will not automatically increment the reference count of the underlying object. What ACE_Weak_Bound_Ptr does is preserve the knowledge that the object is in fact reference counted, and thus provides an alternative to raw pointers where non-ownership associations must be maintained. When the last instance of an \fBACE_Strong_Bound_Ptr\fR that references a particular object is destroyed or overwritten, the corresponding ACE_Weak_Bound_Ptr instances are set to null.
.PP
.SH MEMBER TYPEDEF DOCUMENTATION
.PP
.SS template<classX, classACE_LOCK> typedef \fBACE_Bound_Ptr_Counter\fR<ACE_LOCK> ACE_Weak_Bound_Ptr<X, ACE_LOCK>::COUNTER\fC [private]\fR
.PP
The \fBACE_Bound_Ptr_Counter\fR type.
.PP
.SH CONSTRUCTOR & DESTRUCTOR DOCUMENTATION
.PP
.SS template<classX, classACE_LOCK> ACE_EXPLICIT ACE_Weak_Bound_Ptr<X, ACE_LOCK>::ACE_Weak_Bound_Ptr<X, ACE_LOCK> (X * p = 0)
.PP
Constructor that initializes an ACE_Weak_Bound_Ptr to point to the object
.PP
immediately.
.PP
.SS template<classX, classACE_LOCK> ACE_Weak_Bound_Ptr<X, ACE_LOCK>::ACE_Weak_Bound_Ptr<X, ACE_LOCK> (const ACE_Weak_Bound_Ptr< X,ACE_LOCK >& r)
.PP
Copy constructor binds <this> and <r> to the same object.
.PP
.SS template<classX, classACE_LOCK> ACE_Weak_Bound_Ptr<X, ACE_LOCK>::ACE_Weak_Bound_Ptr<X, ACE_LOCK> (const \fBACE_Strong_Bound_Ptr\fR< X,ACE_LOCK >& r)
.PP
Constructor binds <this> and <r> to the same object.
.PP
.SS template<classX, classACE_LOCK> ACE_Weak_Bound_Ptr<X, ACE_LOCK>::~ACE_Weak_Bound_Ptr<X, ACE_LOCK> (void)
.PP
Destructor.
.PP
.SH MEMBER FUNCTION DOCUMENTATION
.PP
.SS template<classX, classACE_LOCK> int ACE_Weak_Bound_Ptr<X, ACE_LOCK>::add_ref (void)
.PP
Increment the reference count on the underlying object. Returns the new reference count on the object. This function may be used to integrate the bound pointers into an external reference counting mechanism such as those used by COM or CORBA servants.
.PP
.SS template<classX, classACE_LOCK> int ACE_Weak_Bound_Ptr<X, ACE_LOCK>::null (void) const
.PP
Allows us to check for NULL on all ACE_Weak_Bound_Ptr objects.
.PP
.SS template<classX, classACE_LOCK> int ACE_Weak_Bound_Ptr<X, ACE_LOCK>::operator!= (X * p) const
.PP
Inequality operator, which is the opposite of equality.
.PP
.SS template<classX, classACE_LOCK> int ACE_Weak_Bound_Ptr<X, ACE_LOCK>::operator!= (const \fBACE_Strong_Bound_Ptr\fR< X,ACE_LOCK >& r) const
.PP
Inequality operator, which is the opposite of equality.
.PP
.SS template<classX, classACE_LOCK> int ACE_Weak_Bound_Ptr<X, ACE_LOCK>::operator!= (const ACE_Weak_Bound_Ptr< X,ACE_LOCK >& r) const
.PP
Inequality operator, which is the opposite of equality.
.PP
.SS template<classX, classACE_LOCK> \fBACE_Strong_Bound_Ptr\fR< X,ACE_LOCK > ACE_Weak_Bound_Ptr<X, ACE_LOCK>::operator-> (void) const
.PP
Redirection operator. It returns a temporary strong pointer and makes use of the chaining properties of operator-> to ensure that the underlying object does not disappear while you are using it. If you are certain of the lifetimes of the object, and do not want to incur the locking overhead, then use the unsafe_get method instead.
.PP
.SS template<classX, classACE_LOCK> void ACE_Weak_Bound_Ptr<X, ACE_LOCK>::operator= (const \fBACE_Strong_Bound_Ptr\fR< X,ACE_LOCK >& r)
.PP
Assignment operator that binds <this> and <r> to the same object.
.PP
.SS template<classX, classACE_LOCK> void ACE_Weak_Bound_Ptr<X, ACE_LOCK>::operator= (const ACE_Weak_Bound_Ptr< X,ACE_LOCK >& r)
.PP
Assignment operator that binds <this> and <r> to the same object.
.PP
.SS template<classX, classACE_LOCK> int ACE_Weak_Bound_Ptr<X, ACE_LOCK>::operator== (X * p) const
.PP
Equality operator that returns 1 if the ACE_Weak_Bound_Ptr and the raw pointer point to the same underlying object.
.PP
.SS template<classX, classACE_LOCK> int ACE_Weak_Bound_Ptr<X, ACE_LOCK>::operator== (const \fBACE_Strong_Bound_Ptr\fR< X,ACE_LOCK >& r) const
.PP
Equality operator that returns 1 if the ACE_Weak_Bound_Ptr and \fBACE_Strong_Bound_Ptr\fR objects point to the same underlying object. Attention: It also returns 1 if both objects have just been instantiated and not used yet.
.PP
.SS template<classX, classACE_LOCK> int ACE_Weak_Bound_Ptr<X, ACE_LOCK>::operator== (const ACE_Weak_Bound_Ptr< X,ACE_LOCK >& r) const
.PP
Equality operator that returns 1 if both ACE_Weak_Bound_Ptr objects point to the same underlying object. Attention: It also returns 1 if both objects have just been instantiated and not used yet.
.PP
.SS template<classX, classACE_LOCK> int ACE_Weak_Bound_Ptr<X, ACE_LOCK>::remove_ref (void)
.PP
Decrement the reference count on the underlying object, which is deleted if the count has reached zero. Returns the new reference count on the object. This function may be used to integrate the bound pointers into an external reference counting mechanism such as those used by COM or CORBA servants.
.PP
.SS template<classX, classACE_LOCK> void ACE_Weak_Bound_Ptr<X, ACE_LOCK>::reset (X * p = 0)
.PP
Resets the ACE_Weak_Bound_Ptr to refer to a different underlying object.
.PP
.SS template<classX, classACE_LOCK> \fBACE_Strong_Bound_Ptr\fR< X,ACE_LOCK > ACE_Weak_Bound_Ptr<X, ACE_LOCK>::strong (void) const
.PP
Obtain a strong pointer corresponding to this weak pointer. This function is useful to create a temporary strong pointer for conversion to a reference.
.PP
.SS template<classX, classACE_LOCK> X * ACE_Weak_Bound_Ptr<X, ACE_LOCK>::unsafe_get (void) const
.PP
Get the pointer value. Warning: this does not affect the reference count of the underlying object, so it may disappear on you while you are using it if you are not careful.
.PP
.SH FRIENDS AND RELATED FUNCTION DOCUMENTATION
.PP
.SS template<classX, classACE_LOCK> class \fBACE_Strong_Bound_Ptr\fR\fC [friend]\fR
.PP
.SH MEMBER DATA DOCUMENTATION
.PP
.SS template<classX, classACE_LOCK> ACE_Weak_Bound_Ptr<X, ACE_LOCK>::ACE_ALLOC_HOOK_DECLARE
.PP
Declare the dynamic allocation hooks.
.PP
.SS template<classX, classACE_LOCK> \fBCOUNTER\fR * ACE_Weak_Bound_Ptr<X, ACE_LOCK>::counter_\fC [private]\fR
.PP
The reference counter.
.PP
.SS template<classX, classACE_LOCK> X * ACE_Weak_Bound_Ptr<X, ACE_LOCK>::ptr_\fC [private]\fR
.PP
The underlying object.
.PP
.SH AUTHOR
.PP
Generated automatically by Doxygen for ACE from the source code.
|
