Ruby: include/ruby/internal/intern/select/win32.h File Reference

Ruby 3.2.5p208 (2024-07-26 revision 31d0f1a2e7dbfb60731d1f05b868e1d578cda493)

Data Structures | Functions
win32.h File Reference

Public APIs to provide rb_fd_select(). More...

`#include "ruby/internal/dosish.h"`
`#include "ruby/internal/attr/nonnull.h"`
`#include "ruby/internal/attr/pure.h"`
`#include "ruby/internal/attr/noalias.h"`
`#include "ruby/internal/dllexport.h"`
`#include "ruby/assert.h"`

Go to the source code of this file.

## Data Structures
struct | rb_fdset_t
| The data structure which wraps the fd_set bitmap used by select(2). More...

## Functions
void | rb_fd_init (rb_fdset_t *f)
| (Re-)initialises a fdset.
void | rb_fd_term (rb_fdset_t *f)
| Destroys the rb_fdset_t, releasing any memory and resources it used.
void | rb_fd_set (int fd, rb_fdset_t *f)
| Sets an fd to a fdset.
void | rb_w32_fd_copy (rb_fdset_t *dst, const fd_set *src, int max)
| Destructively overwrites an fdset with another.
void | rb_w32_fd_dup (rb_fdset_t *dst, const rb_fdset_t *src)
| Identical to rb_w32_fd_copy(), except it copies unlimited number of file descriptors.
static void | rb_fd_zero (rb_fdset_t *f)
| Wipes out the current set of FDs.
static void | rb_fd_clr (int n, rb_fdset_t *f)
| Releases a specific FD from the given fdset.
static int | rb_fd_isset (int n, rb_fdset_t *f)
| Queries if the given FD is in the given set.
static void | rb_fd_copy (rb_fdset_t *dst, const fd_set *src, int n)
| Destructively overwrites an fdset with another.
static void | rb_fd_dup (rb_fdset_t *dst, const rb_fdset_t *src)
| Identical to rb_fd_copy(), except it copies unlimited number of file descriptors.
static int | rb_fd_select (int n, rb_fdset_t *rfds, rb_fdset_t *wfds, rb_fdset_t *efds, struct timeval *timeout)
| Waits for multiple file descriptors at once.
static fd_set * | rb_fd_ptr (const rb_fdset_t *f)
| Raw pointer to `fd_set`.
static int | rb_fd_max (const rb_fdset_t *f)
| It seems this function has no use.

## Detailed Description

Public APIs to provide rb_fd_select().

Author
  Ruby developers ruby-.nosp@m.core.nosp@m.@ruby.nosp@m.-lan.nosp@m.g.org

Copyright
  This file is a part of the programming language Ruby. Permission is hereby granted, to either redistribute and/or modify this file, provided that the conditions mentioned in the file COPYING are met. Consult the file for details.

Warning
  Symbols prefixed with either `RBIMPL` or `rbimpl` are implementation details. Don't take them as canon. They could rapidly appear then vanish. The name (path) of this header file is also an implementation detail. Do not expect it to persist at the place it is now. Developers are free to move it anywhere anytime at will.

Note
  To ruby-core: remember that this header can be possibly recursively included from extension libraries written in C++. Do not expect for instance `__VA_ARGS__` is always available. We assume C99 for ruby itself but we don't assume languages of extension libraries. They could be written in C++98.

Definition in file win32.h.

## Function Documentation

## ◆ rb_fd_clr()

static void rb_fd_clr | ( | int | n,
|  | rb_fdset_t * | f )
| inlinestatic

Releases a specific FD from the given fdset.

Parameters

  [in] | n | Target FD.
  [out] | f | The fdset that holds `n`.

Postcondition
  `f` doesn't hold n.

Definition at line 136 of file win32.h.

## ◆ rb_fd_copy()

static void rb_fd_copy | ( | rb_fdset_t * | dst,
|  | const fd_set * | src,
|  | int | n )
| inlinestatic

Destructively overwrites an fdset with another.

Parameters

  [out] | dst | Target fdset.
  [in] | src | Source fdset.
  [in] | n | Maximum number of file descriptors to copy.

Postcondition
  `dst` is a copy of `src`.

Definition at line 166 of file win32.h.

## ◆ rb_fd_dup()

static void rb_fd_dup | ( | rb_fdset_t * | dst,
|  | const rb_fdset_t * | src )
| inlinestatic

Identical to rb_fd_copy(), except it copies unlimited number of file descriptors.

Parameters

  [out] | dst | Target fdset.
  [in] | src | Source fdset.

Postcondition
  `dst` is a copy of `src`.

Definition at line 181 of file win32.h.

## ◆ rb_fd_init()

void rb_fd_init | ( | rb_fdset_t * | f | ) |

(Re-)initialises a fdset.

One must be initialised before other `rb_fd_*` operations. Analogous to calling `malloc(3)` to allocate an `fd_set`.

Parameters

  [out] | f | An fdset to squash.

Postcondition
  `f` holds no file descriptors.

## ◆ rb_fd_isset()

static int rb_fd_isset | ( | int | n,
|  | rb_fdset_t * | f )
| inlinestatic

Queries if the given FD is in the given set.

Parameters

  [in] | n | Target FD.
  [in] | f | The fdset to scan.

Return values

  1 | Yes there is.
  0 | No there isn't.

Definition at line 151 of file win32.h.

## ◆ rb_fd_max()

static int rb_fd_max | ( | const rb_fdset_t * | f | ) |
| inlinestatic

It seems this function has no use.

Maybe just remove?

Parameters

  [in] | f | A set.

Returns
  Number of file descriptors stored.

Definition at line 251 of file win32.h.

## ◆ rb_fd_ptr()

static fd_set * rb_fd_ptr | ( | const rb_fdset_t * | f | ) |
| inlinestatic

Raw pointer to `fd_set`.

Parameters

  [in] | f | Target fdset.

Return values

  NULL | `f` is already terminated by rb_fd_term().
  otherwise | Underlying fd_set.

Definition at line 237 of file win32.h.

## ◆ rb_fd_select()

static int rb_fd_select | ( | int | n,
|  | rb_fdset_t * | rfds,
|  | rb_fdset_t * | wfds,
|  | rb_fdset_t * | efds,
|  | struct timeval * | timeout )
| inlinestatic

Waits for multiple file descriptors at once.

Parameters

  [in] | n | Max FD in everything passed, plus one.
  [in,out] | rfds | Set of FDs to wait for reads.
  [in,out] | wfds | Set of FDs to wait for writes.
  [in,out] | efds | Set of FDs to wait for OOBs.
  [in,out] | timeout | Max blocking duration.

Return values

  -1 | Failed, errno set.
  0 | Timeout exceeded.
  otherwise | Total number of file descriptors returned.

Postcondition
  `rfds` contains readable FDs.
  `wfds` contains writable FDs.
  `efds` contains exceptional FDs.
  `timeout` is the time left.

Note
  All pointers are allowed to be null pointers.

Definition at line 212 of file win32.h.

## ◆ rb_fd_set()

void rb_fd_set | ( | int | fd,
|  | rb_fdset_t * | f )

Sets an fd to a fdset.

Parameters

  [in] | fd | A file descriptor.
  [out] | f | Target fdset.

Postcondition
  `f` holds `fd`.

## ◆ rb_fd_term()

void rb_fd_term | ( | rb_fdset_t * | f | ) |

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`.

Parameters

  [out] | f | An fdset to squash.

Postcondition
  `f` holds no file descriptors.

## ◆ rb_fd_zero()

static void rb_fd_zero | ( | rb_fdset_t * | f | ) |
| inlinestatic

Wipes out the current set of FDs.

Parameters

  [out] | f | The fdset to clear.

Postcondition
  `f` has no FDs.

Definition at line 122 of file win32.h.

## ◆ rb_w32_fd_copy()

void rb_w32_fd_copy | ( | rb_fdset_t * | dst,
|  | const fd_set * | src,
|  | int | max )

Destructively overwrites an fdset with another.

Parameters

  [out] | dst | Target fdset.
  [in] | src | Source fdset.
  [in] | max | Maximum number of file descriptors to copy.

Postcondition
  `dst` is a copy of `src`.

Definition at line 2962 of file win32.c.

Referenced by rb_fd_copy(), and rb_w32_fd_copy().

## ◆ rb_w32_fd_dup()

void rb_w32_fd_dup | ( | rb_fdset_t * | dst,
|  | const rb_fdset_t * | src )

Identical to rb_w32_fd_copy(), except it copies unlimited number of file descriptors.

Parameters

  [out] | dst | Target fdset.
  [in] | src | Source fdset.

Postcondition
  `dst` is a copy of `src`.

Definition at line 2977 of file win32.c.

Referenced by rb_fd_dup(), and rb_w32_fd_dup().