hyperscan

package module
v0.0.0-...-1e1dae7 Latest Latest
Warning

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

 Go to latest Published: Jan 19, 2022 License: Apache-2.0, MIT Imports: 13 Imported by: 0

README

gohs travis github go report Go Reference Apache MIT

Golang binding for Intel's HyperScan regex matching library: hyperscan.io

Build

Note: gohs will use Hyperscan v5 API by default, you can also build for Hyperscan v4 with hyperscan_v4 tag.

go get -u -tags hyperscan_v4 github.com/flier/gohs/hyperscan

License

This project is licensed under either of Apache License (LICENSE-APACHE) or MIT license (LICENSE-MIT) at your option.

Contribution

Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in Futures by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.

Documentation

Index

Examples

Constants

View Source 
const (
	// FloatNumber for matching floating point numbers
	FloatNumber = `(?:` +
		`[-+]?[0-9]*\.?[0-9]+([eE][-+]?[0-9]+)?.)`

	// IPv4Address for matching IPv4 address
	IPv4Address = `(?:` +
		`(?:25[0-5]|2[0-4][0-9]|[01]?[0-9][0-9]?\.){3}` +
		`(?:25[0-5]|2[0-4][0-9]|[01]?[0-9][0-9]?))`

	// EmailAddress for matching email address
	EmailAddress = `(?:` +
		`^[A-Za-z0-9](([_\.\-]?[a-zA-Z0-9]+)*)@` +
		`([A-Za-z0-9]+)(([\.\-]?[a-zA-Z0-9]+)*)\.([A-Za-z]{2,})$)`

	// CreditCard for matching credit card number
	CreditCard = `(?:` +
		`4[0-9]{12}(?:[0-9]{3})?|` +
		`5[1-5][0-9]{14}|` +
		`3[47][0-9]{13}|` +
		`3(?:0[0-5]|[68][0-9])[0-9]{11}|` +
		`6(?:011|5[0-9]{2})[0-9]{12}|` +
		`(?:2131|1800|35\d{3})\d{11})` // JCB
)
View Source 
const UnboundedMaxWidth = C.UINT_MAX

UnboundedMaxWidth represents the pattern expression has an unbounded maximum width

Variables

This section is empty.

Functions

func Match 

func Match(pattern string, data []byte) (bool, error)

Match reports whether the byte slice b contains any match of the regular expression pattern.

Example 
package main

import (
	"fmt"

	"gitee.com/ebayboy/hyperscan"
)

func main() {
	matched, err := hyperscan.Match(`foo.*`, []byte(`seafood`))
	fmt.Println(matched, err)
	matched, err = hyperscan.Match(`bar.*`, []byte(`seafood`))
	fmt.Println(matched, err)
	matched, err = hyperscan.Match(`a(b`, []byte(`seafood`))
	fmt.Println(matched, err)
}

Output:

true <nil>
false <nil>
false invalid pattern: a(b, Missing close parenthesis for group started at index 1.

func MatchReader 

func MatchReader(pattern string, reader io.Reader) (bool, error)

MatchReader reports whether the text returned by the Reader contains any match of the regular expression pattern.

Example 
package main

import (
	"fmt"
	"strings"

	"gitee.com/ebayboy/hyperscan"
)

func main() {
	s := strings.NewReader(strings.Repeat("a", 4096) + `seafood`)
	matched, err := hyperscan.MatchReader(`foo.*`, s)
	fmt.Println(matched, err)
	matched, err = hyperscan.MatchReader(`bar.*`, s)
	fmt.Println(matched, err)
	matched, err = hyperscan.MatchReader(`a(b`, s)
	fmt.Println(matched, err)
}

Output:

true <nil>
false <nil>
false invalid pattern: a(b, Missing close parenthesis for group started at index 1.

func MatchString 

func MatchString(pattern string, s string) (matched bool, err error)

MatchString reports whether the string s contains any match of the regular expression pattern.

func Quote 

func Quote(s string) string

Quote returns a quoted string literal representing s.

func SerializedDatabaseSize 

func SerializedDatabaseSize(data []byte) (int, error)

SerializedDatabaseSize reports the size that would be required by a database if it were deserialized.

func ValidPlatform 

func ValidPlatform() error

ValidPlatform test the current system architecture.

func Version 

func Version() string

Version identify this release version. The return version is a string containing the version number of this release build and the date of the build.

Types

type BlockDatabase 

type BlockDatabase interface {
	Database
	BlockScanner
	BlockMatcher
}

BlockDatabase scan the target data that is a discrete, contiguous block which can be scanned in one call and does not require state to be retained.

func NewBlockDatabase 

func NewBlockDatabase(patterns ...*Pattern) (BlockDatabase, error)

NewBlockDatabase create a block database base on the patterns.

func UnmarshalBlockDatabase 

func UnmarshalBlockDatabase(data []byte) (BlockDatabase, error)

UnmarshalBlockDatabase reconstruct a block database from a stream of bytes.

type BlockMatcher 

type BlockMatcher interface {
	// Find returns a slice holding the text of the leftmost match in b of the regular expression.
	// A return value of nil indicates no match.
	Find(data []byte) []byte

	// FindIndex returns a two-element slice of integers defining the location of the leftmost match in b of the regular expression.
	// The match itself is at b[loc[0]:loc[1]]. A return value of nil indicates no match.
	FindIndex(data []byte) []int

	// FindAll is the 'All' version of Find; it returns a slice of all successive matches of the expression,
	// as defined by the 'All' description in the package comment. A return value of nil indicates no match.
	FindAll(data []byte, n int) [][]byte

	// FindAllIndex is the 'All' version of FindIndex; it returns a slice of all successive matches of the expression,
	// as defined by the 'All' description in the package comment. A return value of nil indicates no match.
	FindAllIndex(data []byte, n int) [][]int

	// FindString returns a string holding the text of the leftmost match in s of the regular expression.
	// If there is no match, the return value is an empty string, but it will also be empty
	// if the regular expression successfully matches an empty string. Use FindStringIndex if it is necessary to distinguish these cases.
	FindString(s string) string

	// FindStringIndex returns a two-element slice of integers defining the location of the leftmost match in s of the regular expression.
	// The match itself is at s[loc[0]:loc[1]]. A return value of nil indicates no match.
	FindStringIndex(s string) []int

	// FindAllString is the 'All' version of FindString; it returns a slice of all successive matches of the expression,
	// as defined by the 'All' description in the package comment. A return value of nil indicates no match.
	FindAllString(s string, n int) []string

	// FindAllStringIndex is the 'All' version of FindStringIndex; it returns a slice of all successive matches of the expression,
	// as defined by the 'All' description in the package comment. A return value of nil indicates no match.
	FindAllStringIndex(s string, n int) [][]int

	// Match reports whether the pattern database matches the byte slice b.
	Match(b []byte) bool

	// MatchString reports whether the pattern database matches the string s.
	MatchString(s string) bool
}

BlockMatcher implements regular expression search.

type BlockScanner 

type BlockScanner interface {
	// This is the function call in which the actual pattern matching takes place for block-mode pattern databases.
	Scan(data []byte, scratch *Scratch, handler MatchHandler, context interface{}) error
}

BlockScanner is the block (non-streaming) regular expression scanner.

Example 
package main

import (
	"fmt"

	"gitee.com/ebayboy/hyperscan"
)

func main() {
	// Pattern with `L` flag enable leftmost start of match reporting.
	p, err := hyperscan.ParsePattern(`/foo(bar)+/L`)
	if err != nil {
		fmt.Println("parse pattern failed,", err)
		return
	}

	// Create new block database with pattern
	db, err := hyperscan.NewBlockDatabase(p)
	if err != nil {
		fmt.Println("create database failed,", err)
		return
	}
	defer db.Close()

	// Create new scratch for scanning
	s, err := hyperscan.NewScratch(db)
	if err != nil {
		fmt.Println("create scratch failed,", err)
		return
	}
	defer func() {
		_ = s.Free()
	}()

	// Record matching text
	type Match struct {
		from uint64
		to   uint64
	}
	var matches []Match
	handler := hyperscan.MatchHandler(func(id uint, from, to uint64, flags uint, context interface{}) error {
		matches = append(matches, Match{from, to})
		return nil
	})

	data := []byte("hello foobarbar!")

	// Scan data block with handler
	if err := db.Scan(data, s, handler, nil); err != nil {
		fmt.Println("database scan failed,", err)
		return
	}

	// Hyperscan will reports all matches
	for _, m := range matches {
		fmt.Println("match [", m.from, ":", m.to, "]", string(data[m.from:m.to]))
	}

}

Output:

match [ 6 : 12 ] foobar
match [ 6 : 15 ] foobarbar

type CompileFlag 

type CompileFlag uint

CompileFlag represents a pattern flag 

const (
	// Caseless represents set case-insensitive matching.
	Caseless CompileFlag = C.HS_FLAG_CASELESS
	// DotAll represents matching a `.` will not exclude newlines.
	DotAll CompileFlag = C.HS_FLAG_DOTALL
	// MultiLine set multi-line anchoring.
	MultiLine CompileFlag = C.HS_FLAG_MULTILINE
	// SingleMatch set single-match only mode.
	SingleMatch CompileFlag = C.HS_FLAG_SINGLEMATCH
	// AllowEmpty allow expressions that can match against empty buffers.
	AllowEmpty CompileFlag = C.HS_FLAG_ALLOWEMPTY
	// Utf8Mode enable UTF-8 mode for this expression.
	Utf8Mode CompileFlag = C.HS_FLAG_UTF8
	// UnicodeProperty enable Unicode property support for this expression.
	UnicodeProperty CompileFlag = C.HS_FLAG_UCP
	// PrefilterMode enable prefiltering mode for this expression.
	PrefilterMode CompileFlag = C.HS_FLAG_PREFILTER
	// SomLeftMost enable leftmost start of match reporting.
	SomLeftMost CompileFlag = C.HS_FLAG_SOM_LEFTMOST
)
const (
	// Combination represents logical combination.
	Combination CompileFlag = C.HS_FLAG_COMBINATION
	// Quiet represents don't do any match reporting.
	Quiet CompileFlag = C.HS_FLAG_QUIET
)

func ParseCompileFlag 

func ParseCompileFlag(s string) (CompileFlag, error)

ParseCompileFlag parse the compile pattern flags from string 

i	Caseless 		Case-insensitive matching
s	DotAll			Dot (.) will match newlines
m	MultiLine		Multi-line anchoring
H	SingleMatch		Report match ID at most once (`o` deprecated)
V	AllowEmpty		Allow patterns that can match against empty buffers (`e` deprecated)
8	Utf8Mode		UTF-8 mode (`u` deprecated)
W	UnicodeProperty		Unicode property support (`p` deprecated)
P	PrefilterMode		Prefiltering mode (`f` deprecated)
L	SomLeftMost		Leftmost start of match reporting (`l` deprecated)
C	Combination		Logical combination of patterns (Hyperscan 5.0)
Q	Quiet			Quiet at matching (Hyperscan 5.0)

func (CompileFlag) String 

func (flags CompileFlag) String() string

type CpuFeature 

type CpuFeature int

CpuFeature is the CPU feature support flags 

const (
	// AVX2 is a CPU features flag indicates that the target platform supports AVX2 instructions.
	AVX2 CpuFeature = C.HS_CPU_FEATURES_AVX2
	// AVX512 is a CPU features flag indicates that the target platform supports AVX512 instructions, specifically AVX-512BW. Using AVX512 implies the use of AVX2.
	AVX512 CpuFeature = C.HS_CPU_FEATURES_AVX512
)

type Database 

type Database interface {
	// Provides information about a database.
	Info() (DbInfo, error)

	// Provides the size of the given database in bytes.
	Size() (int, error)

	// Free a compiled pattern database.
	Close() error

	// Serialize a pattern database to a stream of bytes.
	Marshal() ([]byte, error)

	// Reconstruct a pattern database from a stream of bytes at a given memory location.
	Unmarshal([]byte) error
}

Database is an immutable database that can be used by the Hyperscan scanning API.

func Compile 

func Compile(expr string) (Database, error)

Compile a regular expression and returns, if successful, a pattern database in the block mode that can be used to match against text.

func MustCompile 

func MustCompile(expr string) Database

MustCompile is like Compile but panics if the expression cannot be parsed. It simplifies safe initialization of global variables holding compiled regular expressions.

func UnmarshalDatabase 

func UnmarshalDatabase(data []byte) (Database, error)

UnmarshalDatabase reconstruct a pattern database from a stream of bytes.

type DatabaseBuilder 

type DatabaseBuilder struct {
	// Array of patterns to compile.
	Patterns []*Pattern

	// Compiler mode flags that affect the database as a whole. (Default: block mode)
	Mode ModeFlag

	// If not nil, the platform structure is used to determine the target platform for the database.
	// If nil, a database suitable for running on the current host platform is produced.
	Platform Platform
}

DatabaseBuilder is a type to help to build up a database

func (*DatabaseBuilder) AddExpressionWithFlags 

func (b *DatabaseBuilder) AddExpressionWithFlags(expr Expression, flags CompileFlag) *DatabaseBuilder

AddExpressionWithFlags add more expressions with flags to the database.

func (*DatabaseBuilder) AddExpressions 

func (b *DatabaseBuilder) AddExpressions(exprs ...Expression) *DatabaseBuilder

AddExpressions add more expressions to the database.

func (*DatabaseBuilder) Build 

func (b *DatabaseBuilder) Build() (Database, error)

Build a database base on the expressions and platform.

type DbInfo 

type DbInfo string

DbInfo identify the version and platform information for the supplied database.

func SerializedDatabaseInfo 

func SerializedDatabaseInfo(data []byte) (DbInfo, error)

SerializedDatabaseInfo provides information about a serialized database.

func (DbInfo) Mode 

func (i DbInfo) Mode() (ModeFlag, error)

Mode is the scanning mode for the supplied database.

func (DbInfo) String 

func (i DbInfo) String() string

func (DbInfo) Version 

func (i DbInfo) Version() (string, error)

Version is the version for the supplied database.

type ExprExt 

type ExprExt struct {
	Flags           ExtFlag // Flags governing which parts of this structure are to be used by the compiler.
	MinOffset       uint64  // The minimum end offset in the data stream at which this expression should match successfully.
	MaxOffset       uint64  // The maximum end offset in the data stream at which this expression should match successfully.
	MinLength       uint64  // The minimum match length (from start to end) required to successfully match this expression.
	EditDistance    uint32  // Allow patterns to approximately match within this edit distance.
	HammingDistance uint32  // Allow patterns to approximately match within this Hamming distance.
}

ExprExt is a structure containing additional parameters related to an expression.

func ParseExprExt 

func ParseExprExt(s string) (ext *ExprExt, err error)

ParseExprExt parse containing additional parameters from string

func (*ExprExt) String 

func (ext *ExprExt) String() string

func (*ExprExt) With 

func (ext *ExprExt) With(exts ...Ext) *ExprExt

With specifies the additional parameters related to an expression.

type ExprInfo 

type ExprInfo struct {
	MinWidth        uint // The minimum length in bytes of a match for the pattern.
	MaxWidth        uint // The maximum length in bytes of a match for the pattern.
	ReturnUnordered bool // Whether this expression can produce matches that are not returned in order, such as those produced by assertions.
	AtEndOfData     bool // Whether this expression can produce matches at end of data (EOD).
	OnlyAtEndOfData bool // Whether this expression can *only* produce matches at end of data (EOD).
}

ExprInfo containing information related to an expression

type Expression 

type Expression string

Expression of pattern

func (Expression) String 

func (e Expression) String() string

type Ext 

type Ext func(ext *ExprExt)

Ext is a option containing additional parameters related to an expression.

func EditDistance 

func EditDistance(n uint32) Ext

EditDistance allow patterns to approximately match within this edit distance.

func HammingDistance 

func HammingDistance(n uint32) Ext

HammingDistance allow patterns to approximately match within this Hamming distance.

func MaxOffset 

func MaxOffset(n uint64) Ext

MaxOffset given the maximum end offset in the data stream at which this expression should match successfully.

func MinLength 

func MinLength(n uint64) Ext

MinLength given the minimum match length (from start to end) required to successfully match this expression.

func MinOffset 

func MinOffset(n uint64) Ext

MinOffset given the minimum end offset in the data stream at which this expression should match successfully.

type ExtFlag 

type ExtFlag uint64

ExtFlag are used in ExprExt.Flags to indicate which fields are used. 

const (
	// ExtMinOffset is a flag indicating that the ExprExt.MinOffset field is used.
	ExtMinOffset ExtFlag = C.HS_EXT_FLAG_MIN_OFFSET
	// ExtMaxOffset is a flag indicating that the ExprExt.MaxOffset field is used.
	ExtMaxOffset ExtFlag = C.HS_EXT_FLAG_MAX_OFFSET
	// ExtMinLength is a flag indicating that the ExprExt.MinLength field is used.
	ExtMinLength ExtFlag = C.HS_EXT_FLAG_MIN_LENGTH
	// ExtEditDistance is a flag indicating that the ExprExt.EditDistance field is used.
	ExtEditDistance ExtFlag = C.HS_EXT_FLAG_EDIT_DISTANCE
	// ExtHammingDistance is a flag indicating that the ExprExt.HammingDistance field is used.
	ExtHammingDistance ExtFlag = C.HS_EXT_FLAG_HAMMING_DISTANCE
)

type HsError 

type HsError int

HsError represents an error 

const (
	// ErrSuccess is the error returned if the engine completed normally.
	ErrSuccess HsError = C.HS_SUCCESS
	// ErrInvalid is the error returned if a parameter passed to this function was invalid.
	ErrInvalid HsError = C.HS_INVALID
	// ErrNoMemory is the error returned if a memory allocation failed.
	ErrNoMemory HsError = C.HS_NOMEM
	// ErrScanTerminated is the error returned if the engine was terminated by callback.
	ErrScanTerminated HsError = C.HS_SCAN_TERMINATED
	// ErrCompileError is the error returned if the pattern compiler failed.
	ErrCompileError HsError = C.HS_COMPILER_ERROR
	// ErrDatabaseVersionError is the error returned if the given database was built for a different version of Hyperscan.
	ErrDatabaseVersionError HsError = C.HS_DB_VERSION_ERROR
	// ErrDatabasePlatformError is the error returned if the given database was built for a different platform (i.e., CPU type).
	ErrDatabasePlatformError HsError = C.HS_DB_PLATFORM_ERROR
	// ErrDatabaseModeError is the error returned if the given database was built for a different mode of operation.
	ErrDatabaseModeError HsError = C.HS_DB_MODE_ERROR
	// ErrBadAlign is the error returned if a parameter passed to this function was not correctly aligned.
	ErrBadAlign HsError = C.HS_BAD_ALIGN
	// ErrBadAlloc is the error returned if the memory allocator did not correctly return memory suitably aligned.
	ErrBadAlloc HsError = C.HS_BAD_ALLOC
	// ErrScratchInUse is the error returned if the scratch region was already in use.
	ErrScratchInUse HsError = C.HS_SCRATCH_IN_USE
	// ErrArchError is the error returned if unsupported CPU architecture.
	ErrArchError HsError = C.HS_ARCH_ERROR
)

func (HsError) Error 

func (e HsError) Error() string

type MatchContext 

type MatchContext interface {
	Database() Database

	Scratch() Scratch

	UserData() interface{}
}

MatchContext represents a match context

type MatchEvent 

type MatchEvent interface {
	Id() uint

	From() uint64

	To() uint64

	Flags() ScanFlag
}

MatchEvent indicates a match event

type MatchHandler 

type MatchHandler hsMatchEventHandler

MatchHandler handles match events

type ModeFlag 

type ModeFlag uint

ModeFlag represents the compile mode flags 

const (
	// BlockMode for the block scan (non-streaming) database.
	BlockMode ModeFlag = C.HS_MODE_BLOCK
	// NoStreamMode is alias for Block.
	NoStreamMode ModeFlag = C.HS_MODE_NOSTREAM
	// StreamMode for the streaming database.
	StreamMode ModeFlag = C.HS_MODE_STREAM
	// VectoredMode for the vectored scanning database.
	VectoredMode ModeFlag = C.HS_MODE_VECTORED
	// SomHorizonLargeMode use full precision to track start of match offsets in stream state.
	SomHorizonLargeMode ModeFlag = C.HS_MODE_SOM_HORIZON_LARGE
	// SomHorizonMediumMode use medium precision to track start of match offsets in stream state. (within 2^32 bytes)
	SomHorizonMediumMode ModeFlag = C.HS_MODE_SOM_HORIZON_MEDIUM
	// SomHorizonSmallMode use limited precision to track start of match offsets in stream state. (within 2^16 bytes)
	SomHorizonSmallMode ModeFlag = C.HS_MODE_SOM_HORIZON_SMALL
	// ModeMask represents the mask of database mode
	ModeMask ModeFlag = 0xFF
)

func ParseModeFlag 

func ParseModeFlag(s string) (ModeFlag, error)

ParseModeFlag parse a database mode from string

func (ModeFlag) String 

func (m ModeFlag) String() string

type Pattern 

type Pattern struct {
	Expression             // The expression to parse.
	Flags      CompileFlag // Flags which modify the behaviour of the expression.
	Id         int         // The ID number to be associated with the corresponding pattern
	// contains filtered or unexported fields
}

Pattern is a matching pattern

func NewPattern 

func NewPattern(expr string, flags CompileFlag) *Pattern

NewPattern returns a new pattern base on expression and compile flags.

func ParsePattern 

func ParsePattern(s string) (*Pattern, error)

ParsePattern parse pattern from a formated string. 

<integer id>:/<expression>/<flags>

For example, the following pattern will match `test` in the caseless and multi-lines mode 

/test/im
Example

This example demonstrates parsing pattern with id and flags 

package main

import (
	"fmt"

	"gitee.com/ebayboy/hyperscan"
)

func main() {
	p, err := hyperscan.ParsePattern("3:/foobar/i8")

	fmt.Println(err)
	fmt.Println(p.Id)
	fmt.Println(p.Expression)
	fmt.Println(p.Flags)
}

Output:

<nil>
3
foobar
8i

func (*Pattern) Ext 

func (p *Pattern) Ext() (*ExprExt, error)

Ext provides additional parameters related to an expression.

func (*Pattern) Info 

func (p *Pattern) Info() (*ExprInfo, error)

Info provides information about a regular expression.

func (*Pattern) IsValid 

func (p *Pattern) IsValid() bool

IsValid validate the pattern contains a regular expression.

func (*Pattern) String 

func (p *Pattern) String() string

func (*Pattern) WithExt 

func (p *Pattern) WithExt(exts ...Ext) *Pattern

WithExt is used to set the additional parameters related to an expression.

type Patterns 

type Patterns []*Pattern

Patterns is a set of matching patterns

func ParsePatterns 

func ParsePatterns(r io.Reader) (patterns Patterns, err error)

ParsePatterns parse lines as `Patterns`.

Example

This example demonstrates parsing patterns with comment 

package main

import (
	"fmt"
	"strings"

	"gitee.com/ebayboy/hyperscan"
)

func main() {
	patterns, err := hyperscan.ParsePatterns(strings.NewReader(`
# empty line and comment will be skipped

1:/hatstand.*teakettle/s
2:/(hatstand|teakettle)/iH
3:/^.{10,20}hatstand/m	
`))

	fmt.Println(err)
	for _, p := range patterns {
		fmt.Println(p)
	}
}

Output:

<nil>
1:/hatstand.*teakettle/s
2:/(hatstand|teakettle)/Hi
3:/^.{10,20}hatstand/m

type Platform 

type Platform interface {
	// Information about the target platform which may be used to guide the optimisation process of the compile.
	Tune() TuneFlag

	// Relevant CPU features available on the target platform
	CpuFeatures() CpuFeature
}

Platform is a type containing information on the target platform.

func NewPlatform 

func NewPlatform(tune TuneFlag, cpu CpuFeature) Platform

NewPlatform create a new platform information on the target platform.

func PopulatePlatform 

func PopulatePlatform() Platform

PopulatePlatform populates the platform information based on the current host.

type ScanFlag 

type ScanFlag uint

ScanFlag represents a scan flag

type Scratch 

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

Scratch is a Hyperscan scratch space.

func NewScratch 

func NewScratch(db Database) (*Scratch, error)

NewScratch allocate a "scratch" space for use by Hyperscan. This is required for runtime use, and one scratch space per thread, or concurrent caller, is required.

func (*Scratch) Clone 

func (s *Scratch) Clone() (*Scratch, error)

Clone allocate a scratch space that is a clone of an existing scratch space.

func (*Scratch) Free 

func (s *Scratch) Free() error

Free a scratch block previously allocated

func (*Scratch) Realloc 

func (s *Scratch) Realloc(db Database) error

Realloc reallocate the scratch for another database.

func (*Scratch) Size 

func (s *Scratch) Size() (int, error)

Size provides the size of the given scratch space.

type Stream 

type Stream interface {
	Scan(data []byte) error

	Close() error

	Reset() error

	Clone() (Stream, error)
}

Stream exist in the Hyperscan library so that pattern matching state can be maintained across multiple blocks of target data

type StreamCompressor 

type StreamCompressor interface {
	// Creates a compressed representation of the provided stream in the buffer provided.
	Compress(stream Stream) ([]byte, error)

	// Decompresses a compressed representation created by `CompressStream` into a new stream.
	Expand(buf []byte, flags ScanFlag, scratch *Scratch, handler MatchHandler, context interface{}) (Stream, error)

	// Decompresses a compressed representation created by `CompressStream` on top of the 'to' stream.
	ResetAndExpand(stream Stream, buf []byte, flags ScanFlag, scratch *Scratch, handler MatchHandler, context interface{}) (Stream, error)
}

StreamCompressor implements stream compressor.

type StreamDatabase 

type StreamDatabase interface {
	Database
	StreamScanner
	StreamMatcher
	StreamCompressor

	StreamSize() (int, error)
}

StreamDatabase scan the target data to be scanned is a continuous stream, not all of which is available at once; blocks of data are scanned in sequence and matches may span multiple blocks in a stream.

func NewLargeStreamDatabase 

func NewLargeStreamDatabase(patterns ...*Pattern) (StreamDatabase, error)

NewLargeStreamDatabase create a large-sized stream database base on the patterns.

func NewMediumStreamDatabase 

func NewMediumStreamDatabase(patterns ...*Pattern) (StreamDatabase, error)

NewMediumStreamDatabase create a medium-sized stream database base on the patterns.

func NewStreamDatabase 

func NewStreamDatabase(patterns ...*Pattern) (StreamDatabase, error)

NewStreamDatabase create a stream database base on the patterns.

func UnmarshalStreamDatabase 

func UnmarshalStreamDatabase(data []byte) (StreamDatabase, error)

UnmarshalStreamDatabase reconstruct a stream database from a stream of bytes.

type StreamMatcher 

type StreamMatcher interface {
	// Find returns a slice holding the text of the leftmost match in b of the regular expression.
	// A return value of nil indicates no match.
	Find(reader io.ReadSeeker) []byte

	// FindIndex returns a two-element slice of integers defining the location of the leftmost match in b of the regular expression.
	// The match itself is at b[loc[0]:loc[1]]. A return value of nil indicates no match.
	FindIndex(reader io.Reader) []int

	// FindAll is the 'All' version of Find; it returns a slice of all successive matches of the expression,
	// as defined by the 'All' description in the package comment. A return value of nil indicates no match.
	FindAll(reader io.ReadSeeker, n int) [][]byte

	// FindAllIndex is the 'All' version of FindIndex; it returns a slice of all successive matches of the expression,
	// as defined by the 'All' description in the package comment. A return value of nil indicates no match.
	FindAllIndex(reader io.Reader, n int) [][]int

	// Match reports whether the pattern database matches the byte slice b.
	Match(reader io.Reader) bool
}

StreamMatcher implements regular expression search.

type StreamScanner 

type StreamScanner interface {
	Open(flags ScanFlag, scratch *Scratch, handler MatchHandler, context interface{}) (Stream, error)

	Scan(reader io.Reader, scratch *Scratch, handler MatchHandler, context interface{}) error
}

StreamScanner is the streaming regular expression scanner.

Example 
package main

import (
	"fmt"

	"gitee.com/ebayboy/hyperscan"
)

func main() {
	// Pattern with `L` flag enable leftmost start of match reporting.
	p, err := hyperscan.ParsePattern(`/foo(bar)+/L`)
	if err != nil {
		fmt.Println("parse pattern failed,", err)
		return
	}

	// Create new stream database with pattern
	db, err := hyperscan.NewStreamDatabase(p)
	if err != nil {
		fmt.Println("create database failed,", err)
		return
	}
	defer db.Close()

	// Create new scratch for scanning
	s, err := hyperscan.NewScratch(db)
	if err != nil {
		fmt.Println("create scratch failed,", err)
		return
	}
	defer func() {
		_ = s.Free()
	}()

	// Record matching text
	type Match struct {
		from uint64
		to   uint64
	}
	var matches []Match
	handler := hyperscan.MatchHandler(func(id uint, from, to uint64, flags uint, context interface{}) error {
		matches = append(matches, Match{from, to})
		return nil
	})

	data := []byte("hello foobarbar!")

	// Open stream with handler
	st, err := db.Open(0, s, handler, nil)
	if err != nil {
		fmt.Println("open streaming database failed,", err)
		return
	}

	// Scan data with stream
	for i := 0; i < len(data); i += 4 {
		start := i
		end := i + 4
		if end > len(data) {
			end = len(data)
		}
		if err = st.Scan(data[start:end]); err != nil {
			fmt.Println("streaming scan failed,", err)
			return
		}
	}

	// Close stream
	if err = st.Close(); err != nil {
		fmt.Println("streaming scan failed,", err)
		return
	}

	// Hyperscan will reports all matches
	for _, m := range matches {
		fmt.Println("match [", m.from, ":", m.to, "]", string(data[m.from:m.to]))
	}

}

Output:

match [ 6 : 12 ] foobar
match [ 6 : 15 ] foobarbar

type TuneFlag 

type TuneFlag int

TuneFlag is the tuning flags 

const (
	// Generic indicates that the compiled database should not be tuned for any particular target platform.
	Generic TuneFlag = C.HS_TUNE_FAMILY_GENERIC
	// SandyBridge indicates that the compiled database should be tuned for the Sandy Bridge microarchitecture.
	SandyBridge TuneFlag = C.HS_TUNE_FAMILY_SNB
	// IvyBridge indicates that the compiled database should be tuned for the Ivy Bridge microarchitecture.
	IvyBridge TuneFlag = C.HS_TUNE_FAMILY_IVB
	// Haswell indicates that the compiled database should be tuned for the Haswell microarchitecture.
	Haswell TuneFlag = C.HS_TUNE_FAMILY_HSW
	// Silvermont indicates that the compiled database should be tuned for the Silvermont microarchitecture.
	Silvermont TuneFlag = C.HS_TUNE_FAMILY_SLM
	// Broadwell indicates that the compiled database should be tuned for the Broadwell microarchitecture.
	Broadwell TuneFlag = C.HS_TUNE_FAMILY_BDW
	// Skylake indicates that the compiled database should be tuned for the Skylake microarchitecture.
	Skylake TuneFlag = C.HS_TUNE_FAMILY_SKL
	// SkylakeServer indicates that the compiled database should be tuned for the Skylake Server microarchitecture.
	SkylakeServer TuneFlag = C.HS_TUNE_FAMILY_SKX
	// Goldmont indicates that the compiled database should be tuned for the Goldmont microarchitecture.
	Goldmont TuneFlag = C.HS_TUNE_FAMILY_GLM
)

type VectoredDatabase 

type VectoredDatabase interface {
	Database
	VectoredScanner
	VectoredMatcher
}

VectoredDatabase scan the target data that consists of a list of non-contiguous blocks that are available all at once.

func NewVectoredDatabase 

func NewVectoredDatabase(patterns ...*Pattern) (VectoredDatabase, error)

NewVectoredDatabase create a vectored database base on the patterns.

func UnmarshalVectoredDatabase 

func UnmarshalVectoredDatabase(data []byte) (VectoredDatabase, error)

UnmarshalVectoredDatabase reconstruct a vectored database from a stream of bytes.

type VectoredMatcher 

type VectoredMatcher interface {
}

VectoredMatcher implements regular expression search.

type VectoredScanner 

type VectoredScanner interface {
	Scan(data [][]byte, scratch *Scratch, handler MatchHandler, context interface{}) error
}

VectoredScanner is the vectored regular expression scanner.

Example 
package main

import (
	"fmt"

	"gitee.com/ebayboy/hyperscan"
)

func main() {
	// Pattern with `L` flag enable leftmost start of match reporting.
	p, err := hyperscan.ParsePattern(`/foo(bar)+/L`)
	if err != nil {
		fmt.Println("parse pattern failed,", err)
		return
	}

	// Create new vectored database with pattern
	db, err := hyperscan.NewVectoredDatabase(p)
	if err != nil {
		fmt.Println("create database failed,", err)
		return
	}
	defer db.Close()

	// Create new scratch for scanning
	s, err := hyperscan.NewScratch(db)
	if err != nil {
		fmt.Println("create scratch failed,", err)
		return
	}
	defer func() {
		_ = s.Free()
	}()

	// Record matching text
	type Match struct {
		from uint64
		to   uint64
	}
	var matches []Match
	handler := hyperscan.MatchHandler(func(id uint, from, to uint64, flags uint, context interface{}) error {
		matches = append(matches, Match{from, to})
		return nil
	})

	data := []byte("hello foobarbar!")

	// Scan vectored data with handler
	if err := db.Scan([][]byte{data[:8], data[8:12], data[12:]}, s, handler, nil); err != nil {
		fmt.Println("database scan failed,", err)
		return
	}

	// Hyperscan will reports all matches
	for _, m := range matches {
		fmt.Println("match [", m.from, ":", m.to, "]", string(data[m.from:m.to]))
	}

}

Output:

match [ 6 : 12 ] foobar
match [ 6 : 15 ] foobarbar

Source Files

View all Source files

Directories

Path Synopsis
examples
gohs
pcapscan
* Hyperscan example program 2: pcapscan * * This example is a very simple packet scanning benchmark.
 * Hyperscan example program 2: pcapscan * * This example is a very simple packet scanning benchmark.
simplegrep

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.