package memory

Import Path
	modernc.org/memory (on go.dev)

Dependency Relation
	imports 6 packages, and imported by one package

Involved Source Files

	   #d memory.go
		Package memory implements a memory allocator.

		Build status

		available at https://modern-c.appspot.com/-/builder/?importpath=modernc.org%2fmemory

		Changelog

		2017-10-03 Added alternative, unsafe.Pointer-based API.

		Package memory implements a memory allocator.

		Changelog

		2017-10-03 Added alternative, unsafe.Pointer-based API.

		Benchmarks

		AMD Ryzen 9 3900X 12-Core Processor × 24

		 jnml@3900x:~/src/modernc.org/memory$ date ; go version ; go test -run @ -bench . -benchmem |& tee log
		 Fri Nov 20 17:23:04 CET 2020
		 go version go1.15.5 linux/amd64
		 goos: linux
		 goarch: amd64
		 pkg: modernc.org/memory
		 BenchmarkFree16-24             	141188362	         8.26 ns/op	       0 B/op	       0 allocs/op
		 BenchmarkFree32-24             	100000000	        11.4 ns/op	       0 B/op	       0 allocs/op
		 BenchmarkFree64-24             	67160647	        18.3 ns/op	       0 B/op	       0 allocs/op
		 BenchmarkCalloc16-24           	60612698	        19.8 ns/op	       0 B/op	       0 allocs/op
		 BenchmarkCalloc32-24           	47968105	        23.8 ns/op	       0 B/op	       0 allocs/op
		 BenchmarkCalloc64-24           	40752181	        28.6 ns/op	       0 B/op	       0 allocs/op
		 BenchmarkGoCalloc16-24         	66487354	        17.8 ns/op	      16 B/op	       1 allocs/op
		 BenchmarkGoCalloc32-24         	56009206	        21.2 ns/op	      32 B/op	       1 allocs/op
		 BenchmarkGoCalloc64-24         	52086571	        23.4 ns/op	      64 B/op	       1 allocs/op
		 BenchmarkMalloc16-24           	113943390	        10.2 ns/op	       0 B/op	       0 allocs/op
		 BenchmarkMalloc32-24           	113520471	        10.2 ns/op	       0 B/op	       0 allocs/op
		 BenchmarkMalloc64-24           	108787056	        10.7 ns/op	       0 B/op	       0 allocs/op
		 BenchmarkUintptrFree16-24      	146110286	         7.94 ns/op	       0 B/op	       0 allocs/op
		 BenchmarkUintptrFree32-24      	93052707	        12.0 ns/op	       0 B/op	       0 allocs/op
		 BenchmarkUintptrFree64-24      	69805262	        17.3 ns/op	       0 B/op	       0 allocs/op
		 BenchmarkUintptrCalloc16-24    	85282725	        13.7 ns/op	       0 B/op	       0 allocs/op
		 BenchmarkUintptrCalloc32-24    	66489789	        17.9 ns/op	       0 B/op	       0 allocs/op
		 BenchmarkUintptrCalloc64-24    	53561092	        22.7 ns/op	       0 B/op	       0 allocs/op
		 BenchmarkUintptrMalloc16-24    	222978858	         5.28 ns/op	       0 B/op	       0 allocs/op
		 BenchmarkUintptrMalloc32-24    	210443384	         5.30 ns/op	       0 B/op	       0 allocs/op
		 BenchmarkUintptrMalloc64-24    	213706227	         5.47 ns/op	       0 B/op	       0 allocs/op
		 PASS
		 ok  	modernc.org/memory	70.528s
		 jnml@3900x:~/src/modernc.org/memory$

		Intel® Core™ i5-4670 CPU @ 3.40GHz × 4

		 ==== jnml@4670:~/src/modernc.org/memory> date ; go version ; go test -run @ -bench . -benchmem |& tee log
		 Sat Dec  8 12:56:53 CET 2018
		 go version go1.11.2 linux/amd64
		 goos: linux
		 goarch: amd64
		 pkg: modernc.org/memory
		 BenchmarkFree16-4            	100000000	        14.7 ns/op	       0 B/op	       0 allocs/op
		 BenchmarkFree32-4            	100000000	        20.5 ns/op	       0 B/op	       0 allocs/op
		 BenchmarkFree64-4            	50000000	        32.8 ns/op	       0 B/op	       0 allocs/op
		 BenchmarkCalloc16-4          	50000000	        24.4 ns/op	       0 B/op	       0 allocs/op
		 BenchmarkCalloc32-4          	50000000	        29.2 ns/op	       0 B/op	       0 allocs/op
		 BenchmarkCalloc64-4          	50000000	        35.7 ns/op	       0 B/op	       0 allocs/op
		 BenchmarkGoCalloc16-4        	50000000	        27.0 ns/op	      16 B/op	       1 allocs/op
		 BenchmarkGoCalloc32-4        	50000000	        27.3 ns/op	      32 B/op	       1 allocs/op
		 BenchmarkGoCalloc64-4        	30000000	        37.9 ns/op	      64 B/op	       1 allocs/op
		 BenchmarkMalloc16-4          	100000000	        12.9 ns/op	       0 B/op	       0 allocs/op
		 BenchmarkMalloc32-4          	100000000	        12.9 ns/op	       0 B/op	       0 allocs/op
		 BenchmarkMalloc64-4          	100000000	        13.2 ns/op	       0 B/op	       0 allocs/op
		 BenchmarkUintptrFree16-4     	100000000	        12.0 ns/op	       0 B/op	       0 allocs/op
		 BenchmarkUintptrFree32-4     	100000000	        17.5 ns/op	       0 B/op	       0 allocs/op
		 BenchmarkUintptrFree64-4     	50000000	        28.9 ns/op	       0 B/op	       0 allocs/op
		 BenchmarkUintptrCalloc16-4   	100000000	        17.8 ns/op	       0 B/op	       0 allocs/op
		 BenchmarkUintptrCalloc32-4   	100000000	        22.9 ns/op	       0 B/op	       0 allocs/op
		 BenchmarkUintptrCalloc64-4   	50000000	        29.6 ns/op	       0 B/op	       0 allocs/op
		 BenchmarkUintptrMalloc16-4   	200000000	         7.31 ns/op	       0 B/op	       0 allocs/op
		 BenchmarkUintptrMalloc32-4   	200000000	         7.47 ns/op	       0 B/op	       0 allocs/op
		 BenchmarkUintptrMalloc64-4   	200000000	         7.68 ns/op	       0 B/op	       0 allocs/op
		 PASS
		 ok  	modernc.org/memory	73.859s
		 //
		Intel® Xeon(R) CPU E5-1650 v2 @ 3.50GHz × 12

		 ==== jnml@e5-1650:~/src/modernc.org/memory> date ; go version ; go test -run @ -bench . -benchmem
		 Fri Dec  7 14:18:50 CET 2018
		 go version go1.11.2 linux/amd64
		 goos: linux
		 goarch: amd64
		 pkg: modernc.org/memory
		 BenchmarkFree16-12             	100000000	        16.7 ns/op	       0 B/op	       0 allocs/op
		 BenchmarkFree32-12             	50000000	        25.0 ns/op	       0 B/op	       0 allocs/op
		 BenchmarkFree64-12             	30000000	        39.7 ns/op	       0 B/op	       0 allocs/op
		 BenchmarkCalloc16-12           	50000000	        26.3 ns/op	       0 B/op	       0 allocs/op
		 BenchmarkCalloc32-12           	50000000	        33.4 ns/op	       0 B/op	       0 allocs/op
		 BenchmarkCalloc64-12           	30000000	        38.3 ns/op	       0 B/op	       0 allocs/op
		 BenchmarkGoCalloc16-12         	50000000	        26.6 ns/op	      16 B/op	       1 allocs/op
		 BenchmarkGoCalloc32-12         	50000000	        26.8 ns/op	      32 B/op	       1 allocs/op
		 BenchmarkGoCalloc64-12         	30000000	        35.1 ns/op	      64 B/op	       1 allocs/op
		 BenchmarkMalloc16-12           	100000000	        13.5 ns/op	       0 B/op	       0 allocs/op
		 BenchmarkMalloc32-12           	100000000	        13.4 ns/op	       0 B/op	       0 allocs/op
		 BenchmarkMalloc64-12           	100000000	        14.1 ns/op	       0 B/op	       0 allocs/op
		 BenchmarkUintptrFree16-12      	100000000	        14.4 ns/op	       0 B/op	       0 allocs/op
		 BenchmarkUintptrFree32-12      	100000000	        21.7 ns/op	       0 B/op	       0 allocs/op
		 BenchmarkUintptrFree64-12      	50000000	        36.7 ns/op	       0 B/op	       0 allocs/op
		 BenchmarkUintptrCalloc16-12    	100000000	        20.4 ns/op	       0 B/op	       0 allocs/op
		 BenchmarkUintptrCalloc32-12    	50000000	        27.1 ns/op	       0 B/op	       0 allocs/op
		 BenchmarkUintptrCalloc64-12    	50000000	        33.4 ns/op	       0 B/op	       0 allocs/op
		 BenchmarkUintptrMalloc16-12    	200000000	         8.02 ns/op	       0 B/op	       0 allocs/op
		 BenchmarkUintptrMalloc32-12    	200000000	         8.28 ns/op	       0 B/op	       0 allocs/op
		 BenchmarkUintptrMalloc64-12    	200000000	         8.29 ns/op	       0 B/op	       0 allocs/op
		 PASS
		 ok  	modernc.org/memory	80.896s

	      memory64.go
	      mmap_unix.go
	      nocounters.go
	      trace_disabled.go
Package-Level Type Names (total 4, in which 1 are exported)

	/* sort exporteds by: alphabet | popularity */
	 type Allocator (struct)
		Allocator allocates and frees memory. Its zero value is ready for use.  The
		exported counters are updated only when build tag memory.counters is
		present.

		Fields (total 7, in which 3 are exported)
			Allocs int
				// # of allocs.

			Bytes int
				// Asked from OS.

			Mmaps int
				// Asked from OS.

			/* 4 unexporteds ... *//* 4 unexporteds: */
			cap [64]int
			lists [64]uintptr
				// *node

			pages [64]uintptr
				// *page

			regs map[uintptr]struct{}
				// map[*page]struct{}

		Methods (total 17, in which 13 are exported)
			(*T) Calloc(size int) (r []byte, err error)
				Calloc is like Malloc except the allocated memory is zeroed.

			(*T) Close() (err error)
				Close releases all OS resources used by a and sets it to its zero value.

				It's not necessary to Close the Allocator when exiting a process.

			(*T) Free(b []byte) (err error)
				Free deallocates memory (as in C.free). The argument of Free must have been
				acquired from Calloc or Malloc or Realloc.

			(*T) Malloc(size int) (r []byte, err error)
				Malloc allocates size bytes and returns a byte slice of the allocated
				memory. The memory is not initialized. Malloc panics for size < 0 and
				returns (nil, nil) for zero size.

				It's ok to reslice the returned slice but the result of appending to it
				cannot be passed to Free or Realloc as it may refer to a different backing
				array afterwards.

			(*T) Realloc(b []byte, size int) (r []byte, err error)
				Realloc changes the size of the backing array of b to size bytes or returns
				an error, if any.  The contents will be unchanged in the range from the
				start of the region up to the minimum of the old and new  sizes.   If the
				new size is larger than the old size, the added memory will not be
				initialized.  If b's backing array is of zero size, then the call is
				equivalent to Malloc(size), for all values of size; if size is equal to
				zero, and b's backing array is not of zero size, then the call is equivalent
				to Free(b).  Unless b's backing array is of zero size, it must have been
				returned by an earlier call to Malloc, Calloc or Realloc.  If the area
				pointed to was moved, a Free(b) is done.

			(*T) UintptrCalloc(size int) (r uintptr, err error)
				UintptrCalloc is like Calloc except it returns an uintptr.

			(*T) UintptrFree(p uintptr) (err error)
				UintptrFree is like Free except its argument is an uintptr, which must have
				been acquired from UintptrCalloc or UintptrMalloc or UintptrRealloc.

			(*T) UintptrMalloc(size int) (r uintptr, err error)
				UintptrMalloc is like Malloc except it returns an uinptr.

			(*T) UintptrRealloc(p uintptr, size int) (r uintptr, err error)
				UintptrRealloc is like Realloc except its first argument is an uintptr,
				which must have been returned from UintptrCalloc, UintptrMalloc or
				UintptrRealloc.

			(*T) UnsafeCalloc(size int) (r unsafe.Pointer, err error)
				UnsafeCalloc is like Calloc except it returns an unsafe.Pointer.

			(*T) UnsafeFree(p unsafe.Pointer) (err error)
				UnsafeFree is like Free except its argument is an unsafe.Pointer, which must
				have been acquired from UnsafeCalloc or UnsafeMalloc or UnsafeRealloc.

			(*T) UnsafeMalloc(size int) (r unsafe.Pointer, err error)
				UnsafeMalloc is like Malloc except it returns an unsafe.Pointer.

			(*T) UnsafeRealloc(p unsafe.Pointer, size int) (r unsafe.Pointer, err error)
				UnsafeRealloc is like Realloc except its first argument is an
				unsafe.Pointer, which must have been returned from UnsafeCalloc,
				UnsafeMalloc or UnsafeRealloc.

			/* 4 unexporteds ... *//* 4 unexporteds: */
			(*T) mmap(size int) (uintptr, error)
			(*T) newPage(size int) (uintptr, error)
			(*T) newSharedPage(log uint) (uintptr, error)
			(*T) unmap(p uintptr) error
		Implements (at least one exported)
			*T : io.Closer
		As Types Of (only one, which is unexported)
			/* one unexported ... *//* one unexported: */
			  var modernc.org/libc.allocator

	/* 3 unexporteds ... *//* 3 unexporteds: */
	 type node (struct)

		Fields (total 2, neither is exported)
			/* 2 unexporteds ... *//* 2 unexporteds: */
			next uintptr
				// *node

			prev uintptr
				// *node


	 type page (struct)

		Fields (total 4, none are exported)
			/* 4 unexporteds ... *//* 4 unexporteds: */
			brk int
			log uint
			size int
			used int

	 type rawmem ([...]T)
Package-Level Functions (total 8, in which 3 are exported)

	 func UintptrUsableSize(p uintptr) (r int)
		UintptrUsableSize is like UsableSize except its argument is an uintptr,
		which must have been returned from UintptrCalloc, UintptrMalloc or
		UintptrRealloc.

	 func UnsafeUsableSize(p unsafe.Pointer) (r int)
		UnsafeUsableSize is like UsableSize except its argument is an
		unsafe.Pointer, which must have been returned from UnsafeCalloc,
		UnsafeMalloc or UnsafeRealloc.

	 func UsableSize(p *byte) (r int)
		UsableSize reports the size of the memory block allocated at p, which must
		point to the first byte of a slice returned from Calloc, Malloc or Realloc.
		The allocated memory block size can be larger than the size originally
		requested from Calloc, Malloc or Realloc.

	/* 5 unexporteds ... *//* 5 unexporteds: */
	 func init()
	 func mmap(size int) (uintptr, int, error)
		pageSize aligned.

	 func roundup(n, m int) int
		if n%m != 0 { n += m-n%m }. m must be a power of 2.

	 func unmap(addr uintptr, size int) error
	 func usableSize(p uintptr) (r int)
Package-Level Variables (total 2, neither is exported)

	/* 2 unexporteds ... *//* 2 unexporteds: */
	  var osPageMask int
	  var osPageSize int
Package-Level Constants (total 10, none are exported)

	/* 10 unexporteds ... *//* 10 unexporteds: */
	const counters = false
	const headerSize uintptr = 32
	const mallocAllign uintptr = 16
	const maxSlotSize = 262144
	const maxSlotSizeLog = 18
	const pageAvail uintptr = 1048544
	const pageMask = 1048575
	const pageSize = 1048576
	const pageSizeLog = 20
	const trace = false

The pages are generated with Golds v0.3.6. (GOOS=darwin GOARCH=amd64)
Golds is a Go 101 project developed by Tapir Liu.
PR and bug reports are welcome and can be submitted to the issue list.
Please follow @Go100and1 (reachable from the left QR code) to get the latest news of Golds.