https://github.com/hayabusa-cloud/iofd
Universal file descriptor abstractions for Unix systems in Go
https://github.com/hayabusa-cloud/iofd
fd golang unix
Last synced: 4 months ago
JSON representation
Universal file descriptor abstractions for Unix systems in Go
- Host: GitHub
- URL: https://github.com/hayabusa-cloud/iofd
- Owner: hayabusa-cloud
- License: mit
- Created: 2025-12-21T10:41:49.000Z (6 months ago)
- Default Branch: main
- Last Pushed: 2026-02-06T09:02:26.000Z (5 months ago)
- Last Synced: 2026-02-06T15:35:32.920Z (5 months ago)
- Topics: fd, golang, unix
- Language: Go
- Homepage: https://code.hybscloud.com/
- Size: 173 KB
- Stars: 2
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.es.md
- Funding: .github/FUNDING.yml
- License: LICENSE
Awesome Lists containing this project
README
# iofd
[](https://pkg.go.dev/code.hybscloud.com/iofd)
[](https://goreportcard.com/report/github.com/hayabusa-cloud/iofd)
[](https://codecov.io/gh/hayabusa-cloud/iofd)
[](https://opensource.org/licenses/MIT)
Abstracciones universales de descriptores de archivo para sistemas Unix en Go.
Idioma: [English](./README.md) | [简体中文](./README.zh-CN.md) | **Español** | [日本語](./README.ja.md) | [Français](./README.fr.md)
## Descripción General
`iofd` proporciona abstracciones mínimas de descriptores de archivo y handles especializados de Linux para el ecosistema Go. Sirve como la abstracción canónica de handles para sistemas de E/S de alto rendimiento.
### Características Principales
- **Cero Sobrecarga**: Todas las interacciones con el kernel via ensamblador `zcall`, evitando los hooks de syscall de Go
- **Handles Especializados**: `EventFD`, `TimerFD`, `PidFD`, `MemFD`, `SignalFD` específicos de Linux
- **Núcleo Multiplataforma**: Las operaciones base de `FD` funcionan en Linux, Darwin y FreeBSD
## Instalación
```bash
go get code.hybscloud.com/iofd
```
## Inicio Rápido
```go
efd, _ := iofd.NewEventFD(0)
efd.Signal(1)
val, _ := efd.Wait() // val == 1
efd.Close()
```
## API
### Tipos Principales
| Tipo | Descripción |
|------|-------------|
| `FD` | Descriptor de archivo universal con operaciones atómicas |
| `EventFD` | eventfd de Linux para señalización entre hilos |
| `TimerFD` | timerfd de Linux para temporizadores de alta resolución |
| `PidFD` | pidfd de Linux para gestión de procesos sin condiciones de carrera |
| `MemFD` | memfd de Linux para archivos anónimos respaldados por memoria |
| `MappedRegion` | Región de memoria mapeada para acceso sin copia |
| `SignalFD` | signalfd de Linux para manejo síncrono de señales |
### Interfaces
| Interfaz | Métodos | Descripción |
|----------|---------|-------------|
| `PollFd` | `Fd() int` | Descriptor de archivo consultable |
| `PollCloser` | `Fd()`, `Close()` | Descriptor consultable cerrable |
| `Handle` | `Fd()`, `Close()`, `Read()`, `Write()` | Handle de E/S completo |
| `Signaler` | `Signal()`, `Wait()` | Mecanismo de señalización |
| `Timer` | `Arm()`, `Disarm()`, `Read()` | Handle de temporizador |
### Operaciones de FD
```go
// Crear FD desde descriptor raw
fd := iofd.NewFD(rawFd)
// Operaciones atómicas
fd.Raw() // Obtener valor int32 raw
fd.Valid() // Verificar si es válido (no negativo)
fd.Close() // Cierre idempotente
// Operaciones de E/S
fd.Read(buf) // Leer bytes
fd.Write(buf) // Escribir bytes
// Flags del descriptor
fd.SetNonblock(true) // Establecer O_NONBLOCK
fd.SetCloexec(true) // Establecer FD_CLOEXEC
fd.Dup() // Duplicar con CLOEXEC
```
### Mapeo de Memoria MemFD
```go
// Crear memfd y establecer tamaño
mfd, _ := iofd.NewMemFD("buffer")
mfd.Truncate(4096)
// Mapear para acceso sin copia
region, _ := mfd.Mmap(4096, iofd.PROT_READ|iofd.PROT_WRITE)
data := region.Bytes() // []byte respaldado por memoria compartida
copy(data, []byte("hello"))
// Limpieza
region.Unmap()
mfd.Close()
```
## Arquitectura
```
┌─────────────────────────────────────────────────────────┐
│ Capa de Aplicación │
├─────────────────────────────────────────────────────────┤
│ EventFD │ TimerFD │ MemFD │ PidFD │ SignalFD │ FD │
├─────────────────────────────────────────────────────────┤
│ iofd │
├─────────────────────────────────────────────────────────┤
│ zcall │
│ (syscalls de cero sobrecarga) │
├─────────────────────────────────────────────────────────┤
│ Kernel Linux │
└─────────────────────────────────────────────────────────┘
```
## Soporte de Plataformas
| Plataforma | FD Núcleo | EventFD | TimerFD | PidFD | MemFD | SignalFD |
|------------|-----------|---------|---------|-------|-------|----------|
| Linux/amd64 | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
| Linux/arm64 | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
| Darwin/arm64 | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ |
| FreeBSD/amd64 | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ |
**Nota**: Los handles especializados (`EventFD`, `TimerFD`, etc.) son primitivas del kernel específicas de Linux. En Darwin y FreeBSD, solo el tipo `FD` núcleo está disponible.
## Consideraciones de Seguridad
- **Operaciones Atómicas**: Todo acceso a FD usa carga/almacenamiento atómico para seguridad concurrente
- **Verificación de Validez**: Use `Valid()` antes de operaciones en descriptores potencialmente cerrados
- **Idempotencia de Close**: `Close()` puede llamarse múltiples veces de forma segura
- **Vida Útil de MappedRegion**: El slice `Bytes()` solo es válido mientras la región esté mapeada
## Licencia
MIT — ver [LICENSE](./LICENSE).
©2025 Hayabusa Cloud Co., Ltd.