github.com/grailbio/base@v0.0.11/simd/doc.go (about)

     1  // Copyright 2018 GRAIL, Inc.  All rights reserved.
     2  // Use of this source code is governed by the Apache-2.0
     3  // license that can be found in the LICENSE file.
     4  
     5  // Package simd provides access to SIMD-based implementations of several common
     6  // operations on byte arrays which the compiler cannot be trusted to
     7  // autovectorize within the next several years.
     8  //
     9  // The backend assumes SSE4.2 is available: init() checks for SSE4.2 support,
    10  // and panics when it isn't there.  The interface is designed to allow the
    11  // backend to also autodetect e.g. AVX2/AVX-512 and opportunistically use those
    12  // instructions, without any changes to properly written higher-level code.
    13  // Implementation of the AVX2 part of this is in progress.
    14  //
    15  //
    16  // The central constraint driving this package's design is the standard Go
    17  // compiler's inability to inline short assembly functions; see
    18  //   https://groups.google.com/forum/#!topic/golang-nuts/yVOfeHYCIT4
    19  //   https://github.com/golang/go/issues/4947#issuecomment-66075571
    20  // for more details.  As a consequence, it is critical to push looping logic
    21  // down to the assembly level as well, otherwise function call overhead is
    22  // overwhelming.  Conversely, due to the much higher development burden of this
    23  // type of code, we don't go beyond that point; this package is essentially a
    24  // collection of for loops.
    25  //
    26  // Two classes of functions are exported:
    27  //
    28  // - Functions with 'Unsafe' in their names are very performant, but are
    29  // memory-unsafe, do not validate documented preconditions, and may have the
    30  // unusual property of reading/writing to a few bytes *past* the end of the
    31  // given slices.  The MakeUnsafe() function and its relatives allocate
    32  // byte-slices with sufficient extra capacity for all Unsafe functions with the
    33  // latter property to work properly.
    34  //
    35  // - Their safe analogues work properly on ordinary slices, and often panic
    36  // when documented preconditions are not met.  When a precondition is not
    37  // explicitly checked (due to computational cost), safe functions may return
    38  // garbage values when the condition is not met, but they are memory-safe: they
    39  // will not corrupt unrelated memory or perform out-of-bounds read operations.
    40  package simd