|
Size: 1699
Comment: converted to 1.6 markup
|
← Revision 3 as of 2009-04-07 17:12:54 ⇥
Size: 1706
Comment: Removed line breaks that were wreaking havok with the layout
|
| Deletions are marked like this. | Additions are marked like this. |
| Line 1: | Line 1: |
| David Abrahams' Guidelines (republished with permission): | David Abrahams' Guidelines (republished with permission from http://mail.python.org/pipermail/cplusplus-sig/2008-October/013895.html): |
| Line 5: | Line 5: |
| * a handle<> can be NULL, and maintains a reference count on the object it points to |
* a handle<> can be NULL, and maintains a reference count on the object it points to |
| Line 10: | Line 9: |
| * handle<> y(x), where x is not the result of null_ok, never results in a NULL y. An exception will be thrown if x is NULL |
* handle<> y(x), where x is not the result of null_ok, never results in a NULL y. An exception will be thrown if x is NULL |
| Line 13: | Line 11: |
| * handle<> y(borrowed(x)) presumes that *x is borrowed and thus increments its reference count. |
* handle<> y(borrowed(x)) presumes that *x is borrowed and thus increments its reference count. |
| Line 16: | Line 13: |
| * handle<> y(x), where x is not the result of borrowed, presumes that someone has already incremented the reference count on *x for us. |
* handle<> y(x), where x is not the result of borrowed, presumes that someone has already incremented the reference count on *x for us. |
| Line 20: | Line 15: |
| * you can combine borrowed and null_ok in any order, so | * you can combine borrowed and null_ok in any order, so the following are equivalent: |
| Line 22: | Line 17: |
| handle<> y(borrowed(null_ok(x))) and handle<> y(null_ok(borrowed(x))) are equivalent. |
* handle<> y(borrowed(null_ok(x))) * handle<> y(null_ok(borrowed(x))) |
| Line 32: | Line 22: |
| * an object can't be constructed from a raw PyObject* because there's no information in that type about whether the refcount has been incremented for this additional reference |
* an object can't be constructed from a raw PyObject* because there's no information in that type about whether the refcount has been incremented for this additional reference |
| Line 36: | Line 24: |
| * an object can only be constructed from a handle<>. Other interfaces are not for public consumption and thus not documented. Use at your own peril. |
* an object can only be constructed from a handle<>. Other interfaces are not for public consumption and thus not documented. Use at your own peril. |
| Line 40: | Line 26: |
| * an instance of object always "points to" something (maybe None). If the constructor argument (handle) is NULL, an exception will be thrown. |
* an instance of object always "points to" something (maybe None). If the constructor argument (handle) is NULL, an exception will be thrown. |
David Abrahams' Guidelines (republished with permission from http://mail.python.org/pipermail/cplusplus-sig/2008-October/013895.html):
- handle, essentially a smart pointer. Use when necessary.
a handle<> can be NULL, and maintains a reference count on the object it points to
handle<> y(null_ok(x)) allows y to become NULL
handle<> y(x), where x is not the result of null_ok, never results in a NULL y. An exception will be thrown if x is NULL
handle<> y(borrowed(x)) presumes that *x is borrowed and thus increments its reference count.
handle<> y(x), where x is not the result of borrowed, presumes that someone has already incremented the reference count on *x for us.
- you can combine borrowed and null_ok in any order, so the following are equivalent:
handle<> y(borrowed(null_ok(x)))
handle<> y(null_ok(borrowed(x)))
- object, a higher-level notion. Use wherever possible.
an object can't be constructed from a raw PyObject* because there's no information in that type about whether the refcount has been incremented for this additional reference
an object can only be constructed from a handle<>. Other interfaces are not for public consumption and thus not documented. Use at your own peril.
- an instance of object always "points to" something (maybe None). If the constructor argument (handle) is NULL, an exception will be thrown.
You should also always give the handle<> a name instead of making it a temporary for the same reasons as cited in Peter Dimov's guideline: "Smart Pointer Best Practices"