mirror of
https://github.com/ruby/ruby.git
synced 2022-11-09 12:17:21 -05:00
include/ruby/internal/intern/select/largesize.h: add doxygen
Must not be a bad idea to improve documents. [ci skip]
This commit is contained in:
卜部昌平
parent
20716f64e9
commit
29201e1ad2
Notes:
git
2021-09-10 20:01:35 +09:00
1 changed files with 125 additions and 11 deletions
|
|
@ -66,26 +66,134 @@
|
|||
|
||||
struct timeval;
|
||||
|
||||
/**
|
||||
* The data structure which wraps the fd_set bitmap used by select(2). This
|
||||
* allows Ruby to use FD sets larger than that allowed by historic limitations
|
||||
* on modern platforms.
|
||||
*/
|
||||
typedef struct {
|
||||
int maxfd;
|
||||
fd_set *fdset;
|
||||
int maxfd; /**< Maximum allowed number of FDs. */
|
||||
fd_set *fdset; /**< File descriptors buffer */
|
||||
} rb_fdset_t;
|
||||
|
||||
RBIMPL_SYMBOL_EXPORT_BEGIN()
|
||||
void rb_fd_init(rb_fdset_t *);
|
||||
void rb_fd_term(rb_fdset_t *);
|
||||
void rb_fd_zero(rb_fdset_t *);
|
||||
void rb_fd_set(int, rb_fdset_t *);
|
||||
void rb_fd_clr(int, rb_fdset_t *);
|
||||
int rb_fd_isset(int, const rb_fdset_t *);
|
||||
void rb_fd_copy(rb_fdset_t *, const fd_set *, int);
|
||||
RBIMPL_ATTR_NONNULL(())
|
||||
/**
|
||||
* (Re-)initialises a fdset. One must be initialised before other `rb_fd_*`
|
||||
* operations. Analogous to calling `malloc(3)` to allocate an `fd_set`.
|
||||
*
|
||||
* @param[out] f An fdset to squash.
|
||||
* @post `f` holds no file descriptors.
|
||||
*/
|
||||
void rb_fd_init(rb_fdset_t *f);
|
||||
|
||||
RBIMPL_ATTR_NONNULL(())
|
||||
/**
|
||||
* Destroys the ::rb_fdset_t, releasing any memory and resources it used. It
|
||||
* must be reinitialised using rb_fd_init() before future use. Analogous to
|
||||
* calling `free(3)` to release memory for an `fd_set`.
|
||||
*
|
||||
* @param[out] f An fdset to squash.
|
||||
* @post `f` holds no file descriptors.
|
||||
*/
|
||||
void rb_fd_term(rb_fdset_t *f);
|
||||
|
||||
RBIMPL_ATTR_NONNULL(())
|
||||
/**
|
||||
* Wipes out the current set of FDs.
|
||||
*
|
||||
* @param[out] f The fdset to clear.
|
||||
* @post `f` has no FDs.
|
||||
*/
|
||||
void rb_fd_zero(rb_fdset_t *f);
|
||||
|
||||
RBIMPL_ATTR_NONNULL(())
|
||||
/**
|
||||
* Sets an fd to a fdset.
|
||||
*
|
||||
* @param[in] fd A file descriptor.
|
||||
* @param[out] f Target fdset.
|
||||
* @post `f` holds `fd`.
|
||||
*/
|
||||
void rb_fd_set(int fd, rb_fdset_t *f);
|
||||
|
||||
RBIMPL_ATTR_NONNULL(())
|
||||
/**
|
||||
* Releases a specific FD from the given fdset.
|
||||
*
|
||||
* @param[in] fd Target FD.
|
||||
* @param[out] f The fdset that holds `fd`.
|
||||
* @post `f` doesn't hold n.
|
||||
*/
|
||||
void rb_fd_clr(int fd, rb_fdset_t *f);
|
||||
|
||||
RBIMPL_ATTR_NONNULL(())
|
||||
RBIMPL_ATTR_PURE()
|
||||
/**
|
||||
* Queries if the given FD is in the given set.
|
||||
*
|
||||
* @param[in] fd Target FD.
|
||||
* @param[in] f The fdset to scan.
|
||||
* @retval 1 Yes there is.
|
||||
* @retval 0 No there isn't.
|
||||
* @see http://www.freebsd.org/cgi/query-pr.cgi?pr=91421
|
||||
*/
|
||||
int rb_fd_isset(int fd, const rb_fdset_t *f);
|
||||
|
||||
/**
|
||||
* Destructively overwrites an fdset with another.
|
||||
*
|
||||
* @param[out] dst Target fdset.
|
||||
* @param[in] src Source fdset.
|
||||
* @param[in] max Maximum number of file descriptors to copy.
|
||||
* @post `dst` is a copy of `src`.
|
||||
*/
|
||||
void rb_fd_copy(rb_fdset_t *dst, const fd_set *src, int max);
|
||||
|
||||
/**
|
||||
* Identical to rb_fd_copy(), except it copies unlimited number of file
|
||||
* descriptors.
|
||||
*
|
||||
* @param[out] dst Target fdset.
|
||||
* @param[in] src Source fdset.
|
||||
* @post `dst` is a copy of `src`.
|
||||
*/
|
||||
void rb_fd_dup(rb_fdset_t *dst, const rb_fdset_t *src);
|
||||
int rb_fd_select(int, rb_fdset_t *, rb_fdset_t *, rb_fdset_t *, struct timeval *);
|
||||
|
||||
/**
|
||||
* Waits for multiple file descriptors at once.
|
||||
*
|
||||
* @param[in] nfds Max FD in everything passed, plus one.
|
||||
* @param[in,out] rfds Set of FDs to wait for reads.
|
||||
* @param[in,out] wfds Set of FDs to wait for writes.
|
||||
* @param[in,out] efds Set of FDs to wait for OOBs.
|
||||
* @param[in,out] timeout Max blocking duration.
|
||||
* @retval -1 Failed, errno set.
|
||||
* @retval 0 Timeout exceeded.
|
||||
* @retval otherwise Total number of file descriptors returned.
|
||||
* @post `rfds` contains readable FDs.
|
||||
* @post `wfds` contains writable FDs.
|
||||
* @post `efds` contains exceptional FDs.
|
||||
* @post `timeout` is the time left.
|
||||
* @note All pointers are allowed to be null pointers.
|
||||
*/
|
||||
int rb_fd_select(int nfds, rb_fdset_t *rfds, rb_fdset_t *wfds, rb_fdset_t *efds, struct timeval *timeout);
|
||||
RBIMPL_SYMBOL_EXPORT_END()
|
||||
|
||||
RBIMPL_ATTR_NONNULL(())
|
||||
RBIMPL_ATTR_PURE()
|
||||
/* :TODO: can this function be __attribute__((returns_nonnull)) or not? */
|
||||
/**
|
||||
* Raw pointer to `fd_set`.
|
||||
*
|
||||
* @param[in] f Target fdset.
|
||||
* @retval NULL `f` is already terminated by rb_fd_term().
|
||||
* @retval otherwise Underlying fd_set.
|
||||
*
|
||||
* @internal
|
||||
*
|
||||
* Extension library must not touch raw pointers. It was a bad idea to let
|
||||
* them use it.
|
||||
*/
|
||||
static inline fd_set *
|
||||
rb_fd_ptr(const rb_fdset_t *f)
|
||||
{
|
||||
|
|
@ -94,6 +202,12 @@ rb_fd_ptr(const rb_fdset_t *f)
|
|||
|
||||
RBIMPL_ATTR_NONNULL(())
|
||||
RBIMPL_ATTR_PURE()
|
||||
/**
|
||||
* It seems this function has no use. Maybe just remove?
|
||||
*
|
||||
* @param[in] f A set.
|
||||
* @return Number of file descriptors stored.
|
||||
*/
|
||||
static inline int
|
||||
rb_fd_max(const rb_fdset_t *f)
|
||||
{
|
||||
|
|
|
|||
Loading…
Add table
Reference in a new issue