Re: Time to Document Callbacks

On Oct 27, 2009, at 3:24 PM, Tim Bunce wrote:

> The "simplest thing that could possibly work" is probably:
>
>    $dbh->{Callbacks} = {
>        method_foo => sub { ... },
>        method_bar => sub { ... },
>        ChildCallbacks => {
>            method_foo => sub { ... },
>            method_bar => sub { ... },
>        }
>    }
>
> so the code that creates a child handle can just check for
> ChildCallbacks on the parent handle and set those as the Callbacks for
> the new handle.

That looks nice. Are STHs the only things that are "children"?

>> Yes, I saw that in our
>> [exchange](http://markmail.org/message/m2lr3n74nluh52jn) in 2005.  
>> What
>> would it take to make this happen?
>
> Let's get Callbacks and ChildCallbacks documented first.

Okay. Maybe it'll be done when I wake up in the morning? ;-P

>> Oh, that kind of callback. I'd love to see attributes to prepare  
>> passed on
>> to the sth. It makes perfect sense to me. I note that you thought  
>> in 2005
>> that it wouldn't happen before DBI2, but since that's probably  
>> another 5
>> years away at this rate…
>
> [Tangental observation: NYTProf v3 is nearly done... :-]

Oh, nice. Does that mean you'll have more time for the DBI?

> ChildCallbacks seems like the way to go. Simple, effective, and easy  
> to
> implement.

Yeah, looks pretty nice. Would we also be able to pass them to prepare 
()?

> Yes, it's one of the two fundamental problems with the Callback  
> approach.
> The other being that multiple callbacks for the same method can't
> co-exist on the same handle.  Both need to be documented.

Right. The driver-specific issue is troubling, frankly.

>> Well, and tie is pretty hackish IMHO.
>
> The implementation (and performance) may not be great, but the concept
> of tie (values vs containers) is good. Overloading would also work.
> Either way it should be wrapped up in a nice interface.

Such as?

>> But let me cite another example. In our prior discussions, you
>> [wrote](http://markmail.org/message/dgnpmnzkk4g532lc):
>>
>>> Note that sth callbacks, for example, give you a relatively clean  
>>> way to
>>> set the UTF8 flag on fetched data.
>
> It seemed like a good idea at the time but I recant that now.
> It's workable only for someone who knows what driver and methods  
> will be
> used to fetch data from a given handle. So it's just about okay for
> in-house use but I couldn't recommend it as a general solution.

I'm starting to fail to see the point of callbacks aside from connect 
(). :-(

> It would need post-call callbacks. How they get called would depend on
> what works most efficiently and reasonably elegantly. I'd guess that  
> the
> values being returned would be in @_ (as aliases) and $_ would contain
> the handle.

Hrm. That'd be inconsistent with the way precallbacks work.

> Lots of people have published DBIx::* modules and I'd guess many could
> think of interesting uses for Callbacks. End users couldn't use more
> than one such module at a time if they want to add callbacks on the  
> same
> methods.

Fair point.

> On the other hand I'm happy to await the cowpaths.

Yeah, I think it's useful to wait to see what the demand looks like.

> My suggestion (in http://markmail.org/message/dgnpmnzkk4g532lc) in  
> 2005
> still seems reaonable:
>
> $h->callback_add( $method_name, $code_ref [, $pre_or_post ]);
> $h->callback_delete( $method_name, $code_ref [, $pre_or_post ]);

I'd rather they were add_callback and delete_callback (or  
del_callback). But the method name isn't that important, and the API  
looks okay to me.

> except that $h->{Callbacks} = { name => $code, ... } is great for
> setting up multiple callbacks in one go. So perhaps we'd have:
>
> $h->add_callbacks( { name => $code, ... } );
>
> and make $h->{Callbacks} = ... automatically fire the add_callbacks
> method.

Even better.

> We'd still need a way to express pre-vs-post-call, so perhaps
> allow
>
> $h->add_callbacks( { name => [ $pre_code, $post_code ], ... } );
>
> In which case we've ended up back at the current (proposed) data
> structure but with a method to provide some abstraction.
> In which case adding the method can wait until we need to support
> multiple callbacks :)

Works for me.

Best,

David