VirtualBox

Changeset 25723 in vbox for trunk/include


Ignore:
Timestamp:
Jan 11, 2010 2:28:57 PM (15 years ago)
Author:
vboxsync
svn:sync-xref-src-repo-rev:
56466
Message:

iprt/RTSemRW: A little cleanup.

File:
1 edited

Legend:

Unmodified
Added
Removed

  • trunk/include/iprt/semaphore.h

    r25722 r25723  
    668668 *
    669669 * @returns iprt status code.
    670  * @param   RWSem       The Read/Write semaphore to destroy.
    671  */
    672 RTDECL(int)   RTSemRWDestroy(RTSEMRW RWSem);
     670 * @param   hRWSem              Handle to the read/write semaphore.  NIL is
     671 *                              quitly ignored (VINF_SUCCESS).
     672 */
     673RTDECL(int)   RTSemRWDestroy(RTSEMRW hRWSem);
    673674
    674675/**
    … …  
    681682 *          lock validator isn't compiled in or either of the parameters are
    682683 *          invalid.
    683  * @param   hRWSem              The handle to the read/write semaphore.
     684 * @param   hRWSem              Handle to the read/write semaphore.
    684685 * @param   uSubClass           The new sub-class value.
    685686 */
    … …  
    692693 * @retval  VINF_SUCCESS on success.
    693694 * @retval  VERR_INTERRUPT if the wait was interrupted.
    694  * @retval  VERR_INVALID_HANDLE if RWSem is invalid.
    695  *
    696  * @param   RWSem       The Read/Write semaphore to request read access to.
    697  * @param   cMillies    The number of milliseconds to wait.
    698  */
    699 RTDECL(int)   RTSemRWRequestRead(RTSEMRW RWSem, unsigned cMillies);
     695 * @retval  VERR_INVALID_HANDLE if hRWSem is invalid.
     696 *
     697 * @param   hRWSem              Handle to the read/write semaphore.
     698 * @param   cMillies            The number of milliseconds to wait.
     699 */
     700RTDECL(int)   RTSemRWRequestRead(RTSEMRW hRWSem, RTMSINTERVAL cMillies);
    700701
    701702/**
    … …  
    705706 * @retval  VINF_SUCCESS on success.
    706707 * @retval  VERR_INTERRUPT if the wait was interrupted.
    707  * @retval  VERR_INVALID_HANDLE if RWSem is invalid.
    708  *
    709  * @param   RWSem       The Read/Write semaphore to request read access to.
    710  * @param   cMillies    The number of milliseconds to wait.
    711  */
    712 RTDECL(int)   RTSemRWRequestReadNoResume(RTSEMRW RWSem, unsigned cMillies);
     708 * @retval  VERR_INVALID_HANDLE if hRWSem is invalid.
     709 *
     710 * @param   hRWSem              Handle to the read/write semaphore.
     711 * @param   cMillies            The number of milliseconds to wait.
     712 */
     713RTDECL(int)   RTSemRWRequestReadNoResume(RTSEMRW hRWSem, RTMSINTERVAL cMillies);
    713714
    714715/**
    … …  
    718719 * @retval  VINF_SUCCESS on success.
    719720 * @retval  VERR_INTERRUPT if the wait was interrupted.
    720  * @retval  VERR_INVALID_HANDLE if RWSem is invalid.
    721  *
    722  * @param   RWSem       The Read/Write semaphore to request read access to.
    723  * @param   cMillies    The number of milliseconds to wait.
    724  * @param   uId                 Some kind of locking location ID.  Typically a
    725  *                              return address up the stack.  Optional (0).
    726  * @param   pszFile             The file where the lock is being acquired from.
    727  *                              Optional.
    728  * @param   iLine               The line number in that file.  Optional (0).
    729  * @param   pszFunction         The functionn where the lock is being acquired
    730  *                              from.  Optional.
    731  */
    732 RTDECL(int)   RTSemRWRequestReadDebug(RTSEMRW RWSem, unsigned cMillies, RTHCUINTPTR uId, RT_SRC_POS_DECL);
    733 
    734 /**
    735  * Debug version of RTSemRWRequestWriteNoResume that tracks the location.
    736  *
    737  * @returns iprt status code.
    738  * @retval  VINF_SUCCESS on success.
    739  * @retval  VERR_INTERRUPT if the wait was interrupted.
    740  * @retval  VERR_INVALID_HANDLE if RWSem is invalid.
    741  *
    742  * @param   RWSem       The Read/Write semaphore to request read access to.
    743  * @param   cMillies    The number of milliseconds to wait.
    744  * @param   uId                 Some kind of locking location ID.  Typically a
    745  *                              return address up the stack.  Optional (0).
    746  * @param   pszFile             The file where the lock is being acquired from.
    747  *                              Optional.
    748  * @param   iLine               The line number in that file.  Optional (0).
    749  * @param   pszFunction         The functionn where the lock is being acquired
    750  *                              from.  Optional.
    751  */
    752 RTDECL(int)   RTSemRWRequestReadNoResumeDebug(RTSEMRW RWSem, unsigned cMillies, RTHCUINTPTR uId, RT_SRC_POS_DECL);
    753 
    754 /**
    755  * Release read access to a read/write semaphore.
    756  *
    757  * @returns iprt status code.
    758  * @param   RWSem       The Read/Write sempahore to release read access to.
    759  *                      Goes without saying that caller must have read access to the sem.
    760  */
    761 RTDECL(int)   RTSemRWReleaseRead(RTSEMRW RWSem);
    762 
    763 /**
    764  * Request write access to a read/write semaphore, resume on interruption.
    765  *
    766  * @returns iprt status code.
    767  * @retval  VINF_SUCCESS on success.
    768  * @retval  VERR_DEADLOCK if the caller owned the read lock.
    769  * @retval  VERR_INVALID_HANDLE if RWSem is invalid.
    770  *
    771  * @param   RWSem       The Read/Write semaphore to request write access to.
    772  * @param   cMillies    The number of milliseconds to wait.
    773  */
    774 RTDECL(int)   RTSemRWRequestWrite(RTSEMRW RWSem, unsigned cMillies);
    775 
    776 /**
    777  * Request write access to a read/write semaphore, return on interruption.
    778  *
    779  * @returns iprt status code.
    780  * @retval  VINF_SUCCESS on success.
    781  * @retval  VERR_INTERRUPT if the wait was interrupted.
    782  * @retval  VERR_DEADLOCK if the caller owned the read lock.
    783  * @retval  VERR_INVALID_HANDLE if RWSem is invalid.
    784  *
    785  * @param   RWSem       The Read/Write semaphore to request write access to.
    786  * @param   cMillies    The number of milliseconds to wait.
    787  */
    788 RTDECL(int)   RTSemRWRequestWriteNoResume(RTSEMRW RWSem, unsigned cMillies);
    789 
    790 /**
    791  * Debug version of RTSemRWRequestWrite that tracks the location.
    792  *
    793  * @returns IPRT status code, see RTSemRWRequestWrite.
    794  * @param   RWSem               The Read/Write semaphore to request write access
    795  *                              to.
     721 * @retval  VERR_INVALID_HANDLE if hRWSem is invalid.
     722 *
     723 * @param   hRWSem              Handle to the read/write semaphore.
    796724 * @param   cMillies            The number of milliseconds to wait.
    797725 * @param   uId                 Some kind of locking location ID.  Typically a
    … …  
    803731 *                              from.  Optional.
    804732 */
    805 RTDECL(int)  RTSemRWRequestWriteDebug(RTSEMRW RWSem, unsigned cMillies, RTHCUINTPTR uId, RT_SRC_POS_DECL);
     733RTDECL(int)   RTSemRWRequestReadDebug(RTSEMRW hRWSem, RTMSINTERVAL cMillies, RTHCUINTPTR uId, RT_SRC_POS_DECL);
    806734
    807735/**
    808736 * Debug version of RTSemRWRequestWriteNoResume that tracks the location.
    809737 *
    810  * @returns IPRT status code, see RTSemRWRequestWriteNoResume.
    811  * @param   RWSem               The Read/Write semaphore to request write access
    812  *                              to.
     738 * @returns iprt status code.
     739 * @retval  VINF_SUCCESS on success.
     740 * @retval  VERR_INTERRUPT if the wait was interrupted.
     741 * @retval  VERR_INVALID_HANDLE if hRWSem is invalid.
     742 *
     743 * @param   hRWSem              Handle to the read/write semaphore.
    813744 * @param   cMillies            The number of milliseconds to wait.
    814745 * @param   uId                 Some kind of locking location ID.  Typically a
    … …  
    820751 *                              from.  Optional.
    821752 */
    822 RTDECL(int)  RTSemRWRequestWriteNoResumeDebug(RTSEMRW RWSem, unsigned cMillies, RTHCUINTPTR uId, RT_SRC_POS_DECL);
     753RTDECL(int)   RTSemRWRequestReadNoResumeDebug(RTSEMRW hRWSem, RTMSINTERVAL cMillies, RTHCUINTPTR uId, RT_SRC_POS_DECL);
     754
     755/**
     756 * Release read access to a read/write semaphore.
     757 *
     758 * @returns iprt status code.
     759 * @param   hRWSem              Handle to the read/write semaphore.  It goes
     760 *                              without saying that caller must own read
     761 *                              privileges to the semaphore.
     762 */
     763RTDECL(int)   RTSemRWReleaseRead(RTSEMRW hRWSem);
     764
     765/**
     766 * Request write access to a read/write semaphore, resume on interruption.
     767 *
     768 * @returns iprt status code.
     769 * @retval  VINF_SUCCESS on success.
     770 * @retval  VERR_DEADLOCK if the caller owned the read lock.
     771 * @retval  VERR_INVALID_HANDLE if hRWSem is invalid.
     772 *
     773 * @param   hRWSem              Handle to the read/write semaphore.
     774 * @param   cMillies            The number of milliseconds to wait.
     775 */
     776RTDECL(int)   RTSemRWRequestWrite(RTSEMRW hRWSem, RTMSINTERVAL cMillies);
     777
     778/**
     779 * Request write access to a read/write semaphore, return on interruption.
     780 *
     781 * @returns iprt status code.
     782 * @retval  VINF_SUCCESS on success.
     783 * @retval  VERR_INTERRUPT if the wait was interrupted.
     784 * @retval  VERR_DEADLOCK if the caller owned the read lock.
     785 * @retval  VERR_INVALID_HANDLE if hRWSem is invalid.
     786 *
     787 * @param   hRWSem              Handle to the read/write semaphore.
     788 * @param   cMillies            The number of milliseconds to wait.
     789 */
     790RTDECL(int)   RTSemRWRequestWriteNoResume(RTSEMRW hRWSem, RTMSINTERVAL cMillies);
     791
     792/**
     793 * Debug version of RTSemRWRequestWrite that tracks the location.
     794 *
     795 * @returns IPRT status code, see RTSemRWRequestWrite.
     796 * @param   hRWSem              Handle to the read/write semaphore.
     797 * @param   cMillies            The number of milliseconds to wait.
     798 * @param   uId                 Some kind of locking location ID.  Typically a
     799 *                              return address up the stack.  Optional (0).
     800 * @param   pszFile             The file where the lock is being acquired from.
     801 *                              Optional.
     802 * @param   iLine               The line number in that file.  Optional (0).
     803 * @param   pszFunction         The functionn where the lock is being acquired
     804 *                              from.  Optional.
     805 */
     806RTDECL(int)  RTSemRWRequestWriteDebug(RTSEMRW hRWSem, RTMSINTERVAL cMillies, RTHCUINTPTR uId, RT_SRC_POS_DECL);
     807
     808/**
     809 * Debug version of RTSemRWRequestWriteNoResume that tracks the location.
     810 *
     811 * @returns IPRT status code, see RTSemRWRequestWriteNoResume.
     812 * @param   hRWSem              Handle to the read/write semaphore.
     813 * @param   cMillies            The number of milliseconds to wait.
     814 * @param   uId                 Some kind of locking location ID.  Typically a
     815 *                              return address up the stack.  Optional (0).
     816 * @param   pszFile             The file where the lock is being acquired from.
     817 *                              Optional.
     818 * @param   iLine               The line number in that file.  Optional (0).
     819 * @param   pszFunction         The functionn where the lock is being acquired
     820 *                              from.  Optional.
     821 */
     822RTDECL(int)  RTSemRWRequestWriteNoResumeDebug(RTSEMRW hRWSem, RTMSINTERVAL cMillies, RTHCUINTPTR uId, RT_SRC_POS_DECL);
    823823
    824824/**
    … …  
    826826 *
    827827 * @returns iprt status code.
    828  * @param   RWSem       The Read/Write sempahore to release read access to.
    829  *                      Goes without saying that caller must have write access to the sem.
    830  */
    831 RTDECL(int)   RTSemRWReleaseWrite(RTSEMRW RWSem);
     828 * @param   hRWSem              Handle to the read/write semaphore.  Goes
     829 *                              without saying that caller must have write
     830 *                              access to the semaphore.
     831 */
     832RTDECL(int)   RTSemRWReleaseWrite(RTSEMRW hRWSem);
    832833
    833834/**
    … …  
    835836 *
    836837 * @returns true / false accoringly.
    837  * @param   RWSem       The Read/Write semaphore in question.
    838  */
    839 RTDECL(bool)  RTSemRWIsWriteOwner(RTSEMRW RWSem);
     838 * @param   hRWSem              Handle to the read/write semaphore.
     839 */
     840RTDECL(bool)  RTSemRWIsWriteOwner(RTSEMRW hRWSem);
    840841
    841842/**
    … …  
    843844 *
    844845 * @returns The write recursion count (0 if bad semaphore handle).
    845  * @param   RWSem       The Read/Write semaphore in question.
    846  */
    847 RTDECL(uint32_t) RTSemRWGetWriteRecursion(RTSEMRW RWSem);
     846 * @param   hRWSem              Handle to the read/write semaphore.
     847 */
     848RTDECL(uint32_t) RTSemRWGetWriteRecursion(RTSEMRW hRWSem);
    848849
    849850/**
    … …  
    851852 *
    852853 * @returns The read recursion count (0 if bad semaphore handle).
    853  * @param   RWSem       The Read/Write semaphore in question.
    854  */
    855 RTDECL(uint32_t) RTSemRWGetWriterReadRecursion(RTSEMRW RWSem);
     854 * @param   hRWSem              Handle to the read/write semaphore.
     855 */
     856RTDECL(uint32_t) RTSemRWGetWriterReadRecursion(RTSEMRW hRWSem);
    856857
    857858/**
    … …  
    862863 *
    863864 * @returns The read count (0 if bad semaphore handle).
    864  * @param   RWSem       The Read/Write semaphore in question.
    865  */
    866 RTDECL(uint32_t) RTSemRWGetReadCount(RTSEMRW RWSem);
     865 * @param   hRWSem              Handle to the read/write semaphore.
     866 */
     867RTDECL(uint32_t) RTSemRWGetReadCount(RTSEMRW hRWSem);
    867868
    868869/* Strict build: Remap the four request calls to the debug versions. */
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