convert

Documentation

Index

• Constants
• func Convert(wa io.WriterAt, img image.Image, opts Options) error
• type Options
  • func (o *Options) Validate() error
• type Updater

Constants

const BufferSize = 1024 * 1024

The size of the buffer used to read data from non-zero extents of the image. For best performance, the size should be aligned to the image cluster size or the file system block size.

const SegmentSize = 32 * BufferSize

To maxmimze performance we use multiple goroutines to read data from the source image, decompress data, and write data to the target image. To schedule the work to multiple goroutines, the image is split to multiple segments, each processed by a single worker goroutine.

Smaller value may increase the overhead of synchornizing multiple workers. Larger value may be less efficient for smaller images. The default value gives good results for the lima default Ubuntu image. Must be aligned to BufferSize.

const Workers = 8

For best I/O throughput we want to have enough in-flight requests, regardless of number of cores. For best decompression we want to use one worker per core, but too many workers are less effective. The default value gives good results with lima default Ubuntu image.

Functions

func Convert

func Convert(wa io.WriterAt, img image.Image, opts Options) error

Convert copy image to io.WriterAt. Unallocated extents in the image or read data which is all zeros are converted to unallocated byte range in the target image. The target image must be new empty file or a file full of zeroes. To get a sparse target image, the image must be a new empty file, since Convert does not punch holes for zero ranges even if the underlying file system supports hole punching.

Types

type Options

type Options struct {
	// SegmentSize in bytes. Must be aligned to BufferSize. If not set, use the
	// default value (32 MiB).
	SegmentSize int64

	// BufferSize in bytes. If not set, use the default value (1 MiB).
	BufferSize int

	// Workers is the number of goroutines copying buffers in parallel. If not set
	// use the default value (8).
	Workers int

	// If set, update progress during conversion.
	Progress Updater
}

func (*Options) Validate

func (o *Options) Validate() error

Validate validates options and set default values. Returns an error for invalid option values.

type Updater

type Updater interface {
	// Called from multiple goroutines after a byte range of length was converted.
	// If the conversion is successfu, the total number of bytes will be the image
	// virtual size.
	Update(n int64)
}

Updater is an interface for tracking conversion progress.