Пакет runtime

• import "runtime"
• Обзор
• Указатель
• Примеры
• Подкаталоги

Обзор

Пакет runtime содержит операции, взаимодействующие с системой времени выполнения Go, например функции для управления горутинами. Он также включает низкоуровневую информацию о типах, используемую пакетом reflect; см. документацию reflect о программном интерфейсе к системе типов времени выполнения.

Переменные среды

Следующие переменные среды ($name или %name%, в зависимости от операционной системы узла) управляют поведением программ Go во время выполнения. Их значения и использование могут меняться от выпуска к выпуску.

Переменная GOGC задаёт начальный целевой процент сборки мусора. Сборка запускается, когда отношение объёма недавно выделенных данных к объёму данных, оставшихся после предыдущей сборки, достигает этого процента. Значение по умолчанию — GOGC=100. Установка GOGC=off полностью отключает сборщик мусора. runtime/debug.SetGCPercent позволяет изменять этот процент во время выполнения.

Переменная GOMEMLIMIT задаёт мягкое ограничение памяти для среды выполнения. Это ограничение включает кучу Go и всю остальную память, управляемую средой выполнения, но не включает внешние источники памяти, такие как отображения самого исполняемого файла, память, управляемую на других языках, и память, удерживаемую операционной системой от имени программы Go. GOMEMLIMIT — числовое значение в байтах с необязательным суффиксом единицы измерения. Поддерживаются суффиксы B, KiB, MiB, GiB и TiB. Эти суффиксы обозначают количества байтов согласно стандарту IEC 80000-13. То есть они основаны на степенях двойки: KiB означает 2^10 байт, MiB — 2^20 байт и так далее. По умолчанию установлено значение math.MaxInt64, что фактически отключает ограничение памяти. runtime/debug.SetMemoryLimit позволяет изменять это ограничение во время выполнения.

Переменная GODEBUG управляет переменными отладки внутри среды выполнения. Это разделённый запятыми список пар name=val, задающих следующие именованные переменные:

clobberfree: setting clobberfree=1 causes the garbage collector to
clobber the memory content of an object with bad content when it frees
the object.

cpu.*: cpu.all=off disables the use of all optional instruction set extensions.
cpu.extension=off disables use of instructions from the specified instruction set extension.
extension is the lower case name for the instruction set extension such as sse41 or avx
as listed in internal/cpu package. As an example cpu.avx=off disables runtime detection
and thereby use of AVX instructions.

cgocheck: setting cgocheck=0 disables all checks for packages
using cgo to incorrectly pass Go pointers to non-Go code.
Setting cgocheck=1 (the default) enables relatively cheap
checks that may miss some errors. A more complete, but slow,
cgocheck mode can be enabled using GOEXPERIMENT (which
requires a rebuild), see https://pkg.go.dev/internal/goexperiment for details.

checkfinalizers: setting checkfinalizers=1 causes the garbage collector to run
multiple partial non-parallel stop-the-world collections to identify common issues with
finalizers and cleanups, like those listed at
https://go.dev/doc/gc-guide#Finalizers_cleanups_and_weak_pointers. If a potential issue
is found, the program will terminate with a description of all potential issues, the
associated values, and a list of those values' finalizers and cleanups, including where
they were created. It also adds tracking for tiny blocks to help diagnose issues with
those as well. The analysis performed during the partial collection is conservative.
Notably, it flags any path back to the original object from the cleanup function,
cleanup arguments, or finalizer function as a potential issue, even if that path might
be severed sometime later during execution (though this is not a recommended pattern).
This mode also produces one line of output to stderr every GC cycle with information
about the finalizer and cleanup queue lengths. Lines produced by this mode start with
"checkfinalizers:".

decoratemappings: controls whether the Go runtime annotates OS
anonymous memory mappings with context about their purpose. These
annotations appear in /proc/self/maps and /proc/self/smaps as
"[anon: Go: ...]". This setting is only used on Linux. For Go 1.25, it
defaults to `decoratemappings=1`, enabling annotations. Using
`decoratemappings=0` reverts to the pre-Go 1.25 behavior.

disablethp: setting disablethp=1 on Linux disables transparent huge pages for the heap.
It has no effect on other platforms. disablethp is meant for compatibility with versions
of Go before 1.21, which stopped working around a Linux kernel default that can result
in significant memory overuse. See https://go.dev/issue/64332. This setting will be
removed in a future release, so operators should tweak their Linux configuration to suit
their needs before then. See https://go.dev/doc/gc-guide#Linux_transparent_huge_pages.

dontfreezetheworld: by default, the start of a fatal panic or throw
"freezes the world", preempting all threads to stop all running
goroutines, which makes it possible to traceback all goroutines, and
keeps their state close to the point of panic. Setting
dontfreezetheworld=1 disables this preemption, allowing goroutines to
continue executing during panic processing. Note that goroutines that
naturally enter the scheduler will still stop. This can be useful when
debugging the runtime scheduler, as freezetheworld perturbs scheduler
state and thus may hide problems.

efence: setting efence=1 causes the allocator to run in a mode
where each object is allocated on a unique page and addresses are
never recycled.

gccheckmark: setting gccheckmark=1 enables verification of the
garbage collector's concurrent mark phase by performing a
second mark pass while the world is stopped.  If the second
pass finds a reachable object that was not found by concurrent
mark, the garbage collector will panic.

gcpacertrace: setting gcpacertrace=1 causes the garbage collector to
print information about the internal state of the concurrent pacer.

gcshrinkstackoff: setting gcshrinkstackoff=1 disables moving goroutines
onto smaller stacks. In this mode, a goroutine's stack can only grow.

gcstoptheworld: setting gcstoptheworld=1 disables concurrent garbage collection,
making every garbage collection a stop-the-world event. Setting gcstoptheworld=2
also disables concurrent sweeping after the garbage collection finishes.

gctrace: setting gctrace=1 causes the garbage collector to emit a single line to standard
error at each collection, summarizing the amount of memory collected and the
length of the pause. The format of this line is subject to change. Included in
the explanation below is also the relevant runtime/metrics metric for each field.
Currently, it is:
	gc # @#s #%: #+#+# ms clock, #+#/#/#+# ms cpu, #->#-># MB, # MB goal, # MB stacks, #MB globals, # P
where the fields are as follows:
	gc #         the GC number, incremented at each GC
	@#s          time in seconds since program start
	#%           percentage of time spent in GC since program start
	#+...+#      wall-clock/CPU times for the phases of the GC
	#->#-># MB   heap size at GC start, at GC end, and live heap, or /gc/scan/heap:bytes
	# MB goal    goal heap size, or /gc/heap/goal:bytes
	# MB stacks  estimated scannable stack size, or /gc/scan/stack:bytes
	# MB globals scannable global size, or /gc/scan/globals:bytes
	# P          number of processors used, or /sched/gomaxprocs:threads
The phases are stop-the-world (STW) sweep termination, concurrent
mark and scan, and STW mark termination. The CPU times
for mark/scan are broken down in to assist time (GC performed in
line with allocation), background GC time, and idle GC time.
If the line ends with "(forced)", this GC was forced by a
runtime.GC() call.

harddecommit: setting harddecommit=1 causes memory that is returned to the OS to
also have protections removed on it. This is the only mode of operation on Windows,
but is helpful in debugging scavenger-related issues on other platforms. Currently,
only supported on Linux.

inittrace: setting inittrace=1 causes the runtime to emit a single line to standard
error for each package with init work, summarizing the execution time and memory
allocation. No information is printed for inits executed as part of plugin loading
and for packages without both user defined and compiler generated init work.
The format of this line is subject to change. Currently, it is:
	init # @#ms, # ms clock, # bytes, # allocs
where the fields are as follows:
	init #      the package name
	@# ms       time in milliseconds when the init started since program start
	# clock     wall-clock time for package initialization work
	# bytes     memory allocated on the heap
	# allocs    number of heap allocations

madvdontneed: setting madvdontneed=0 will use MADV_FREE
instead of MADV_DONTNEED on Linux when returning memory to the
kernel. This is more efficient, but means RSS numbers will
drop only when the OS is under memory pressure. On the BSDs and
Illumos/Solaris, setting madvdontneed=1 will use MADV_DONTNEED instead
of MADV_FREE. This is less efficient, but causes RSS numbers to drop
more quickly.

memprofilerate: setting memprofilerate=X will update the value of runtime.MemProfileRate.
When set to 0 memory profiling is disabled.  Refer to the description of
MemProfileRate for the default value.

profstackdepth: profstackdepth=128 (the default) will set the maximum stack
depth used by all pprof profilers except for the CPU profiler to 128 frames.
Stack traces that exceed this limit will be truncated to the limit starting
from the leaf frame. Setting profstackdepth to any value above 1024 will
silently default to 1024. Future versions of Go may remove this limitation
and extend profstackdepth to apply to the CPU profiler and execution tracer.

panicnil: setting panicnil=1 disables the runtime error when calling panic with nil
interface value or an untyped nil.

invalidptr: invalidptr=1 (the default) causes the garbage collector and stack
copier to crash the program if an invalid pointer value (for example, 1)
is found in a pointer-typed location. Setting invalidptr=0 disables this check.
This should only be used as a temporary workaround to diagnose buggy code.
The real fix is to not store integers in pointer-typed locations.

sbrk: setting sbrk=1 replaces the memory allocator and garbage collector
with a trivial allocator that obtains memory from the operating system and
never reclaims any memory.

scavtrace: setting scavtrace=1 causes the runtime to emit a single line to standard
error, roughly once per GC cycle, summarizing the amount of work done by the
scavenger as well as the total amount of memory returned to the operating system
and an estimate of physical memory utilization. The format of this line is subject
to change, but currently it is:
	scav # KiB work (bg), # KiB work (eager), # KiB total, #% util
where the fields are as follows:
	# KiB work (bg)    the amount of memory returned to the OS in the background since
	                   the last line
	# KiB work (eager) the amount of memory returned to the OS eagerly since the last line
	# KiB now          the amount of address space currently returned to the OS
	#% util            the fraction of all unscavenged heap memory which is in-use
If the line ends with "(forced)", then scavenging was forced by a
debug.FreeOSMemory() call.

scheddetail: setting schedtrace=X and scheddetail=1 causes the scheduler to emit
detailed multiline info every X milliseconds, describing state of the scheduler,
processors, threads and goroutines.

schedtrace: setting schedtrace=X causes the scheduler to emit a single line to standard
error every X milliseconds, summarizing the scheduler state.

tracebackancestors: setting tracebackancestors=N extends tracebacks with the stacks at
which goroutines were created, where N limits the number of ancestor goroutines to
report. This also extends the information returned by runtime.Stack.
Setting N to 0 will report no ancestry information.

tracefpunwindoff: setting tracefpunwindoff=1 forces the execution tracer
and block and mutex profilers to use the runtime's default stack
unwinder instead of frame pointer unwinding. This increases their
overhead, but could be helpful as a workaround or for debugging
unexpected regressions caused by frame pointer unwinding.

traceadvanceperiod: the approximate period in nanoseconds between trace generations. Only
applies if a program is built with GOEXPERIMENT=exectracer2. Used primarily for testing
and debugging the execution tracer.

tracecheckstackownership: setting tracecheckstackownership=1 enables a debug check in the
execution tracer to double-check stack ownership before taking a stack trace.

asyncpreemptoff: asyncpreemptoff=1 disables signal-based
asynchronous goroutine preemption. This makes some loops
non-preemptible for long periods, which may delay GC and
goroutine scheduling. This is useful for debugging GC issues
because it also disables the conservative stack scanning used
for asynchronously preempted goroutines.

Пакеты net и net/http также используют переменные отладки в GODEBUG. Подробности см. в документации этих пакетов.

Переменная GOMAXPROCS ограничивает число потоков операционной системы, которые могут одновременно выполнять код Go на пользовательском уровне. Число потоков, заблокированных в системных вызовах от имени кода Go, не ограничено; они не учитываются в ограничении GOMAXPROCS. Функция GOMAXPROCS этого пакета позволяет запрашивать и изменять ограничение.

Переменная GORACE настраивает детектор гонок для программ, собранных с помощью -race. Подробности см. в статье о детекторе гонок.

Переменная GOTRACEBACK управляет объёмом вывода, создаваемого при сбое программы Go из-за невосстановленной паники или неожиданного условия времени выполнения. По умолчанию при сбое выводится трассировка стека текущей горутины, из которой исключаются функции внутренней системы времени выполнения, после чего программа завершается с кодом выхода 2. Трассировки стека всех горутин выводятся, если текущей горутины нет или сбой произошёл внутри среды времени выполнения. GOTRACEBACK=none полностью исключает трассировки стека горутин. GOTRACEBACK=single (значение по умолчанию) работает так, как описано выше. GOTRACEBACK=all добавляет трассировки стека всех созданных пользователем горутин. GOTRACEBACK=system действует подобно «all», но добавляет кадры стека для функций времени выполнения и показывает горутины, созданные самой средой времени выполнения. GOTRACEBACK=crash действует подобно «system», но приводит к сбою способом, специфичным для операционной системы, вместо завершения работы. Например, в системах Unix сбой вызывает SIGABRT для создания дампа памяти. GOTRACEBACK=wer действует подобно «crash», но не отключает Windows Error Reporting (WER). По историческим причинам значения GOTRACEBACK 0, 1 и 2 являются синонимами none, all и system соответственно. Функция runtime/debug.SetTraceback позволяет увеличить объём вывода во время выполнения, но не может уменьшить его ниже уровня, заданного переменной среды.

Переменные среды GOARCH, GOOS, GOPATH и GOROOT дополняют набор переменных среды Go. Они влияют на сборку программ Go (см. cmd/go и go/build). Значения GOARCH, GOOS и GOROOT фиксируются во время компиляции и доступны через константы или функции этого пакета, но не влияют на выполнение системы времени выполнения.

Безопасность

На платформах Unix система времени выполнения Go ведёт себя немного иначе, если для исполняемого файла установлены атрибуты setuid/setgid или он запущен с аналогичными свойствами, чтобы предотвратить опасное поведение. В Linux это определяется проверкой флага AT_SECURE во вспомогательном векторе, в BSD и Solaris/Illumos — проверкой системного вызова issetugid, а в AIX — проверкой совпадения uid/gid с эффективными uid/gid.

Когда среда выполнения определяет, что исполняемый файл имеет свойства setuid/setgid, она выполняет два основных действия:

• Значение переменной среды GOTRACEBACK устанавливается в 'none'.
• Если получен сигнал, завершающий программу, или программа сталкивается с невосстановимой паникой, которая иначе переопределила бы значение GOTRACEBACK, сведения о стеке горутины, регистрах и другой связанной с памятью информации не выводятся.

Кроме того, на платформах Unix среда выполнения Go автоматически проверяет, открыты ли стандартные файловые дескрипторы ввода/вывода (0, 1, 2). Если какой-либо из них закрыт, он открывается с указанием на /dev/null.

Указатель

• Константы
• Переменные
• func BlockProfile(p []BlockProfileRecord) (n int, ok bool)
• func Breakpoint()
• func CPUProfile() []byte
• func Caller(skip int) (pc uintptr, file string, line int, ok bool)
• func Callers(skip int, pc []uintptr) int
• func GC()
• func GOMAXPROCS(n int) int
• func GOROOT() string
• func Goexit()
• func GoroutineProfile(p []StackRecord) (n int, ok bool)
• func Gosched()
• func KeepAlive(x any)
• func LockOSThread()
• func MemProfile(p []MemProfileRecord, inuseZero bool) (n int, ok bool)
• func MutexProfile(p []BlockProfileRecord) (n int, ok bool)
• func NumCPU() int
• func NumCgoCall() int64
• func NumGoroutine() int
• func ReadMemStats(m *MemStats)
• func ReadTrace() (buf []byte)
• func SetBlockProfileRate(rate int)
• func SetCPUProfileRate(hz int)
• func SetCgoTraceback(version int, traceback, context, symbolizer unsafe.Pointer)
• func SetDefaultGOMAXPROCS()
• func SetFinalizer(obj any, finalizer any)
• func SetMutexProfileFraction(rate int) int
• func Stack(buf []byte, all bool) int
• func StartTrace() error
• func StopTrace()
• func ThreadCreateProfile(p []StackRecord) (n int, ok bool)
• func UnlockOSThread()
• func Version() string
• type BlockProfileRecord
• type Cleanup
• func AddCleanup[T, S any](ptr *T, cleanup func(S), arg S) Cleanup
• func (c Cleanup) Stop()
• type Error
• type Frame
• type Frames
• func CallersFrames(callers []uintptr) *Frames
• func (ci *Frames) Next() (frame Frame, more bool)
• type Func
• func FuncForPC(pc uintptr) *Func
• func (f *Func) Entry() uintptr
• func (f *Func) FileLine(pc uintptr) (file string, line int)
• func (f *Func) Name() string
• type MemProfileRecord
• func (r *MemProfileRecord) InUseBytes() int64
• func (r *MemProfileRecord) InUseObjects() int64
• func (r *MemProfileRecord) Stack() []uintptr
• type MemStats
• type PanicNilError
• func (*PanicNilError) Error() string
• func (*PanicNilError) RuntimeError()
• type Pinner
• func (p *Pinner) Pin(pointer any)
• func (p *Pinner) Unpin()
• type StackRecord
• func (r *StackRecord) Stack() []uintptr
• type TypeAssertionError
• func (e *TypeAssertionError) Error() string
• func (*TypeAssertionError) RuntimeError()

Файлы пакета

alg.go arena.go asan0.go atomic_pointer.go badlinkname.go badlinkname_linux.go cgo.go cgo_mmap.go cgo_sigaction.go cgocall.go cgocallback.go cgocheck.go cgroup_linux.go chan.go checkptr.go compiler.go complex.go coro.go covercounter.go covermeta.go cpuflags.go cpuflags_amd64.go cpuprof.go cputicks.go create_file_unix.go debug.go debugcall.go debuglog.go debuglog_off.go defs_linux_amd64.go dit.go env_posix.go error.go extern.go fastlog2.go fastlog2table.go fds_unix.go fipsbypass.go float.go heapdump.go hexdump.go histogram.go iface.go lfstack.go libinit.go linkname.go linkname_shim.go linkname_unix.go list.go list_manual.go lock_futex.go lock_spinbit.go lockrank.go lockrank_off.go malloc.go malloc_generated.go malloc_stubs.go malloc_tables_generated.go map.go map_fast32.go map_fast64.go map_faststr.go mbarrier.go mbitmap.go mcache.go mcentral.go mcheckmark.go mcleanup.go mem.go mem_linux.go mem_nonsbrk.go metrics.go mfinal.go mfixalloc.go mgc.go mgclimit.go mgcmark.go mgcmark_greenteagc.go mgcpacer.go mgcscavenge.go mgcstack.go mgcsweep.go mgcwork.go mheap.go minmax.go mpagealloc.go mpagealloc_64bit.go mpagecache.go mpallocbits.go mprof.go mranges.go msan0.go msize.go mspanset.go mstats.go mwbbuf.go nbpipe_pipe2.go netpoll.go netpoll_epoll.go nonwindows_stub.go note_other.go os_linux.go os_linux64.go os_linux_generic.go os_linux_noauxv.go os_nonopenbsd.go os_unix.go panic.go pinner.go plugin.go preempt.go preempt_amd64.go preempt_nonwindows.go preempt_xreg.go print.go proc.go profbuf.go proflabel.go race0.go rand.go rdebug.go retry.go runtime.go runtime1.go runtime2.go runtime_boring.go runtime_clearenv.go rwmutex.go secret.go secret_asm.go security_linux.go security_unix.go select.go sema.go set_vma_name_linux.go signal_amd64.go signal_linux_amd64.go signal_unix.go sigqueue.go sigqueue_note.go sigtab_linux_generic.go slice.go softfloat64.go stack.go stkframe.go string.go stubs.go stubs2.go stubs3.go stubs_amd64.go stubs_linux.go stubs_nonwasm.go symtab.go symtabinl.go synctest.go sys_nonppc64x.go sys_x86.go tagptr.go tagptr_64bit.go test_amd64.go time.go time_nofake.go timeasm.go tls_stub.go trace.go traceallocfree.go traceback.go tracebuf.go tracecpu.go traceevent.go tracemap.go traceregion.go traceruntime.go tracestack.go tracestatus.go tracestring.go tracetime.go tracetype.go type.go unsafe.go utf8.go valgrind0.go vdso_elf64.go vdso_linux.go vdso_linux_amd64.go vgetrandom_linux.go write_err.go

Константы

Compiler — имя цепочки инструментов компилятора, с помощью которой был собран выполняющийся исполняемый файл. Известные цепочки инструментов:

gc      Also known as cmd/compile.
gccgo   The gccgo front end, part of the GCC compiler suite.

const Compiler = "gc"

GOARCH — целевая архитектура выполняющейся программы: одна из 386, amd64, arm, s390x и так далее.

const GOARCH string = goarch.GOARCH

GOOS — целевая операционная система выполняющейся программы: одна из darwin, freebsd, linux и так далее. Чтобы просмотреть возможные сочетания GOOS и GOARCH, выполните команду "go tool dist list".

const GOOS string = goos.GOOS

Переменные

MemProfileRate управляет долей выделений памяти, записываемых и отображаемых в профиле памяти. Профилировщик стремится отбирать в среднем одно выделение на каждые MemProfileRate байт выделенной памяти.

Чтобы включить в профиль каждый выделенный блок, установите MemProfileRate в 1. Чтобы полностью отключить профилирование, установите MemProfileRate в 0.

Инструменты обработки профилей памяти предполагают, что частота профилирования постоянна на протяжении всего времени выполнения программы и равна текущему значению. Программы, изменяющие частоту профилирования памяти, должны делать это только один раз, как можно раньше во время выполнения программы (например, в начале main).

var MemProfileRate int = 512 * 1024

func BlockProfile 1.1

func BlockProfile(p []BlockProfileRecord) (n int, ok bool)

BlockProfile возвращает n — число записей в текущем профиле блокировок. Если len(p) >= n, BlockProfile копирует профиль в p и возвращает n, true. Если len(p) < n, BlockProfile не изменяет p и возвращает n, false.

Большинству пользователей следует использовать пакет runtime/pprof или флаг -test.blockprofile пакета testing, а не вызывать BlockProfile напрямую.

func Breakpoint

func Breakpoint()

Breakpoint выполняет ловушку останова.

func CPUProfile

func CPUProfile() []byte

CPUProfile вызывает панику. Ранее эта функция предоставляла прямой доступ к фрагментам профиля в формате pprof, создаваемого средой выполнения. Подробности создания этого формата изменились, поэтому эта функциональность была удалена.

Устарело: используйте пакет runtime/pprof, обработчики пакета net/http/pprof или флаг -test.cpuprofile пакета testing.

func Caller

func Caller(skip int) (pc uintptr, file string, line int, ok bool)

Caller сообщает сведения об имени файла и номере строки для вызовов функций в стеке вызывающей горутины. Аргумент skip задаёт число кадров стека, которые нужно пропустить, причём 0 обозначает вызывающий код функции Caller. (По историческим причинам значение skip в Caller отличается от значения в Callers.) Возвращаемые значения содержат счётчик команд, имя файла (с использованием прямой косой черты в качестве разделителя пути даже в Windows) и номер строки в файле для соответствующего вызова. Логическое значение ok равно false, если восстановить сведения не удалось.

func Callers

func Callers(skip int, pc []uintptr) int

Callers заполняет срез pc адресами возврата вызовов функций в стеке вызывающей горутины. Аргумент skip задаёт число кадров стека, которые нужно пропустить перед записью в pc: 0 обозначает кадр самой Callers, а 1 — кадр вызывающего кода Callers. Функция возвращает число записей, помещённых в pc.

Чтобы преобразовать эти адреса команд в символическую информацию, например имена функций и номера строк, используйте CallersFrames. CallersFrames учитывает встроенные функции и преобразует адреса возврата в адреса вызовов. Не рекомендуется напрямую перебирать возвращённый срез адресов команд или использовать FuncForPC для любого из возвращённых адресов, поскольку эти способы не учитывают встраивание функций и преобразование адресов возврата.

func GC

func GC()

GC запускает сборку мусора и блокирует вызывающий код до её завершения. Она также может заблокировать всю программу.

func GOMAXPROCS

func GOMAXPROCS(n int) int

GOMAXPROCS задаёт максимальное число процессоров, которые могут одновременно выполнять код, и возвращает предыдущее значение. Если n < 1, текущее значение не изменяется.

Значение по умолчанию

Если для переменной среды GOMAXPROCS задано положительное целое число, GOMAXPROCS по умолчанию принимает это значение.

В противном случае среда выполнения Go выбирает подходящее значение по умолчанию, исходя из сочетания следующих факторов:

• число логических ЦП на компьютере,
• маска привязки процесса к ЦП,
• а также в Linux — средняя пропускная способность ЦП процесса, ограниченная квотой ЦП cgroup, если она задана.

Если задано GODEBUG=containermaxprocs=0, а переменная среды GOMAXPROCS не установлена, GOMAXPROCS по умолчанию принимает значение runtime.NumCPU. Обратите внимание, что GODEBUG=containermaxprocs=0 является значением по умолчанию для версии языка 1.24 и ниже.

Обновления

Среда выполнения Go периодически обновляет значение по умолчанию при изменении общего числа логических ЦП, маски привязки процесса к ЦП или квоты cgroup. Установка пользовательского значения с помощью переменной среды GOMAXPROCS или вызова GOMAXPROCS отключает автоматические обновления. Значение по умолчанию и автоматические обновления можно восстановить вызовом SetDefaultGOMAXPROCS.

Если задано GODEBUG=updatemaxprocs=0, среда выполнения Go не выполняет автоматическое обновление GOMAXPROCS. Обратите внимание, что GODEBUG=updatemaxprocs=0 является значением по умолчанию для версии языка 1.24 и ниже.

Совместимость

Обратите внимание, что поведение GOMAXPROCS по умолчанию может изменяться по мере совершенствования планировщика, особенно приведённая ниже деталь реализации.

Подробности реализации

При вычислении значения GOMAXPROCS по умолчанию на основе cgroups среда выполнения Go вычисляет «среднее ограничение пропускной способности ЦП» как квоту ЦП cgroup, делённую на период. В cgroup v2 эти значения берутся из файла cpu.max. В cgroup v1 они берутся соответственно из cpu.cfs_quota_us и cpu.cfs_period_us. В средах выполнения контейнеров, позволяющих настраивать ограничения ЦП, это значение обычно соответствует параметру «ограничение ЦП», а не «запрос ЦП».

Среда выполнения Go обычно выбирает для GOMAXPROCS значение по умолчанию, равное минимуму из числа логических ЦП, числа ЦП в маске привязки процесса и ограничения пропускной способности ЦП cgroup. Однако она никогда не устанавливает GOMAXPROCS ниже 2, если только число логических ЦП или ЦП в маске привязки не меньше 2.

Если ограничение пропускной способности ЦП cgroup не является целым числом, среда выполнения Go округляет его вверх до ближайшего целого числа.

Значение GOMAXPROCS обновляется не чаще одного раза в секунду, а при простое приложения — реже.

func GOROOT

func GOROOT() string

GOROOT возвращает корневой каталог дерева Go. Если переменная среды GOROOT была задана при запуске процесса, используется её значение; в противном случае используется корневой каталог, применённый при сборке Go.

Устарело: корневой каталог, применённый при сборке Go, не будет иметь смысла, если исполняемый файл скопирован на другой компьютер. Используйте системный путь для поиска исполняемого файла «go», а команду «go env GOROOT» — для определения его GOROOT.

func Goexit

func Goexit()

Goexit завершает горутину, которая её вызывает. Другие горутины не затрагиваются. Перед завершением горутины Goexit выполняет все отложенные вызовы. Поскольку Goexit не является паникой, любые вызовы recover в этих отложенных функциях вернут nil.

Вызов Goexit из главной горутины завершает эту горутину, не дожидаясь возврата func main. Поскольку func main ещё не завершилась, программа продолжает выполнение других горутин. Если все остальные горутины завершатся, программа аварийно завершится.

При вызове из потока, созданного не средой выполнения Go, функция приводит к аварийному завершению.

func GoroutineProfile

func GoroutineProfile(p []StackRecord) (n int, ok bool)

GoroutineProfile возвращает n — число записей в профиле стеков активных горутин. Если len(p) >= n, GoroutineProfile копирует профиль в p и возвращает n, true. Если len(p) < n, GoroutineProfile не изменяет p и возвращает n, false.

Большинству пользователей следует использовать пакет runtime/pprof, а не вызывать GoroutineProfile напрямую.

func Gosched

func Gosched()

Gosched уступает процессор, позволяя выполняться другим горутинам. Она не приостанавливает текущую горутину, поэтому выполнение возобновляется автоматически.

func KeepAlive 1.7

func KeepAlive(x any)

KeepAlive отмечает свой аргумент как достижимый в данный момент. Это гарантирует, что объект не будет освобождён и для него не запустится финализатор до точки программы, в которой вызвана KeepAlive.

Предельно упрощённый пример, показывающий, когда требуется KeepAlive:

type File struct { d int }
d, err := syscall.Open("/file/path", syscall.O_RDONLY, 0)
// ... do something if err != nil ...
p := &File{d}
runtime.SetFinalizer(p, func(p *File) { syscall.Close(p.d) })
var buf [10]byte
n, err := syscall.Read(p.d, buf[:])
// Ensure p is not finalized until Read returns.
runtime.KeepAlive(p)
// No more uses of p after this point.

Без вызова KeepAlive финализатор мог бы запуститься в начале syscall.Read и закрыть файловый дескриптор до того, как syscall.Read выполнит фактический системный вызов.

Примечание: KeepAlive следует использовать только для предотвращения преждевременного запуска финализаторов. В частности, при использовании с unsafe.Pointer продолжают действовать правила допустимого использования unsafe.Pointer.

func LockOSThread

func LockOSThread()

LockOSThread привязывает вызывающую горутину к текущему потоку операционной системы. Вызывающая горутина всегда будет выполняться в этом потоке, а никакая другая горутина не будет в нём выполняться, пока вызывающая горутина не вызовет UnlockOSThread столько же раз, сколько LockOSThread. Если вызывающая горутина завершится, не разблокировав поток, поток будет завершён.

Все функции init выполняются в стартовом потоке. Вызов LockOSThread из функции init приведёт к тому, что главная функция будет вызвана в этом потоке.

Горутина должна вызвать LockOSThread перед вызовом служб ОС или библиотечных функций вне Go, зависящих от состояния потока.

func MemProfile

func MemProfile(p []MemProfileRecord, inuseZero bool) (n int, ok bool)

MemProfile возвращает профиль памяти, выделенной и освобождённой в каждом месте выделения.

MemProfile возвращает n — число записей в текущем профиле памяти. Если len(p) >= n, MemProfile копирует профиль в p и возвращает n, true. Если len(p) < n, MemProfile не изменяет p и возвращает n, false.

Если inuseZero равно true, профиль включает записи выделений, для которых r.AllocBytes > 0, но r.AllocBytes == r.FreeBytes. Это места, где память была выделена, но затем полностью возвращена среде выполнения.

Возвращаемый профиль может отставать на два цикла сборки мусора. Это позволяет избежать смещения профиля в сторону выделений: выделения происходят в реальном времени, а освобождения откладываются до выполнения очистки сборщиком мусора, поэтому профиль учитывает только выделения, которые сборщик мусора уже мог освободить.

Большинству пользователей следует использовать пакет runtime/pprof или флаг -test.memprofile пакета testing, а не вызывать MemProfile напрямую.

func MutexProfile 1.8

func MutexProfile(p []BlockProfileRecord) (n int, ok bool)

MutexProfile возвращает n — число записей в текущем профиле мьютексов. Если len(p) >= n, MutexProfile копирует профиль в p и возвращает n, true. В противном случае MutexProfile не изменяет p и возвращает n, false.

Большинству пользователей следует использовать пакет runtime/pprof, а не вызывать MutexProfile напрямую.

func NumCPU

func NumCPU() int

NumCPU возвращает число логических ЦП, доступных текущему процессу.

Набор доступных ЦП определяется запросом к операционной системе при запуске процесса. Изменения распределения ЦП операционной системой после запуска процесса не учитываются.

func NumCgoCall

func NumCgoCall() int64

NumCgoCall возвращает число вызовов cgo, выполненных текущим процессом.

func NumGoroutine

func NumGoroutine() int

NumGoroutine возвращает число существующих в данный момент горутин.

func ReadMemStats

func ReadMemStats(m *MemStats)

ReadMemStats заполняет m статистикой распределителя памяти.

Возвращаемая статистика распределителя памяти актуальна на момент вызова ReadMemStats. Это отличается от профиля кучи, который представляет собой снимок состояния на момент последнего завершённого цикла сборки мусора.

func ReadTrace 1.5

func ReadTrace() (buf []byte)

ReadTrace возвращает следующий фрагмент двоичных данных трассировки, блокируя выполнение до появления данных. Если трассировка отключена и все накопленные за время её работы данные возвращены, ReadTrace возвращает nil. Вызывающий код должен скопировать возвращённые данные до следующего вызова ReadTrace. ReadTrace можно вызывать только из одной горутины одновременно.

func SetBlockProfileRate 1.1

func SetBlockProfileRate(rate int)

SetBlockProfileRate управляет долей событий блокировки горутин, регистрируемых в профиле блокировок. Профилировщик стремится отбирать в среднем одно событие блокировки на каждые rate наносекунд, проведённых в заблокированном состоянии.

Чтобы включить в профиль каждое событие блокировки, передайте rate = 1. Чтобы полностью отключить профилирование, передайте rate <= 0.

func SetCPUProfileRate

func SetCPUProfileRate(hz int)

SetCPUProfileRate задаёт частоту профилирования ЦП — hz выборок в секунду. Если hz <= 0, SetCPUProfileRate отключает профилирование. Если профилировщик включён, изменить частоту, не отключив его предварительно, нельзя.

Большинству пользователей следует использовать пакет runtime/pprof или флаг -test.cpuprofile пакета testing, а не вызывать SetCPUProfileRate напрямую.

func SetCgoTraceback 1.7

func SetCgoTraceback(version int, traceback, context, symbolizer unsafe.Pointer)

SetCgoTraceback задаёт три функции C для получения сведений о трассировке стека из кода C и преобразования этих сведений в символическую информацию. Они используются при выводе трассировок стека программы, использующей cgo.

Функции traceback и context могут вызываться из обработчика сигнала, поэтому они должны использовать только асинхронно-безопасные функции. Функция symbolizer может вызываться во время сбоя программы и поэтому должна осторожно обращаться с памятью. Ни одна из этих функций не может вызывать код Go.

Функция context вызывается с одним аргументом — указателем на структуру:

struct {
	Context uintptr
}

На языке C эта структура будет иметь вид:

struct {
	uintptr_t Context;
};

Если поле Context равно 0, функция context вызывается для записи текущего контекста трассировки стека. Она должна записать в поле Context сведения о текущей точке выполнения, необходимые для последующего формирования трассировки стека, вероятно, указатель стека и PC. В этом случае функция context вызывается из кода C.

Если поле Context не равно 0, это значение, возвращённое предыдущим вызовом функции context. Этот случай возникает, когда контекст больше не нужен, то есть когда код Go возвращается к вызывающему его коду C. Это позволяет функции context освободить связанные ресурсы.

Хотя функция context могла бы корректно записывать полную трассировку стека при каждом вызове, а функция traceback — просто копировать её, в типичной программе функция context будет вызываться много раз, и для этого контекста трассировка стека может так и не понадобиться. Запись полной трассировки стека при вызове функции context, вероятно, будет неэффективной.

Функция traceback вызывается с одним аргументом — указателем на структуру:

struct {
	Context    uintptr
	SigContext uintptr
	Buf        *uintptr
	Max        uintptr
}

На языке C эта структура будет иметь вид:

struct {
	uintptr_t  Context;
	uintptr_t  SigContext;
	uintptr_t* Buf;
	uintptr_t  Max;
};

Поле Context будет равно нулю, чтобы получить трассировку стека из текущей точки выполнения программы. В этом случае функция трассировки стека будет вызвана из кода C.

В противном случае Context будет значением, ранее возвращённым вызовом функции context. Функция трассировки стека должна получить трассировку стека из сохранённой точки выполнения программы. Функция трассировки стека может быть вызвана из потока выполнения, отличного от того, который записал контекст, но только если известно, что контекст действителен и не изменяется. Функция трассировки стека также может быть вызвана глубже в стеке вызовов в том же потоке, который записал контекст. Функция трассировки стека может вызываться несколько раз с одним и тем же значением Context; обычно уместно по возможности кэшировать результат при первом вызове для конкретного значения контекста.

Если функция трассировки стека вызывается из обработчика сигнала в системе Unix, SigContext будет аргументом контекста сигнала, переданным обработчику сигнала (указатель C ucontext_t*, приведённый к uintptr_t). Его можно использовать, чтобы начать трассировку с точки, в которой произошёл сигнал. Если функция трассировки стека вызывается не из обработчика сигнала, SigContext будет равен нулю.

Buf — место, в которое следует записать информацию о трассировке стека. Это должны быть значения PC, такие что Buf[0] — это PC вызывающей функции, Buf[1] — PC вызывающей функции для этой функции и так далее. Max — максимальное количество записей. Функция должна записать ноль, чтобы обозначить вершину стека или то, что вызывающая функция находится в другом стеке, предположительно в стеке Go.

В отличие от runtime.Callers, возвращаемые значения PC при передаче функции символизации должны указывать на файл и строку инструкции вызова. Дополнительное вычитание не требуется и неуместно.

На всех платформах функция трассировки стека вызывается, когда вызов из Go в C и затем обратно в Go запрашивает трассировку стека. На linux/amd64, linux/ppc64le, linux/arm64 и freebsd/amd64 функция трассировки стека также вызывается, когда поток, выполняющий вызов cgo, получает сигнал. Функция трассировки стека не должна делать предположений о том, когда её вызывают, поскольку будущие версии Go могут вызывать её дополнительно.

Функция символизации будет вызвана с одним аргументом — указателем на структуру:

struct {
	PC      uintptr // program counter to fetch information for
	File    *byte   // file name (NUL terminated)
	Lineno  uintptr // line number
	Func    *byte   // function name (NUL terminated)
	Entry   uintptr // function entry point
	More    uintptr // set non-zero if more info for this PC
	Data    uintptr // unused by runtime, available for function
}

В синтаксисе C эта структура будет выглядеть так:

struct {
	uintptr_t PC;
	char*     File;
	uintptr_t Lineno;
	char*     Func;
	uintptr_t Entry;
	uintptr_t More;
	uintptr_t Data;
};

Поле PC будет содержать значение, возвращённое вызовом функции трассировки стека.

При первом вызове функции для конкретной трассировки все поля, кроме PC, будут равны 0. Функция должна заполнить остальные поля, если это возможно, присвоив им 0/nil, если информация недоступна. Поле Data можно использовать для хранения полезной информации между вызовами. Поле More следует установить в ненулевое значение, если для этого PC имеется дополнительная информация, иначе — в ноль. Если More установлено в ненулевое значение, функция будет вызвана повторно с тем же PC и может вернуть другую информацию (это предназначено для использования со встроенными функциями). Если More равно нулю, функция будет вызвана со следующим значением PC в трассировке стека. Когда трассировка стека завершена, функция будет вызвана ещё раз со значением PC, равным нулю; это можно использовать для освобождения любой информации. После каждого вызова поля структуры останутся такими же, какими были при возврате из функции, за исключением поля PC, если поле More равно нулю. Функция не должна сохранять копию указателя на структуру между вызовами.

При вызове SetCgoTraceback аргумент version — это номер версии структур, которые функции ожидают получить. Сейчас он должен быть равен нулю.

Функция символизации может быть nil; в этом случае результаты функции трассировки стека будут отображаться в виде чисел. Если функция трассировки стека равна nil, функция символизации никогда не будет вызвана. Функция context может быть nil; в этом случае функция трассировки стека будет вызываться только с полем context, установленным в ноль. Если функция context равна nil, вызовы из Go в C и обратно в Go не будут отображать трассировку стека для участка стека вызовов, относящегося к C.

SetCgoTraceback следует вызывать только один раз, в идеале — из функции init.

func SetDefaultGOMAXPROCS 1.25

func SetDefaultGOMAXPROCS()

SetDefaultGOMAXPROCS обновляет настройку GOMAXPROCS до значения по умолчанию для среды выполнения, описанного в GOMAXPROCS, игнорируя переменную среды GOMAXPROCS.

SetDefaultGOMAXPROCS можно использовать, чтобы включить автоматическое обновление GOMAXPROCS по умолчанию, если оно было отключено переменной среды GOMAXPROCS или предыдущим вызовом GOMAXPROCS, либо чтобы принудительно выполнить немедленное обновление, если вызывающая сторона знает об изменении общего числа логических ЦП, маски привязки к ЦП или квоты cgroup.

func SetFinalizer

func SetFinalizer(obj any, finalizer any)

SetFinalizer устанавливает для obj указанную функцию финализатора. Когда сборщик мусора обнаруживает недостижимый блок с привязанным финализатором, он удаляет эту привязку и запускает finalizer(obj) в отдельной горутине. Это снова делает obj достижимым, но уже без привязанного финализатора. Если SetFinalizer больше не вызывается, при следующем обнаружении obj как недостижимого сборщик мусора освободит obj.

SetFinalizer(obj, nil) удаляет любой финализатор, привязанный к obj.

В новом коде Go следует рассмотреть возможность использования AddCleanup, который гораздо менее подвержен ошибкам, чем SetFinalizer.

Аргумент obj должен быть указателем на объект, выделенный вызовом new, взятием адреса составного литерала или взятием адреса локальной переменной. Аргумент finalizer должен быть функцией, принимающей один аргумент, которому можно присвоить тип obj; функция может иметь произвольные игнорируемые возвращаемые значения. Если хотя бы одно из этих условий не выполняется, SetFinalizer может аварийно завершить программу.

Финализаторы выполняются в порядке зависимостей: если A указывает на B, у обоих есть финализаторы и они недостижимы по другим причинам, выполняется только финализатор для A; после освобождения A может выполниться финализатор для B. Если циклическая структура содержит блок с финализатором, не гарантируется, что этот цикл будет собран сборщиком мусора и что финализатор будет запущен, поскольку невозможно установить порядок, который соблюдал бы зависимости.

Запуск финализатора планируется на произвольное время после того, как программа больше не может достичь объекта, на который указывает obj. Не гарантируется, что финализаторы выполнятся до завершения программы, поэтому обычно они полезны только для освобождения немеморных ресурсов, связанных с объектом, в долго работающей программе. Например, объект os.File может использовать финализатор для закрытия связанного дескриптора файла операционной системы, если программа отбрасывает os.File, не вызвав Close. Но полагаться на финализатор для сброса буфера ввода-вывода в памяти, например bufio.Writer, было бы ошибкой, поскольку при завершении программы буфер не будет сброшен.

Не гарантируется запуск финализатора, если размер *obj равен нулю байт, поскольку он может иметь тот же адрес в памяти, что и другие объекты нулевого размера. См. https://go.dev/ref/spec#Size_and_alignment_guarantees.

Не гарантируется запуск финализатора для объектов, выделенных в инициализаторах переменных уровня пакета. Такие объекты могут быть выделены компоновщиком, а не в куче.

Обратите внимание: поскольку финализаторы могут выполниться через произвольно долгое время после того, как на объект больше нет ссылок, среда выполнения вправе применять оптимизацию экономии памяти, объединяя объекты в один слот выделения памяти. Финализатор для недостижимого объекта в таком выделении может никогда не выполниться, если объект всегда находится в одном пакете с достижимым объектом. Обычно такое объединение происходит только для очень маленьких объектов (размером около 16 байт или меньше), не содержащих указателей.

Финализатор может выполниться сразу после того, как объект станет недостижимым. Чтобы правильно использовать финализаторы, программа должна гарантировать, что объект остаётся достижимым до тех пор, пока он не перестанет быть необходимым. Объекты, хранящиеся в глобальных переменных или обнаруживаемые при отслеживании указателей от глобальной переменной, являются достижимыми. Аргумент или получатель функции может стать недостижимым в последней точке, в которой функция обращается к нему. Чтобы сделать недостижимый объект достижимым, передайте его в вызов функции KeepAlive, чтобы обозначить последнюю точку функции, в которой объект должен оставаться достижимым.

Например, если p указывает на структуру, например os.File, содержащую дескриптор файла d, и у p есть финализатор, закрывающий этот дескриптор, а последнее использование p в функции — вызов syscall.Write(p.d, buf, size), то p может стать недостижимым сразу после входа программы в syscall.Write. В этот момент может выполниться финализатор, закрыв p.d и вызвав ошибку syscall.Write при записи в закрытый файловый дескриптор (или, что хуже, в совершенно другой файловый дескриптор, открытый другой горутиной). Чтобы избежать этой проблемы, вызовите KeepAlive(p) после вызова syscall.Write.

Все финализаторы программы последовательно выполняются одной горутиной. Если финализатор должен выполняться долго, ему следует запустить для этого новую горутину.

В терминологии модели памяти Go вызов SetFinalizer(x, f) «синхронизируется перед» вызовом финализатора f(x). Однако нет гарантии, что KeepAlive(x) или любое другое использование x «синхронизируется перед» f(x), поэтому в общем случае финализатору следует использовать мьютекс или другой механизм синхронизации, если ему нужно обращаться к изменяемому состоянию x. Например, рассмотрим финализатор, который проверяет изменяемое поле в x, периодически изменяемое в основной программе до того, как x станет недостижимым и будет вызван финализатор. Изменения в основной программе и проверка в финализаторе должны использовать соответствующую синхронизацию, например мьютексы или атомарные операции, чтобы избежать гонок чтения и записи.

func SetMutexProfileFraction 1.8

func SetMutexProfileFraction(rate int) int

SetMutexProfileFraction управляет долей событий конкуренции за мьютексы, которые попадают в профиль мьютексов. В среднем регистрируется 1/rate событий. Возвращается предыдущее значение rate.

Чтобы полностью отключить профилирование, передайте rate 0. Чтобы только прочитать текущее значение rate, передайте rate < 0. (При n>1 детали выборки могут измениться.)

func Stack

func Stack(buf []byte, all bool) int

Stack записывает трассировку стека вызывающей горутины в buf и возвращает количество байтов, записанных в buf. Если all равно true, Stack записывает в buf трассировки стека всех остальных горутин после трассировки текущей горутины.

func StartTrace 1.5

func StartTrace() error

StartTrace включает трассировку для текущего процесса. Во время трассировки данные буферизуются и доступны через ReadTrace. StartTrace возвращает ошибку, если трассировка уже включена. Большинству клиентов следует использовать пакет runtime/trace или флаг -test.trace пакета testing, а не вызывать StartTrace напрямую.

func StopTrace 1.5

func StopTrace()

StopTrace останавливает трассировку, если она была включена ранее. StopTrace возвращает управление только после завершения всех операций чтения данных трассировки.

func ThreadCreateProfile

func ThreadCreateProfile(p []StackRecord) (n int, ok bool)

ThreadCreateProfile возвращает n — количество записей в профиле создания потоков. Если len(p) >= n, ThreadCreateProfile копирует профиль в p и возвращает n, true. Если len(p) < n, ThreadCreateProfile не изменяет p и возвращает n, false.

Большинству клиентов следует использовать пакет runtime/pprof, а не вызывать ThreadCreateProfile напрямую.

func UnlockOSThread

func UnlockOSThread()

UnlockOSThread отменяет предыдущий вызов LockOSThread. Если в результате количество активных вызовов LockOSThread в вызывающей горутине становится равным нулю, вызывающая горутина отвязывается от закреплённого за ней потока операционной системы. Если активных вызовов LockOSThread нет, функция ничего не делает.

Перед вызовом UnlockOSThread вызывающая сторона должна убедиться, что поток ОС подходит для выполнения других горутин. Если вызывающая сторона внесла постоянные изменения в состояние потока, которые могут повлиять на другие горутины, ей не следует вызывать эту функцию; вместо этого горутина должна оставаться привязанной к потоку ОС до завершения горутины (и, следовательно, потока).

func Version

func Version() string

Version возвращает строку версии дерева исходного кода Go. Это либо хеш коммита и дата сборки, либо, если возможно, тег релиза, например "go1.3".

type BlockProfileRecord 1.1

BlockProfileRecord описывает события блокировки, возникшие в определённой последовательности вызовов (трассировке стека).

type BlockProfileRecord struct {
    Count  int64
    Cycles int64
    StackRecord
}

type Cleanup 1.24

Cleanup — это дескриптор вызова очистки для конкретного объекта.

type Cleanup struct {
    // contains filtered or unexported fields
}

func AddCleanup 1.24

func AddCleanup[T, S any](ptr *T, cleanup func(S), arg S) Cleanup

AddCleanup привязывает к ptr функцию очистки. Через некоторое время после того, как ptr станет недостижимым, среда выполнения вызовет cleanup(arg) в отдельной горутине.

Типичный пример использования: ptr — это объект-обёртка для базового ресурса (например, объект File, оборачивающий файловый дескриптор ОС), arg — базовый ресурс (например, файловый дескриптор ОС), а функция очистки освобождает базовый ресурс (например, вызывает системный вызов close).

Для ptr существует немного ограничений. В частности, несколько функций очистки можно привязать к одному и тому же указателю или к разным указателям внутри одного выделенного блока памяти.

Если ptr достижим из cleanup или arg, ptr никогда не будет собран сборщиком мусора, а функция очистки никогда не выполнится. Для защиты от простых случаев этого рода AddCleanup вызывает панику, если arg равен ptr.

Порядок выполнения функций очистки не определён. В частности, если несколько объектов указывают друг на друга и все становятся недостижимыми одновременно, их функции очистки становятся готовыми к выполнению и могут выполняться в любом порядке. Это справедливо, даже если объекты образуют цикл.

Функции очистки выполняются параллельно с любыми созданными пользователем горутинами. Они также могут выполняться параллельно друг с другом (в отличие от финализаторов). Если функция очистки должна выполняться долго, ей следует создать новую горутину, чтобы не блокировать выполнение других функций очистки.

Если для ptr заданы и функция очистки, и финализатор, функция очистки выполнится только после того, как объект будет финализирован и станет недостижимым без привязанного финализатора.

Выполнение вызова cleanup(arg) не всегда гарантируется; в частности, не гарантируется его выполнение до завершения программы.

Выполнение функций очистки не гарантируется, если размер T равен нулю байт, поскольку объект может иметь тот же адрес в памяти, что и другие объекты нулевого размера. См. https://go.dev/ref/spec#Size_and_alignment_guarantees.

Не гарантируется выполнение функции очистки для объектов, выделенных в инициализаторах переменных уровня пакета. Такие объекты могут быть выделены компоновщиком, а не в куче.

Обратите внимание: поскольку функции очистки могут выполниться через произвольно долгое время после того, как на объект больше нет ссылок, среда выполнения вправе применять оптимизацию экономии памяти, объединяя объекты в один слот выделения памяти. Функция очистки для недостижимого объекта в таком выделении может никогда не выполниться, если объект всегда находится в одном пакете с достижимым объектом. Обычно такое объединение происходит только для очень маленьких объектов (размером около 16 байт или меньше), не содержащих указателей.

Функция очистки может выполниться сразу после того, как объект станет недостижимым. Чтобы правильно использовать функции очистки, программа должна гарантировать, что объект остаётся достижимым до тех пор, пока запуск его функции очистки не станет безопасным. Объекты, хранящиеся в глобальных переменных или обнаруживаемые при отслеживании указателей от глобальной переменной, являются достижимыми. Аргумент или получатель функции может стать недостижимым в последней точке, в которой функция обращается к нему. Чтобы гарантировать, что функция очистки не будет вызвана преждевременно, передайте объект функции KeepAlive после последней точки, в которой объект должен оставаться достижимым.

Пример

Код:

tempFile, err := os.CreateTemp(os.TempDir(), "file.*")
if err != nil {
    fmt.Println("failed to create temp file:", err)
    return
}

ch := make(chan struct{})

// Attach a cleanup function to the file object.
runtime.AddCleanup(&tempFile, func(fileName string) {
    if err := os.Remove(fileName); err == nil {
        fmt.Println("temp file has been removed")
    }
    ch <- struct{}{}
}, tempFile.Name())

if err := tempFile.Close(); err != nil {
    fmt.Println("failed to close temp file:", err)
    return
}

// Run the garbage collector to reclaim unreachable objects
// and enqueue their cleanup functions.
runtime.GC()

// Wait until cleanup function is done.
<-ch

Вывод:

temp file has been removed

func (Cleanup) Stop 1.24

func (c Cleanup) Stop()

Stop отменяет вызов функции очистки. Stop не повлияет на функцию очистки, если она уже поставлена в очередь на выполнение (поскольку ptr стал недостижимым). Чтобы гарантировать удаление функции очистки вызовом Stop, вызывающая сторона должна обеспечить достижимость указателя, переданного AddCleanup, на протяжении вызова Stop.

type Error

Error обозначает ошибку среды выполнения, используемую при панике.

Среда выполнения Go вызывает панику в различных случаях, описанных в спецификации языка Go, например при выходе за границы среза или массива, закрытии nil-канала, ошибках утверждения типа и т. д.

В таких случаях среда выполнения Go вызывает панику с ошибкой, реализующей Error. Это может быть полезно при восстановлении после паники, чтобы отличить пользовательские паники приложения от фундаментальных паник среды выполнения.

Пакетам вне стандартной библиотеки Go не следует реализовывать Error.

type Error interface {
    error

    // RuntimeError is a no-op function but
    // serves to distinguish types that are runtime
    // errors from ordinary errors: a type is a
    // runtime error if it has a RuntimeError method.
    RuntimeError()
}

type Frame 1.7

Frame содержит информацию, возвращаемую функцией Frames для каждого кадра вызова.

type Frame struct {
    // PC is the program counter for the location in this frame.
    // For a frame that calls another frame, this will be the
    // program counter of a call instruction. Because of inlining,
    // multiple frames may have the same PC value, but different
    // symbolic information.
    PC uintptr

    // Func is the Func value of this call frame. This may be nil
    // for non-Go code or fully inlined functions.
    Func *Func

    // Function is the package path-qualified function name of
    // this call frame. If non-empty, this string uniquely
    // identifies a single function in the program.
    // This may be the empty string if not known.
    // If Func is not nil then Function == Func.Name().
    Function string

    // File and Line are the file name and line number of the
    // location in this frame. For non-leaf frames, this will be
    // the location of a call. These may be the empty string and
    // zero, respectively, if not known. The file name uses
    // forward slashes, even on Windows.
    File string
    Line int

    // Entry point program counter for the function; may be zero
    // if not known. If Func is not nil then Entry ==
    // Func.Entry().
    Entry uintptr
    // contains filtered or unexported fields
}

type Frames 1.7

Frames можно использовать для получения информации о функции, файле и строке для среза значений PC, возвращённых функцией Callers.

type Frames struct {
    // contains filtered or unexported fields
}

Пример

Код:

c := func() {
    // Ask runtime.Callers for up to 10 PCs, including runtime.Callers itself.
    pc := make([]uintptr, 10)
    n := runtime.Callers(0, pc)
    if n == 0 {
        // No PCs available. This can happen if the first argument to
        // runtime.Callers is large.
        //
        // Return now to avoid processing the zero Frame that would
        // otherwise be returned by frames.Next below.
        return
    }

    pc = pc[:n] // pass only valid pcs to runtime.CallersFrames
    frames := runtime.CallersFrames(pc)

    // Loop to get frames.
    // A fixed number of PCs can expand to an indefinite number of Frames.
    for {
        frame, more := frames.Next()

        // Canonicalize function name and skip callers of this function
        // for predictable example output.
        // You probably don't need this in your own code.
        function := strings.ReplaceAll(frame.Function, "main.main", "runtime_test.ExampleFrames")
        fmt.Printf("- more:%v | %s\n", more, function)
        if function == "runtime_test.ExampleFrames" {
            break
        }

        // Check whether there are more frames to process after this one.
        if !more {
            break
        }
    }
}

b := func() { c() }
a := func() { b() }

a()

Вывод:

- more:true | runtime.Callers
- more:true | runtime_test.ExampleFrames.func1
- more:true | runtime_test.ExampleFrames.func2
- more:true | runtime_test.ExampleFrames.func3
- more:true | runtime_test.ExampleFrames

func CallersFrames 1.7

func CallersFrames(callers []uintptr) *Frames

CallersFrames принимает срез значений PC, возвращённых функцией Callers, и подготавливает данные для возврата информации о функции, файле и строке. Не изменяйте срез, пока не закончите работу с объектом Frames.

func (*Frames) Next 1.7

func (ci *Frames) Next() (frame Frame, more bool)

Next возвращает Frame, представляющий следующий кадр вызова в срезе значений PC. Если уже возвращены все кадры вызовов, Next возвращает нулевой Frame.

Результат more указывает, вернёт ли следующий вызов Next допустимый Frame. Он не обязательно указывает, вернул ли текущий вызов кадр.

Идиоматический пример использования см. в примере Frames.

type Func

Func представляет функцию Go в выполняемом двоичном файле.

type Func struct {
    // contains filtered or unexported fields
}

func FuncForPC

func FuncForPC(pc uintptr) *Func

FuncForPC возвращает *Func, описывающий функцию, содержащую указанный адрес счётчика команд, или nil.

Если pc представляет несколько функций из-за встраивания, функция возвращает *Func, описывающий самую внутреннюю функцию, но с адресом входа самой внешней функции.

func (*Func) Entry

func (f *Func) Entry() uintptr

Entry возвращает адрес входа функции.

func (*Func) FileLine

func (f *Func) FileLine(pc uintptr) (file string, line int)

FileLine возвращает имя файла и номер строки исходного кода, соответствующие счётчику команд pc. Результат будет неточным, если pc не является счётчиком команд внутри f.

func (*Func) Name

func (f *Func) Name() string

Name возвращает имя функции.

type MemProfileRecord

MemProfileRecord описывает активные объекты, выделенные определённой последовательностью вызовов (трассировкой стека).

type MemProfileRecord struct {
    AllocBytes, FreeBytes     int64       // number of bytes allocated, freed
    AllocObjects, FreeObjects int64       // number of objects allocated, freed
    Stack0                    [32]uintptr // stack trace for this record; ends at first 0 entry
}

func (*MemProfileRecord) InUseBytes

func (r *MemProfileRecord) InUseBytes() int64

InUseBytes возвращает количество используемых байтов (AllocBytes - FreeBytes).

func (*MemProfileRecord) InUseObjects

func (r *MemProfileRecord) InUseObjects() int64

InUseObjects возвращает количество используемых объектов (AllocObjects - FreeObjects).

func (*MemProfileRecord) Stack

func (r *MemProfileRecord) Stack() []uintptr

Stack возвращает трассировку стека, связанную с записью, — префикс r.Stack0.

type MemStats

MemStats содержит статистику распределителя памяти.

type MemStats struct {

    // Alloc is bytes of allocated heap objects.
    //
    // This is the same as HeapAlloc (see below).
    Alloc uint64

    // TotalAlloc is cumulative bytes allocated for heap objects.
    //
    // TotalAlloc increases as heap objects are allocated, but
    // unlike Alloc and HeapAlloc, it does not decrease when
    // objects are freed.
    TotalAlloc uint64

    // Sys is the total bytes of memory obtained from the OS.
    //
    // Sys is the sum of the XSys fields below. Sys measures the
    // virtual address space reserved by the Go runtime for the
    // heap, stacks, and other internal data structures. It's
    // likely that not all of the virtual address space is backed
    // by physical memory at any given moment, though in general
    // it all was at some point.
    Sys uint64

    // Lookups is the number of pointer lookups performed by the
    // runtime.
    //
    // This is primarily useful for debugging runtime internals.
    Lookups uint64

    // Mallocs is the cumulative count of heap objects allocated.
    // The number of live objects is Mallocs - Frees.
    Mallocs uint64

    // Frees is the cumulative count of heap objects freed.
    Frees uint64

    // HeapAlloc is bytes of allocated heap objects.
    //
    // "Allocated" heap objects include all reachable objects, as
    // well as unreachable objects that the garbage collector has
    // not yet freed. Specifically, HeapAlloc increases as heap
    // objects are allocated and decreases as the heap is swept
    // and unreachable objects are freed. Sweeping occurs
    // incrementally between GC cycles, so these two processes
    // occur simultaneously, and as a result HeapAlloc tends to
    // change smoothly (in contrast with the sawtooth that is
    // typical of stop-the-world garbage collectors).
    HeapAlloc uint64

    // HeapSys is bytes of heap memory obtained from the OS.
    //
    // HeapSys measures the amount of virtual address space
    // reserved for the heap. This includes virtual address space
    // that has been reserved but not yet used, which consumes no
    // physical memory, but tends to be small, as well as virtual
    // address space for which the physical memory has been
    // returned to the OS after it became unused (see HeapReleased
    // for a measure of the latter).
    //
    // HeapSys estimates the largest size the heap has had.
    HeapSys uint64

    // HeapIdle is bytes in idle (unused) spans.
    //
    // Idle spans have no objects in them. These spans could be
    // (and may already have been) returned to the OS, or they can
    // be reused for heap allocations, or they can be reused as
    // stack memory.
    //
    // HeapIdle minus HeapReleased estimates the amount of memory
    // that could be returned to the OS, but is being retained by
    // the runtime so it can grow the heap without requesting more
    // memory from the OS. If this difference is significantly
    // larger than the heap size, it indicates there was a recent
    // transient spike in live heap size.
    HeapIdle uint64

    // HeapInuse is bytes in in-use spans.
    //
    // In-use spans have at least one object in them. These spans
    // can only be used for other objects of roughly the same
    // size.
    //
    // HeapInuse minus HeapAlloc estimates the amount of memory
    // that has been dedicated to particular size classes, but is
    // not currently being used. This is an upper bound on
    // fragmentation, but in general this memory can be reused
    // efficiently.
    HeapInuse uint64

    // HeapReleased is bytes of physical memory returned to the OS.
    //
    // This counts heap memory from idle spans that was returned
    // to the OS and has not yet been reacquired for the heap.
    HeapReleased uint64

    // HeapObjects is the number of allocated heap objects.
    //
    // Like HeapAlloc, this increases as objects are allocated and
    // decreases as the heap is swept and unreachable objects are
    // freed.
    HeapObjects uint64

    // StackInuse is bytes in stack spans.
    //
    // In-use stack spans have at least one stack in them. These
    // spans can only be used for other stacks of the same size.
    //
    // There is no StackIdle because unused stack spans are
    // returned to the heap (and hence counted toward HeapIdle).
    StackInuse uint64

    // StackSys is bytes of stack memory obtained from the OS.
    //
    // StackSys is StackInuse, plus any memory obtained directly
    // from the OS for OS thread stacks.
    //
    // In non-cgo programs this metric is currently equal to StackInuse
    // (but this should not be relied upon, and the value may change in
    // the future).
    //
    // In cgo programs this metric includes OS thread stacks allocated
    // directly from the OS. Currently, this only accounts for one stack in
    // c-shared and c-archive build modes and other sources of stacks from
    // the OS (notably, any allocated by C code) are not currently measured.
    // Note this too may change in the future.
    StackSys uint64

    // MSpanInuse is bytes of allocated mspan structures.
    MSpanInuse uint64

    // MSpanSys is bytes of memory obtained from the OS for mspan
    // structures.
    MSpanSys uint64

    // MCacheInuse is bytes of allocated mcache structures.
    MCacheInuse uint64

    // MCacheSys is bytes of memory obtained from the OS for
    // mcache structures.
    MCacheSys uint64

    // BuckHashSys is bytes of memory in profiling bucket hash tables.
    BuckHashSys uint64

    // GCSys is bytes of memory in garbage collection metadata.
    GCSys uint64 // Go 1.2

    // OtherSys is bytes of memory in miscellaneous off-heap
    // runtime allocations.
    OtherSys uint64 // Go 1.2

    // NextGC is the target heap size of the next GC cycle.
    //
    // The garbage collector's goal is to keep HeapAlloc ≤ NextGC.
    // At the end of each GC cycle, the target for the next cycle
    // is computed based on the amount of reachable data and the
    // value of GOGC.
    NextGC uint64

    // LastGC is the time the last garbage collection finished, as
    // nanoseconds since 1970 (the UNIX epoch).
    LastGC uint64

    // PauseTotalNs is the cumulative nanoseconds in GC
    // stop-the-world pauses since the program started.
    //
    // During a stop-the-world pause, all goroutines are paused
    // and only the garbage collector can run.
    PauseTotalNs uint64

    // PauseNs is a circular buffer of recent GC stop-the-world
    // pause times in nanoseconds.
    //
    // The most recent pause is at PauseNs[(NumGC+255)%256]. In
    // general, PauseNs[N%256] records the time paused in the most
    // recent N%256th GC cycle. There may be multiple pauses per
    // GC cycle; this is the sum of all pauses during a cycle.
    PauseNs [256]uint64

    // PauseEnd is a circular buffer of recent GC pause end times,
    // as nanoseconds since 1970 (the UNIX epoch).
    //
    // This buffer is filled the same way as PauseNs. There may be
    // multiple pauses per GC cycle; this records the end of the
    // last pause in a cycle.
    PauseEnd [256]uint64 // Go 1.4

    // NumGC is the number of completed GC cycles.
    NumGC uint32

    // NumForcedGC is the number of GC cycles that were forced by
    // the application calling the GC function.
    NumForcedGC uint32 // Go 1.8

    // GCCPUFraction is the fraction of this program's available
    // CPU time used by the GC since the program started.
    //
    // GCCPUFraction is expressed as a number between 0 and 1,
    // where 0 means GC has consumed none of this program's CPU. A
    // program's available CPU time is defined as the integral of
    // GOMAXPROCS since the program started. That is, if
    // GOMAXPROCS is 2 and a program has been running for 10
    // seconds, its "available CPU" is 20 seconds. GCCPUFraction
    // does not include CPU time used for write barrier activity.
    //
    // This is the same as the fraction of CPU reported by
    // GODEBUG=gctrace=1.
    GCCPUFraction float64 // Go 1.5

    // EnableGC indicates that GC is enabled. It is always true,
    // even if GOGC=off.
    EnableGC bool

    // DebugGC is currently unused.
    DebugGC bool

    // BySize reports per-size class allocation statistics.
    //
    // BySize[N] gives statistics for allocations of size S where
    // BySize[N-1].Size < S ≤ BySize[N].Size.
    //
    // This does not report allocations larger than BySize[60].Size.
    BySize [61]struct {
        // Size is the maximum byte size of an object in this
        // size class.
        Size uint32

        // Mallocs is the cumulative count of heap objects
        // allocated in this size class. The cumulative bytes
        // of allocation is Size*Mallocs. The number of live
        // objects in this size class is Mallocs - Frees.
        Mallocs uint64

        // Frees is the cumulative count of heap objects freed
        // in this size class.
        Frees uint64
    }
}

type PanicNilError 1.21

PanicNilError возникает, когда код вызывает panic(nil).

До Go 1.21 в программах, вызывавших panic(nil), функция recover возвращала nil. Начиная с Go 1.21 в программах, вызывающих panic(nil), функция recover возвращает *PanicNilError. Программы могут вернуться к прежнему поведению, установив GODEBUG=panicnil=1.

type PanicNilError struct {
    // contains filtered or unexported fields
}

func (*PanicNilError) Error 1.21

func (*PanicNilError) Error() string

func (*PanicNilError) RuntimeError 1.21

func (*PanicNilError) RuntimeError()

type Pinner 1.21

Pinner — это набор объектов Go, каждый из которых закреплён в фиксированном месте памяти. Метод Pinner.Pin закрепляет один объект, а Pinner.Unpin снимает закрепление со всех закреплённых объектов.

Pinner предназначен для решения двух задач. Во-первых, он позволяет коду C безопасно использовать указатели Go, которые не были явно переданы коду C через вызов cgo. Например, он обеспечивает безопасное взаимодействие с указателем, хранящимся внутри структуры, указатель на которую передан функции C. Во-вторых, он позволяет памяти C безопасно хранить этот указатель Go и после возврата из вызова cgo при условии, что объект остаётся закреплённым.

Pinner обеспечивает автоматическое снятие закрепления со своих объектов через некоторое время после того, как сам Pinner станет недостижимым, чтобы объекты, на которые он ссылается, не утекали. Однако это означает, что сам Pinner должен оставаться достижимым на протяжении вызова cgo или всё время, пока C хранит ссылку на закреплённые указатели Go.

Повторное использование Pinner безопасно и даже рекомендуется, чтобы избежать затрат на инициализацию новых Pinner при первом использовании.

Нулевое значение Pinner готово к использованию.

type Pinner struct {
    // contains filtered or unexported fields
}

func (*Pinner) Pin 1.21

func (p *Pinner) Pin(pointer any)

Pin закрепляет объект Go, не позволяя сборщику мусора переместить или освободить его до вызова метода Pinner.Unpin.

Указатель на закреплённый объект можно напрямую сохранить в памяти C или включить в память Go, передаваемую функциям C. Если сам закреплённый объект содержит указатели на объекты Go, эти объекты необходимо закрепить отдельно, если к ним будет обращаться код C.

Аргумент должен быть указателем любого типа или unsafe.Pointer.

Безопасно вызывать Pin для указателей не на объекты Go — в этом случае Pin ничего не сделает.

func (*Pinner) Unpin 1.21

func (p *Pinner) Unpin()

Unpin снимает закрепление со всех закреплённых объектов Pinner. После вызова Unpin безопасно и рекомендуется повторно использовать Pinner.

type StackRecord

StackRecord описывает один стек выполнения.

type StackRecord struct {
    Stack0 [32]uintptr // stack trace for this record; ends at first 0 entry
}

func (*StackRecord) Stack

func (r *StackRecord) Stack() []uintptr

Stack возвращает трассировку стека, связанную с записью, — префикс r.Stack0.

type TypeAssertionError

TypeAssertionError описывает неудачное утверждение типа.

type TypeAssertionError struct {
    // contains filtered or unexported fields
}

func (*TypeAssertionError) Error

func (e *TypeAssertionError) Error() string

func (*TypeAssertionError) RuntimeError

func (*TypeAssertionError) RuntimeError()

Подкаталоги