|
»
« Return to Thread: libusb future
Re: libusb future
by Daniel Drake
::
Rate this Message:
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?
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.
> I also
> don't like "intr" and "devh".
intr --> interrupt, that's easy.
devh --> dev_handle?
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.
> And, since I'm getting picky,
> fpusb_dev_get_descriptor implies that it will gets any kind of
> descriptor (rather than just the device descriptor), and
> fpusb_dev_get_config doesn't mention the word "descriptor".
Picky is good. I did throw in those functions rather quickly, will give
them more sensible names.
> You don't have an API to fetch string descriptors yet, do you?
Not yet.
> I'm torn about how to handle the naming of sync vs async routines, even
> in my own code. Although "libusb_submit_bulk_urb" accurately reflects
> what the routine does, in fact the libusb user doesn't know about or
> think in terms of URBs. That is an implementation detail.
>
> I could be talked into this:
> libusb_submit_bulk_transfer
> libusb_submit_bulk_transfer_async
> or this:
> libusb_submit_bulk_transfer_and_wait
> libusb_submit_bulk_transfer
>
Will give that some more thought. For the sync case I am quite fond of
the style of simplistic synchrnous function names used in both
libusb-0.1 and in the kernel itself e.g. usb_control_msg(). Simple
function names for simple users of the library :)
*thinks*
Any comments on:
libusb_bulk_transfer()
libusb_async_bulk_transfer()
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.
(this is subject to change based on further thinking on my part or
influential discussions like this one)
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?
Thanks for the feedback - much appreciated.
Daniel
-------------------------------------------------------------------------
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
> 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?
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.
> I also
> don't like "intr" and "devh".
intr --> interrupt, that's easy.
devh --> dev_handle?
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.
> And, since I'm getting picky,
> fpusb_dev_get_descriptor implies that it will gets any kind of
> descriptor (rather than just the device descriptor), and
> fpusb_dev_get_config doesn't mention the word "descriptor".
Picky is good. I did throw in those functions rather quickly, will give
them more sensible names.
> You don't have an API to fetch string descriptors yet, do you?
Not yet.
> I'm torn about how to handle the naming of sync vs async routines, even
> in my own code. Although "libusb_submit_bulk_urb" accurately reflects
> what the routine does, in fact the libusb user doesn't know about or
> think in terms of URBs. That is an implementation detail.
>
> I could be talked into this:
> libusb_submit_bulk_transfer
> libusb_submit_bulk_transfer_async
> or this:
> libusb_submit_bulk_transfer_and_wait
> libusb_submit_bulk_transfer
>
Will give that some more thought. For the sync case I am quite fond of
the style of simplistic synchrnous function names used in both
libusb-0.1 and in the kernel itself e.g. usb_control_msg(). Simple
function names for simple users of the library :)
*thinks*
Any comments on:
libusb_bulk_transfer()
libusb_async_bulk_transfer()
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.
(this is subject to change based on further thinking on my part or
influential discussions like this one)
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?
Thanks for the feedback - much appreciated.
Daniel
-------------------------------------------------------------------------
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 |
