Re: GIO API review
Am Donnerstag, den 13.12.2007, 17:31 +0100 schrieb Alexander Larsson:
typedef enum {
G_FILE_QUERY_INFO_FLAGS_NONE = 0,
G_FILE_QUERY_INFO_NOFOLLOW_SYMLINKS = (10)
}
vs
typedef enum {
G_FILE_MONITOR_FLAGS_NONE = 0,
G_FILE_MONITOR_FLAGS_MONITOR_MOUNTS = (10)
} GFileMonitorFlags;
What do people think is the best approach here?
To my knowledge GTK+ would call them:
typedef enum { /* flags */
G_FILE_QUERY_INFO_NONE = 0,
G_FILE_QUERY_INFO_NOFOLLOW_SYMLINKS = (10)
} GFileQueryInfoFlags;
and
typedef enum { /* flags */
G_FILE_MONITOR_NONE = 0,
G_FILE_MONITOR_MONITOR_MOUNTS = (10)
} GFileMonitorFlags;
A problem is the doublicate monitor, so the second value should be
something like:
G_FILE_MONITOR_WATCH_MOUNTS
Ciao,
Mathias
--
Mathias Hasselmann [EMAIL PROTECTED]
http://taschenorakel.de/
signature.asc
Description: Dies ist ein digital signierter Nachrichtenteil
___
gtk-devel-list mailing list
gtk-devel-list@gnome.org
http://mail.gnome.org/mailman/listinfo/gtk-devel-list
Re: GIO API review
On Fri, 2007-12-14 at 15:49 +0100, Sven Herzberg wrote: Alexander Larsson wrote: I'm for gio/gio.h. It seems more inline with all our other libraries. Only gobject does the glib-object.h thing. Shouldn't gio.h be enough? This would really drop 4 letters that every gio-using developer had to type and which are really redundant. I really don't like this foobar/foobar.h style because it forces developers just to type more than they IMHO should. I'm not wedded to any particular version. gio.h may conflict with another include dir namespace, but since its just one file that is probably safe. The double dir version seems more commonly used in general though. Other peoples opinions? ___ gtk-devel-list mailing list gtk-devel-list@gnome.org http://mail.gnome.org/mailman/listinfo/gtk-devel-list
Re: GIO API review
On Thu, 2007-12-13 at 19:45 +0100, Richard Hult wrote: Mikael Hallendal wrote: I just wanted to clarify though that it's not so much for technical reasons I suggested that we namespace a bit more carefully. For example, if we plan to never use the GAsync infrastructure for anything other than GIO there is a point to put it under the GIO namespace as it shows where it belongs and what part of GLib it is used for. It also means we can have GFooAsync later without the two getting confused with each other. The same for GCancellable and similar namespaces. And in this particular example, g_async_*, there is already a clash: we have g_async_queue_* right now, which is unrelated of course. A slightly longer name to avoid confusion here would be a fairly low price to pay in terms of typing. And I don't agree that it would be harder to read code with slightly longer names, on the contrary, at least when the added part is reasonably long. If it's clear what subsystem the function is related to, the developer doesn't have to stop to think. I don't think this is really a conflict. The type name is GAsyncResult, not GAsync. I don't think it is a problem to have different kinds of types that start with GAsync, and its not like they are totally unrelated (they are both about async tings). Its a similar situation to e.g. GtkIconTheme and GtkIconView. ___ gtk-devel-list mailing list gtk-devel-list@gnome.org http://mail.gnome.org/mailman/listinfo/gtk-devel-list
Re: GIO API review
On Thu, 2007-12-13 at 19:19 +0100, Mikael Hallendal wrote: For example, if we plan to never use the GAsync infrastructure for anything other than GIO there is a point to put it under the GIO namespace as it shows where it belongs and what part of GLib it is used for. It also means we can have GFooAsync later without the two getting confused with each other. The same for GCancellable and similar namespaces. Eh, why would we not use these for anything other than GIO. They were specifically designed to be generic and to be used by other APIs. Anything that has cancellable operations (things like libsoup or whateveR) should use GCancellable. And GAsyncResult is a very powerful pattern for doing async operation that all libraries with async operations should take advantage of. And things like GInputStream/GOutputStream are obviously useful for other things, like loading pixbufs from any kind of source by implementing GInputStream. Without any namespace other than g_ it gives the idea that these frameworks are used for more than one subsystem (at least to me). Which is why they are good names, as this is the intention. GAsync, GCancellable, g_push, g_pop, g_loadable, g_simple are examples of namespaces that would benefit from being under the GIO name spaced as they are too generic by themselves. A few of these are unnecessary taking up namespace, and I'm working on fixing these. ___ gtk-devel-list mailing list gtk-devel-list@gnome.org http://mail.gnome.org/mailman/listinfo/gtk-devel-list
Re: GIO API review
14 dec 2007 kl. 09.27 skrev Alexander Larsson: Hi, On Thu, 2007-12-13 at 19:19 +0100, Mikael Hallendal wrote: For example, if we plan to never use the GAsync infrastructure for anything other than GIO there is a point to put it under the GIO namespace as it shows where it belongs and what part of GLib it is used for. It also means we can have GFooAsync later without the two getting confused with each other. The same for GCancellable and similar namespaces. Eh, why would we not use these for anything other than GIO. They were specifically designed to be generic and to be used by other APIs. Please re-read the start of the paragraph you quoted. If this is the case, all the better. Anything that has cancellable operations (things like libsoup or whateveR) should use GCancellable. Perfect! Without any namespace other than g_ it gives the idea that these frameworks are used for more than one subsystem (at least to me). Which is why they are good names, as this is the intention. Then we agree. GAsync, GCancellable, g_push, g_pop, g_loadable, g_simple are examples of namespaces that would benefit from being under the GIO name spaced as they are too generic by themselves. A few of these are unnecessary taking up namespace, and I'm working on fixing these. And here too. :) Cheers, Mikael Hallendal -- Imendio AB, http://www.imendio.com ___ gtk-devel-list mailing list gtk-devel-list@gnome.org http://mail.gnome.org/mailman/listinfo/gtk-devel-list
Re: GIO API review
Alexander Larsson wrote: On Thu, 2007-12-13 at 14:50 +0100, Michael Natterer wrote: Alexander Larsson wrote: On Wed, 2007-12-12 at 16:46 +0100, Michael Natterer wrote: Alexander Larsson wrote: On Tue, 2007-12-11 at 17:48 +0100, Michael Natterer wrote: Hey everybody, We've been doing a GIO API review in the last couple of days and here is the list of comments and issues we've come up with: General: It seems GIO allows individual files to be included, this should be avoided like gobject does it: #if !defined (__GLIB_GIO_H_INSIDE__) !defined (GIO_COMPILATION) #error Only gio.h can be included directly. #endif Why? I know gobject does this, but I never understood why. It seems to just make build times longer. Because otherwise you get into the very same typedef and include mess we have in glib and gtk+. It makes it *very* hard to change anything type related in the future. Any addition of a new function that happens to use a new type which was not used in that header before might work fine for the library's build itdelf, but might break the build of applications that include whatever combination of headers. Clear structure of headers and types should never be traded for compile time, we also keep distinct things in distinct .c files. Why would we scatter our typedefs across our libraries, or keep certain includes in headers forever? Ok. I guess this makes sense. I'll do this. Thanks :-) I forgot to mention, gobject has its common header in glib/. I'm not quite sure about this decision and I'm also not sure if saying #include glib-io.h or #include gio/gio.h is the more natural thing to do... Just for consideration. I'm for gio/gio.h. It seems more inline with all our other libraries. Only gobject does the glib-object.h thing. Shouldn't gio.h be enough? This would really drop 4 letters that every gio-using developer had to type and which are really redundant. I really don't like this foobar/foobar.h style because it forces developers just to type more than they IMHO should. Regards, Sven ___ gtk-devel-list mailing list gtk-devel-list@gnome.org http://mail.gnome.org/mailman/listinfo/gtk-devel-list
Re: GIO API review
On Dec 14, 2007 3:27 AM, Alexander Larsson [EMAIL PROTECTED] wrote: Anything that has cancellable operations (things like libsoup or whateveR) should use GCancellable. And GAsyncResult is a very powerful pattern for doing async operation that all libraries with async operations should take advantage of. And things like GInputStream/GOutputStream are obviously useful for other things, like loading pixbufs from any kind of source by implementing GInputStream. It would probably be good to emphasize thie generic applicability in the docs and give some examples for the pattern. ___ gtk-devel-list mailing list gtk-devel-list@gnome.org http://mail.gnome.org/mailman/listinfo/gtk-devel-list
Re: GIO API review
On Wed, 2007-12-12 at 16:53 +0100, Murray Cumming wrote: On Wed, 2007-12-12 at 16:37 +0100, Alexander Larsson wrote: GAsnc*- GIOAsync* G*Stream - GIOStream* GIcon - GIOIcon G*Icon- GIOIcon* GCancellable - GIOCancellable ... I strongly oppose this. I personally prefer the naming Mitch suggests. I know from the name which sub-library the API belongs to in GLib. I don't think this is something that is all that important when you actually use the API. It certainly isn't so important that its worth (methaphorically) punching you in the face every time you read or write the symbol. If these are are all about IO and/or generally meant to be used together, I would also like them to share some namespace. If glib doesn't do it then I'll probably do it when I wrap them in glibmm. But I love namespaces. If they are likely to be used separately, if they are generally meant to be self-contained then I'd be happy with just g_. They are not only about I/I really. I'd like to think of them as part of the glib module, but for technical reasons (glib doesn't link to gobject) they can't be in libglib.so. Now, some objects are clearly I/O related, but many are just peripherally related to I/O and show up in the API because they are required to express the other interfaces (like, files can have icons, so we need an icon type, but it can't go in libglib, so it must go in libgio). If we add things like GSettings to libgio (to avoid adding yet more .so's) then things look even more weird. GIOSettings? ___ gtk-devel-list mailing list gtk-devel-list@gnome.org http://mail.gnome.org/mailman/listinfo/gtk-devel-list
Re: GIO API review
On Wed, 2007-12-12 at 16:46 +0100, Michael Natterer wrote: Alexander Larsson wrote: On Tue, 2007-12-11 at 17:48 +0100, Michael Natterer wrote: Hey everybody, We've been doing a GIO API review in the last couple of days and here is the list of comments and issues we've come up with: General: It seems GIO allows individual files to be included, this should be avoided like gobject does it: #if !defined (__GLIB_GIO_H_INSIDE__) !defined (GIO_COMPILATION) #error Only gio.h can be included directly. #endif Why? I know gobject does this, but I never understood why. It seems to just make build times longer. Because otherwise you get into the very same typedef and include mess we have in glib and gtk+. It makes it *very* hard to change anything type related in the future. Any addition of a new function that happens to use a new type which was not used in that header before might work fine for the library's build itdelf, but might break the build of applications that include whatever combination of headers. Clear structure of headers and types should never be traded for compile time, we also keep distinct things in distinct .c files. Why would we scatter our typedefs across our libraries, or keep certain includes in headers forever? Ok. I guess this makes sense. I'll do this. I would even argue that it makes most sense to keep all opaque typedefs in one single file and include that from gio.h and from each source file within GIO. This way you can avoid including any headers from headers at all and it makes things so *very* much easier to maintain. We changed all of GIMP to this policy a few years back and never had a single (!!!) problem related to includes ever since. I'm not sure this is all that much cleaner. But if we go with the one global header we can switch to this later as we please. ___ gtk-devel-list mailing list gtk-devel-list@gnome.org http://mail.gnome.org/mailman/listinfo/gtk-devel-list
Re: GIO API review
On Wed, 2007-12-12 at 16:48 +0100, Mikael Hallendal wrote: 12 dec 2007 kl. 14.59 skrev Alexander Larsson: Hi, On Tue, 2007-12-11 at 17:48 +0100, Michael Natterer wrote: A big issue is that GIO wastes namespaces massively: g_app, GAsync, g_buffered, g_cancellable, g_content, g_data, g_desktop, g_directory, g_drive, g_file, g_filename, g_filter, g_icon, g_input, g_io, g_schedule, g_cancel, g_loadable, g_local, g_memory, g_mount, g_native, g_seekable, g_simple, g_themed, g_unix, g_vfs, g_volume, g_win32, g_push, g_pop That's clearly too much and can be reduced. While these are not strictly namespaces (the namespace is g_), they partly clash with g_foos and g_bars we already have, or might need in the future. We stronlgy suggest to use a common g_io/GIO prefix for all functions/types in GIO. GAsnc*- GIOAsync* G*Stream - GIOStream* GIcon - GIOIcon G*Icon- GIOIcon* GCancellable - GIOCancellable ... I strongly oppose this. While gio is a separate library these are all symbols in the glib module, and while it might be a problem at times we can handle any conflict issues (since we control both libs and release them toghether). So, I don't think the problem with this is that bad. I mean, gobject doesn't call its symbols GObjectClosure, g_object_signal, GObjectValue, etc, and this has not been a problem. The big issue is that GIO wastes a lot (31) of namespaces for no purpose. While some might not make sense to put under the GIO namespace (GIOIcon might be one of these, I don't know), the main chunk of them do. The 31 number is a bit high, as a bunch of the listed things are internal only and some we could remove (as discussed in this thread, which is a good thing). Furthermore I don't think that e.g. having a GSimpleAsyncResult class grabs the whole g_simple namespace. However, it is true that there parts of the g_ namespace that are consumed by gio. However, that is true for any addition to glib or gobject too and yet we add names there. Also, even if we used a g_io_ prefix we should avoid name conflicts anyway. It would be very problematic if we had both g_icon and g_io_icon types for instance. There is no actual technical problem with using the g_ namespace in gio (as they ship in the same module we can avoid conflicts), the only danger of having the gio symbols use the g_ namespace is that we fear that this would give naming problems when we later add stuff to glib. Name conflicts would mean we would have to choose other names than what we might want, so we risk having to use worse names later. However, the proposed solution is imho far worse as it involves making all the gio names worse just to protect against the risk of having to use worse name in the future. I deeply disagree with you saying there is no purpose in using the g_ namespace for this. API design is to a very large degree about good naming. And using the g_ namespace leads to better naming: shorter names, no enforcing the io meme on types where it doesn't make sense, and a greater emphasis that these are core glib types that you should use instead of third party APIs. I think my essential problem with this is that gio is for all intents an purposes part of the abstract glib module, just as much as e.g. gobject is. The fact that technical reasons force it into a separate .so should not affect how we reason about it. The types it introduces should be thought of as core glib types. The examples you took from GObject are perfect examples of parts that are a fundamental and big part of the GObject library and got their own namespaces. I'm sure there are a bunch of those in GIO as well, however, we should really consider it several times when introducing new namespaces. Both for future and for people trying to use the library. I just picked any random symbols in gobject. No symbols in libgobject use any prefix other than g_ (all symbols are in the form of g_desciption_of_type). I think this is correct, as its part of the core API of glib, as much as I'd like to think the new libgio APIs are. Having some types in libgio have the g_io_ prefix seems even weirder, then is not even a namespace for a .so file. ___ gtk-devel-list mailing list gtk-devel-list@gnome.org http://mail.gnome.org/mailman/listinfo/gtk-devel-list
Re: Name of the utility library (Was: GIO API review)
On Thu, 2007-12-13 at 12:34 +0100, Mathias Hasselmann wrote: Am Donnerstag, den 13.12.2007, 12:17 +0100 schrieb Alexander Larsson: If we add things like GSettings to libgio (to avoid adding yet more .so's) then things look even more weird. GIOSettings? Off-topic, but random though since we couldn't find a name of the utility .so between libgobject and libgtk yet. What's about libgcore.so? I think the current plan is that the symbols would be in libgio.so, but then we can make the actual modules be separate, with their own .pc file and headers in a separate subdir. I'm not sure I like this, as I don't quite see the point of fragmenting the headers etc like that, but it does make the name of the .so an academic issue, as it hides it behind the .pc file names which is what developers see. ___ gtk-devel-list mailing list gtk-devel-list@gnome.org http://mail.gnome.org/mailman/listinfo/gtk-devel-list
Name of the utility library (Was: GIO API review)
Am Donnerstag, den 13.12.2007, 12:17 +0100 schrieb Alexander Larsson: If we add things like GSettings to libgio (to avoid adding yet more .so's) then things look even more weird. GIOSettings? Off-topic, but random though since we couldn't find a name of the utility .so between libgobject and libgtk yet. What's about libgcore.so? Ciao, Mathias -- Mathias Hasselmann [EMAIL PROTECTED] http://taschenorakel.de/ signature.asc Description: Dies ist ein digital signierter Nachrichtenteil ___ gtk-devel-list mailing list gtk-devel-list@gnome.org http://mail.gnome.org/mailman/listinfo/gtk-devel-list
Re: GIO API review
On Thu, 2007-12-13 at 14:43 +0100, Michael Natterer wrote: Alexander Larsson wrote: It just adds new types and type relations you have to learn, and forces you to remember that you have to cast to some common class to do things like cancelling a directory monitor. It adds nothing useful to the user of the API, it just means you have to learn more and remember more. But we have casts all over the place in gobject/gtk+. And the APIs of both classes is 100% *identical*. You can't seriously argue against a common interface. In this case, having a common base class strikes me almost as a no-brainer. How would you justify having the *exactly* same API twice on two very closely related classes? I would rather argue that having to learn only *one* GMonoitor API is much more obvious and straightforward. The actual implementation details (the fact that there are subclasses at all) could be almost invisible in the public API. - two closely related classes - two identical APIs - common base class *please* :-) I don't think is so important, so sure, lets do this. However, what would the name of the base class be? GMonitor? That strikes me as a bit to generic. GFileSystemMonitor? GChangeMonitor? ___ gtk-devel-list mailing list gtk-devel-list@gnome.org http://mail.gnome.org/mailman/listinfo/gtk-devel-list
Re: GIO API review
Alexander Larsson wrote: On Thu, 2007-12-13 at 14:43 +0100, Michael Natterer wrote: Alexander Larsson wrote: It just adds new types and type relations you have to learn, and forces you to remember that you have to cast to some common class to do things like cancelling a directory monitor. It adds nothing useful to the user of the API, it just means you have to learn more and remember more. But we have casts all over the place in gobject/gtk+. And the APIs of both classes is 100% *identical*. You can't seriously argue against a common interface. In this case, having a common base class strikes me almost as a no-brainer. How would you justify having the *exactly* same API twice on two very closely related classes? I would rather argue that having to learn only *one* GMonoitor API is much more obvious and straightforward. The actual implementation details (the fact that there are subclasses at all) could be almost invisible in the public API. - two closely related classes - two identical APIs - common base class *please* :-) I don't think is so important, so sure, lets do this. However, what would the name of the base class be? GMonitor? That strikes me as a bit to generic. GFileSystemMonitor? GChangeMonitor? GFileSystemMonitor gets my vote. Unless you want to go for GIOMonitor :) -- Regards, Martyn ___ gtk-devel-list mailing list gtk-devel-list@gnome.org http://mail.gnome.org/mailman/listinfo/gtk-devel-list
Re: GIO API review
On Thu, 2007-12-13 at 14:50 +0100, Michael Natterer wrote: Alexander Larsson wrote: On Wed, 2007-12-12 at 16:46 +0100, Michael Natterer wrote: Alexander Larsson wrote: On Tue, 2007-12-11 at 17:48 +0100, Michael Natterer wrote: Hey everybody, We've been doing a GIO API review in the last couple of days and here is the list of comments and issues we've come up with: General: It seems GIO allows individual files to be included, this should be avoided like gobject does it: #if !defined (__GLIB_GIO_H_INSIDE__) !defined (GIO_COMPILATION) #error Only gio.h can be included directly. #endif Why? I know gobject does this, but I never understood why. It seems to just make build times longer. Because otherwise you get into the very same typedef and include mess we have in glib and gtk+. It makes it *very* hard to change anything type related in the future. Any addition of a new function that happens to use a new type which was not used in that header before might work fine for the library's build itdelf, but might break the build of applications that include whatever combination of headers. Clear structure of headers and types should never be traded for compile time, we also keep distinct things in distinct .c files. Why would we scatter our typedefs across our libraries, or keep certain includes in headers forever? Ok. I guess this makes sense. I'll do this. Thanks :-) I forgot to mention, gobject has its common header in glib/. I'm not quite sure about this decision and I'm also not sure if saying #include glib-io.h or #include gio/gio.h is the more natural thing to do... Just for consideration. I'm for gio/gio.h. It seems more inline with all our other libraries. Only gobject does the glib-object.h thing. ___ gtk-devel-list mailing list gtk-devel-list@gnome.org http://mail.gnome.org/mailman/listinfo/gtk-devel-list
Re: GIO API review
Hi all!, On mar, 2007-12-11 at 17:48 +0100, Michael Natterer wrote: Hey everybody, We've been doing a GIO API review in the last couple of days and here is the list of comments and issues we've come up with: I Just wanted to raise another concern I have. Besides defining enums containing flags like GFileBlahFlags in gio, values inside these also are defined like G_FILE_BLAH_FLAGS_FOOBAR (note the _FLAGS_ in the definition) I don't think the values should specify too whether they're a flag, as the enum is already defined as a set of these, that way it'd also conform more to glib and gtk+ style. Regards, Carlos ___ gtk-devel-list mailing list gtk-devel-list@gnome.org http://mail.gnome.org/mailman/listinfo/gtk-devel-list
Re: GIO API review
On Tue, 2007-12-11 at 17:48 +0100, Michael Natterer wrote: GFile: == g_mount_for_location should probably be g_file_mount_for_location I've changed this to g_file_mount_enclosing_volume() ___ gtk-devel-list mailing list gtk-devel-list@gnome.org http://mail.gnome.org/mailman/listinfo/gtk-devel-list
Re: GIO API review
On Tue, 2007-12-11 at 17:48 +0100, Michael Natterer wrote: There is no need to break the common prefix for global things: g_push_current_cancellable - g_cancellable_push_current g_pop_current_cancellable - g_cancellable_pop_current Done. ___ gtk-devel-list mailing list gtk-devel-list@gnome.org http://mail.gnome.org/mailman/listinfo/gtk-devel-list
Re: GIO API review
On Thu, 2007-12-13 at 17:25 +0100, Carlos Garnacho wrote:
Hi all!,
On mar, 2007-12-11 at 17:48 +0100, Michael Natterer wrote:
Hey everybody,
We've been doing a GIO API review in the last couple of days and
here is the list of comments and issues we've come up with:
I Just wanted to raise another concern I have. Besides defining enums
containing flags like GFileBlahFlags in gio, values inside these also
are defined like G_FILE_BLAH_FLAGS_FOOBAR (note the _FLAGS_ in the
definition)
I don't think the values should specify too whether they're a flag, as
the enum is already defined as a set of these, that way it'd also
conform more to glib and gtk+ style.
There is actually currently some inconsistencies here:
typedef enum {
G_FILE_QUERY_INFO_FLAGS_NONE = 0,
G_FILE_QUERY_INFO_NOFOLLOW_SYMLINKS = (10)
}
vs
typedef enum {
G_FILE_MONITOR_FLAGS_NONE = 0,
G_FILE_MONITOR_FLAGS_MONITOR_MOUNTS = (10)
} GFileMonitorFlags;
What do people think is the best approach here?
___
gtk-devel-list mailing list
gtk-devel-list@gnome.org
http://mail.gnome.org/mailman/listinfo/gtk-devel-list
Re: GIO API review
13 dec 2007 kl. 12.51 skrev Alexander Larsson: Hi, On Wed, 2007-12-12 at 16:48 +0100, Mikael Hallendal wrote: 12 dec 2007 kl. 14.59 skrev Alexander Larsson: Hi, On Tue, 2007-12-11 at 17:48 +0100, Michael Natterer wrote: A big issue is that GIO wastes namespaces massively: g_app, GAsync, g_buffered, g_cancellable, g_content, g_data, g_desktop, g_directory, g_drive, g_file, g_filename, g_filter, g_icon, g_input, g_io, g_schedule, g_cancel, g_loadable, g_local, g_memory, g_mount, g_native, g_seekable, g_simple, g_themed, g_unix, g_vfs, g_volume, g_win32, g_push, g_pop That's clearly too much and can be reduced. While these are not strictly namespaces (the namespace is g_), they partly clash with g_foos and g_bars we already have, or might need in the future. We stronlgy suggest to use a common g_io/GIO prefix for all functions/types in GIO. GAsnc*- GIOAsync* G*Stream - GIOStream* GIcon - GIOIcon G*Icon- GIOIcon* GCancellable - GIOCancellable ... I strongly oppose this. While gio is a separate library these are all symbols in the glib module, and while it might be a problem at times we can handle any conflict issues (since we control both libs and release them toghether). So, I don't think the problem with this is that bad. I mean, gobject doesn't call its symbols GObjectClosure, g_object_signal, GObjectValue, etc, and this has not been a problem. The big issue is that GIO wastes a lot (31) of namespaces for no purpose. While some might not make sense to put under the GIO namespace (GIOIcon might be one of these, I don't know), the main chunk of them do. The 31 number is a bit high, as a bunch of the listed things are internal only and some we could remove (as discussed in this thread, which is a good thing). Furthermore I don't think that e.g. having a GSimpleAsyncResult class grabs the whole g_simple namespace. However, it is true that there parts of the g_ namespace that are consumed by gio. However, that is true for any addition to glib or gobject too and yet we add names there. Also, even if we used a g_io_ prefix we should avoid name conflicts anyway. It would be very problematic if we had both g_icon and g_io_icon types for instance. GIcon is probably one of the examples where it makes sense to not have it under the GIO namespace. I just wanted to clarify though that it's not so much for technical reasons I suggested that we namespace a bit more carefully. For example, if we plan to never use the GAsync infrastructure for anything other than GIO there is a point to put it under the GIO namespace as it shows where it belongs and what part of GLib it is used for. It also means we can have GFooAsync later without the two getting confused with each other. The same for GCancellable and similar namespaces. Without any namespace other than g_ it gives the idea that these frameworks are used for more than one subsystem (at least to me). I don't think the shorter name argument is all that valid given that g_io_ is a very short namespace either. If that is the only reason I think we should change. Also keep in mind, I'm not suggestion that *everything* should go in under g_io_, they would have to be weighted on their own merits and GIcon which is often used as an example might be one that doesn't make sense and have use cases outside of GIO. GFile, GDrive, GVolume, GVfs are examples of namespaces that (without looking closer) strikes me as valid ones without the GIO. The namespaces themselves suggest that they have to do with the IO layer. GAsync, GCancellable, g_push, g_pop, g_loadable, g_simple are examples of namespaces that would benefit from being under the GIO name spaced as they are too generic by themselves. Best Regards, Mikael Hallendal -- Imendio AB, http://www.imendio.com ___ gtk-devel-list mailing list gtk-devel-list@gnome.org http://mail.gnome.org/mailman/listinfo/gtk-devel-list
Re: GIO API review
Alexander Larsson wrote:
On Thu, 2007-12-13 at 17:25 +0100, Carlos Garnacho wrote:
Hi all!,
On mar, 2007-12-11 at 17:48 +0100, Michael Natterer wrote:
Hey everybody,
We've been doing a GIO API review in the last couple of days and
here is the list of comments and issues we've come up with:
I Just wanted to raise another concern I have. Besides defining enums
containing flags like GFileBlahFlags in gio, values inside these also
are defined like G_FILE_BLAH_FLAGS_FOOBAR (note the _FLAGS_ in the
definition)
I don't think the values should specify too whether they're a flag, as
the enum is already defined as a set of these, that way it'd also
conform more to glib and gtk+ style.
There is actually currently some inconsistencies here:
typedef enum {
G_FILE_QUERY_INFO_FLAGS_NONE = 0,
G_FILE_QUERY_INFO_NOFOLLOW_SYMLINKS = (10)
}
vs
typedef enum {
G_FILE_MONITOR_FLAGS_NONE = 0,
G_FILE_MONITOR_FLAGS_MONITOR_MOUNTS = (10)
} GFileMonitorFlags;
What do people think is the best approach here?
I don't really see the need for adding symbols to the library to
represent 0. If there is only one flag in each of these that matters,
doesn't it make more sense to just have a boolean?
If I was writing this and used an enum to represent 0, I would use:
G_FILE_QUERY_INFO_DEFAULT
G_FILE_QUERY_INFO_DONT_FOLLOW_SYMLINKS
and
G_FILE_MONITOR_DEFAULT
G_FILE_MONITOR_MOUNTS
--
Regards,
Martyn
___
gtk-devel-list mailing list
gtk-devel-list@gnome.org
http://mail.gnome.org/mailman/listinfo/gtk-devel-list
Re: GIO API review
Mikael Hallendal wrote: I just wanted to clarify though that it's not so much for technical reasons I suggested that we namespace a bit more carefully. For example, if we plan to never use the GAsync infrastructure for anything other than GIO there is a point to put it under the GIO namespace as it shows where it belongs and what part of GLib it is used for. It also means we can have GFooAsync later without the two getting confused with each other. The same for GCancellable and similar namespaces. And in this particular example, g_async_*, there is already a clash: we have g_async_queue_* right now, which is unrelated of course. A slightly longer name to avoid confusion here would be a fairly low price to pay in terms of typing. And I don't agree that it would be harder to read code with slightly longer names, on the contrary, at least when the added part is reasonably long. If it's clear what subsystem the function is related to, the developer doesn't have to stop to think. /Richard -- Imendio AB, http://www.imendio.com/ ___ gtk-devel-list mailing list gtk-devel-list@gnome.org http://mail.gnome.org/mailman/listinfo/gtk-devel-list
Re: GIO API review
On Dec 13, 2007 1:21 PM, Martyn Russell [EMAIL PROTECTED] wrote: I don't really see the need for adding symbols to the library to represent 0. If there is only one flag in each of these that matters, doesn't it make more sense to just have a boolean? This is not adding any symbols to the library. It merely tells the compiler to recognize some more names for 0. And using meaningful names makes the code a lot more self-explanatory. Matthias ___ gtk-devel-list mailing list gtk-devel-list@gnome.org http://mail.gnome.org/mailman/listinfo/gtk-devel-list
Re: GIO API review
On 13/12/2007, Martyn Russell [EMAIL PROTECTED] wrote: Alexander Larsson wrote: On Thu, 2007-12-13 at 14:43 +0100, Michael Natterer wrote: Alexander Larsson wrote: It just adds new types and type relations you have to learn, and forces you to remember that you have to cast to some common class to do things like cancelling a directory monitor. It adds nothing useful to the user of the API, it just means you have to learn more and remember more. But we have casts all over the place in gobject/gtk+. And the APIs of both classes is 100% *identical*. You can't seriously argue against a common interface. In this case, having a common base class strikes me almost as a no-brainer. How would you justify having the *exactly* same API twice on two very closely related classes? I would rather argue that having to learn only *one* GMonoitor API is much more obvious and straightforward. The actual implementation details (the fact that there are subclasses at all) could be almost invisible in the public API. - two closely related classes - two identical APIs - common base class *please* :-) I don't think is so important, so sure, lets do this. However, what would the name of the base class be? GMonitor? That strikes me as a bit to generic. GFileSystemMonitor? GChangeMonitor? GFileSystemMonitor gets my vote. Unless you want to go for GIOMonitor :) There is also a third monitor that has not been mentioned in this context - the volume monitor. Looking at the code I see that it is not exactly in the same spirit as the file and dir monitors, but it might be confusing that it does not have GMonitor as base class when other monitors do... Just a thought. Cheers, Mikkel ___ gtk-devel-list mailing list gtk-devel-list@gnome.org http://mail.gnome.org/mailman/listinfo/gtk-devel-list
Re: GIO API review
Sorry for mis-following-up and resending, i have too many mail accounts. On Wed, 2007-12-12 at 00:25 +, Emmanuele Bassi wrote: On Tue, 2007-12-11 at 21:22 +0200, Vincent Geddes wrote: Hi, On Tue, 2007-12-11 at 17:48 +0100, Michael Natterer wrote: Also, subclasses should probably append their name, not prepend it: GFilterOutputStream - GIOOutputStreamFilter GUnixOutputStream - GIOOutputStreamUnix ... This makes the file and inheritence structure much clearer and would be consistent with stuff we already have (e.g. GtkTreeModelFilter, GtkTreeModelSort). Looking over the GTK+ classes, it seems like the TreeView classes are the odd ones out. Most classes seem to follow the naming pattern in gio, examples being GtkToggleButton, GtkCheckMenuItem, GtkAccelLabel, GtkAboutDialog, etc. true. :-) Besides, the proposed naming in the review does go against the naming convention set by Smalltalk, Java, C#, et al; and if implemented will probably confuse users coming to GTK+ from those worlds. even though I usually favour internal consistency against the proof by other language when writing an API for my projects, in this case I completely agree: C++, Java, C# and other languages that have I/O stream classes went down the same naming policy with Type(Input|Output)Stream. I agree it should be InputStream and OutputStream (instead of StreamInput and StreamOutput, which would be taking the proposal to its extreme), but then we have good examples for the append approach in glib (no need to take GTK+ as an example here): GParamSpecFloat GParamSpecInt GParamSpecFoo ... This also enables comfortable working with the source code: ls gio/gioinputstream*.h gioinputstreamfile.h gioinputstreamfoo.h gioinputstreambar.h ... grep foo gio/gioinputstream*.c ...you get the idea. (yes i know you can ls and grep with the other approach too, my point is rather that it's nice and helpful to recognize common ancestry by common prefixes) As Behdad says, this is not a human language, and we shouldn't trade internal structural consistency and consistency *within* glib for whatever consistency with other frameworks (which is clearly less important than internal consistency). ciao, --mitch ___ gtk-devel-list mailing list gtk-devel-list@gnome.org http://mail.gnome.org/mailman/listinfo/gtk-devel-list
Re: GIO API review
On Tue, 2007-12-11 at 17:48 +0100, Michael Natterer wrote: Hey everybody, We've been doing a GIO API review in the last couple of days and here is the list of comments and issues we've come up with: General: It seems GIO allows individual files to be included, this should be avoided like gobject does it: #if !defined (__GLIB_GIO_H_INSIDE__) !defined (GIO_COMPILATION) #error Only gio.h can be included directly. #endif Why? I know gobject does this, but I never understood why. It seems to just make build times longer. A big issue is that GIO wastes namespaces massively: g_app, GAsync, g_buffered, g_cancellable, g_content, g_data, g_desktop, g_directory, g_drive, g_file, g_filename, g_filter, g_icon, g_input, g_io, g_schedule, g_cancel, g_loadable, g_local, g_memory, g_mount, g_native, g_seekable, g_simple, g_themed, g_unix, g_vfs, g_volume, g_win32, g_push, g_pop That's clearly too much and can be reduced. While these are not strictly namespaces (the namespace is g_), they partly clash with g_foos and g_bars we already have, or might need in the future. We stronlgy suggest to use a common g_io/GIO prefix for all functions/types in GIO. GAsnc*- GIOAsync* G*Stream - GIOStream* GIcon - GIOIcon G*Icon- GIOIcon* GCancellable - GIOCancellable ... I strongly oppose this. While gio is a separate library these are all symbols in the glib module, and while it might be a problem at times we can handle any conflict issues (since we control both libs and release them toghether). So, I don't think the problem with this is that bad. I mean, gobject doesn't call its symbols GObjectClosure, g_object_signal, GObjectValue, etc, and this has not been a problem. The negative aspect of such a change is that every symbol and name gets longer, which is harder to read and harder to write. Also when you work on a higher level you're forced to know which sub library of glib each class is from (which you don't really care about, especially if these types are exposed in higher level APIs). It also makes the symbol names weird. I mean GIOIcon? Is that in icon somehow related to an io operation (no), or is it an generic icon type (yes, that we hopefully will be using in a lot more APIs later)? Also, subclasses should probably append their name, not prepend it: GFilterOutputStream - GIOOutputStreamFilter GUnixOutputStream - GIOOutputStreamUnix ... This makes the file and inheritence structure much clearer and would be consistent with stuff we already have (e.g. GtkTreeModelFilter, GtkTreeModelSort). This was brought up on this list before during the initial gio reviews. The original version in fact had things appended (at least at places, it wasn't totally consistent). But it was all cleaned up to be consistent, and after that discussion I picked the current model. And I really think the current model is better. Its flows more natural in human language and its what other programming languages do, Its also easy to understand what name a class should have, while the postfix model does not always make this obvious, especially with multiple levels of inheritance: GInputStream is a stream for input (shouldn't it then be GStreamInput?), then we have an abstract subclass for this that adds some file specific operations: GFileInputStream. What is the name of an implementation of this for local files. In the prefix model its the easily readable GLocalFileInputStream. What is it in the postfix model? GInputStreamFileLocal? GFileInputStreamLocal? The first is the strictly correct one i guess, but its a quite bad name, the second is slightly more readable, but seems to imply that its parent is GFileInputStream, which does not follow the postfix pattern. All progress callbacks should have a cancellable argument, otherwise you always need to pass the cancellable as user_data if your progress dialog has a cancel button. While it certainly won't hurt to add it there I don't really see it as much of an advantage either. You really want the cancel button to immediately cancel the operation, not wait until the next progress callback. Furthermore, many ops don't have a progress callback so you need a cancellable object stored anyway. So, the natural thing is to store the cancellable in the cancel dialog and then pass it into the operation and use this for all cancellation. Then, when updating the progress bar in the dialog cancellation is not involved at all. All parent instance members should be called parent_instance for consistency, parent is a far too common member name to be used like that. Yeah, I'll change that. Nitpick: The number of padding elements in class structures varies, why? I added a lot where it seemed likely things will be extended in the future and less for things that weren't likely to change. This is mainly to save memory. GFile: == g_mount_for_location should probably
Re: GIO API review
Alexander Larsson wrote: On Tue, 2007-12-11 at 17:48 +0100, Michael Natterer wrote: GAsnc*- GIOAsync* G*Stream - GIOStream* GIcon - GIOIcon G*Icon- GIOIcon* GCancellable - GIOCancellable ... I strongly oppose this. I personally prefer the naming Mitch suggests. I know from the name which sub-library the API belongs to in GLib. So, I don't think the problem with this is that bad. I mean, gobject doesn't call its symbols GObjectClosure, g_object_signal, GObjectValue, etc, and this has not been a problem. There are of course inconsistencies through out the toolkit already. The negative aspect of such a change is that every symbol and name gets longer, which is harder to read and harder to write. Also when you work on a higher level you're forced to know which sub library of glib each class is from (which you don't really care about, especially if these types are exposed in higher level APIs). That's true. It also makes the symbol names weird. I mean GIOIcon? Is that in icon somehow related to an io operation (no), or is it an generic icon type (yes, that we hopefully will be using in a lot more APIs later)? Well, that depends how you look at it. Some people might think that it is just an icon object which is part of the GIO library, others might think it is an icon object with IO functions. I suppose you could argue that if it doesn't have any IO functionality, could it be added to the glib core library? Before you mentioned that it could be considered to have IO functionality, I hadn't really thought of it like that, I just assumed it was an Icon object in the GIO library :) But I see your point. Also, subclasses should probably append their name, not prepend it: GFilterOutputStream - GIOOutputStreamFilter GUnixOutputStream - GIOOutputStreamUnix ... This makes the file and inheritence structure much clearer and would be consistent with stuff we already have (e.g. GtkTreeModelFilter, GtkTreeModelSort). This was brought up on this list before during the initial gio reviews. The original version in fact had things appended (at least at places, it wasn't totally consistent). But it was all cleaned up to be consistent, and after that discussion I picked the current model. And I really think the current model is better. Its flows more natural in human language and its what other programming languages do, Its also easy to understand what name a class should have, while the postfix model does not always make this obvious, especially with multiple levels of inheritance: I tend to find the current naming less clear regarding what exactly it inherits from and takes longer to adopt to when learning the new API. I agree though, it doesn't sound too nice when saying it from a human language point of view. Just don't look at the Gossip source code ;) All progress callbacks should have a cancellable argument, otherwise you always need to pass the cancellable as user_data if your progress dialog has a cancel button. While it certainly won't hurt to add it there I don't really see it as much of an advantage either. You really want the cancel button to immediately cancel the operation, not wait until the next progress callback. Furthermore, many ops don't have a progress callback so you need a cancellable object stored anyway. So, the natural thing is to store the cancellable in the cancel dialog and then pass it into the operation and use this for all cancellation. Then, when updating the progress bar in the dialog cancellation is not involved at all. That is assuming you never want to cancel the operation from some calculation inside the callback. I personally would prefer the cancellation in the callback. Also, there is no good reason to use abbreviations like std and fs, we are not in the 60ies any more ;) std - standard fs - filesystem std:type - standard::type std:is_hidden - standard::is-hidden standard::type is 14 bytes, std:type is 8, given 10 std:* attributes per file and 1000 files in a directory, this means transfering 6 more bytes over dbus when reading this directory using gvfs. I'm not sure this is a horrible number, as there are bound to be other slow parts when involving gvfs (such as network traffic), but it might matter. I don't mind changing this though. What do other people change? I think standard and filesystem are better. They save questions and people looking up the acronyms in the documentation too. There also seems to be quite some duplication between GFileInfo and GFileAttributeValue for no good reason, such as: g_file_info_get_attribute_string vs. g_file_attribute_value_get_string g_file_info_set_attribute_int32 vs. g_file_attribute_value_set_int32 ... Where these functions in GFileInfo just seem to create/get a GFileAttributeValue and call the corresponding API, in fact these seem to be the only calls to g_file_attribute_value_* inside GIO.
Re: GIO API review
On Wed, 2007-12-12 at 15:13 +, Martyn Russell wrote: Alexander Larsson wrote: On Tue, 2007-12-11 at 17:48 +0100, Michael Natterer wrote: GAsnc*- GIOAsync* G*Stream - GIOStream* GIcon - GIOIcon G*Icon- GIOIcon* GCancellable - GIOCancellable ... I strongly oppose this. I personally prefer the naming Mitch suggests. I know from the name which sub-library the API belongs to in GLib. I don't think this is something that is all that important when you actually use the API. It certainly isn't so important that its worth (methaphorically) punching you in the face every time you read or write the symbol. So, I don't think the problem with this is that bad. I mean, gobject doesn't call its symbols GObjectClosure, g_object_signal, GObjectValue, etc, and this has not been a problem. There are of course inconsistencies through out the toolkit already. I wouldn't call it inconsistent. I think it is a correct design decision that it is called g_signal_stop_emission, and not g_object_signal_stop_emission. The negative aspect of such a change is that every symbol and name gets longer, which is harder to read and harder to write. Also when you work on a higher level you're forced to know which sub library of glib each class is from (which you don't really care about, especially if these types are exposed in higher level APIs). That's true. It also makes the symbol names weird. I mean GIOIcon? Is that in icon somehow related to an io operation (no), or is it an generic icon type (yes, that we hopefully will be using in a lot more APIs later)? Well, that depends how you look at it. Some people might think that it is just an icon object which is part of the GIO library, others might think it is an icon object with IO functions. I suppose you could argue that if it doesn't have any IO functionality, could it be added to the glib core library? No it can't, because it uses GObject. This goes back to the previous discussion about what library to use when adding other gobject based APIs like DConf to glib. At the moment I think the idea is to put those in libgio, but have separate headers and a separate .pc files. This makes the g_io_ prefix even weirder. And I really think the current model is better. Its flows more natural in human language and its what other programming languages do, Its also easy to understand what name a class should have, while the postfix model does not always make this obvious, especially with multiple levels of inheritance: I tend to find the current naming less clear regarding what exactly it inherits from and takes longer to adopt to when learning the new API. I agree though, it doesn't sound too nice when saying it from a human language point of view. I think this misses the point. I don't see the primary thing for a class name is to describe what class it inherits from, it is to describe what the class *does*. In some cases this is a completely different name from the base class, as in GtkButton vs GtkWidget (not GtkButtonWidget), but sometimes a good way to describe the class is to prepend something to it. Take for instance GDataInputStream, where Data was prepended, resulting in a new name that describes what it does (data input). Now, there is sort of a third case which is where we have a implementation of an abstract class/interface for a specific backend, such as GVolume/GUnixVolume or GFile/GLocalFile. I think its really this case that people think is better to use postfixes for. But I don't think its better even there. While it certainly won't hurt to add it there I don't really see it as much of an advantage either. You really want the cancel button to immediately cancel the operation, not wait until the next progress callback. Furthermore, many ops don't have a progress callback so you need a cancellable object stored anyway. So, the natural thing is to store the cancellable in the cancel dialog and then pass it into the operation and use this for all cancellation. Then, when updating the progress bar in the dialog cancellation is not involved at all. That is assuming you never want to cancel the operation from some calculation inside the callback. I personally would prefer the cancellation in the callback. Its certainly possible to cancel from the callback. All you have to do is store the cancallable in the dialog and pass the dialog pointer as user data. Now, do we want to make it *easier* to cancel from the progress callback. I don't think doing so is a good design as it will cause cancellation to not be as responsive as it should be. So, passing the cancellable in the progress callback would encourage problematic designs. GIOScheduler: = Each function has a different namespace here, I suggest: GIOSchedulerJobFunc GIOSchedulerDataFund g_io_scheduler_schedule_job g_io_scheduler_cancel_all_jobs
Re: GIO API review
Alexander Larsson wrote: On Tue, 2007-12-11 at 17:48 +0100, Michael Natterer wrote: Hey everybody, We've been doing a GIO API review in the last couple of days and here is the list of comments and issues we've come up with: General: It seems GIO allows individual files to be included, this should be avoided like gobject does it: #if !defined (__GLIB_GIO_H_INSIDE__) !defined (GIO_COMPILATION) #error Only gio.h can be included directly. #endif Why? I know gobject does this, but I never understood why. It seems to just make build times longer. Because otherwise you get into the very same typedef and include mess we have in glib and gtk+. It makes it *very* hard to change anything type related in the future. Any addition of a new function that happens to use a new type which was not used in that header before might work fine for the library's build itdelf, but might break the build of applications that include whatever combination of headers. Clear structure of headers and types should never be traded for compile time, we also keep distinct things in distinct .c files. Why would we scatter our typedefs across our libraries, or keep certain includes in headers forever? Allowing single library headers to be included just adds one more completely unneccessary layer of compatibility that needs to be preserved by all means as long as we guarantee source compatibility. *Please* let's at least get rid of that compatibility mess by simply not creating it in the first place. Also, if you have a common header for your library, you can easily split headers later if it turns out to be neccessary. I would even argue that it makes most sense to keep all opaque typedefs in one single file and include that from gio.h and from each source file within GIO. This way you can avoid including any headers from headers at all and it makes things so *very* much easier to maintain. We changed all of GIMP to this policy a few years back and never had a single (!!!) problem related to includes ever since. Deploying such a policy makes it completely clear where the opaque typedefs are: they are always in giotypes.h. There would be no need to have the typedef for GMount in gfile.h and have a comment like this: /* GMount typedef is in gfile.h due to include order issues */ in gmount.h, because there would be *no* include order issues. (will follow up on the rest in another mail) ciao, --mitch ___ gtk-devel-list mailing list gtk-devel-list@gnome.org http://mail.gnome.org/mailman/listinfo/gtk-devel-list
Re: GIO API review
12 dec 2007 kl. 14.59 skrev Alexander Larsson: Hi, On Tue, 2007-12-11 at 17:48 +0100, Michael Natterer wrote: A big issue is that GIO wastes namespaces massively: g_app, GAsync, g_buffered, g_cancellable, g_content, g_data, g_desktop, g_directory, g_drive, g_file, g_filename, g_filter, g_icon, g_input, g_io, g_schedule, g_cancel, g_loadable, g_local, g_memory, g_mount, g_native, g_seekable, g_simple, g_themed, g_unix, g_vfs, g_volume, g_win32, g_push, g_pop That's clearly too much and can be reduced. While these are not strictly namespaces (the namespace is g_), they partly clash with g_foos and g_bars we already have, or might need in the future. We stronlgy suggest to use a common g_io/GIO prefix for all functions/types in GIO. GAsnc*- GIOAsync* G*Stream - GIOStream* GIcon - GIOIcon G*Icon- GIOIcon* GCancellable - GIOCancellable ... I strongly oppose this. While gio is a separate library these are all symbols in the glib module, and while it might be a problem at times we can handle any conflict issues (since we control both libs and release them toghether). So, I don't think the problem with this is that bad. I mean, gobject doesn't call its symbols GObjectClosure, g_object_signal, GObjectValue, etc, and this has not been a problem. The big issue is that GIO wastes a lot (31) of namespaces for no purpose. While some might not make sense to put under the GIO namespace (GIOIcon might be one of these, I don't know), the main chunk of them do. The examples you took from GObject are perfect examples of parts that are a fundamental and big part of the GObject library and got their own namespaces. I'm sure there are a bunch of those in GIO as well, however, we should really consider it several times when introducing new namespaces. Both for future and for people trying to use the library. Best Regards, Mikael Hallendal -- Imendio AB, http://www.imendio.com/ ___ gtk-devel-list mailing list gtk-devel-list@gnome.org http://mail.gnome.org/mailman/listinfo/gtk-devel-list
Re: GIO API review
On Wed, 2007-12-12 at 16:37 +0100, Alexander Larsson wrote: GAsnc*- GIOAsync* G*Stream - GIOStream* GIcon - GIOIcon G*Icon- GIOIcon* GCancellable - GIOCancellable ... I strongly oppose this. I personally prefer the naming Mitch suggests. I know from the name which sub-library the API belongs to in GLib. I don't think this is something that is all that important when you actually use the API. It certainly isn't so important that its worth (methaphorically) punching you in the face every time you read or write the symbol. If these are are all about IO and/or generally meant to be used together, I would also like them to share some namespace. If glib doesn't do it then I'll probably do it when I wrap them in glibmm. But I love namespaces. If they are likely to be used separately, if they are generally meant to be self-contained then I'd be happy with just g_. -- [EMAIL PROTECTED] www.murrayc.com www.openismus.com ___ gtk-devel-list mailing list gtk-devel-list@gnome.org http://mail.gnome.org/mailman/listinfo/gtk-devel-list
Re: GIO API review
Alexander Larsson wrote: On Tue, 2007-12-11 at 17:48 +0100, Michael Natterer wrote: G*Monitor: == GFileMonitor - GIOMonitorFile GDirectoryMonitor - GIOMonitorDirectory Wouldn't it make sense to have a common (perhaps abstract) base class here, or derive one from the other? The APIs are very similar at least. They are very similar, but I'm not sure what advantage a common base class would have. Its not likely that you pass around an object that is either a file monitor or a directory monitor, so GMonitor would not be used anywhere. Well the common base class would install the changed signal, it would have cancel(), is_cancelles(), set_rate_limit() and emit_event() APIs, they would share their properties, and they would share the code instead of duplicating it. GIOMonitor would simply be an abstract base class, and it doesn't matter if you really need the polymorphy here (passing them around around as Monitor instead of File or Directory monitor), the point is that there is code duplication in two very similar classes, that almost cries for a common base class. ciao, --mitch ___ gtk-devel-list mailing list gtk-devel-list@gnome.org http://mail.gnome.org/mailman/listinfo/gtk-devel-list
Re: GIO API review
Hi, On Tue, 2007-12-11 at 17:48 +0100, Michael Natterer wrote: We stronlgy suggest to use a common g_io/GIO prefix for all functions/types in GIO. GAsnc*- GIOAsync* G*Stream - GIOStream* GIcon - GIOIcon G*Icon- GIOIcon* GCancellable - GIOCancellable I strongly agree with Mitch here. Having a common prefix would help a lot to keep the GLib API structured. Also, subclasses should probably append their name, not prepend it: GFilterOutputStream - GIOOutputStreamFilter GUnixOutputStream - GIOOutputStreamUnix Yes please. This is perhaps not close to the human language, but we are talking about an API here. I really like to see all output stream classes listed together and this naming convention achieves this automatically. Sven ___ gtk-devel-list mailing list gtk-devel-list@gnome.org http://mail.gnome.org/mailman/listinfo/gtk-devel-list
GIO API review
Hey everybody, We've been doing a GIO API review in the last couple of days and here is the list of comments and issues we've come up with: General: It seems GIO allows individual files to be included, this should be avoided like gobject does it: #if !defined (__GLIB_GIO_H_INSIDE__) !defined (GIO_COMPILATION) #error Only gio.h can be included directly. #endif A big issue is that GIO wastes namespaces massively: g_app, GAsync, g_buffered, g_cancellable, g_content, g_data, g_desktop, g_directory, g_drive, g_file, g_filename, g_filter, g_icon, g_input, g_io, g_schedule, g_cancel, g_loadable, g_local, g_memory, g_mount, g_native, g_seekable, g_simple, g_themed, g_unix, g_vfs, g_volume, g_win32, g_push, g_pop That's clearly too much and can be reduced. While these are not strictly namespaces (the namespace is g_), they partly clash with g_foos and g_bars we already have, or might need in the future. We stronlgy suggest to use a common g_io/GIO prefix for all functions/types in GIO. GAsnc*- GIOAsync* G*Stream - GIOStream* GIcon - GIOIcon G*Icon- GIOIcon* GCancellable - GIOCancellable ... Also, subclasses should probably append their name, not prepend it: GFilterOutputStream - GIOOutputStreamFilter GUnixOutputStream - GIOOutputStreamUnix ... This makes the file and inheritence structure much clearer and would be consistent with stuff we already have (e.g. GtkTreeModelFilter, GtkTreeModelSort). All progress callbacks should have a cancellable argument, otherwise you always need to pass the cancellable as user_data if your progress dialog has a cancel button. All parent instance members should be called parent_instance for consistency, parent is a far too common member name to be used like that. Nitpick: The number of padding elements in class structures varies, why? GFile: == g_mount_for_location should probably be g_file_mount_for_location Some async operations are not implemented: _query_settable_attributes_async _query_writable_namespaces_async _delete_file_async _trash_async _make_directory_async _make_symbolic_link_async _copy_async _move_async Is there an ETA for these? Especially copy_async() and move_async() seem very important missing pieces. A General issue with GFile is that the name suggests that you are holding some kind of file handle, where you actually have nothing but a filename (or uri). This could be problematic since the API does not make clear which functions simply work on the filename representation in memory and which do actual I/O (read: which function is cheap and which is expensive). E.g. g_file_contains_file gives no hint about whether it's just doing string operations on the filename, or actual I/O. Since GFile is merely an interface, it can probably not be stated generally which of the functions does I/O and which doesn't. It might however make sense to mention that in the docs for the built-in default implementation of local files. GFileEnumerator: GFileEnumerator - GIOFileEnumerator GMountOperation: GMountOperation - GIOMountOperation G_PASSWORD_FLAGS_ANON_SUPPORTED - G_IO_PASSWORD_FLAGS_ANONYMOUS_SUPPORTED Most of the API seems to deal with setting user/pass/choice in response to signals. Shouldn't there be one function to pass the entire set of response fields related to one signal instead of a combo of setters plus reply() ? G*Monitor: == GFileMonitor - GIOMonitorFile GDirectoryMonitor - GIOMonitorDirectory Wouldn't it make sense to have a common (perhaps abstract) base class here, or derive one from the other? The APIs are very similar at least. GFileAttribute: === GFileAttribute* - GIOFileAttribute* GFileAttributeValue: why is the union not a GValue? Our biggest issue is probably that the attributes are semantically very similar to object properties and should therefore follow the conventions introduced there: Namespace should be separated from attribute name by '::', not ':', gobject does this for both properties and detailled signals, so GIO should name file attributes consistently. The use of '_' should be avoided, please use '-' instead. We put a great deal of effort into canonicalizing identifiers elsewhere (object property names and signal names), so GIO should follow that habit here for the sake of consistency. Also, there is no good reason to use abbreviations like std and fs, we are not in the 60ies any more ;) std - standard fs - filesystem std:type - standard::type std:is_hidden - standard::is-hidden There also seems to be quite some duplication between GFileInfo and GFileAttributeValue for no good reason, such as: g_file_info_get_attribute_string vs. g_file_attribute_value_get_string g_file_info_set_attribute_int32 vs. g_file_attribute_value_set_int32 ... Where these functions in GFileInfo just seem to create/get a GFileAttributeValue and call the corresponding API
Re: GIO API review
Hi, On Tue, 2007-12-11 at 17:48 +0100, Michael Natterer wrote: Also, subclasses should probably append their name, not prepend it: GFilterOutputStream - GIOOutputStreamFilter GUnixOutputStream - GIOOutputStreamUnix ... This makes the file and inheritence structure much clearer and would be consistent with stuff we already have (e.g. GtkTreeModelFilter, GtkTreeModelSort). Looking over the GTK+ classes, it seems like the TreeView classes are the odd ones out. Most classes seem to follow the naming pattern in gio, examples being GtkToggleButton, GtkCheckMenuItem, GtkAccelLabel, GtkAboutDialog, etc. Besides, the proposed naming in the review does go against the naming convention set by Smalltalk, Java, C#, et al; and if implemented will probably confuse users coming to GTK+ from those worlds. - Vincent ___ gtk-devel-list mailing list gtk-devel-list@gnome.org http://mail.gnome.org/mailman/listinfo/gtk-devel-list
Re: GIO API review
On Tue, 2007-12-11 at 21:22 +0200, Vincent Geddes wrote: Hi, On Tue, 2007-12-11 at 17:48 +0100, Michael Natterer wrote: Also, subclasses should probably append their name, not prepend it: GFilterOutputStream - GIOOutputStreamFilter GUnixOutputStream - GIOOutputStreamUnix ... This makes the file and inheritence structure much clearer and would be consistent with stuff we already have (e.g. GtkTreeModelFilter, GtkTreeModelSort). Looking over the GTK+ classes, it seems like the TreeView classes are the odd ones out. Most classes seem to follow the naming pattern in gio, examples being GtkToggleButton, GtkCheckMenuItem, GtkAccelLabel, GtkAboutDialog, etc. Besides, the proposed naming in the review does go against the naming convention set by Smalltalk, Java, C#, et al; and if implemented will probably confuse users coming to GTK+ from those worlds. It's not only different from the naming conventions in those programming languages, it's also different from plain English, as far as I can tell as a non-native speaker. Jürg ___ gtk-devel-list mailing list gtk-devel-list@gnome.org http://mail.gnome.org/mailman/listinfo/gtk-devel-list
Re: GIO API review
On Tue, 2007-12-11 at 15:37 -0500, Jürg Billeter wrote: It's not only different from the naming conventions in those programming languages, it's also different from plain English, as far as I can tell as a non-native speaker. But then again, it's not a human language... -- behdad http://behdad.org/ ...very few phenomena can pull someone out of Deep Hack Mode, with two noted exceptions: being struck by lightning, or worse, your *computer* being struck by lightning. -- Matt Welsh ___ gtk-devel-list mailing list gtk-devel-list@gnome.org http://mail.gnome.org/mailman/listinfo/gtk-devel-list
Re: GIO API review
On Tue, 2007-12-11 at 21:22 +0200, Vincent Geddes wrote: Hi, On Tue, 2007-12-11 at 17:48 +0100, Michael Natterer wrote: Also, subclasses should probably append their name, not prepend it: GFilterOutputStream - GIOOutputStreamFilter GUnixOutputStream - GIOOutputStreamUnix ... This makes the file and inheritence structure much clearer and would be consistent with stuff we already have (e.g. GtkTreeModelFilter, GtkTreeModelSort). Looking over the GTK+ classes, it seems like the TreeView classes are the odd ones out. Most classes seem to follow the naming pattern in gio, examples being GtkToggleButton, GtkCheckMenuItem, GtkAccelLabel, GtkAboutDialog, etc. true. :-) Besides, the proposed naming in the review does go against the naming convention set by Smalltalk, Java, C#, et al; and if implemented will probably confuse users coming to GTK+ from those worlds. even though I usually favour internal consistency against the proof by other language when writing an API for my projects, in this case I completely agree: C++, Java, C# and other languages that have I/O stream classes went down the same naming policy with Type(Input|Output)Stream. ciao, Emmanuele. -- Emmanuele Bassi, W: http://www.emmanuelebassi.net B: http://log.emmanuelebassi.net ___ gtk-devel-list mailing list gtk-devel-list@gnome.org http://mail.gnome.org/mailman/listinfo/gtk-devel-list
