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

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

Examples

• Package

Constants

const (
	// POLL_TIMEOUT defines the default timeout for polling in seconds.
	POLL_TIMEOUT = 0.1
	// POLL_CHUNKSIZE is the default size of chunks to read during polling.
	POLL_CHUNKSIZE = 4096
	// POLL_MAXSIZE is the default maximum size for polling data.
	POLL_MAXSIZE = 0
)

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 Context

type Context struct {

	// Options defines the optional settings.
	Options dictx.Dict

	// 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
}

Context represents the configuration and state for communication handling.

func NewContext

func NewContext(path string, opts dictx.Dict) *Context

NewContext creates and initializes a new Context instance with optional settings. The parsed options are:

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

func (*Context) Path

func (c *Context) Path() string

Path returns the file system path of the named pipe.

type NamedPipe

type NamedPipe struct {
	// Context containing common attributes and functions.
	*Context
	// 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.

func (*NamedPipe) Cancel

func (p *NamedPipe) Cancel()

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

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.