[Xapian-tickets] [Xapian] #554: Document using operator new and delete for implementing clone() (was: Complement clone() method with destroy())

[Xapian]

#554: Document using operator new and delete for implementing clone()
---------------------------+------------------------------------------------
 Reporter:  olly           |       Owner:  olly    
     Type:  enhancement    |      Status:  assigned
 Priority:  normal         |   Milestone:  1.3.0   
Component:  Documentation  |     Version:          
 Severity:  normal         |    Keywords:          
Blockedby:                 |    Platform:  All     
 Blocking:                 |  
---------------------------+------------------------------------------------
Changes (by olly):

  * status:  new => assigned
  * component:  Library API => Documentation


Old description:

> Currently methods like {{{MatchSpy::clone()}}} return an object which has
> to be deallocatable with {{{delete}}}.  If we added a virtual method:
>
> {{{
> #!cpp
> virtual void
> MatchSpy::destroy()
> {
>     delete this;
> }
> }}}
>
> Then instead of:
>
> {{{
> #!cpp
> delete matchspy;
> }}}
>
> Xapian could use:
>
> {{{
> #!cpp
> matchspy->destroy();
> }}}
>
> And then subclasses of {{{MatchSpy}}} could allocate themselves in other
> ways in {{{clone()}}} and provide the corresponding code to deallocate
> the object in {{{destroy()}}}.
>
> This might make it feasible to implement {{{MatchSpy::clone()}}} in the
> bindings.
>
> Marking for 1.3.0 for now.

New description:

 Methods like {{{MatchSpy::clone()}}} return an object which has to
 be deallocatable with {{{delete}}}.  If you define {{{operator new}}} and
 {{{operator delete}}} for your subclass then you can actually allocate
 objects in your implementation of the {{{clone()}}} method as you want and
 then handle deallocation appropriately via {{{operator delete}}}.  See the
 first comment for example code.

 This might make it feasible to implement {{{MatchSpy::clone()}}} in
 the bindings.

 ----

 ''Original summary and description:''

 = Complement clone() method with destroy() =

 Currently methods like {{{MatchSpy::clone()}}} return an object which has
 to be deallocatable with {{{delete}}}.  If we added a virtual method:

 {{{
 #!cpp
 virtual void
 MatchSpy::destroy()
 {
     delete this;
 }
 }}}

 Then instead of:

 {{{
 #!cpp
 delete matchspy;
 }}}

 Xapian could use:

 {{{
 #!cpp
 matchspy->destroy();
 }}}

 And then subclasses of {{{MatchSpy}}} could allocate themselves in other
 ways in {{{clone()}}} and provide the corresponding code to deallocate the
 object in {{{destroy()}}}.

 This might make it feasible to implement {{{MatchSpy::clone()}}} in the
 bindings.

 Marking for 1.3.0 for now.

--

Comment:

 So that means we need to document this technique somewhere appropriate (so
 updating summary and description), and link to this from the notes in the
 doxygen comments such as:

 > Note that the returned object will be deallocated by Xapian after use
 > with "delete".  It must therefore have been allocated with "new".

 And then implement {{{MatchSpy::clone()}}} etc in the bindings.

-- 
Ticket URL: <http://trac.xapian.org/ticket/554#comment:2>
Xapian <http://xapian.org/>
Xapian