ddlog

package
v0.0.0-...-ca5ded8 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Nov 29, 2022 License: MIT Imports: 7 Imported by: 0

Documentation

Overview

Package ddlog contains Go bindings for the DDlog C API.

Index

Constants

This section is empty.

Variables

View Source 
var (
	// StdSomeConstructor is a static string for the "std.Some" DDlog constructor.
	StdSomeConstructor = NewCString("std.Some")
	// StdNoneConstructor is a static string for the "std.None" DDlog constructor.
	StdNoneConstructor = NewCString("std.None")

	// StdLeftConstructor is a static string for the "std.Left" DDlog constructor.
	StdLeftConstructor = NewCString("std.Left")
	// StdRightConstructor is a static string for the "std.Right" DDlog constructor.
	StdRightConstructor = NewCString("std.Right")
)

Functions

func DefaultErrMsgPrinter 

func DefaultErrMsgPrinter(msg string)

DefaultErrMsgPrinter is the default printer used to display DDlog error messages. It prints the messages to stderr. Override it by calling SetErrMsgPrinter.

func SetErrMsgPrinter 

func SetErrMsgPrinter(errMsgPrinter ErrMsgPrinter)

SetErrMsgPrinter overrides the default error message printer used to display DDlog error messages. An errMsgPrinter set to nil be cause all error messages to be dropped. Concurrent calls to the provided errMsgPrinter will be sequential.

Types

type CString 

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

CString is a wrapper around a C string. This is useful when you want to pre-allocate a "static" string once and use it multiple times, as it avoids multiple calls to C.CString / copies.

func NewCString 

func NewCString(s string) CString

NewCString creates a new CString. It invokes C.CString which allocates a C string in the C heap using malloc and copies the contents of the Go string to that location. Because this is a "C pointer", it is not subject to the restrictions of Go pointers (https://golang.org/cmd/cgo/#hdr-Passing_pointers). It is the caller's responsibility to release the allocated memory by calling Free.

func (CString) Free 

func (cs CString) Free()

Free releases the memory allocated in the C heap for the underlying C string. Do not use the Cstring instance after calling this method.

type Command 

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

Command is a wrapper around a DDlog command (ddlog_cmd *). Creating a Command with one of the functions below will never fail; however the command it creates may fail to execute.

func NewDeleteKeyCommand 

func NewDeleteKeyCommand(tableID TableID, r Record) Command

NewDeleteKeyCommand creates a delete-by-key command. tableID must have a primary key for this command to work.

func NewDeleteValCommand 

func NewDeleteValCommand(tableID TableID, r Record) Command

NewDeleteValCommand creates a delete-by-value command.

func NewInsertCommand 

func NewInsertCommand(tableID TableID, r Record) Command

NewInsertCommand creates an insert command.

func NewInsertOrUpdateCommand 

func NewInsertOrUpdateCommand(tableID TableID, r Record) Command

NewInsertOrUpdateCommand creates an insert-or-update command.

type ErrMsgPrinter 

type ErrMsgPrinter func(msg string)

ErrMsgPrinter is the function type for the user-provided printer which will be invoked every time DDlog generates an error.

type OutRecordDumper 

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

OutRecordDumper implements the OutRecordHandler interface: use it to log all the changes received from DDlog to a file.

func NewOutRecordDumper 

func NewOutRecordDumper(changesFileName string) (*OutRecordDumper, error)

NewOutRecordDumper creates an OutRecordDumper instance.

func NewOutRecordStdoutDumper 

func NewOutRecordStdoutDumper() (*OutRecordDumper, error)

NewOutRecordStdoutDumper creates an OutRecordDumper instance which writes all the changes received from DDlog to stdout.

func (*OutRecordDumper) Handle 

func (d *OutRecordDumper) Handle(p *Program, tableID TableID, r Record, weight int64)

Handle logs all the changes received from DDlog to a file. This should roughly match the output format from the DDlog CLI. Errors occurring when writing to disk are ignored.

type OutRecordHandler 

type OutRecordHandler interface {
	// Handle is called for every change reported by DDlog. There will a call to Handle for each
	// new or deleted record (there is no notion of "modified" output record in DDlog). Handle
	// will be called exactly once for each new / deleted record.
	Handle(*Program, TableID, Record, int64)
}

OutRecordHandler defines an interface which lets the client register a "callback" (when creating a Program) for DDlog changes.

type OutRecordSink 

type OutRecordSink struct{}

OutRecordSink implements the OutRecordHandler interface: use it to discard all the changes received from DDlog.

func NewOutRecordSink 

func NewOutRecordSink() (*OutRecordSink, error)

NewOutRecordSink creates an OutRecordSink instance.

func (*OutRecordSink) Handle 

func (s *OutRecordSink) Handle(p *Program, tableID TableID, r Record, weight int64)

Handle will discard all the changes received from DDlog.

type Program 

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

Program is an instance of a DDlog program. It corresponds to ddlog_prog struct in the C API.

func NewProgram 

func NewProgram(workers uint, outRecordHandler OutRecordHandler) (*Program, error)

NewProgram creates a new instance of a DDlog Program. workers is the number of worker threads that DDlog is allowed to use. outRecordHandler implements the Handle method, which will be called every time an output record is created / deleted. If workers is greater than 1, Handle can be called concurrently from multiple worker threads.

func (*Program) ApplyUpdate 

func (p *Program) ApplyUpdate(command Command) error

ApplyUpdate applies a single update to DDlog tables. Must be called as part of a transaction.

func (*Program) ApplyUpdates 

func (p *Program) ApplyUpdates(commands ...Command) error

ApplyUpdates applies updates to DDlog tables. Must be called as part of a transaction.

func (*Program) ApplyUpdatesAsTransaction 

func (p *Program) ApplyUpdatesAsTransaction(commands ...Command) error

ApplyUpdatesAsTransaction starts a transaction, applies updates to DDlog tables and commits the transaction.

func (*Program) ClearRelation 

func (p *Program) ClearRelation(tableID TableID) error

ClearRelation clears all input relations in the provided table.

func (*Program) CommitTransaction 

func (p *Program) CommitTransaction() error

CommitTransaction commits a transaction.

func (*Program) CommitTransactionChangesAsArray 

func (p *Program) CommitTransactionChangesAsArray() error

CommitTransactionChangesAsArray commits a transaction. It uses a different implementation from CommitTransaction, which may yield better performance when many output records are generated. Unlike with CommitTransaction, DDlog will not generate one callback for each output record, but will return an array of output records (with weight). Note that we still generate one OutRecordHandler callback for each output record.

func (*Program) DumpInputSnapshot 

func (p *Program) DumpInputSnapshot(name string) error

DumpInputSnapshot dumps current snapshot of input tables to the provided file in a format suitable for replay debugging.

func (*Program) GetTableID 

func (p *Program) GetTableID(name string) TableID

GetTableID gets the table id by name.

func (*Program) GetTableName 

func (p *Program) GetTableName(tableID TableID) string

GetTableName gets the table name by id.

func (*Program) GetTableOriginalName 

func (p *Program) GetTableOriginalName(name string) string

GetTableOriginalName gets the table's original name, if the relation had an 'original=\"name\"' annotation. Otherwise it returns the table name itself (if it is a legal table name).

func (*Program) RollbackTransaction 

func (p *Program) RollbackTransaction() error

RollbackTransaction rollbacks an ongoing transaction.

func (*Program) StartRecordingCommands 

func (p *Program) StartRecordingCommands(name string) error

StartRecordingCommands creates a file with the provided name to record all the commands sent to DDlog. If the file already exists, it will be truncated.

func (*Program) StartTransaction 

func (p *Program) StartTransaction() error

StartTransaction starts a transaction. Note that DDlog does not support nested or concurrent transactions.

func (*Program) Stop 

func (p *Program) Stop() error

Stop stops the DDlog program and deallocates all the resources allocated by DDlog.

func (*Program) StopRecordingCommands 

func (p *Program) StopRecordingCommands() error

StopRecordingCommands stops recording the commands sent to DDlog to file and closes the file.

type Record 

type Record interface {

	// Free releases the memory associated with a given record. Do not call this method if
	// ownership of the record has already been transferred to DDlog (e.g. by adding the record
	// to a command).
	Free()
	// Dump returns a string representation of a record.
	Dump() string

	// IsNull returns true iff the record is NULL.
	IsNull() bool
	// IsBool returns true iff the record is a boolean record.
	IsBool() bool
	// IsInt returns true iff the record is an integer record.
	IsInt() bool
	// IsString returns true iff the record is a string record.
	IsString() bool
	// IsTuple returns true iff the record is a tuple record.
	IsTuple() bool
	// IsVector returns true iff the record is a vector record.
	IsVector() bool
	// IsMap returns true iff the record is a map record.
	IsMap() bool
	// IsSet returns true iff the record is a set record.
	IsSet() bool
	// IsStruct returns true iff the record is a struct record.
	IsStruct() bool

	// IntBits returns the minimum number of bits required to represent the record if it is an
	// integer record. It returns 0 if the record is not an integer record.
	IntBits() int

	// ToBool returns the value of a boolean record. Behavior is undefined if the record is not
	// a boolean.
	ToBool() bool
	// ToBoolSafe returns the value of a boolean record. Returns an error if the record is not a
	// boolean.
	ToBoolSafe() (bool, error)
	// ToU128 returns the value of an integer record as a Uint128. Behavior is undefined if the
	// record is not an integer or if its value does not fit into 128 bits.
	ToU128() uint128.Uint128
	// ToU128Safe returns the value of an integer record as a Uint128. Returns an error if the
	// record is not an integer or if its value does not fit into 128 bits.
	ToU128Safe() (uint128.Uint128, error)
	// ToU64 returns the value of an integer record as a uint64. Behavior is undefined if the
	// record is not an integer or if its value does not fit into 64 bits.
	ToU64() uint64
	// ToU64Safe returns the value of an integer record as a uint64. Returns an error if the
	// record is not an integer or if its value does not fit into 64 bits.
	ToU64Safe() (uint64, error)
	// ToU32 returns the value of an integer record as a uint32. Behavior is undefined if the
	// record is not an integer or if its value does not fit into 32 bits.
	ToU32() uint32
	// ToU32Safe returns the value of an integer record as a uint32. Returns an error if the
	// record is not an integer or if its value does not fit into 32 bits.
	ToU32Safe() (uint32, error)
	// ToI64 returns the value of an integer record as an int64. Behavior is undefined if the
	// record is not an integer or if its value does not fit into 64 bits.
	ToI64() int64
	// ToI64Safe returns the value of an integer record as an int64. Returns an error if the
	// record is not an integer or if its value does not fit into 64 bits.
	ToI64Safe() (int64, error)
	// ToI32 returns the value of an integer record as an int32. Behavior is undefined if the
	// record is not an integer or if its value does not fit into 32 bits.
	ToI32() int32
	// ToI32Safe returns the value of an integer record as an int32. Returns an error if the
	// record is not an integer or if its value does not fit into 32 bits.
	ToI32Safe() (int32, error)
	// ToString returns the value of a string record. Behavior is undefined if the record is not
	// a string.
	ToString() string
	// ToStringSafe returns the value of a string record. Returns an error if the record is not
	// a string.
	ToStringSafe() (string, error)

	// AsTuple interprets the current record as a tuple, enabling the caller to use methods
	// which are specific to tuples on the returned object. Behavior is undefined if the record
	// is not a tuple.
	AsTuple() RecordTuple
	// AsTupleSafe interprets the current record as a tuple, enabling the caller to use methods
	// which are specific to tuples on the returned object. Returns an error if the record is
	// not a tuple.
	AsTupleSafe() (RecordTuple, error)
	// AsVector interprets the current record as a vector, enabling the caller to use methods
	// which are specific to vectors on the returned object. Behavior is undefined if the record
	// is not a vector.
	AsVector() RecordVector
	// AsVectorSafe interprets the current record as a vector, enabling the caller to use
	// methods which are specific to vectors on the returned object. Returns an error if the
	// record is not a vector.
	AsVectorSafe() (RecordVector, error)
	// AsMap interprets the current record as a map, enabling the caller to use methods which
	// are specific to maps on the returned object. Behavior is undefined if the record is not a
	// map.
	AsMap() RecordMap
	// AsMapSafe interprets the current record as a map, enabling the caller to use methods
	// which are specific to maps on the returned object. Returns an error if the record is not
	// a map.
	AsMapSafe() (RecordMap, error)
	// AsSet interprets the current record as a set, enabling the caller to use methods which
	// are specific to sets on the returned object. Behavior is undefined if the record is not a
	// set.
	AsSet() RecordSet
	// AsSetSafe interprets the current record as a set, enabling the caller to use methods
	// which are specific to sets on the returned object. Returns an error if the record is not
	// a set.
	AsSetSafe() (RecordSet, error)
	// AsStruct interprets the current record as a struct, enabling the caller to use methods
	// which are specific to structs on the returned object. Behavior is undefined if the record
	// is not a struct.
	AsStruct() RecordStruct
	// AsStructSafe interprets the current record as a struct, enabling the caller to use
	// methods which are specific to structs on the returned object. Returns an error if the
	// record is not a struct.
	AsStructSafe() (RecordStruct, error)
	// contains filtered or unexported methods
}

Record represents a DDlog record. It is an interface, rather than simply a wrapper around a ddlog_record pointer, to provide some type-safety. In particular, some methods are not included in this interface because they are specific to a type of record (e.g. Push() for a RecordVector).

func NewRecordBool 

func NewRecordBool(v bool) Record

NewRecordBool creates a boolean record.

func NewRecordI32 

func NewRecordI32(v int32) Record

NewRecordI32 creates a record for a signed integer value. Can be used to populate any DDlog field of type `signed<N>`, `N<=32`.

func NewRecordI64 

func NewRecordI64(v int64) Record

NewRecordI64 creates a record for a signed integer value. Can be used to populate any DDlog field of type `signed<N>`, `N<=64`.

func NewRecordLeft 

func NewRecordLeft(r Record) Record

NewRecordLeft is a convenience wrapper around NewRecordStructStatic for the std.Left constructor.

func NewRecordNone 

func NewRecordNone() Record

NewRecordNone is a convenience wrapper around NewRecordStructStatic for the std.None constructor.

func NewRecordNull 

func NewRecordNull() Record

NewRecordNull returns a NULL record, which can be used as a placeholder for an invalid record.

func NewRecordRight 

func NewRecordRight(r Record) Record

NewRecordRight is a convenience wrapper around NewRecordStructStatic for the std.Right constructor.

func NewRecordSome 

func NewRecordSome(r Record) Record

NewRecordSome is a convenience wrapper around NewRecordStructStatic for the std.Some constructor.

func NewRecordString 

func NewRecordString(v string) Record

NewRecordString creates a record for a string.

func NewRecordU128 

func NewRecordU128(v uint128.Uint128) Record

NewRecordU128 creates a record for an unsigned integer value. Can be used to populate any DDlog field of type `bit<N>`, `N<=128`.

func NewRecordU32 

func NewRecordU32(v uint32) Record

NewRecordU32 creates a record for an unsigned integer value. Can be used to populate any DDlog field of type `bit<N>`, `N<=32`.

func NewRecordU64 

func NewRecordU64(v uint64) Record

NewRecordU64 creates a record for an unsigned integer value. Can be used to populate any DDlog field of type `bit<N>`, `N<=64`.

type RecordMap 

type RecordMap interface {
	Record
	// Push appends a key-value pair to the map.
	Push(rKey, rValue Record)
	// KeyAt returns the i-th key of the map. Returns a NULL record if the map has fewer than i
	// key-value pairs.
	KeyAt(idx int) Record
	// ValueAt returns the i-th value of the map. Returns a NULL record if the map has fewer
	// than i key-value pairs.
	ValueAt(idx int) Record
	// At returns the i-th key-value pair of the map. Returns a NULL record if the map has fewer
	// than i key-value pairs.
	At(idx int) (Record, Record)
	// Size returns the number of key-value pairs in the map.
	Size() int
}

RecordMap extends the Record interface for DDlog records of type map.

func NewRecordMap 

func NewRecordMap(records ...Record) RecordMap

NewRecordMap creates a map record with specified key-value pairs.

type RecordSet 

type RecordSet interface {
	Record
	// Push appends an element to the set.
	Push(rValue Record)
	// At returns the i-th element of the set. Returns a NULL record if the set has fewer than i
	// elements.
	At(idx int) Record
	// Size returns the number of elements in the set.
	Size() int
}

RecordSet extends the Record interface for DDlog records of type set.

func NewRecordSet 

func NewRecordSet(records ...Record) RecordSet

NewRecordSet creates a set record with specified elements.

type RecordStruct 

type RecordStruct interface {
	Record
	// Name returns the constructor name for the struct.
	Name() string
	// At returns the i-th field of the struct. Returns a NULL record if the struct has fewer
	// than i fields.
	At(idx int) Record
}

RecordStruct extends the Record interface for DDlog records of type struct.

func NewRecordStruct 

func NewRecordStruct(constructor string, records ...Record) RecordStruct

NewRecordStruct creates a struct record with specified constructor name and arguments.

func NewRecordStructStatic 

func NewRecordStructStatic(constructor CString, records ...Record) RecordStruct

NewRecordStructStatic creates a struct record with specified constructor name and arguments. Unlike NewRecordStruct, this function takes a CString for the constructor to avoid making an extra copy of the constructor string when it is "static" (known ahead of time).

type RecordTuple 

type RecordTuple interface {
	Record
	// Push appends an element to the tuple.
	Push(rValue Record)
	// At returns the i-th element of the tuple. Returns a NULL record if the tuple has fewer
	// than i elements.
	At(idx int) Record
	// Size returns the number of elements in the tuple.
	Size() int
}

RecordTuple extends the Record interface for DDlog records of type tuple.

func NewRecordPair 

func NewRecordPair(r1, r2 Record) RecordTuple

NewRecordPair is a convenience way to create a 2-tuple. Such tuples are useful when constructing maps out of key-value pairs.

func NewRecordTuple 

func NewRecordTuple(records ...Record) RecordTuple

NewRecordTuple creates a tuple record with specified fields.

type RecordVector 

type RecordVector interface {
	Record
	// Push appends an element to the vector.
	Push(rValue Record)
	// At returns the i-th element of the vector. Returns a NULL record if the vector has fewer
	// than i elements.
	At(idx int) Record
	// Size returns the number of elements in the vector.
	Size() int
}

RecordVector extends the Record interface for DDlog records of type vector.

func NewRecordVector 

func NewRecordVector(records ...Record) RecordVector

NewRecordVector creates a vector record with specified elements.

type TableID 

type TableID uint

TableID is a unique table identifier allocated by DDlog.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.