Update erasure documentation
This commit is contained in:
parent
3b3e446102
commit
f4b5519451
3 changed files with 32 additions and 8 deletions
|
@ -1,15 +1,20 @@
|
|||
// Package erasure is a Go wrapper for the Intel Intelligent Storage
|
||||
// Acceleration Library (Intel ISA-L). Intel ISA-L is a CPU optimized
|
||||
// implementation of erasure code.
|
||||
// implementation of erasure coding algorithms.
|
||||
//
|
||||
// For more information on Intel ISA-L, please visit:
|
||||
// https://01.org/intel%C2%AE-storage-acceleration-library-open-source-version
|
||||
//
|
||||
// Usage
|
||||
// Usage:
|
||||
//
|
||||
// TODO: Explain Encode and Decode inputs and outputs
|
||||
// Encode encodes a block of data. The input is the original data. The output
|
||||
// is a 2 tuple containing (k + m) chunks of erasure encoded data and the
|
||||
// length of the original object.
|
||||
//
|
||||
// TODO: Explain matrix size and how it corresponds to protection level
|
||||
// Decode decodes 2 tuple data containing (k + m) chunks back into its original form.
|
||||
// Additionally original block length should also be provided as input.
|
||||
//
|
||||
// Decoded data is exactly similar in length and content as the original data.
|
||||
//
|
||||
// Encoding data may be performed in 3 steps.
|
||||
//
|
||||
|
@ -23,13 +28,27 @@
|
|||
// 2. Create a new encoder
|
||||
// 3. Decode data
|
||||
//
|
||||
// Encoder parameters contain four configurable elements:
|
||||
// Encoder parameters contain three configurable elements:
|
||||
// ParseEncoderParams(k, m, technique int) (EncoderParams, error)
|
||||
// k - Number of rows in matrix
|
||||
// m - Number of colums in matrix
|
||||
// technique - Matrix type, can be either CAUCHY (recommended) or VANDERMONDE
|
||||
// constraints: k + m < Galois Field (2^8)
|
||||
//
|
||||
// Choosing right parity and matrix technique is left for application to decide.
|
||||
//
|
||||
// But here are the few points to keep in mind
|
||||
//
|
||||
// Techniques:
|
||||
// - Vandermonde is most commonly used method for choosing coefficients in erasure
|
||||
// encoding but does not guarantee invertable for every sub matrix.
|
||||
// Users may want to adjust for k > 5. (k is data blocks)
|
||||
// - Whereas Cauchy is our recommended method for choosing coefficients in erasure coding.
|
||||
// Since any sub-matrix of a Cauchy matrix is invertable.
|
||||
//
|
||||
// Total blocks:
|
||||
// - Data blocks and Parity blocks should not be greater than 'Galois Field' (2^8)
|
||||
//
|
||||
// Example
|
||||
//
|
||||
// Creating and using an encoder
|
||||
|
@ -44,4 +63,5 @@
|
|||
// params := erasure.ParseEncoderParams(10, 5, erasure.CAUCHY)
|
||||
// encoder := erasure.NewEncoder(params)
|
||||
// originalData, err := encoder.Decode(encodedData, length)
|
||||
//
|
||||
package erasure
|
||||
|
|
|
@ -27,6 +27,10 @@ import (
|
|||
"unsafe"
|
||||
)
|
||||
|
||||
// Decode decodes 2 tuple data containing (k + m) chunks back into its original form.
|
||||
// Additionally original block length should also be provided as input.
|
||||
//
|
||||
// Decoded data is exactly similar in length and content as the original data.
|
||||
func (e *Encoder) Decode(chunks [][]byte, length int) ([]byte, error) {
|
||||
var decode_matrix *C.uint8_t
|
||||
var decode_tbls *C.uint8_t
|
||||
|
|
|
@ -56,9 +56,9 @@ type Encoder struct {
|
|||
|
||||
// ParseEncoderParams creates an EncoderParams object.
|
||||
//
|
||||
// k and n represent the matrix size, which corresponds to the protection level.
|
||||
//
|
||||
// k and m represent the matrix size, which corresponds to the protection level
|
||||
// technique is the matrix type. Valid inputs are CAUCHY (recommended) or VANDERMONDE.
|
||||
//
|
||||
func ParseEncoderParams(k, m, technique int) (*EncoderParams, error) {
|
||||
if k < 1 {
|
||||
return nil, errors.New("k cannot be zero")
|
||||
|
@ -88,7 +88,7 @@ func ParseEncoderParams(k, m, technique int) (*EncoderParams, error) {
|
|||
}, nil
|
||||
}
|
||||
|
||||
// NewEncoder creates an encoder with a given set of parameters.
|
||||
// NewEncoder creates an encoder object with a given set of parameters.
|
||||
func NewEncoder(ep *EncoderParams) *Encoder {
|
||||
var k = C.int(ep.K)
|
||||
var m = C.int(ep.M)
|
||||
|
|
Loading…
Reference in a new issue