VirtualBox

Changeset 18961 in vbox for trunk


Ignore:
Timestamp:
Apr 16, 2009 6:14:47 PM (16 years ago)
Author:
vboxsync
svn:sync-xref-src-repo-rev:
46044
Message:

iprt/file.h: Some adjustements to the Async I/O API.

File:
1 edited

Legend:

Unmodified
Added
Removed

  • trunk/include/iprt/file.h

    r18912 r18961  
    763763RTDECL(void) RTFileReadAllFree(void *pvFile, size_t cbFile);
    764764
     765
     766
    765767/** @page pg_rt_asyncio RT File async I/O API
    766768 *
    … …  
    769771
    770772/**
    771  * Create a async I/O request handle.
    772  *
    773  * @returns IPRT status code.
    774  * @param   phRequest          Where to store the request handle.
    775  */
    776 RTDECL(int) RTFileAioReqCreate(PRTFILEAIOREQ phRequest);
    777 
    778 /**
    779  * Destroy a async I/O request handle.
    780  *
    781  * @returns nothing
    782  * @param   hRequest           The request handle.
    783  */
    784 RTDECL(void) RTFileAioReqDestroy(RTFILEAIOREQ hRequest);
    785 
    786 /**
    787  * Prepare a read task for a async request.
    788  *
    789  * @returns IPRT status code.
    790  * @param   hRequest        The request handle.
    791  * @param   File            The file to read from.
     773 * Creates an async I/O request handle.
     774 *
     775 * @returns IPRT status code.
     776 * @param   phReq           Where to store the request handle.
     777 */
     778RTDECL(int) RTFileAioReqCreate(PRTFILEAIOREQ phReq);
     779
     780/**
     781 * Destroys an async I/O request handle.
     782 *
     783 * @param   hReq            The request handle.
     784 */
     785RTDECL(void) RTFileAioReqDestroy(RTFILEAIOREQ hReq);
     786
     787/**
     788 * Prepares an async read request.
     789 *
     790 * @returns IPRT status code.
     791 *
     792 * @param   hReq            The request handle.
     793 * @param   hFile           The file to read from.
    792794 * @param   off             The offset to start reading at.
    793795 * @param   pvBuf           Where to store the read bits.
    794796 * @param   cbRead          Number of bytes to read.
    795797 * @param   pvUser          Opaque user data associated with this request which
    796  *                          can be retrieved with RTFileAioReqGetUser()
    797  */
    798 RTDECL(int) RTFileAioReqPrepareRead(RTFILEAIOREQ hRequest, RTFILE File,
    799                                     RTFOFF off, void *pvBuf, size_t cbRead,
    800                                     void *pvUser);
    801 
    802 /**
    803  * Prepare a write task for a async request.
    804  *
    805  * @returns IPRT status code.
    806  * @param   hRequest        The request handle.
    807  * @param   File            The file to write to.
     798 *                          can be retrieved with RTFileAioReqGetUser().
     799 */
     800RTDECL(int) RTFileAioReqPrepareRead(RTFILEAIOREQ hReq, RTFILE hFile, RTFOFF off,
     801                                    void *pvBuf, size_t cbRead, void *pvUser);
     802
     803/**
     804 * Prepares an async write request.
     805 *
     806 * @returns IPRT status code.
     807 *
     808 * @param   hReq            The request handle.
     809 * @param   hFile           The file to write to.
    808810 * @param   off             The offset to start writing at.
    809811 * @param   pvBuf           Where to store the written bits.
    810812 * @param   cbRead          Number of bytes to write.
    811813 * @param   pvUser          Opaque user data associated with this request which
    812  *                          can be retrieved with RTFileAioReqGetUser()
    813  */
    814 RTDECL(int) RTFileAioReqPrepareWrite(RTFILEAIOREQ hRequest, RTFILE File,
    815                                      RTFOFF off, void *pvBuf, size_t cbWrite,
    816                                      void *pvUser);
    817 
    818 /**
    819  * Prepare a async flush of all cached data associated with a file handle.
    820  *
    821  * @returns IPRT status code.
    822  * @param   hRequest        The request handle.
    823  * @param   File            The file to flush.
     814 *                          can be retrieved with RTFileAioReqGetUser().
     815 */
     816RTDECL(int) RTFileAioReqPrepareWrite(RTFILEAIOREQ hReq, RTFILE hFile, RTFOFF off,
     817                                     void *pvBuf, size_t cbWrite, void *pvUser);
     818
     819/**
     820 * Prepares an async flush of all cached data associated with a file handle.
     821 *
     822 * @returns IPRT status code.
     823 *
     824 * @param   hReq            The request handle.
     825 * @param   hFile           The file to flush.
    824826 * @param   pvUser          Opaque user data associated with this request which
    825  *                          can be retrieved with RTFileAioReqGetUser()
    826  */
    827 RTDECL(int) RTFileAioReqPrepareFlush(RTFILEAIOREQ Request, RTFILE File, void *pvUser);
    828 
    829 /**
    830  * Get the opaque user data associated with the given request.
     827 *                          can be retrieved with RTFileAioReqGetUser().
     828 *
     829 * @remarks May also flush other caches on some platforms.
     830 */
     831RTDECL(int) RTFileAioReqPrepareFlush(RTFILEAIOREQ hReq, RTFILE hFile, void *pvUser);
     832
     833/**
     834 * Gets the opaque user data associated with the given request.
    831835 *
    832836 * @returns Opaque user data.
    833  * @retval  NULL if there is no user data associated with the given request.
    834  * @param   hRequest        The request handle.
    835  */
    836 RTDECL(void *) RTFileAioReqGetUser(RTFILEAIOREQ hRequest);
     837 * @retval  NULL if the request hasn't been prepared yet.
     838 *
     839 * @param   hReq            The request handle.
     840 */
     841RTDECL(void *) RTFileAioReqGetUser(RTFILEAIOREQ hReq);
    837842
    838843/**
    … …  
    844849 * @retval  VERR_FILE_AIO_COMPLETED   If the request could not be canceled because it already completed.
    845850 *
    846  * @param   hRequest   The request to cancel.
    847  */
    848 RTDECL(int) RTFileAioReqCancel(RTFILEAIOREQ hRequest);
    849 
    850 /**
    851  * Get the status of a completed request.
     851 * @param   hReq            The request to cancel.
     852 */
     853RTDECL(int) RTFileAioReqCancel(RTFILEAIOREQ hReq);
     854
     855/**
     856 * Gets the status of a completed request.
    852857 *
    853858 * @returns The IPRT status code of the given request.
    854  * @param   hRequest          The request handle.
    855  * @param   pcbTransferred    Where to store the number of bytes transfered.
    856  */
    857 RTDECL(int) RTFileAioReqGetRC(RTFILEAIOREQ hRequest, size_t *pcbTransfered);
    858 
    859 /**
    860  * Create an async I/O context.
    861  *
    862  * @returns IPRT status code.
    863  * @param   phAioContext    Where to store the aio context handle.
     859 * @retval  VERR_FILE_AIO_IN_PROGRESS if the request isn't yet completed.
     860 *
     861 * @param   hReq            The request handle.
     862 * @param   pcbTransferred  Where to store the number of bytes transfered.
     863 *                          Optional since it is not relevant for all kinds of
     864 *                          requests.
     865 */
     866RTDECL(int) RTFileAioReqGetRC(RTFILEAIOREQ hReq, size_t *pcbTransfered);
     867
     868
     869
     870/**
     871 * Creates an async I/O context.
     872 *
     873 * @todo briefly explain what an async context is here or in the page
     874 *       above.
     875 *
     876 * @returns IPRT status code.
     877 * @param   phAioCtx        Where to store the async I/O context handle.
    864878 * @param   cAioReqsMax     How many async I/O requests the context should be capable
    865  *                          to handle. -1 means that the context should support an
    866  *                          unlimited number of requests.
    867  */
    868 RTDECL(int) RTFileAioCtxCreate(RTFILEAIOCTX phAioContext, int cAioReqsMax);
    869 
    870 /**
    871  * Destroy an async I/O context.
    872  *
    873  * @returns IPRT status code.
    874  * @param   hAioContext     The aio context handle.
    875  */
    876 RTDECL(int) RTFileAioCtxDestroy(RTFILEAIOCTX hAioContext);
     879 *                          to handle. Pass RTFILEAIO_UNLIMITED_REQS if the
     880 *                          context should support an unlimited number of
     881 *                          requests.
     882 */
     883RTDECL(int) RTFileAioCtxCreate(RTFILEAIOCTX phAioCtx, uint32_t cAioReqsMax);
     884
     885/** Unlimited number of requests.
     886 * Used with RTFileAioCtxCreate and RTFileAioCtxGetMaxReqCount. */
     887#define RTFILEAIO_UNLIMITED_REQS    UINT32_MAX
     888
     889/**
     890 * Destroys an async I/O context.
     891 *
     892 * @returns IPRT status code.
     893 * @param   hAioCtx         The async I/O context handle.
     894 */
     895RTDECL(int) RTFileAioCtxDestroy(RTFILEAIOCTX hAioCtx);
    877896
    878897/**
    … …  
    880899 *
    881900 * @returns Maximum number of tasks the context can handle.
    882  *          -1 if there is no limit.
    883  *
    884  * @param   hAioContext     The aio context handle.
     901 *          RTFILEAIO_UNLIMITED_REQS if there is no limit.
     902 *
     903 * @param   hAioCtx         The async I/O context handle.
    885904 *                          If NIL_RTAIOCONTEXT is passed the maximum value
    886905 *                          which can be passed to RTFileAioCtxCreate()
    887906 *                          is returned.
    888907 */
    889 RTDECL(int) RTFileAioCtxGetMaxReqCount(RTFILEAIOCTX hAioContext);
    890 
    891 /**
    892  * Submit an array of requests to an aio context for processing.
    893  *
    894  * @returns IPRT status code.
    895  * @param   hAioContext     The context handle.
    896  * @param   aRequests       Array of requests to submit.
    897  * @param   cRequests       Number of requests in the array.
    898  */
    899 RTDECL(int) RTFileAioCtxSubmit(RTFILEAIOCTX hAioContext, RTFILEAIOREQ aRequests[], unsigned cRequests);
    900 
    901 /**
    902  * Wait for request completion.
    903  *
    904  * @returns IPRT status code.
    905  * @retval  VERR_NUMBER_TOO_BIG      If cMinRequests or cMaxRequests exceeds limit.
    906  * @retval  VERR_TIMEOUT             If the timeout value expired before at least cMinRequests requests finished.
    907  * @retval  VERR_INTERRUPTED         If the completion context was interrupted with RTFileAioCtxWakeup().
    908  * @retval  VERR_FILE_AIO_NO_REQUEST If there is no pending request to wait for completion.
    909  *
    910  * @param   hAioContext            The aio context handle to get completed requests from.
    911  * @param   cMinRequests           The minimum number of requests which have to complete until this function returns.
    912  * @param   apRequestsCompleted    Where to store the completed tasks.
    913  * @param   cMaxRequests           The maximum number of requests the array can hold.
    914  * @param   pcRequestsCompleted    Where to store the number of requests completed.
    915  * @param   cMillisTimeout         Maximum number of millisceonds to wait before returning.
    916  *                                 Use RT_INDEFINITE_WAIT to wait forever.
    917  */
    918 RTDECL(int) RTFileAioCtxWaitForCompletion(RTFILEAIOCTX hAioContext, int cMinRequests,
    919                                           RTFILEAIOREQ apRequestsCompleted[], int cMaxRequests,
    920                                           int *pcRequestsCompleted, unsigned cMillisTimeout);
    921 
    922 /**
    923  * Let's return RTFileAioCtxWaitForCompletion() immediateley.
    924  *
    925  * @returns IPRT status code.
    926  * @param   hAioContext            The context handle to wakeup.
    927  */
    928 RTDECL(int) RTFileAioCtxWakeup(RTFILEAIOCTX hAioContext);
     908RTDECL(uint32_t) RTFileAioCtxGetMaxReqCount(RTFILEAIOCTX hAioCtx);
     909
     910/**
     911 * Submits a set of requests to an async I/O context for processing.
     912 *
     913 * @returns IPRT status code.
     914 *
     915 * @param   hAioCtx         The async I/O context handle.
     916 * @param   pahReqs         Pointer to an array of request handles.
     917 * @param   cReqs           The number of entries in the array.
     918 *
     919 * @remarks @a cReqs uses the type size_t while it really is a uint32_t, this is
     920 *          to avoid annoying warnings when using RT_ELEMENTS and similar
     921 *          macros.
     922 */
     923RTDECL(int) RTFileAioCtxSubmit(RTFILEAIOCTX hAioCtx, PRTFILEAIOREQ phReqs, size_t cReqs);
     924
     925/**
     926 * Waits for request completion.
     927 *
     928 * @returns IPRT status code.
     929 * @retval  VERR_INVALID_POINTER     If pcReqs or/and pahReqs are invalid.
     930 * @retval  VERR_INVALID_HANDLE      If hAioCtx is invalid.
     931 * @retval  VERR_OUT_OF_RANGE        If cMinReqs is larger than cReqs.
     932 * @retval  VERR_INVALID_PARAMETER   If cReqs is 0.
     933 * @retval  VERR_TIMEOUT             If cMinReqs didn't complete before the
     934 *                                   timeout expired.
     935 * @retval  VERR_INTERRUPTED         If the completion context was interrupted
     936 *                                   by RTFileAioCtxWakeup().
     937 * @retval  VERR_FILE_AIO_NO_REQUEST If there are no pending request.
     938 *
     939 * @param   hAioCtx         The async I/O context handle to wait and get
     940 *                          completed requests from.
     941 * @param   cMinReqs        The minimum number of requests which have to
     942 *                          complete before this function returns.
     943 * @param   cMillisTimeout  The number of milliseconds to wait before returning
     944 *                          VERR_TIMEOUT. Use RT_INDEFINITE_WAIT to wait
     945 *                          forever.
     946 * @param   pahReqs         Pointer to an array where the handles of the
     947 *                          completed requests will be stored on success.
     948 * @param   cReqs           The number of entries @a pahReqs can hold.
     949 * @param   pcReqs          Where to store the number of returned (complete)
     950 *                          requests. This will always be set.
     951 *
     952 * @remarks The wait will be resume if interrupted by a signal. An
     953 *          RTFileAioCtxWaitNoResume variant can be added later if it becomes
     954 *          necessary.
     955 *
     956 * @remarks @a cMinReqs and @a cReqs use the type size_t while they really are
     957 *          uint32_t's, this is to avoid annoying warnings when using
     958 *          RT_ELEMENTS and similar macros.
     959 */
     960RTDECL(int) RTFileAioCtxWait(RTFILEAIOCTX hAioCtx, size_t cMinReqs, unsigned cMillisTimeout,
     961                             PRTFILEAIOREQ paphReqs, size_t cReqs, uint32_t *pcReqs);
     962
     963/**
     964 * Forces any RTFileAioCtxWait() call from another thread to return immediately.
     965 *
     966 * @returns IPRT status code.
     967 *
     968 * @param   hAioCtx         The handle of the async I/O context to wakeup.
     969 */
     970RTDECL(int) RTFileAioCtxWakeup(RTFILEAIOCTX hAioCtx);
    929971
    930972#endif /* IN_RING3 */
Note: See TracChangeset for help on using the changeset viewer.

© 2025 Oracle Support Privacy / Do Not Sell My Info Terms of Use Trademark Policy Automated Access Etiquette