lib/asio.h

   1 /*
   2  *      UCW Library -- Asynchronous I/O
   3  *
   4  *      (c) 2006 Martin Mares <mj@ucw.cz>
   5  *
   6  *      This software may be freely distributed and used according to the terms
   7  *      of the GNU Lesser General Public License.
   8  */
   9
  10 #ifndef _UCW_ASIO_H
  11 #define _UCW_ASIO_H
  12
  13 #include "lib/workqueue.h"
  14 #include "lib/clists.h"
  15
  16 /*
  17  *  This module takes care of scheduling and executing asynchronous I/O requests
  18  *  on files opened with O_DIRECT. It is primarily used by the fb-direct fastbuf
  19  *  back-end, but you can use it explicitly, too.
  20  *
  21  *  You can define several I/O queues, each for use by a single thread. Requests
  22  *  on a single queue are always processed in order of their submits, requests
  23  *  from different queues may be interleaved (although the current implementation
  24  *  does not do so). Normal read and write requests are returned to their queue
  25  *  when they are completed. Write-back requests are automatically freed when
  26  *  done, but the number of such requests in fly is limited in order to avoid
  27  *  consuming all memory, so a submit of a write-back request can block.
  28  */
  29
  30 struct asio_queue {
  31   uns buffer_size;                      // How large buffers do we use [user-settable]
  32   uns max_writebacks;                   // Maximum number of writeback requests active [user-settable]
  33   uns allocated_requests;
  34   uns running_requests;                 // Total number of running requests
  35   uns running_writebacks;               // How many of them are writebacks
  36   clist idle_list;                      // Recycled requests waiting for get
  37   clist done_list;                      // Finished requests
  38   struct work_queue queue;
  39   uns use_count;                        // For use by the caller
  40 };
  41
  42 enum asio_op {
  43   ASIO_FREE,
  44   ASIO_READ,
  45   ASIO_WRITE,
  46   ASIO_WRITE_BACK,                      // Background write with no success notification
  47 };
  48
  49 struct asio_request {
  50   struct work work;                     // asio_requests are internally just work nodes
  51   struct asio_queue *queue;
  52   byte *buffer;
  53   int fd;
  54   enum asio_op op;
  55   uns len;
  56   int status;
  57   int returned_errno;
  58   int submitted;
  59   void *user_data;                      // For use by the caller
  60 };
  61
  62 void asio_init_queue(struct asio_queue *q);                     // Initialize a new queue
  63 void asio_cleanup_queue(struct asio_queue *q);
  64 struct asio_request *asio_get(struct asio_queue *q);            // Get an empty request
  65 void asio_submit(struct asio_request *r);                       // Submit the request (can block if too many writebacks)
  66 struct asio_request *asio_wait(struct asio_queue *q);           // Wait for the first finished request, NULL if no more
  67 void asio_put(struct asio_request *r);                          // Return a finished request for recycling
  68 void asio_sync(struct asio_queue *q);                           // Wait until all requests are finished
  69
  70 #endif  /* !_UCW_ASIO_H */