namedpipes

README

This package provides a simple model for working with named pipes on Unix-like systems. It allows for creating, reading, writing and managing named pipes.

Named Pipes are also called FIFO (First In, First Out) are a special type of files which are used to facilitate two-way communication between processes without storing anything on the disk.

Features

• Non-blocking I/O: Supports non-blocking read and write operations.
• Customizable Polling: Set custom poll intervals and chunk sizes for efficient data transfer.
• Timeouts and Break Events: Easily manage read and write timeouts and handle cancelable operations with break events.

Installation

go get github.com/exonlabs/go-utils/pkg/unix/namedpipes

Usage Examples

https://github.com/exonlabs/go-utils/tree/master/examples/namedpipe

Documentation

Overview

Example

package main

import (
	"fmt"

	"github.com/exonlabs/go-utils/pkg/abc/dictx"
	"github.com/exonlabs/go-utils/pkg/unix/namedpipes"
)

func main() {
	// Path to the pipe (change the path accordingly for your platform)
	pipePath := "/tmp/test_pipe"

	// Create a named pipe
	err := namedpipes.Create(pipePath, 0o666)
	if err != nil {
		fmt.Printf("Failed to create pipe: %v\n", err)
		return
	}
	defer namedpipes.Delete(pipePath) // Ensure the pipe is deleted after use

	// Set up options for the pipe
	options := dictx.Dict{
		"poll_timeout":   0.1,
		"poll_chunksize": 4096,
	}

	// Create a new pipe instance
	pipe := namedpipes.New(pipePath, options)

	// Write data to the pipe
	dataToWrite := []byte("Hello, named pipe!")
	err = pipe.Write(dataToWrite, 1.0)
	if err != nil {
		fmt.Printf("Failed to write to pipe: %v\n", err)
		return
	}

	// Read data from the pipe
	dataRead, err := pipe.Read(1.0)
	if err != nil {
		fmt.Printf("Failed to read from pipe: %v\n", err)
		return
	}

	// Output the read data
	fmt.Printf("Data read from pipe: %s\n", dataRead)
}

Index

• Variables
• func Create(path string, perm os.FileMode) error
• func Delete(path string) error
• type NamedPipe
  • func New(path string, opts dictx.Dict) *NamedPipe
  • func (p *NamedPipe) Cancel()
  • func (c *NamedPipe) Path() string
  • func (p *NamedPipe) Read(timeout float64) ([]byte, error)
  • func (p *NamedPipe) Write(data []byte, timeout float64) error

Examples

• Package

Variables

var (
	// ErrOpen indicates a connection open failure.
	ErrOpen = errors.New("open failed")

	// ErrRead indicates a read failure.
	ErrRead = errors.New("read failed")

	// ErrWrite indicates a write failure.
	ErrWrite = errors.New("write failed")

	// ErrBreak indicates an operation interruption.
	ErrBreak = errors.New("operation break")

	// ErrTimeout indicates that the operation timed out.
	ErrTimeout = errors.New("operation timeout")
)

Functions

func Create

func Create(path string, perm os.FileMode) error

Create creates a named pipe at the specified path with the given permissions.

func Delete

func Delete(path string) error

Delete removes the named pipe at the specified path if it exists.

Types

type NamedPipe

type NamedPipe struct {

	// PollTimeout defines the timeout in seconds for read data polling.
	PollTimeout float64
	// PollChunkSize defines the size of chunks to read during polling.
	PollChunkSize int
	// PollMaxSize defines the maximum size for read polling data.
	// use 0 or negative value to disable max limit for read data polling.
	PollMaxSize int
	// contains filtered or unexported fields
}

NamedPipe represents a named pipe and provides methods for reading, writing, and managing the pipe.

func New

func New(path string, opts dictx.Dict) *NamedPipe

New creates a new NamedPipe instance with options.

The parsed options are:

• poll_timeout: (float64) the timeout in seconds for read data polling. polling timeout value must be > 0.
• poll_chunksize: (int) the size of chunks to read during polling. polling chunk size value must be > 0.
• poll_maxsize: (int) the maximum size for read data. use 0 or negative value to disable max limit for read polling.

func (*NamedPipe) Cancel

func (p *NamedPipe) Cancel()

Cancel triggers the pipe's BreakEvent, cancelling any waiting operations.

func (*NamedPipe) Path

func (c *NamedPipe) Path() string

Path returns the file system path of the named pipe.

func (*NamedPipe) Read

func (p *NamedPipe) Read(timeout float64) ([]byte, error)

Read waits to receive data from the named pipe until a timeout occurs, cancel/close events or an error occurs. timeout=0 waits forever until data is received.

func (*NamedPipe) Write

func (p *NamedPipe) Write(data []byte, timeout float64) error

Write wait to write data to the named pipe until a timeout occurs, cancel/close events or an error occurs. timeout=0 waits forever until data is written.