README

sio

GoDoc

sio is a pure Go implementation of SIO (Serial I/O).

Installation

$ go get go-hep.org/x/hep/sio

Documentation

The documentation is browsable at godoc.org: https://godoc.org/go-hep.org/x/hep/sio

Example

package main

import (
	"fmt"
	"io"

	"go-hep.org/x/hep/sio"
)

type LCRunHeader struct {
	RunNbr   int32
	Detector string
	Descr    string
	SubDets  []string
}

func main() {
	fname := "c_sim.slcio"
	fmt.Printf(">>> opening [%s]\n", fname)

	f, err := sio.Open(fname)
	if err != nil {
		panic(err)
	}
	defer f.Close()

	var runhdr LCRunHeader
	runhdr.RunNbr = 42
	rec := f.Record("LCRunHeader")
	rec.SetUnpack(true)
	rec.Connect("RunHeader", &runhdr)

	fmt.Printf("::: [%s]\n", f.Name())
	fmt.Printf("::: [%s]\n", f.FileName())
	for {
		fmt.Printf("-----------------------------------------------\n")
		var rec *sio.Record

		rec, err = f.ReadRecord()
		fmt.Printf("***\n")
		if err != nil {
			if err == io.EOF {
				break
			}
			panic(err)
		}
		if rec == nil {
			fmt.Printf("** no record!\n")
			break
		}

		fmt.Printf(">> record: %s\n", rec.Name())
		if rec.Name() == "LCRunHeader" {
			fmt.Printf("runnbr: %d\n", runhdr.RunNbr)
			fmt.Printf("det:    %q\n", runhdr.Detector)
			dets := "["
			for i, det := range runhdr.SubDets {
				dets += fmt.Sprintf("%q", det)
				if i+1 != len(runhdr.SubDets) {
					dets += ", "
				}
			}
			dets += "]"
			fmt.Printf("dets:   %s\n", dets)
		}
	}
}

TODO

  • implement read/write pointers
  • implement buffered i/o
  • handle big files (ie: file offsets as int64)

Bibliography

Documentation

Overview

    Package sio implements a record-oriented persistency mechanism.

    Index

    Constants

    This section is empty.

    Variables

    View Source
    var (
    	ErrStreamNoRecMarker   = errors.New("sio: no record marker found")
    	ErrRecordNoBlockMarker = errors.New("sio: no block marker found")
    	ErrBlockConnected      = errors.New("sio: block already connected")
    
    	// ErrBlockShortRead means that the deserialization of a SIO block
    	// read too few bytes with regard to what was written out in the
    	// Block header length.
    	ErrBlockShortRead = errors.New("sio: read too few bytes")
    )

    Functions

    This section is empty.

    Types

    type Block

    type Block interface {
    	Codec
    	Versioner
    
    	Name() string
    }

      Block is the interface implemented by an object that can be stored to (and loaded from) an SIO stream.

      type Codec

      type Codec interface {
      	Marshaler
      	Unmarshaler
      }

        Code is the interface implemented by an object that can unmarshal and marshal itself from and to a binary, sio-compatible, form.

        type Decoder

        type Decoder struct {
        	// contains filtered or unexported fields
        }

          Decoder decodes SIO streams. Decoder provides a nice API to deal with errors that may occur during decoding.

          func NewDecoder

          func NewDecoder(r Reader) *Decoder

            NewDecoder creates a new Decoder reading from the provided sio.Reader.

            func (*Decoder) Decode

            func (dec *Decoder) Decode(ptr interface{})

              Decode reads the next value from the input sio stream and stores it in the data, an empty interface value wrapping a pointer to a concrete value.

              func (*Decoder) Err

              func (dec *Decoder) Err() error

                Err returns the first encountered error while decoding, if any.

                func (*Decoder) Pointer

                func (dec *Decoder) Pointer(ptr interface{})

                  Pointer marks a (pointer to a) pointer, assigning it a unique identifier, so links between values (inside a given SIO record) can be rebuilt.

                  func (*Decoder) Tag

                  func (dec *Decoder) Tag(ptr interface{})

                    Tag tags a pointer, assigning it a unique identifier, so links between values (inside a given SIO record) can be rebuilt.

                    type Encoder

                    type Encoder struct {
                    	// contains filtered or unexported fields
                    }

                      Encoder encodes values into a SIO stream. Encoder provides a nice API to deal with errors that may occur during encoding.

                      func NewEncoder

                      func NewEncoder(w Writer) *Encoder

                        NewEncoder creates a new Encoder writing to the provided sio.Writer.

                        func (*Encoder) Encode

                        func (enc *Encoder) Encode(data interface{})

                          Encode writes the next value to the output sio stream.

                          func (*Encoder) Err

                          func (dec *Encoder) Err() error

                            Err returns the first encountered error while decoding, if any.

                            func (*Encoder) Pointer

                            func (enc *Encoder) Pointer(ptr interface{})

                              Pointer marks a (pointer to a) pointer, assigning it a unique identifier, so links between values (inside a given SIO record) can be stored.

                              func (*Encoder) Tag

                              func (enc *Encoder) Tag(ptr interface{})

                                Tag tags a pointer, assigning it a unique identifier, so links between values (inside a given sio record) can be stored.

                                type Linker

                                type Linker interface {
                                	LinkSio(v uint32) error
                                }

                                  Linker is the interface implemented by an object that needs to recompute (internal) pointers, after the sio layer had performed pointer tagging/chasing relocation.

                                  type Marshaler

                                  type Marshaler interface {
                                  	MarshalSio(w Writer) error
                                  }

                                    Marshaler is the interface implemented by an object that can marshal itself into a binary, sio-compatible, form.

                                    type Operation

                                    type Operation int
                                    const (
                                    	OpRead Operation = iota
                                    	OpWrite
                                    )

                                    type Reader

                                    type Reader interface {
                                    	io.Reader
                                    
                                    	Versioner
                                    	Tag(ptr interface{}) error
                                    	Pointer(ptr interface{}) error
                                    }

                                      Reader is the interface that wraps the basic io.Reader interface and adds SIO pointer tagging capabilities.

                                      type Record

                                      type Record struct {
                                      	// contains filtered or unexported fields
                                      }

                                        Record manages blocks of data

                                        func (*Record) Compress

                                        func (rec *Record) Compress() bool

                                          Compress returns the compression flag

                                          func (*Record) Connect

                                          func (rec *Record) Connect(name string, ptr interface{}) error

                                            Connect connects a Block to this Record (for reading or writing)

                                            func (*Record) Disconnect

                                            func (rec *Record) Disconnect()

                                              Disconnect disconnects all blocks previously connected to this Record (for reading or writing.)

                                              func (*Record) Name

                                              func (rec *Record) Name() string

                                                Name returns the name of this record

                                                func (*Record) Options

                                                func (rec *Record) Options() uint32

                                                  Options returns the options of this record.

                                                  func (*Record) SetCompress

                                                  func (rec *Record) SetCompress(compress bool)

                                                    SetCompress sets or resets the compression flag

                                                    func (*Record) SetUnpack

                                                    func (rec *Record) SetUnpack(unpack bool)

                                                      SetUnpack sets whether to unpack incoming records

                                                      func (*Record) Unpack

                                                      func (rec *Record) Unpack() bool

                                                        Unpack returns whether to unpack incoming records

                                                        type Stream

                                                        type Stream struct {
                                                        	// contains filtered or unexported fields
                                                        }

                                                          Stream manages operations of a single RIO stream.

                                                          func Create

                                                          func Create(fname string) (*Stream, error)

                                                            Create opens and connects a RIO stream to a file for writing

                                                            func Open

                                                            func Open(fname string) (*Stream, error)

                                                              Open opens and connects a RIO stream to a file for reading

                                                              func (*Stream) Close

                                                              func (stream *Stream) Close() error

                                                                Close closes a stream and the underlying file

                                                                func (*Stream) CurPos

                                                                func (stream *Stream) CurPos() int64

                                                                  CurPos returns the current position in the file

                                                                  -1 if error
                                                                  

                                                                  func (*Stream) DelRecord

                                                                  func (stream *Stream) DelRecord(n string)

                                                                    DelRecord removes the Record with name n from this Stream. DelRecord is a no-op if such a Record was not known to the Stream.

                                                                    func (*Stream) Fd

                                                                    func (stream *Stream) Fd() uintptr

                                                                      Fd returns the integer Unix file descriptor referencing the underlying open file.

                                                                      func (*Stream) FileName

                                                                      func (stream *Stream) FileName() string

                                                                        FileName returns the name of the file connected to that stream

                                                                        func (*Stream) HasRecord

                                                                        func (stream *Stream) HasRecord(n string) bool

                                                                          HasRecord returns whether a Record with name n has been added to this Stream

                                                                          func (*Stream) Mode

                                                                          func (stream *Stream) Mode() (os.FileMode, error)

                                                                            Mode returns the stream mode (as os.FileMode)

                                                                            func (*Stream) Name

                                                                            func (stream *Stream) Name() string

                                                                              Name returns the stream name

                                                                              func (*Stream) ReadRecord

                                                                              func (stream *Stream) ReadRecord() (*Record, error)

                                                                                ReadRecord reads the next record

                                                                                func (*Stream) Record

                                                                                func (stream *Stream) Record(name string) *Record

                                                                                  Record adds a Record to the list of records to read/write or returns the Record with that name.

                                                                                  func (*Stream) Records

                                                                                  func (stream *Stream) Records() []*Record

                                                                                    Records returns the list of Records currently attached to this Stream.

                                                                                    func (*Stream) Seek

                                                                                    func (stream *Stream) Seek(offset int64, whence int) (int64, error)

                                                                                      Seek sets the offset for the next Read or Write on the stream to offset, interpreted according to whence: 0 means relative to the origin of the file, 1 means relative to the current offset, and 2 means relative to the end. It returns the new offset and an error, if any.

                                                                                      func (*Stream) SetCompressionLevel

                                                                                      func (stream *Stream) SetCompressionLevel(lvl int)

                                                                                        SetCompressionLevel sets the (zlib) compression level

                                                                                        func (*Stream) Stat

                                                                                        func (stream *Stream) Stat() (os.FileInfo, error)

                                                                                          Stat returns the FileInfo structure describing underlying file. If there is an error, it will be of type *os.PathError.

                                                                                          func (*Stream) Sync

                                                                                          func (stream *Stream) Sync() error

                                                                                            Sync commits the current contents of the stream to stable storage.

                                                                                            func (*Stream) WriteRecord

                                                                                            func (stream *Stream) WriteRecord(record *Record) error

                                                                                            type Unmarshaler

                                                                                            type Unmarshaler interface {
                                                                                            	UnmarshalSio(r Reader) error
                                                                                            }

                                                                                              Unmarshaler is the interface implemented by an object that can unmarshal a binary, sio-compatible, representation of itself.

                                                                                              type Versioner

                                                                                              type Versioner interface {
                                                                                              	VersionSio() uint32
                                                                                              }

                                                                                                Versioner is the interface implemented by an object that tells which version of SIO serialization/deserialization it supports.

                                                                                                type Writer

                                                                                                type Writer interface {
                                                                                                	io.Writer
                                                                                                
                                                                                                	Versioner
                                                                                                	Tag(ptr interface{}) error
                                                                                                	Pointer(ptr interface{}) error
                                                                                                }

                                                                                                  Writer is the interface that wraps the basic io.Writer interface and adds SIO pointer tagging capabilities.

                                                                                                  Directories

                                                                                                  Path Synopsis
                                                                                                  cmd