golint

internal/impl/libraptorq/decoder.go

@@ -9,9 +9,18 @@ import (
  "github.com/harmony-one/go-raptorq/pkg/raptorq"
 )
 
+// DecoderFactory is a factory of libRaptorQ-based decoder instances.
 type DecoderFactory struct {
 }
 
+// New returns a new decoder instance.
+//
+// commonOTI and schemeSpecificOTI are the RaptorQ OTIs,
+// received from the sender.
+//
+// New returns a nil instance and an error if the decoder cannot be created.
+// This can, for example,
+// occur if the given commonOTI or schemeSpecificOTI is out of range.
 func (*DecoderFactory) New(commonOTI uint64, schemeSpecificOTI uint32) (
  decoder raptorq.Decoder, err error) {
  wrapped := swig.NewBytesDecoder(swig.HostToNet64(commonOTI),
@@ -33,9 +42,13 @@ func (*DecoderFactory) New(commonOTI uint64, schemeSpecificOTI uint32) (
 }
 
 func finalizeDecoder(decoder *Decoder) {
- decoder.Close()
+ err := decoder.Close()
+ if err != nil {
+ // Do nothing for now. Maybe log in verbose mode once we have one.
+ }
 }
 
+// Decoder is a RaptorQ decoder instance.
 type Decoder struct {
  wrapped swig.BytesDecoder
  commonOTI uint64
@@ -74,54 +87,76 @@ func (dec *Decoder) readyBlocksLoop() {
  }
 }
 
+// CommonOTI returns the common object transmission information for the codec.
 func (dec *Decoder) CommonOTI() uint64 {
  return dec.commonOTI
 }
 
+// TransferLength returns the size of the transfer object, in octets.
 func (dec *Decoder) TransferLength() uint64 {
  return dec.commonOTI >> 24
 }
 
+// SymbolSize returns the symbol size, in octets.
 func (dec *Decoder) SymbolSize() uint16 {
  return uint16(dec.commonOTI)
 }
 
+// SchemeSpecificOTI returns the scheme-specific object transmission
+// information for the codec.
 func (dec *Decoder) SchemeSpecificOTI() uint32 {
  return dec.schemeSpecificOTI
 }
 
+// NumSourceBlocks returns the number of source blocks in the transfer object.
 func (dec *Decoder) NumSourceBlocks() uint8 {
  return uint8(dec.schemeSpecificOTI >> 24)
 }
 
+// SourceBlockSize returns the size of the given source block, in octets,
 func (dec *Decoder) SourceBlockSize(sbn uint8) uint32 {
  return uint32(dec.wrapped.Block_size(sbn))
 }
 
+// NumSourceSymbols returns the number of source symbols in the given block.
 func (dec *Decoder) NumSourceSymbols(sbn uint8) uint16 {
  return dec.wrapped.Symbols(sbn)
 }
 
+// NumSubBlocks returns the number of sub-blocks in the given source block.
+//
+// This is also the same as number of sub-symbols per symbol.
 func (dec *Decoder) NumSubBlocks() uint16 {
  return uint16(dec.schemeSpecificOTI >> 8)
 }
 
+// SymbolAlignmentParameter returns the symbol alignment parameter, that is,
+// the number of octets to which all symbols,
+// and sub-symbols should align in memory.
 func (dec *Decoder) SymbolAlignmentParameter() uint8 {
  return uint8(dec.schemeSpecificOTI)
 }
 
+// Decode decodes the given symbol.
+//
+// Decoding is done asynchronously,
+// so IsSourceObjectReady or IsSourceBlockReady may not immediately return up
+// to date result.
 func (dec *Decoder) Decode(sbn uint8, esi uint32, symbol []byte) {
  dec.wrapped.Add_symbol(symbol, esi, sbn)
 }
 
+// IsSourceBlockReady returns whether the given source block is ready.
 func (dec *Decoder) IsSourceBlockReady(sbn uint8) bool {
  return dec.wrapped.Is_block_ready(sbn)
 }
 
+// IsSourceObjectReady returns whether the entire source object is ready.
 func (dec *Decoder) IsSourceObjectReady() bool {
  return dec.wrapped.Is_ready()
 }
 
+// SourceBlock retrieves the given source block into the given buffer.
 func (dec *Decoder) SourceBlock(sbn uint8, buf []byte) (n int, err error) {
  n = int(dec.wrapped.Decode_block_bytes(buf, 0, sbn))
  if n != int(dec.SourceBlockSize(sbn)) {
@@ -130,6 +165,7 @@ func (dec *Decoder) SourceBlock(sbn uint8, buf []byte) (n int, err error) {
  return
 }
 
+// SourceObject retrieves the entire source object into the given buffer.
 func (dec *Decoder) SourceObject(buf []byte) (n int, err error) {
  n = int(dec.wrapped.Decode_bytes(buf, 0))
  if n != int(dec.TransferLength()) {
@@ -138,18 +174,33 @@ func (dec *Decoder) SourceObject(buf []byte) (n int, err error) {
  return
 }
 
+// FreeSourceBlock frees all internal memory used for the given source block.
 func (dec *Decoder) FreeSourceBlock(sbn uint8) {
  dec.wrapped.Free(sbn)
 }
 
+// AddReadyBlockChan adds a channel through which the decoder notifies the
+// block number of each source block ready.
+//
+// Use this to get notified of source blocks as soon as they become ready.
+//
+// Source blocks already ready at the time of the call are immediately sent
+// to the channel.
+//
+// AddReadyBlockChan returns an error if the channel has already been added.
 func (dec *Decoder) AddReadyBlockChan(ch chan<- uint8) (err error) {
  return dec.rbcs.AddChannel(ch)
 }
 
+// RemoveReadyBlockChan removes a channel previously registered using
+// AddReadyBlockChan.
+//
+// RemoveReadyBlockChan returns an error if the channel has not yet been added.
 func (dec *Decoder) RemoveReadyBlockChan(ch chan<- uint8) (err error) {
  return dec.rbcs.RemoveChannel(ch)
 }
 
+// Close closes the decoder.
 func (dec *Decoder) Close() (err error) {
  switch wrapped := dec.wrapped.(type) {
  case swig.BytesDecoder:

internal/impl/libraptorq/encoder.go

@@ -8,9 +8,11 @@ import (
  "github.com/harmony-one/go-raptorq/pkg/raptorq"
 )
 
+// EncoderFactory is a factory of libRaptorQ-based encoder instances.
 type EncoderFactory struct {
 }
 
+// New creates a new encoder instance.
 func (*EncoderFactory) New(input []byte, symbolSize uint16, minSubSymbolSize uint16,
  maxSubBlockSize uint32, alignment uint8) (enc raptorq.Encoder, err error) {
  wrapped := swig.InitBytesEncoder(input, minSubSymbolSize, symbolSize,
@@ -26,50 +28,70 @@ func (*EncoderFactory) New(input []byte, symbolSize uint16, minSubSymbolSize uin
 }
 
 func finalizeEncoder(encoder *Encoder) {
- encoder.Close()
+ err := encoder.Close()
+ if err != nil {
+ // Do nothing for now. Maybe log in verbose mode once we have one.
+ }
 }
 
+// Encoder is a libRaptorQ-based encoder instance.
 type Encoder struct {
  wrapped swig.BytesEncoder
  maxSubBlockSize uint32
 }
 
+// CommonOTI returns the common object transmission information for the codec.
 func (enc *Encoder) CommonOTI() uint64 {
  return swig.NetToHost64(enc.wrapped.OTI_Common())
 }
 
+// TransferLength returns the length of the source object, in octets.
 func (enc *Encoder) TransferLength() uint64 {
  return enc.CommonOTI() >> 24
 }
 
+// SymbolSize returns the size of each symbol, in octets.
 func (enc *Encoder) SymbolSize() uint16 {
  return uint16(enc.CommonOTI())
 }
 
+// SchemeSpecificOTI returns the scheme-specific object transmission
+// information for the codec.
 func (enc *Encoder) SchemeSpecificOTI() uint32 {
  return uint32(swig.NetToHost32(enc.wrapped.OTI_Scheme_Specific()))
 }
 
+// NumSourceBlocks returns the number of source blocks in the source object.
 func (enc *Encoder) NumSourceBlocks() uint8 {
  return uint8(enc.SchemeSpecificOTI() >> 24)
 }
 
+// SourceBlockSize returns the size of the given source block, in octets.
 func (enc *Encoder) SourceBlockSize(sbn uint8) uint32 {
  return uint32(enc.wrapped.Block_size(sbn))
 }
 
+// NumSourceSymbols returns the number of source symbols in the given block.
 func (enc *Encoder) NumSourceSymbols(sbn uint8) uint16 {
  return enc.wrapped.Symbols(sbn)
 }
 
+// NumSubBlocks returns the number of sub-blocks in the given source block.
 func (enc *Encoder) NumSubBlocks() uint16 {
  return uint16(enc.SchemeSpecificOTI() >> 8)
 }
 
+// SymbolAlignmentParameter returns the number of octets to which all symbols
+// and sub-symbols align in memory.
 func (enc *Encoder) SymbolAlignmentParameter() uint8 {
  return uint8(enc.SchemeSpecificOTI())
 }
 
+// Encode retrieves one encoding symbol,
+// identified by the given source block number – encoding symbol ID pair.
+//
+// Encode returns the number of octets written into the given buffer,
+// and an error indication, or nil if no error.
 func (enc *Encoder) Encode(sbn uint8, esi uint32, buf []byte) (written uint, err error) {
  if len(buf) < int(enc.SymbolSize()) {
  err = errors.New("RaptorQ encoder buffer too small")
@@ -82,22 +104,34 @@ func (enc *Encoder) Encode(sbn uint8, esi uint32, buf []byte) (written uint, err
  return
 }
 
+// MaxSubBlockSize returns the maximum sub-block size, in octets.
+//
+// This number is WS * Al in RFC 6330.
 func (enc *Encoder) MaxSubBlockSize() uint32 {
  return enc.maxSubBlockSize
 }
 
+// FreeSourceBlock frees resource used for encoding the given source block.
 func (enc *Encoder) FreeSourceBlock(sbn uint8) {
  enc.wrapped.Free(sbn)
 }
 
+// MinSymbols is the number of encoding symbols that needs to be generated and
+// sent for the given source block,
+// so that the receiver can retrieve the source block with 99% probability.
+//
+// This number is K in RFC 6330.
 func (enc *Encoder) MinSymbols(sbn uint8) uint16 {
  return uint16(enc.wrapped.Extended_symbols(sbn))
 }
 
+// MaxSymbols is the number of encoding symbols that can potentially be
+// generated for the given source block. It is somewhere around 2**24.
 func (enc *Encoder) MaxSymbols(sbn uint8) uint32 {
  return uint32(enc.wrapped.Max_repair(sbn))
 }
 
+// Close closes the encoder instance.
 func (enc *Encoder) Close() (err error) {
  switch wrapped := enc.wrapped.(type) {
  case swig.BytesEncoder:

internal/readyblockchan/readyblockchan.go

@@ -7,12 +7,14 @@ import (
  "sync"
 )
 
+// AlreadyAdded signals the given ready block channel has already been added.
 type AlreadyAdded chan<- uint8
 
 func (e AlreadyAdded) Error() string {
  return fmt.Sprintf("ready-block channel %+v already added", e)
 }
 
+// NotFound signals the given ready block channel is not found.
 type NotFound chan<- uint8
 
 func (e NotFound) Error() string {
@@ -26,6 +28,8 @@ type ReadyBlockChannels struct {
  channels []chan<- uint8
 }
 
+// Reset resets this instance. Existing channels are closed and removed,
+// and all blocks are reset as not received.
 func (rbcs *ReadyBlockChannels) Reset(numSourceBlocks uint8) {
  rbcs.mutex.Lock()
  defer rbcs.mutex.Unlock()
@@ -36,6 +40,12 @@ func (rbcs *ReadyBlockChannels) Reset(numSourceBlocks uint8) {
  rbcs.ready = make([]bool, numSourceBlocks)
 }
 
+// AddChannel adds the given channel.
+//
+// If any source block has already been received,
+// AddChannel sends its number immediately.
+//
+// If the channel already exists, AddChannel returns an error.
 func (rbcs *ReadyBlockChannels) AddChannel(ch chan<- uint8) (
  err error,
 ) {
@@ -56,6 +66,11 @@ func (rbcs *ReadyBlockChannels) AddChannel(ch chan<- uint8) (
  return
 }
 
+// RemoveChannel removes the given channel.
+//
+// Removed channel is not closed.
+//
+// If the given channel is not found, RemoveChannel returns an error.
 func (rbcs *ReadyBlockChannels) RemoveChannel(ch chan<- uint8) (
  err error,
 ) {
@@ -77,6 +92,11 @@ func (rbcs *ReadyBlockChannels) RemoveChannel(ch chan<- uint8) (
  return
 }
 
+// AddBlock adds a source block as having been received.
+//
+// For each source block,
+// the first call – and only the first call – sends the block number to all
+// channels registered.
 func (rbcs *ReadyBlockChannels) AddBlock(sbn uint8) {
  rbcs.mutex.Lock()
  defer rbcs.mutex.Unlock()

pkg/defaults/default.go

@@ -3,10 +3,12 @@ package defaults
 import "github.com/harmony-one/go-raptorq/pkg/raptorq"
 import "github.com/harmony-one/go-raptorq/internal/impl/libraptorq"
 
+// DefaultEncoderFactory is the default encoder factory.
 func DefaultEncoderFactory() raptorq.EncoderFactory {
  return &libraptorq.EncoderFactory{}
 }
 
+// DefaultDecoderFactory is the default decoder factory.
 func DefaultDecoderFactory() raptorq.DecoderFactory {
  return &libraptorq.DecoderFactory{}
 }