github.com/lrita/cmap@v0.0.0-20231108122212-cb084a67f554/README.md (about)

     1  # cmap [![Build Status](https://travis-ci.org/lrita/cmap.svg?branch=master)](https://travis-ci.org/lrita/cmap) [![GoDoc](https://godoc.org/github.com/lrita/cmap?status.png)](https://godoc.org/github.com/lrita/cmap) [![codecov](https://codecov.io/gh/lrita/cmap/branch/master/graph/badge.svg)](https://codecov.io/gh/lrita/cmap) [![Go Report Card](https://goreportcard.com/badge/github.com/lrita/cmap)](https://goreportcard.com/report/github.com/lrita/cmap)
     2  
     3  The `map` type in Go doesn't support concurrent reads and writes. `cmap(concurrent-map)` provides a high-performance solution to this by sharding the map with minimal time spent waiting for locks.
     4  
     5  The `sync.Map` has a few key differences from this map. The stdlib `sync.Map` is designed for append-only scenarios. So if you want to use the map for something more like in-memory db, you might benefit from using our version. You can read more about it in the golang repo, for example [here](https://github.com/golang/go/issues/21035) and [here](https://stackoverflow.com/questions/11063473/map-with-concurrent-access)
     6  
     7  _Here we fork some README document from [concurrent-map](https://github.com/orcaman/concurrent-map)_
     8  
     9  ## usage
    10  
    11  Import the package:
    12  
    13  ```go
    14  import (
    15  	"github.com/lrita/cmap"
    16  )
    17  
    18  ```
    19  
    20  ```bash
    21  go get "github.com/lrita/cmap"
    22  ```
    23  
    24  The package is now imported under the "cmap" namespace.
    25  
    26  ## example
    27  
    28  ```go
    29  
    30  	// Create a new map.
    31  	var m cmap.Cmap
    32  
    33  	// Stores item within map, sets "bar" under key "foo"
    34  	m.Store("foo", "bar")
    35  
    36  	// Retrieve item from map.
    37  	if tmp, ok := m.Load("foo"); ok {
    38  		bar := tmp.(string)
    39  	}
    40  
    41  	// Deletes item under key "foo"
    42  	m.Delete("foo")
    43  
    44  	// If you are using g1.18+, you can use the generics implementation
    45  
    46  	var n cmap.Map[string, string]
    47  
    48  	// Stores item within map, sets "bar" under key "foo"
    49  	n.Store("foo", "bar")
    50  
    51  	// Retrieve item from map.
    52  	if tmp, ok := n.Load("foo"); ok {
    53  	    bar := tmp
    54  	}
    55  
    56  	// Deletes item under key "foo"
    57  	n.Delete("foo")
    58  ```
    59  
    60  ## benchmark
    61  
    62  ```bash
    63  goos: darwin
    64  goarch: amd64
    65  pkg: github.com/lrita/cmap
    66  BenchmarkLoadMostlyHits/*cmap_test.DeepCopyMap-4         	50000000	        34.5 ns/op
    67  BenchmarkLoadMostlyHits/*cmap_test.RWMutexMap-4          	20000000	        65.2 ns/op
    68  BenchmarkLoadMostlyHits/*sync.Map-4                      	50000000	        34.8 ns/op
    69  BenchmarkLoadMostlyHits/*cmap.Cmap-4                     	30000000	        53.5 ns/op
    70  BenchmarkLoadMostlyMisses/*cmap_test.DeepCopyMap-4       	50000000	        26.7 ns/op
    71  BenchmarkLoadMostlyMisses/*cmap_test.RWMutexMap-4        	20000000	        62.5 ns/op
    72  BenchmarkLoadMostlyMisses/*sync.Map-4                    	50000000	        22.7 ns/op
    73  BenchmarkLoadMostlyMisses/*cmap.Cmap-4                   	30000000	        40.3 ns/op
    74  --- SKIP: BenchmarkLoadOrStoreBalanced/*cmap_test.DeepCopyMap
    75      cmap_bench_test.go:91: DeepCopyMap has quadratic running time.
    76  BenchmarkLoadOrStoreBalanced/*cmap_test.RWMutexMap-4     	 3000000	       437 ns/op
    77  BenchmarkLoadOrStoreBalanced/*sync.Map-4                 	 3000000	       546 ns/op
    78  BenchmarkLoadOrStoreBalanced/*cmap.Cmap-4                	 3000000	       497 ns/op
    79  --- SKIP: BenchmarkLoadOrStoreUnique/*cmap_test.DeepCopyMap
    80      cmap_bench_test.go:123: DeepCopyMap has quadratic running time.
    81  BenchmarkLoadOrStoreUnique/*cmap_test.RWMutexMap-4       	 2000000	       990 ns/op
    82  BenchmarkLoadOrStoreUnique/*sync.Map-4                   	 1000000	      1032 ns/op
    83  BenchmarkLoadOrStoreUnique/*cmap.Cmap-4                  	 2000000	       892 ns/op
    84  BenchmarkLoadOrStoreCollision/*cmap_test.DeepCopyMap-4   	100000000	        18.2 ns/op
    85  BenchmarkLoadOrStoreCollision/*cmap_test.RWMutexMap-4    	10000000	       165 ns/op
    86  BenchmarkLoadOrStoreCollision/*sync.Map-4                	100000000	        19.6 ns/op
    87  BenchmarkLoadOrStoreCollision/*cmap.Cmap-4               	20000000	        65.7 ns/op
    88  BenchmarkRange/*cmap_test.DeepCopyMap-4                  	  200000	      8646 ns/op
    89  BenchmarkRange/*cmap_test.RWMutexMap-4                   	   20000	     62046 ns/op
    90  BenchmarkRange/*sync.Map-4                               	  200000	      9317 ns/op
    91  BenchmarkRange/*cmap.Cmap-4                              	   50000	     31107 ns/op
    92  BenchmarkAdversarialAlloc/*cmap_test.DeepCopyMap-4       	 2000000	       531 ns/op
    93  BenchmarkAdversarialAlloc/*cmap_test.RWMutexMap-4        	20000000	        74.3 ns/op
    94  BenchmarkAdversarialAlloc/*sync.Map-4                    	 5000000	       390 ns/op
    95  BenchmarkAdversarialAlloc/*cmap.Cmap-4                   	30000000	        53.6 ns/op
    96  BenchmarkAdversarialDelete/*cmap_test.DeepCopyMap-4      	 5000000	       273 ns/op
    97  BenchmarkAdversarialDelete/*cmap_test.RWMutexMap-4       	20000000	        94.4 ns/op
    98  BenchmarkAdversarialDelete/*sync.Map-4                   	10000000	       137 ns/op
    99  BenchmarkAdversarialDelete/*cmap.Cmap-4                  	30000000	        43.3 ns/op
   100  ```