Explain I/O priorieties

svn path=/trunk/; revision=6000

diff --git a/gio/ChangeLog b/gio/ChangeLog
index 6712bc6..006e23c 100644 (file)
--- a/gio/ChangeLog
+++ b/gio/ChangeLog
@@ -1,5 +1,7 @@
 2007-11-29  Matthias Clasen <mclasen@redhat.com>
 
+       * *.c: Explain I/O priority.
+
        * *.c: More coding style fixes.
 
 2007-11-29  Matthias Clasen <mclasen@redhat.com>

diff --git a/gio/gbufferedinputstream.c b/gio/gbufferedinputstream.c
index 61d1716..a3994a8 100644 (file)
--- a/gio/gbufferedinputstream.c
+++ b/gio/gbufferedinputstream.c
@@ -445,7 +445,8 @@ async_fill_callback_wrapper (GObject      *source_object,
  * g_buffered_input_stream_fill_async:
  * @stream: #GBufferedInputStream.
  * @count: a #gssize.
- * @io_priority: the io priority of the request.
+ * @io_priority: the <link linkend="gio-GIOScheduler">I/O priority</link> 
+ *     of the request.
  * @cancellable: optional #GCancellable object
  * @callback: a #GAsyncReadyCallback.
  * @user_data: a #gpointer.

diff --git a/gio/gfile.c b/gio/gfile.c
index e1f1208..9c1d381 100644 (file)
--- a/gio/gfile.c
+++ b/gio/gfile.c
@@ -669,7 +669,8 @@ g_file_enumerate_children (GFile                *file,
  * @file: input #GFile.
  * @attributes: a string containing a #GFileAttributeInfo query.
  * @flags: a set of #GFileQueryInfoFlags.
- * @io_priority: the io priority of the request.
+ * @io_priority: the <link linkend="gio-GIOScheduler">I/O priority</link> 
+ *     of the request.
  * @cancellable: optional #GCancellable object, %NULL to ignore.
  * @callback: a #GAsyncReadyCallback to call when the request is satisfied
  * @user_data: the data to pass to callback function
@@ -796,7 +797,8 @@ g_file_query_info (GFile                *file,
  * @file: input #GFile.
  * @attributes: a string containing a #GFileAttributeInfo query.
  * @flags: a set of #GFileQueryInfoFlags.
- * @io_priority: the io priority of the request.
+ * @io_priority: the <link linkend="gio-GIOScheduler">I/O priority</link> 
+ *     of the request.
  * @cancellable: optional #GCancellable object, %NULL to ignore. 
  * @callback: a #GAsyncReadyCallback to call when the request is satisfied
  * @user_data: the data to pass to callback function
@@ -1152,7 +1154,8 @@ g_file_replace (GFile             *file,
 /**
  * g_file_read_async:
  * @file: input #GFile.
- * @io_priority: the io priority of the request. 
+ * @io_priority: the <link linkend="gio-GIOScheduler">I/O priority</link> 
+ *     of the request. 
  * @cancellable: optional #GCancellable object, %NULL to ignore.
  * @callback: a #GAsyncReadyCallback.
  * @user_data: a #gpointer. 
@@ -1224,7 +1227,8 @@ g_file_read_finish (GFile         *file,
  * g_file_append_to_async:
  * @file: input #GFile.
  * @flags: a set of #GFileCreateFlags.
- * @io_priority: the io priority of the request. 
+ * @io_priority: the <link linkend="gio-GIOScheduler">I/O priority</link> 
+ *     of the request. 
  * @cancellable: optional #GCancellable object, %NULL to ignore.
  * @callback: a #GAsyncReadyCallback. 
  * @user_data: a #gpointer. 
@@ -1300,7 +1304,8 @@ g_file_append_to_finish (GFile         *file,
  * g_file_create_async:
  * @file: input #GFile.
  * @flags: a set of #GFileCreateFlags.
- * @io_priority: the io priority of the request.
+ * @io_priority: the <link linkend="gio-GIOScheduler">I/O priority</link> 
+ *     of the request.
  * @cancellable: optional #GCancellable object, %NULL to ignore.
  * @callback: a #GAsyncReadyCallback. 
  * @user_data: a #gpointer. 
@@ -1378,7 +1383,8 @@ g_file_create_finish (GFile         *file,
  * @etag: an Entity Tag for the current #GFile.
  * @make_backup: a #gboolean.
  * @flags: a set of #GFileCreateFlags.
- * @io_priority: the io priority of the request.
+ * @io_priority: the <link linkend="gio-GIOScheduler">I/O priority</link> 
+ *     of the request.
  * @cancellable: optional #GCancellable object, %NULL to ignore.
  * @callback: a #GAsyncReadyCallback. 
  * @user_data: a #gpointer. 
@@ -2293,7 +2299,8 @@ g_file_set_display_name (GFile         *file,
  * g_file_set_display_name_async:
  * @file: input #GFile.
  * @display_name: a string.
- * @io_priority: the io priority of the request. 
+ * @io_priority: the <link linkend="gioscheduler">I/O priority</link> 
+ *     of the request. 
  * @cancellable: optional #GCancellable object, %NULL to ignore.
  * @callback: a #GAsyncReadyCallback. 
  * @user_data: a #gpointer. 
@@ -2604,7 +2611,8 @@ g_file_real_set_attributes_from_info (GFile                *file,
  * @file: input #GFile.
  * @info: a #GFileInfo.
  * @flags: a #GFileQueryInfoFlags.
- * @io_priority: the io priority of the request. 
+ * @io_priority: the <link linkend="gio-GIOScheduler">I/O priority</link> 
+ *     of the request. 
  * @cancellable: optional #GCancellable object, %NULL to ignore.
  * @callback: a #GAsyncReadyCallback. 
  * @user_data: a #gpointer.

diff --git a/gio/gfileenumerator.c b/gio/gfileenumerator.c
index 6be67e5..de4c38c 100644 (file)
--- a/gio/gfileenumerator.c
+++ b/gio/gfileenumerator.c
@@ -231,7 +231,8 @@ next_async_callback_wrapper (GObject      *source_object,
  * g_file_enumerator_next_files_async:
  * @enumerator: a #GFileEnumerator.
  * @num_files: the number of file info objects to request
- * @io_priority: the io priority of the request. the io priority of the request
+ * @io_priority: the <link linkend="gioscheduler">io priority</link> 
+ *     of the request. 
  * @cancellable: optional #GCancellable object, %NULL to ignore.
  * @callback: callback to call when the request is satisfied
  * @user_data: the user_data to pass to callback function 
@@ -362,7 +363,8 @@ close_async_callback_wrapper (GObject      *source_object,
 /**
  * g_file_enumerator_close_async:
  * @enumerator: a #GFileEnumerator.
- * @io_priority: the io priority of the request.
+ * @io_priority: the <link linkend="gio-GIOScheduler">I/O priority</link> 
+ *     of the request.
  * @cancellable: optional #GCancellable object, %NULL to ignore. 
  * @callback: callback to call when the request is satisfied
  * @user_data: the user_data to pass to callback function 

diff --git a/gio/gfileinputstream.c b/gio/gfileinputstream.c
index bc5cc70..c7dd4cf 100644 (file)
--- a/gio/gfileinputstream.c
+++ b/gio/gfileinputstream.c
@@ -181,7 +181,8 @@ 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 of the request.
+ * @io_priority: the <link linkend="gio-GIOScheduler">I/O priority</link> 
+ *     of the request.
  * @cancellable: optional #GCancellable object, %NULL to ignore. 
  * @callback: callback to call when the request is satisfied
  * @user_data: the data to pass to callback function

diff --git a/gio/gfileoutputstream.c b/gio/gfileoutputstream.c
index d252d54..6dc332e 100644 (file)
--- a/gio/gfileoutputstream.c
+++ b/gio/gfileoutputstream.c
@@ -191,7 +191,8 @@ async_ready_callback_wrapper (GObject *source_object,
  * g_file_output_stream_query_info_async:
  * @stream: a #GFileOutputStream.
  * @attributes: a file attribute query string.
- * @io_priority: the io priority of the request.
+ * @io_priority: the <link linkend="gio-GIOScheduler">I/O priority</link> 
+ *     of the request.
  * @cancellable: optional #GCancellable object, %NULL to ignore. 
  * @callback: callback to call when the request is satisfied
  * @user_data: the data to pass to callback function

diff --git a/gio/gfilteroutputstream.c b/gio/gfilteroutputstream.c
index 982f907..534ea7c 100644 (file)
--- a/gio/gfilteroutputstream.c
+++ b/gio/gfilteroutputstream.c
@@ -380,5 +380,3 @@ g_filter_output_stream_close_finish (GOutputStream  *stream,
 
 #define __G_FILTER_OUTPUT_STREAM_C__
 #include "gioaliasdef.c"
-
-/* vim: ts=2 sw=2 et */

diff --git a/gio/ginputstream.c b/gio/ginputstream.c
index 2bb3d7c..afc82a2 100644 (file)
--- a/gio/ginputstream.c
+++ b/gio/ginputstream.c
@@ -520,7 +520,8 @@ 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 io priority of the request. the io priority of the request
+ * @io_priority: the <link linkend="gio-GIOScheduler">I/O priority</link> 
+ * of the request. 
  * @cancellable: optional #GCancellable object, %NULL to ignore.
  * @callback: callback to call when the request is satisfied
  * @user_data: the data to pass to callback function
@@ -654,7 +655,8 @@ 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 io priority of the request. the io priority of the request
+ * @io_priority: the <link linkend="gio-GIOScheduler">I/O priority</link> 
+ * of the request. 
  * @cancellable: optional #GCancellable object, %NULL to ignore. 
  * @callback: callback to call when the request is satisfied
  * @user_data: the data to pass to callback function
@@ -785,7 +787,8 @@ g_input_stream_skip_finish (GInputStream  *stream,
 /**
  * g_input_stream_close_async:
  * @stream: A #GInputStream.
- * @io_priority: the io priority of the request. the io priority of the request
+ * @io_priority: the <link linkend="gio-GIOScheduler">I/O priority</link> 
+ * of the request. 
  * @cancellable: optional cancellable object
  * @callback: callback to call when the request is satisfied
  * @user_data: the data to pass to callback function

diff --git a/gio/gioscheduler.c b/gio/gioscheduler.c
index f3f9f06..52e2ca6 100644 (file)
--- a/gio/gioscheduler.c
+++ b/gio/gioscheduler.c
@@ -33,6 +33,12 @@
  * Schedules asynchronous I/O operations for integration into the main 
  * event loop (#GMainLoop).
  * 
+ * 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.
  **/
 
 struct _GIOJob {
@@ -188,7 +194,8 @@ run_job_at_idle (gpointer data)
  * @job_func: a #GIOJobFunc.
  * @user_data: a #gpointer.
  * @notify: a #GDestroyNotify.
- * @io_priority: the i/o priority of the request. a #gint.
+ * @io_priority: the <link linkend="gioscheduler">I/O priority</link> 
+ * of the request.
  * @cancellable: optional #GCancellable object, %NULL to ignore.
  *
  * Schedules the I/O Job.
@@ -326,7 +333,6 @@ mainloop_proxy_notify (gpointer data)
  * @block: boolean flag indicating whether or not this job should block.
  * 
  * Sends an I/O job to the application's main loop for processing.
- * 
  **/
 void
 g_io_job_send_to_mainloop (GIOJob         *job,