Changeset 18 for pjproject/main/pjlib/include/pj/ioqueue.h

Timestamp:

Nov 7, 2005 3:47:28 PM (18 years ago)

Author:

bennylp

Message:

Added file I/O and file access API

File:

• pjproject/main/pjlib/include/pj/ioqueue.h (modified) (5 diffs)

pjproject/main/pjlib/include/pj/ioqueue.h

@@ -15 +15 @@
 
 /**
- * @defgroup PJ_IO Network I/O
- * @brief Network I/O
+ * @defgroup PJ_IO Input/Output
+ * @brief Input/Output
  * @ingroup PJ_OS
  *
@@ -53 +53 @@
  * completed.
  *
+ * The I/O Queue can work on both socket and file descriptors. For 
+ * asynchronous file operations however, one must make sure that the correct
+ * file I/O back-end is used, because not all file I/O back-end can be
+ * used with the ioqueue. Please see \ref PJ_FILE_IO for more details.
+ *
  * The framework works natively in platforms where asynchronous operation API
  * exists, such as in Windows NT with IoCompletionPort/IOCP. In other 
@@ -61 +66 @@
  * The I/O queue provides more than just unified abstraction. It also:
  *  - makes sure that the operation uses the most effective way to utilize
- *    the underlying mechanism, to provide the maximum theoritical
+ *    the underlying mechanism, to achieve the maximum theoritical
  *    throughput possible on a given platform.
  *  - choose the most efficient mechanism for event polling on a given
@@ -488 +493 @@
                                           int *addrlen);
 
-
 /**
  * Instruct the I/O Queue to write to the handle. This function will return
@@ -530 +534 @@
 
 /**
- * This function behaves similarly as #pj_ioqueue_write(), except that
- * pj_sock_sendto() (or equivalent) will be called to send the data.
+ * Instruct the I/O Queue to write to the handle. This function will return
+ * immediately (i.e. non-blocking) regardless whether some data has been 
+ * transfered. If the function can't complete immediately, the caller will
+ * be notified about the completion when it calls pj_ioqueue_poll(). If 
+ * operation completes immediately and data has been transfered, the function
+ * returns PJ_SUCCESS and the callback will NOT be called.
  *
  * @param key       the key that identifies the handle.