From c524cabff279c6a3bc6b95eb4c20f7c6a5e34e31 Mon Sep 17 00:00:00 2001 From: Matthias Clasen Date: Fri, 30 Nov 2007 18:11:03 +0000 Subject: [PATCH] Add docs for etags svn path=/trunk/; revision=6001 --- gio/ChangeLog | 4 ++++ gio/gbufferedinputstream.c | 2 +- gio/gfile.c | 47 +++++++++++++++++++++++++++++----------------- gio/gfileattribute.c | 12 ++++++------ gio/gfileenumerator.c | 2 +- gio/gfileinfo.c | 4 ++-- gio/gfileinputstream.c | 2 +- gio/ginputstream.c | 6 +++--- gio/gioscheduler.c | 2 ++ 9 files changed, 50 insertions(+), 31 deletions(-) diff --git a/gio/ChangeLog b/gio/ChangeLog index 006e23c..eab9299 100644 --- a/gio/ChangeLog +++ b/gio/ChangeLog @@ -1,3 +1,7 @@ +2007-11-30 Matthias Clasen + + * *.c: Explain etags and link to the explanation + 2007-11-29 Matthias Clasen * *.c: Explain I/O priority. diff --git a/gio/gbufferedinputstream.c b/gio/gbufferedinputstream.c index a3994a8..62c96f9 100644 --- a/gio/gbufferedinputstream.c +++ b/gio/gbufferedinputstream.c @@ -445,7 +445,7 @@ async_fill_callback_wrapper (GObject *source_object, * g_buffered_input_stream_fill_async: * @stream: #GBufferedInputStream. * @count: a #gssize. - * @io_priority: the I/O priority + * @io_priority: the I/O priority * of the request. * @cancellable: optional #GCancellable object * @callback: a #GAsyncReadyCallback. diff --git a/gio/gfile.c b/gio/gfile.c index 9c1d381..6ff826c 100644 --- a/gio/gfile.c +++ b/gio/gfile.c @@ -46,7 +46,8 @@ * virtual file system. #GFiles are lightweight, immutable * objects that do no I/O upon creation. It is necessary to understand that * #GFile objects do not represent files, merely a handle to a file. All - * file I/O is implemented as streaming operations (see #GInputStream and #GOutputStream). + * file I/O is implemented as streaming operations (see #GInputStream and + * #GOutputStream). * * To construct a #GFile, you can use: * g_file_new_for_path() if you have a path. @@ -72,7 +73,14 @@ * g_file_unmount_mountable() to unmount a mountable file. * g_file_eject_mountable() to eject a mountable file. * - * + * entity tag + * One notable feature of #GFiles are entity tags, or "etags" for + * short. Entity tags are somewhat like a more abstract version of the + * traditional mtime, and can be used to quickly determine if the file has + * been modified from the version on the file system. See the HTTP 1.1 + * specification + * for HTTP Etag headers, which are a very similar concept. + * **/ static void g_file_base_init (gpointer g_class); @@ -669,7 +677,7 @@ g_file_enumerate_children (GFile *file, * @file: input #GFile. * @attributes: a string containing a #GFileAttributeInfo query. * @flags: a set of #GFileQueryInfoFlags. - * @io_priority: the I/O priority + * @io_priority: the I/O priority * of the request. * @cancellable: optional #GCancellable object, %NULL to ignore. * @callback: a #GAsyncReadyCallback to call when the request is satisfied @@ -797,7 +805,7 @@ g_file_query_info (GFile *file, * @file: input #GFile. * @attributes: a string containing a #GFileAttributeInfo query. * @flags: a set of #GFileQueryInfoFlags. - * @io_priority: the I/O priority + * @io_priority: the I/O priority * of the request. * @cancellable: optional #GCancellable object, %NULL to ignore. * @callback: a #GAsyncReadyCallback to call when the request is satisfied @@ -1095,8 +1103,9 @@ g_file_create (GFile *file, /** * g_file_replace: * @file: input #GFile. - * @etag: an Entity Tag for the current #GFile. - * @make_backup: %TRUE if a backup should be created. + * @etag: an entity tag for the + * current #GFile. + * @make_backup: %TRUE if a backup should be created`. * @flags: a set of #GFileCreateFlags. * @cancellable: optional #GCancellable object, %NULL to ignore. * @error: a #GError, or %NULL @@ -1154,7 +1163,7 @@ g_file_replace (GFile *file, /** * g_file_read_async: * @file: input #GFile. - * @io_priority: the I/O priority + * @io_priority: the I/O priority * of the request. * @cancellable: optional #GCancellable object, %NULL to ignore. * @callback: a #GAsyncReadyCallback. @@ -1227,7 +1236,7 @@ g_file_read_finish (GFile *file, * g_file_append_to_async: * @file: input #GFile. * @flags: a set of #GFileCreateFlags. - * @io_priority: the I/O priority + * @io_priority: the I/O priority * of the request. * @cancellable: optional #GCancellable object, %NULL to ignore. * @callback: a #GAsyncReadyCallback. @@ -1304,7 +1313,7 @@ g_file_append_to_finish (GFile *file, * g_file_create_async: * @file: input #GFile. * @flags: a set of #GFileCreateFlags. - * @io_priority: the I/O priority + * @io_priority: the I/O priority * of the request. * @cancellable: optional #GCancellable object, %NULL to ignore. * @callback: a #GAsyncReadyCallback. @@ -1380,10 +1389,11 @@ g_file_create_finish (GFile *file, /** * g_file_replace_async: * @file: input #GFile. - * @etag: an Entity Tag for the current #GFile. + * @etag: an entity tag for the + * current #GFile. * @make_backup: a #gboolean. * @flags: a set of #GFileCreateFlags. - * @io_priority: the I/O priority + * @io_priority: the I/O priority * of the request. * @cancellable: optional #GCancellable object, %NULL to ignore. * @callback: a #GAsyncReadyCallback. @@ -2299,7 +2309,7 @@ g_file_set_display_name (GFile *file, * g_file_set_display_name_async: * @file: input #GFile. * @display_name: a string. - * @io_priority: the I/O priority + * @io_priority: the I/O priority * of the request. * @cancellable: optional #GCancellable object, %NULL to ignore. * @callback: a #GAsyncReadyCallback. @@ -2611,7 +2621,7 @@ g_file_real_set_attributes_from_info (GFile *file, * @file: input #GFile. * @info: a #GFileInfo. * @flags: a #GFileQueryInfoFlags. - * @io_priority: the I/O priority + * @io_priority: the I/O priority * of the request. * @cancellable: optional #GCancellable object, %NULL to ignore. * @callback: a #GAsyncReadyCallback. @@ -4390,10 +4400,12 @@ g_file_load_contents_finish (GFile *file, * @file: input #GFile. * @contents: a string containing the new contents for @file. * @length: the length of @contents in bytes. - * @etag: the old entity tag for the document. + * @etag: the old entity tag + * for the document. * @make_backup: a #gboolean. * @flags: a set of #GFileCreateFlags. - * @new_etag: a location to a new entity tag for the document. + * @new_etag: a location to a new entity tag + * for the document. * @cancellable: optional #GCancellable object, %NULL to ignore. * @error: a #GError, or %NULL * @@ -4592,7 +4604,7 @@ replace_contents_open_callback (GObject *obj, * @file: input #GFile. * @contents: string of contents to replace the file with. * @length: the length of @contents in bytes. - * @etag: a new entity tag for the @file. + * @etag: a new entity tag for the @file. * @make_backup: a #gboolean. * @flags: a set of #GFileCreateFlags. * @cancellable: optional #GCancellable object, %NULL to ignore. @@ -4655,7 +4667,8 @@ g_file_replace_contents_async (GFile *file, * g_file_replace_contents_finish: * @file: input #GFile. * @res: a #GAsyncResult. - * @new_etag: a location of a new entity tag for the document. + * @new_etag: a location of a new entity tag + * for the document. * @error: a #GError, or %NULL * * Finishes an asynchronous replace of the given @file. See diff --git a/gio/gfileattribute.c b/gio/gfileattribute.c index d11b25b..facdf38 100644 --- a/gio/gfileattribute.c +++ b/gio/gfileattribute.c @@ -67,14 +67,14 @@ * * * "std"The "Standard" namespace. General file - * information that any application may need should be put in this namespace. Examples - * include the file's name, type, and size. + * information that any application may need should be put in this namespace. + * Examples include the file's name, type, and size. * "etag"The "Entity Tag" namespace. * GIO use "entity tags" to quickly determine if a file has been modified - * from the version on the file system. Entity tags are globally unique identifiers, - * and should always be sent with the current revision of a file. - * An example of a key in this namespace is "value", which contains the value of the - * current entity tag. + * from the version on the file system. Entity tags are globally unique + * identifiers, and should always be sent with the current revision of a + * file. An example of a key in this namespace is "value", which contains + * the value of the current entity tag. * "id"The "Identification" namespace. This * namespace is used by file managers and applications that list directories * to check for loops and to uniquely identify files. diff --git a/gio/gfileenumerator.c b/gio/gfileenumerator.c index de4c38c..e525aa8 100644 --- a/gio/gfileenumerator.c +++ b/gio/gfileenumerator.c @@ -363,7 +363,7 @@ close_async_callback_wrapper (GObject *source_object, /** * g_file_enumerator_close_async: * @enumerator: a #GFileEnumerator. - * @io_priority: the I/O priority + * @io_priority: the I/O priority * of the request. * @cancellable: optional #GCancellable object, %NULL to ignore. * @callback: callback to call when the request is satisfied diff --git a/gio/gfileinfo.c b/gio/gfileinfo.c index 3ce611d..4c574b5 100644 --- a/gio/gfileinfo.c +++ b/gio/gfileinfo.c @@ -1325,8 +1325,8 @@ g_file_info_get_symlink_target (GFileInfo *info) * g_file_info_get_etag: * @info: a #GFileInfo. * - * Gets the entity tag for a given #GFileInfo. - * See %G_FILE_ATTRIBUTE_ETAG_VALUE. + * Gets the entity tag for a given + * #GFileInfo. See %G_FILE_ATTRIBUTE_ETAG_VALUE. * * Returns: a string containing the value of the "etag:value" attribute. **/ diff --git a/gio/gfileinputstream.c b/gio/gfileinputstream.c index c7dd4cf..57056db 100644 --- a/gio/gfileinputstream.c +++ b/gio/gfileinputstream.c @@ -181,7 +181,7 @@ async_ready_callback_wrapper (GObject *source_object, * g_file_input_stream_query_info_async: * @stream: a #GFileInputStream. * @attributes: a file attribute query string. - * @io_priority: the I/O priority + * @io_priority: the I/O priority * of the request. * @cancellable: optional #GCancellable object, %NULL to ignore. * @callback: callback to call when the request is satisfied diff --git a/gio/ginputstream.c b/gio/ginputstream.c index afc82a2..548691b 100644 --- a/gio/ginputstream.c +++ b/gio/ginputstream.c @@ -520,7 +520,7 @@ async_ready_close_callback_wrapper (GObject *source_object, * @stream: A #GInputStream. * @buffer: a buffer to read data into (which should be at least count bytes long). * @count: the number of bytes that will be read from the stream - * @io_priority: the I/O priority + * @io_priority: the I/O priority * of the request. * @cancellable: optional #GCancellable object, %NULL to ignore. * @callback: callback to call when the request is satisfied @@ -655,7 +655,7 @@ g_input_stream_read_finish (GInputStream *stream, * g_input_stream_skip_async: * @stream: A #GInputStream. * @count: the number of bytes that will be skipped from the stream - * @io_priority: the I/O priority + * @io_priority: the I/O priority * of the request. * @cancellable: optional #GCancellable object, %NULL to ignore. * @callback: callback to call when the request is satisfied @@ -787,7 +787,7 @@ g_input_stream_skip_finish (GInputStream *stream, /** * g_input_stream_close_async: * @stream: A #GInputStream. - * @io_priority: the I/O priority + * @io_priority: the I/O priority * of the request. * @cancellable: optional cancellable object * @callback: callback to call when the request is satisfied diff --git a/gio/gioscheduler.c b/gio/gioscheduler.c index 52e2ca6..13a8cf4 100644 --- a/gio/gioscheduler.c +++ b/gio/gioscheduler.c @@ -33,12 +33,14 @@ * Schedules asynchronous I/O operations for integration into the main * event loop (#GMainLoop). * + * I/O priority * Each I/O operation has a priority, and the scheduler uses the priorities * to determine the order in which operations are executed. They are * not used to determine system-wide I/O scheduling. * Priorities are integers, with lower numbers indicating higher priority. * It is recommended to choose priorities between %G_PRIORITY_LOW and * %G_PRIORITY_HIGH, with %G_PRIORITY_DEFAULT as a default. + * **/ struct _GIOJob { -- 2.7.4