diff options
-rw-r--r-- | gio/ChangeLog | 4 | ||||
-rw-r--r-- | gio/gbufferedinputstream.c | 2 | ||||
-rw-r--r-- | gio/gfile.c | 47 | ||||
-rw-r--r-- | gio/gfileattribute.c | 12 | ||||
-rw-r--r-- | gio/gfileenumerator.c | 2 | ||||
-rw-r--r-- | gio/gfileinfo.c | 4 | ||||
-rw-r--r-- | gio/gfileinputstream.c | 2 | ||||
-rw-r--r-- | gio/ginputstream.c | 6 | ||||
-rw-r--r-- | gio/gioscheduler.c | 2 |
9 files changed, 50 insertions, 31 deletions
diff --git a/gio/ChangeLog b/gio/ChangeLog index 006e23c16..eab929921 100644 --- a/gio/ChangeLog +++ b/gio/ChangeLog @@ -1,3 +1,7 @@ +2007-11-30 Matthias Clasen <mclasen@redhat.com> + + * *.c: Explain etags and link to the explanation + 2007-11-29 Matthias Clasen <mclasen@redhat.com> * *.c: Explain I/O priority. diff --git a/gio/gbufferedinputstream.c b/gio/gbufferedinputstream.c index a3994a8aa..62c96f986 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 <link linkend="gio-GIOScheduler">I/O priority</link> + * @io_priority: the <link linkend="io-priority">I/O priority</link> * of the request. * @cancellable: optional #GCancellable object * @callback: a #GAsyncReadyCallback. diff --git a/gio/gfile.c b/gio/gfile.c index 9c1d381b6..6ff826c02 100644 --- a/gio/gfile.c +++ b/gio/gfile.c @@ -46,7 +46,8 @@ * virtual file system. #GFile<!-- -->s 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. * - * + * <para id="gfile-etag"><indexterm><primary>entity tag</primary></indexterm> + * One notable feature of #GFile<!-- -->s 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 + * <ulink url="http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.19">specification</ulink> + * for HTTP Etag headers, which are a very similar concept. + * </para> **/ 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 <link linkend="gio-GIOScheduler">I/O priority</link> + * @io_priority: the <link linkend="io-priority">I/O priority</link> * 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 <link linkend="gio-GIOScheduler">I/O priority</link> + * @io_priority: the <link linkend="io-priority">I/O priority</link> * 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 <link linkend="gfile-etag">entity tag</link> 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 <link linkend="gio-GIOScheduler">I/O priority</link> + * @io_priority: the <link linkend="io-priority">I/O priority</link> * 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 <link linkend="gio-GIOScheduler">I/O priority</link> + * @io_priority: the <link linkend="io-priority">I/O priority</link> * 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 <link linkend="gio-GIOScheduler">I/O priority</link> + * @io_priority: the <link linkend="io-priority">I/O priority</link> * 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 <link linkend="gfile-etag">entity tag</link> for the + * current #GFile. * @make_backup: a #gboolean. * @flags: a set of #GFileCreateFlags. - * @io_priority: the <link linkend="gio-GIOScheduler">I/O priority</link> + * @io_priority: the <link linkend="io-priority">I/O priority</link> * 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 <link linkend="gioscheduler">I/O priority</link> + * @io_priority: the <link linkend="io-priority">I/O priority</link> * 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 <link linkend="gio-GIOScheduler">I/O priority</link> + * @io_priority: the <link linkend="io-priority">I/O priority</link> * 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 <link linkend="gfile-etag">entity tag</link> + * 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 <link linkend="gfile-etag">entity tag</link> + * 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 <link linkend="gfile-etag">entity tag</link> 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 <link linkend="gfile-etag">entity tag</link> + * 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 d11b25bfb..facdf3820 100644 --- a/gio/gfileattribute.c +++ b/gio/gfileattribute.c @@ -67,14 +67,14 @@ * </thead> * <tbody> * <row><entry>"std"</entry><entry>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.</entry></row> + * information that any application may need should be put in this namespace. + * Examples include the file's name, type, and size.</entry></row> * <row><entry>"etag"</entry><entry>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.</entry></row> + * 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.</entry></row> * <row><entry>"id"</entry><entry>The "Identification" namespace. This * namespace is used by file managers and applications that list directories * to check for loops and to uniquely identify files.</entry></row> diff --git a/gio/gfileenumerator.c b/gio/gfileenumerator.c index de4c38caa..e525aa8a1 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 <link linkend="gio-GIOScheduler">I/O priority</link> + * @io_priority: the <link linkend="io-priority">I/O priority</link> * 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 3ce611d9c..4c574b580 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 <link linkend="gfile-etag">entity tag</link> 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 c7dd4cfdd..57056dba9 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 <link linkend="gio-GIOScheduler">I/O priority</link> + * @io_priority: the <link linkend="io-priority">I/O priority</link> * 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 afc82a27c..548691b99 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 <link linkend="gio-GIOScheduler">I/O priority</link> + * @io_priority: the <link linkend="io-priority">I/O priority</link> * 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 <link linkend="gio-GIOScheduler">I/O priority</link> + * @io_priority: the <link linkend="io-priority">I/O priority</link> * 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 <link linkend="gio-GIOScheduler">I/O priority</link> + * @io_priority: the <link linkend="io-priority">I/O priority</link> * 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 52e2ca626..13a8cf477 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). * + * <para id="io-priority"><indexterm><primary>I/O priority</primary></indexterm> * Each I/O operation has a priority, and the scheduler uses the priorities * to determine the order in which operations are executed. They are * <emphasis>not</emphasis> 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. + * </para> **/ struct _GIOJob { |