Added a very brief introduction to ASIO.

[libucw.git] / lib / asio.h

diff --git a/lib/asio.h b/lib/asio.h
index 45c7fb9f40d1899040814e9b8e9b08f7513833bf..6773c81fd1333d95a610381b509f9dd2ed7922ef 100644 (file)
--- a/lib/asio.h
+++ b/lib/asio.h
@@ -13,7 +13,19 @@
 #include "lib/workqueue.h"
 #include "lib/clists.h"
 
-/* FIXME: Comment, especially on request ordering */
+/*
+ *  This module takes care of scheduling and executing asynchronous I/O requests
+ *  on files opened with O_DIRECT. It is primarily used by the fb-direct fastbuf
+ *  back-end, but you can use it explicitly, too.
+ *
+ *  You can define several I/O queues, each for use by a single thread. Requests
+ *  on a single queue are always processed in order of their submits, requests
+ *  from different queues may be interleaved (although the current implementation
+ *  does not do so). Normal read and write requests are returned to their queue
+ *  when they are completed. Write-back requests are automatically freed when
+ *  done, but the number of such requests in fly is limited in order to avoid
+ *  consuming all memory, so a submit of a write-back request can block.
+ */
 
 struct asio_queue {
   uns buffer_size;                     // How large buffers do we use [user-settable]
@@ -24,6 +36,7 @@ struct asio_queue {
   clist idle_list;                     // Recycled requests waiting for get
   clist done_list;                     // Finished requests
   struct work_queue queue;
+  uns use_count;                       // For use by the caller
 };
 
 enum asio_op {
@@ -43,6 +56,7 @@ struct asio_request {
   int status;
   int returned_errno;
   int submitted;
+  void *user_data;                     // For use by the caller
 };
 
 void asio_init_queue(struct asio_queue *q);                    // Initialize a new queue