Cadenas, drains y multishot: dependencias dentro del ring

Hasta ahora cada sqe era independiente: los enviabas en lote y el kernel los ejecutaba en cualquier orden. Pero el trabajo real tiene dependencias —recibe y luego reenvía, abre y luego lee y luego cierra— y expresarlas volviendo a espacio de usuario entre paso y paso desperdicia todo lo que ganaste con el lote. io_uring deja describir esas dependencias dentro del anillo: enlaces que ordenan operaciones y peticiones multishot que se rearman solas. La E/S empieza a parecerse a un programa.

IOSQE_IO_LINK: encadenar operaciones

Marcar sqe->flags |= IOSQE_IO_LINK crea una cadena: el siguiente sqe no arranca hasta que este complete. El caso canónico es un proxy que recibe de un socket y reenvía a otro sin volver a espacio de usuario entre medias.

/* Cadena recv -> send: reenviar lo recibido sin pasar por userspace */
struct io_uring_sqe *sqe;

sqe = io_uring_get_sqe(&ring);
io_uring_prep_recv(sqe, conn_fd, buf, len, 0);
sqe->flags |= IOSQE_IO_LINK;         /* el send NO arranca hasta que este recv complete */

sqe = io_uring_get_sqe(&ring);
io_uring_prep_send(sqe, peer_fd, buf, len, 0);
io_uring_submit(&ring);              /* un solo envío para las dos operaciones dependientes */

La semántica de fallo es lo importante: si un eslabón devuelve error, la cadena se corta y todos los eslabones siguientes se cancelan con -ECANCELED. Ojo con el valor: si el recv es corto, el send de arriba enviaría len bytes contando basura; una cadena que dependa del resultado (no solo de la finalización) exige longitudes fijas, MSG_WAITALL, o partir en dos pasos. El enlace ordena, no propaga valores por sí solo.

Todos los eslabones de una cadena se envían en un único io_uring_submit: el kernel construye la lista enlazada al leer los sqe y la ejecuta entera sin devolverte el control entre pasos. Por defecto intenta cada operación en línea, de forma no bloqueante; solo si bloquearía la delega a un hilo trabajador (io-wq). Puedes forzar esa ejecución asíncrona con IOSQE_ASYNC cuando sabes de antemano que la operación va a dormir, evitando el intento en línea que fracasaría.

Cadenas con descriptores directos

Cuando el eslabón siguiente necesita un descriptor que produjo el anterior —abrir y luego leer— la pieza que lo hace funcionar son los descriptores directos de la lección 1: openat_direct deposita el descriptor en una ranura conocida y el read la usa con IOSQE_FIXED_FILE.

/* open -> read -> close encadenados, pasando el descriptor por la tabla registrada */
sqe = io_uring_get_sqe(&ring);
io_uring_prep_openat_direct(sqe, AT_FDCWD, path, O_RDONLY, 0, /*file_index=*/7);
sqe->flags |= IOSQE_IO_LINK;

sqe = io_uring_get_sqe(&ring);
io_uring_prep_read(sqe, /*index=*/7, buf, len, 0);
sqe->flags |= (IOSQE_FIXED_FILE | IOSQE_IO_LINK);

sqe = io_uring_get_sqe(&ring);
io_uring_prep_close_direct(sqe, /*file_index=*/7);
io_uring_submit(&ring);              /* tres operaciones, un envío, cero regresos a userspace */

HARDLINK y DRAIN: matices del orden

IOSQE_IO_LINK corta la cadena al primer error. A veces quieres que continúe pase lo que pase (por ejemplo, cerrar siempre aunque la lectura falle): eso es IOSQE_IO_HARDLINK, que mantiene el orden pero no aborta ante un fallo del eslabón previo.

sqe->flags |= IOSQE_IO_HARDLINK;     /* enlace duro: ordena, pero no cancela si el previo falla */

Distinto es IOSQE_IO_DRAIN, que no es un enlace local entre vecinos sino una barrera global: la operación marcada no arranca hasta que todo lo enviado antes en el anillo haya completado, y nada posterior la adelanta. Sirve para puntos de sincronización, como un fsync que debe ver todas las escrituras previas.

sqe->flags |= IOSQE_IO_DRAIN;        /* barrera: espera a que TODO lo previo del ring complete */

El drain es caro: obliga a vaciar todo lo pendiente y frena el paralelismo del anillo, así que se reserva para verdaderos puntos de consistencia. No lo confundas con el enlace: LINK ordena dos vecinos y deja que el resto del anillo vuele en paralelo; DRAIN es una pared que atraviesa todo el flujo.

Un enlace tiene un peligro: si un eslabón se cuelga —un recv de un cliente que nunca envía—, la cadena queda bloqueada. Para eso existe IORING_OP_LINK_TIMEOUT, un temporizador enlazado que cancela la operación previa si tarda demasiado:

/* LINK_TIMEOUT: cancelar el recv del eslabón previo si supera 5 segundos */
struct __kernel_timespec ts = { .tv_sec = 5 };
sqe = io_uring_get_sqe(&ring);
io_uring_prep_recv(sqe, fd, buf, len, 0);
sqe->flags |= IOSQE_IO_LINK;                 /* el timeout se enlaza a este recv */

sqe = io_uring_get_sqe(&ring);
io_uring_prep_link_timeout(sqe, &ts, 0);     /* si el recv tarda, recibe -ECANCELED y el timeout -ETIME */
io_uring_submit(&ring);

Un tercer modificador, IOSQE_ASYNC, no toca el orden sino el dónde se ejecuta la operación:

/* Forzar ejecución en un hilo io-wq cuando sabes que la operación va a bloquear */
struct io_uring_sqe *sqe = io_uring_get_sqe(&ring);
io_uring_prep_read(sqe, fd_lento, buf, len, 0);
sqe->flags |= IOSQE_ASYNC;           /* salta el intento en línea no bloqueante */
io_uring_submit(&ring);

flowchart LR
subgraph Enlace_local
  L1[recv] -->|LINK| L2[send] -->|LINK| L3[close]
end
subgraph Barrera_global
  D0[op A] --> B[fsync con DRAIN]
  D1[op B] --> B
  B --> D2[op posterior]
end

Multishot: una petición, muchos completados

Un accept normal produce un CQE y hay que reenviarlo para la siguiente conexión: un envío por conexión. El modo multishot invierte esa proporción: una sola sqe acepta conexiones indefinidamente y postea un CQE por cada una. El flag IORING_CQE_F_MORE indica que la petición sigue armada.

/* accept multishot: UNA sqe acepta conexiones sin cesar */
struct io_uring_sqe *sqe = io_uring_get_sqe(&ring);
io_uring_prep_multishot_accept(sqe, listen_fd, NULL, NULL, 0);
io_uring_submit(&ring);

struct io_uring_cqe *cqe;
while (io_uring_wait_cqe(&ring, &cqe) == 0) {
	int conn_fd = cqe->res;                   /* cada conexión entrante es un CQE */
	if (!(cqe->flags & IORING_CQE_F_MORE)) {
		/* F_MORE=0: la petición multishot terminó; hay que re-armarla */
	}
	io_uring_cqe_seen(&ring, cqe);
}

Multishot existe también para poll, que se vuelve una suscripción de eventos en vez de un aviso de un solo uso: en lugar de rearmar el poll tras cada evento como obliga epoll en disparo por flanco, lo armas una vez y recibes un CQE por cada transición.

/* poll multishot: una suscripción que dispara un CQE por cada evento, sin rearmar */
struct io_uring_sqe *sqe = io_uring_get_sqe(&ring);
io_uring_prep_poll_multishot(sqe, fd, POLLIN);
io_uring_submit(&ring);
/* mientras cqe->flags tenga IORING_CQE_F_MORE, la suscripción sigue activa */

Y para recv, que necesita búferes proporcionados (lección 4). Si la cola de completado se desborda, el kernel puede terminar la petición multishot —limpia F_MORE— y toca al programa re-armarla.