github.com/alexyer/taggedptr@v0.0.0-20160103160510-29e0338f9028/README.md (about)

     1  [![Build Status](https://travis-ci.org/alexyer/taggedptr.svg)](https://travis-ci.org/alexyer/taggedptr)
     2  [![Coverage Status](https://coveralls.io/repos/alexyer/taggedptr/badge.svg?branch=master&service=github)](https://coveralls.io/github/alexyer/taggedptr?branch=master)
     3  
     4  # Description
     5  This module contains methods to tag the pointer.
     6  Tagged pointer is a pointer with additional data associate with it.
     7  It's possible because data must be word aligned,
     8  hence least significant bits could be used to store some data.
     9  It's useful in lock-free programming,
    10  to store some data in pointer atomically using CAS instructions.
    11  
    12  ## Examples
    13  ```go
    14  type TestStruct struct {
    15  	Field int
    16  }
    17  
    18  s := &TestStruct{42}
    19  
    20  // Tag pointer and assign new value
    21  newPtr, _ := Tag(unsafe.Pointer(s), 3)
    22  s = (*TestStruct)(newPtr)
    23  
    24  // Get clear pointer
    25  initialPtr := GetPointer(unsafe.Pointer(s))
    26  
    27  // Get tag
    28  tag := GetTag(unsafe.Pointer(s))
    29  
    30  // Tag, compare and swap pointer
    31  casPtr := unsafe.Pointer(s)
    32  CompareAndSwap(&casPtr, casPtr, casPtr, 0, 1)
    33  
    34  // Atomically tag pointer
    35  AttemptTag(&casPtr, casPtr, 1)
    36  
    37  // Get both pointer and tag values
    38  ptr, tag := Get(unsafe.Pointer(s))
    39  ```