|
»
« Return to Thread: libusb future
Re: libusb future
by Tim Roberts
::
Rate this Message:
Daniel Drake wrote:
> Tim Roberts wrote:
>
>> Well, certainly the "poll" routines do not explain themselves.
>>
>
> I'm not sure how I can make these ones better. Use the word "iterate"
> instead of poll?
>
Describe what they actually DO in a sentence.
"fpusb_wait_request_complete"? "fpusb_wait_for_queue_empty"? I tried
to trace through the code in io.c a little, but since all the return
types are int, I'm not sure what's actually being passed around.
> Given that this function will only be called by async users (i.e.
> advanced users) the naming here probably isn't too important -- they
> will have to read the docs to understand how to properly integrate
> asynchronous I/O into their application.
>
History shows that what they will ACTUALLY do is post to this mailing
list saying "I want to do asynchronous USB I/O please help me send me
code it should be easy Im in a hurry thx."
> The main reason for these abbreviations is that I felt that function
> names were becoming too long. Some of these are going to be called a lot
> by applications. I guess there's a balance to be met but I guess I may
> have gone too far on the shortening approach.
>
In my opinion, yes. Most programmers' editors have auto word completion
now, so typing long function names is not the burden it once was. The
benefit is that your code reads like a prose paragraph.
> Any comments on:
> libusb_bulk_transfer()
> libusb_async_bulk_transfer()
>
I'd be fine with that.
> One other thing I am slightly torn about is naming functions in terms of
> the 'thing' that they operate on (or return). For example, libusb-0.1
> does usb_open() and usb_close() but at the moment in fpusb I do
> fpusb_devh_open() and fpusb_devh_close() because they deal with device
> handles. Then there's fpusb_devh_claim_intf() etc.
>
Yes, it's a difficult balance. One thing to remember is that EVERYTHING
uses a device handle. Because of that, I'm not sure it's really
necessary to mention it in the API. At the very least, I don't think
there is any potential confusion between "device" and "device handle"
here, and "dev" certainly reads better than "devh".
> But then there are other functions that I don't name like that because
> it either doesn't seem appropriate or just doesn't seem right. For
> example the transfer functions. Do you have any opinions on naming
> styles here and where the balance should be?
>
The name should reflect what is being done. A bulk transfer isn't
really being "done" to the device handle, although it is certainly a
critical part of doing it.
One example of taking this to an extreme is Microsoft's new driver
model, KMDF. Underneath, it's written in C++, but the official API is
in C. The API name always includes the class where the method would
have been. So, the wrapper for IoCompleteRequest is WdfRequestComplete
(which works on a WDFREQUEST object). Instead of IoCallDriver to
submit a request, you use WdfIoTargetSendIoctlSynchronously, because the
request gets sent to a WDFIOTARGET object.
KMDF takes things to the extreme. Your fingers do get a bit tired of
typing WdfIoTargetSendInternalIoctlOthersSynchronously,
WdfIoTartgetFormatRequestForInternalIoctlOthers,
WdfRequestRetrieveUnsafeUserInputBuffer,
WdfRequestProbeAndLockUserBufferForRead, and
WdfDeviceInitRegisterPnpStateChangeCallback, but it's also very easy to
guess the name of the API you need at any given point, and the code does
read pretty well.
> -------------------------------------------------------------------------
> This SF.net email is sponsored by: Microsoft
> Defy all challenges. Microsoft(R) Visual Studio 2005.
> http://clk.atdmt.com/MRT/go/vse0120000070mrt/direct/01/
>
Wow! THAT surprises me.
--
Tim Roberts, timr@...
Providenza & Boekelheide, Inc.
-------------------------------------------------------------------------
This SF.net email is sponsored by: Microsoft
Defy all challenges. Microsoft(R) Visual Studio 2005.
http://clk.atdmt.com/MRT/go/vse0120000070mrt/direct/01/
_______________________________________________
Libusb-devel mailing list
Libusb-devel@...
https://lists.sourceforge.net/lists/listinfo/libusb-devel
> Tim Roberts wrote:
>
>> Well, certainly the "poll" routines do not explain themselves.
>>
>
> I'm not sure how I can make these ones better. Use the word "iterate"
> instead of poll?
>
Describe what they actually DO in a sentence.
"fpusb_wait_request_complete"? "fpusb_wait_for_queue_empty"? I tried
to trace through the code in io.c a little, but since all the return
types are int, I'm not sure what's actually being passed around.
> Given that this function will only be called by async users (i.e.
> advanced users) the naming here probably isn't too important -- they
> will have to read the docs to understand how to properly integrate
> asynchronous I/O into their application.
>
History shows that what they will ACTUALLY do is post to this mailing
list saying "I want to do asynchronous USB I/O please help me send me
code it should be easy Im in a hurry thx."
> The main reason for these abbreviations is that I felt that function
> names were becoming too long. Some of these are going to be called a lot
> by applications. I guess there's a balance to be met but I guess I may
> have gone too far on the shortening approach.
>
In my opinion, yes. Most programmers' editors have auto word completion
now, so typing long function names is not the burden it once was. The
benefit is that your code reads like a prose paragraph.
> Any comments on:
> libusb_bulk_transfer()
> libusb_async_bulk_transfer()
>
I'd be fine with that.
> One other thing I am slightly torn about is naming functions in terms of
> the 'thing' that they operate on (or return). For example, libusb-0.1
> does usb_open() and usb_close() but at the moment in fpusb I do
> fpusb_devh_open() and fpusb_devh_close() because they deal with device
> handles. Then there's fpusb_devh_claim_intf() etc.
>
Yes, it's a difficult balance. One thing to remember is that EVERYTHING
uses a device handle. Because of that, I'm not sure it's really
necessary to mention it in the API. At the very least, I don't think
there is any potential confusion between "device" and "device handle"
here, and "dev" certainly reads better than "devh".
> But then there are other functions that I don't name like that because
> it either doesn't seem appropriate or just doesn't seem right. For
> example the transfer functions. Do you have any opinions on naming
> styles here and where the balance should be?
>
The name should reflect what is being done. A bulk transfer isn't
really being "done" to the device handle, although it is certainly a
critical part of doing it.
One example of taking this to an extreme is Microsoft's new driver
model, KMDF. Underneath, it's written in C++, but the official API is
in C. The API name always includes the class where the method would
have been. So, the wrapper for IoCompleteRequest is WdfRequestComplete
(which works on a WDFREQUEST object). Instead of IoCallDriver to
submit a request, you use WdfIoTargetSendIoctlSynchronously, because the
request gets sent to a WDFIOTARGET object.
KMDF takes things to the extreme. Your fingers do get a bit tired of
typing WdfIoTargetSendInternalIoctlOthersSynchronously,
WdfIoTartgetFormatRequestForInternalIoctlOthers,
WdfRequestRetrieveUnsafeUserInputBuffer,
WdfRequestProbeAndLockUserBufferForRead, and
WdfDeviceInitRegisterPnpStateChangeCallback, but it's also very easy to
guess the name of the API you need at any given point, and the code does
read pretty well.
> -------------------------------------------------------------------------
> This SF.net email is sponsored by: Microsoft
> Defy all challenges. Microsoft(R) Visual Studio 2005.
> http://clk.atdmt.com/MRT/go/vse0120000070mrt/direct/01/
>
Wow! THAT surprises me.
--
Tim Roberts, timr@...
Providenza & Boekelheide, Inc.
-------------------------------------------------------------------------
This SF.net email is sponsored by: Microsoft
Defy all challenges. Microsoft(R) Visual Studio 2005.
http://clk.atdmt.com/MRT/go/vse0120000070mrt/direct/01/
_______________________________________________
Libusb-devel mailing list
Libusb-devel@...
https://lists.sourceforge.net/lists/listinfo/libusb-devel
« Return to Thread: libusb future
| Free embeddable forum powered by Nabble | Forum Help |
