You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@qpid.apache.org by Paul Colby <pa...@colby.id.au> on 2011/02/06 03:30:06 UTC
Renaming some messaging API member functions
Hi all,
As part of the PHP binding I'm working on, I need to rename (or
discard) a couple member functions from the existing C++ messaging API
(this is to work around a specific SWIG / PHP limitation - see
https://sourceforge.net/tracker/?func=detail&aid=3168531&group_id=1645&atid=101645
for more info).
The methods affected are:
* qpid::messaging::Receiver::fetch
* qpid::messaging::Receiver::get
* qpid::messaging::Session::nextReceiver
In all three cases, the problem is that there exists two overloaded
versions of the function - one that takes an object reference, and
returns a bool result, while the other returns an object and throws an
exception on errors (I'm sure you're all familiar with the differences
between those overloads).
Anyway, due to the SWIG / PHP limitation mentioned above, we need to
rename one of each overloaded pair of methods in the generated PHP
wrapper.
So, for example, we might rename the "throwing" version of
nextReceiver such that we end up with the following (pseudo) methods
in PHP:
bool Session::nextReceiver(Receiver &, Duration) throws();
Receiver Session::nextReceiverThrows(Duration) throws(NoMessageAvailable);
(that's how they could look just to PHP scripts - I'm not talking
about changing anything in the C++ API itself).
So, we need to decide which overloads to rename, and how.
The top level options are:
1. we rename just one of each pair, such as the nextReceiverThrows
example above, keeping one of the overloads with the existing method
name.
2. we rename both overloads, for example nextReveiverBool and
nextReceiverThrows.
3. we "ignore" one of the overloads, meaning that one of each pair of
overloaded methods will simply not exist in the PHP binding.
Personally, I prefer option 1 - just renaming one of each overloaded
pair of member functions (though I don't mind option 3 either).
Assuming we go with 1 (or 3), we would then need to decide: will we
rename (or ignore) the "throwing" versions, or the bool-return
versions (we should, IMO, be consistent for all three problematic
overloads).
Personally, I think we should rename the bool-return versions, because:
a. I prefer using the throwing versions, so would prefer to keep their
current method names the same; and
b. all of the messaging examples (that I've looked at so far) use the
throwing versions, so by keeping those method names unchanged, the PHP
examples can most-closely relfect the official cpp examples.
Also, assuming we agreed to rename the bool-return versions (or the
throwing versions, for that matter), then we'd need to choose the new
names. Some examples I can think of:
* getBool, fetchBool, nextReceiverBool
* getIfAny, fetchIfAny, nextIfAny
* getMessage, fetchMessage, next
I'm not really sold on any of those suggestions though... hopefully
someone will have some better ideas :)
Thoughts? Opinions? :)
Paul.
----
http://colby.id.au
---------------------------------------------------------------------
Apache Qpid - AMQP Messaging Implementation
Project: http://qpid.apache.org
Use/Interact: mailto:dev-subscribe@qpid.apache.org
Re: Renaming some messaging API member functions
Posted by Rajith Attapattu <ra...@gmail.com>.
I think this conversation is probably a good indication that we need to
perhaps look at the API again and think,
1) How could we structure the base client written in "C++" ( or "C" if we
take that route) that would make language bindings more easy to manage.
2) What are the methods/patterns that we are going to advertise as the core
"API".
3) How much leeway are we going to allow each language binding to offer
language specific idioms, either as value additions or as workarounds to
problems cause by the "impedance mismatch" btw various programming
languages.
We need to provide our user community a consistent message about what we are
planning around the API.
However in order to do that, we ourselves needs to agree and understand what
we want to offer.
Maybe we could start with item #2 and then look at item # 1.
That way we might be able to get a reasonable idea about item #3.
And then perhaps we can iterate through this cycle a few times to get to a
reasonable understanding and then document it.
Thoughts ?
Regards,
Rajith
On Mon, Feb 7, 2011 at 10:50 AM, Alan Conway <ac...@redhat.com> wrote:
> On 02/05/2011 09:30 PM, Paul Colby wrote:
>
>> Hi all,
>>
>> As part of the PHP binding I'm working on, I need to rename (or
>> discard) a couple member functions from the existing C++ messaging API
>> (this is to work around a specific SWIG / PHP limitation - see
>>
>> https://sourceforge.net/tracker/?func=detail&aid=3168531&group_id=1645&atid=101645
>> for more info).
>>
>> The methods affected are:
>> * qpid::messaging::Receiver::fetch
>> * qpid::messaging::Receiver::get
>> * qpid::messaging::Session::nextReceiver
>>
>> In all three cases, the problem is that there exists two overloaded
>> versions of the function - one that takes an object reference, and
>> returns a bool result, while the other returns an object and throws an
>> exception on errors (I'm sure you're all familiar with the differences
>> between those overloads).
>>
>> Anyway, due to the SWIG / PHP limitation mentioned above, we need to
>> rename one of each overloaded pair of methods in the generated PHP
>> wrapper.
>>
>> So, for example, we might rename the "throwing" version of
>> nextReceiver such that we end up with the following (pseudo) methods
>> in PHP:
>>
>> bool Session::nextReceiver(Receiver&, Duration) throws();
>> Receiver Session::nextReceiverThrows(Duration) throws(NoMessageAvailable);
>>
>> (that's how they could look just to PHP scripts - I'm not talking
>> about changing anything in the C++ API itself).
>>
>> So, we need to decide which overloads to rename, and how.
>>
>> The top level options are:
>> 1. we rename just one of each pair, such as the nextReceiverThrows
>> example above, keeping one of the overloads with the existing method
>> name.
>> 2. we rename both overloads, for example nextReveiverBool and
>> nextReceiverThrows.
>> 3. we "ignore" one of the overloads, meaning that one of each pair of
>> overloaded methods will simply not exist in the PHP binding.
>>
>> Personally, I prefer option 1 - just renaming one of each overloaded
>> pair of member functions (though I don't mind option 3 either).
>>
>> Assuming we go with 1 (or 3), we would then need to decide: will we
>> rename (or ignore) the "throwing" versions, or the bool-return
>> versions (we should, IMO, be consistent for all three problematic
>> overloads).
>>
>> Personally, I think we should rename the bool-return versions, because:
>> a. I prefer using the throwing versions, so would prefer to keep their
>> current method names the same; and
>> b. all of the messaging examples (that I've looked at so far) use the
>> throwing versions, so by keeping those method names unchanged, the PHP
>> examples can most-closely relfect the official cpp examples.
>>
>> Also, assuming we agreed to rename the bool-return versions (or the
>> throwing versions, for that matter), then we'd need to choose the new
>> names. Some examples I can think of:
>>
>> * getBool, fetchBool, nextReceiverBool
>> * getIfAny, fetchIfAny, nextIfAny
>> * getMessage, fetchMessage, next
>>
>> I'm not really sold on any of those suggestions though... hopefully
>> someone will have some better ideas :)
>>
>> Thoughts? Opinions? :)
>>
>
> I like getIfAny, some other alternatives: getNoThrow, tryGet. I agree with
> using the "decorated" name for the nothrow variant, since it acts as a
> reminder that you do have to check the return value.
>
> ---------------------------------------------------------------------
> Apache Qpid - AMQP Messaging Implementation
> Project: http://qpid.apache.org
> Use/Interact: mailto:dev-subscribe@qpid.apache.org
>
>
--
Regards,
Rajith Attapattu
Red Hat
http://rajith.2rlabs.com/
Re: Renaming some messaging API member functions
Posted by Alan Conway <ac...@redhat.com>.
On 02/05/2011 09:30 PM, Paul Colby wrote:
> Hi all,
>
> As part of the PHP binding I'm working on, I need to rename (or
> discard) a couple member functions from the existing C++ messaging API
> (this is to work around a specific SWIG / PHP limitation - see
> https://sourceforge.net/tracker/?func=detail&aid=3168531&group_id=1645&atid=101645
> for more info).
>
> The methods affected are:
> * qpid::messaging::Receiver::fetch
> * qpid::messaging::Receiver::get
> * qpid::messaging::Session::nextReceiver
>
> In all three cases, the problem is that there exists two overloaded
> versions of the function - one that takes an object reference, and
> returns a bool result, while the other returns an object and throws an
> exception on errors (I'm sure you're all familiar with the differences
> between those overloads).
>
> Anyway, due to the SWIG / PHP limitation mentioned above, we need to
> rename one of each overloaded pair of methods in the generated PHP
> wrapper.
>
> So, for example, we might rename the "throwing" version of
> nextReceiver such that we end up with the following (pseudo) methods
> in PHP:
>
> bool Session::nextReceiver(Receiver&, Duration) throws();
> Receiver Session::nextReceiverThrows(Duration) throws(NoMessageAvailable);
>
> (that's how they could look just to PHP scripts - I'm not talking
> about changing anything in the C++ API itself).
>
> So, we need to decide which overloads to rename, and how.
>
> The top level options are:
> 1. we rename just one of each pair, such as the nextReceiverThrows
> example above, keeping one of the overloads with the existing method
> name.
> 2. we rename both overloads, for example nextReveiverBool and
> nextReceiverThrows.
> 3. we "ignore" one of the overloads, meaning that one of each pair of
> overloaded methods will simply not exist in the PHP binding.
>
> Personally, I prefer option 1 - just renaming one of each overloaded
> pair of member functions (though I don't mind option 3 either).
>
> Assuming we go with 1 (or 3), we would then need to decide: will we
> rename (or ignore) the "throwing" versions, or the bool-return
> versions (we should, IMO, be consistent for all three problematic
> overloads).
>
> Personally, I think we should rename the bool-return versions, because:
> a. I prefer using the throwing versions, so would prefer to keep their
> current method names the same; and
> b. all of the messaging examples (that I've looked at so far) use the
> throwing versions, so by keeping those method names unchanged, the PHP
> examples can most-closely relfect the official cpp examples.
>
> Also, assuming we agreed to rename the bool-return versions (or the
> throwing versions, for that matter), then we'd need to choose the new
> names. Some examples I can think of:
>
> * getBool, fetchBool, nextReceiverBool
> * getIfAny, fetchIfAny, nextIfAny
> * getMessage, fetchMessage, next
>
> I'm not really sold on any of those suggestions though... hopefully
> someone will have some better ideas :)
>
> Thoughts? Opinions? :)
I like getIfAny, some other alternatives: getNoThrow, tryGet. I agree with using
the "decorated" name for the nothrow variant, since it acts as a reminder that
you do have to check the return value.
---------------------------------------------------------------------
Apache Qpid - AMQP Messaging Implementation
Project: http://qpid.apache.org
Use/Interact: mailto:dev-subscribe@qpid.apache.org