Пакет 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 означает 210 байт, MiB означает 220 байт и так далее. Значение по умолчанию — 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. 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. pagetrace: setting pagetrace=/path/to/file will write out a trace of page events that can be viewed, analyzed, and visualized using the x/debug/cmd/pagetrace tool. Build your program with GOEXPERIMENT=pagetrace to enable this functionality. Do not enable this functionality if your program is a setuid binary as it introduces a security risk in that scenario. Currently not supported on Windows, plan9 or js/wasm. Setting this option for some applications can produce large traces, so use with care. panicnil: setting panicnil=1 disables the runtime error when calling panic with nil interface value or an untyped nil. runtimecontentionstacks: setting runtimecontentionstacks=1 enables inclusion of call stacks related to contention on runtime-internal locks in the "mutex" profile, subject to the MutexProfileFraction setting. When runtimecontentionstacks=0, contention on runtime-internal locks will report as "runtime._LostContendedRuntimeLock". When runtimecontentionstacks=1, the call stacks will correspond to the unlock call that released the lock. But instead of the value corresponding to the amount of contention that call stack caused, it corresponds to the amount of time the caller of unlock had to wait in its original call to lock. A future release is expected to align those and remove this setting. 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 to use the runtime's default stack unwinder instead of frame pointer unwinding. This increases tracer 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 или запускается с правами setuid/setgid, чтобы предотвратить опасные действия. В Linux это определяется проверкой флага AT_SECURE в дополнительном векторе, в BSD и Solaris/Illumos это определяется проверкой системного вызова issetugid, а в AIX — проверкой совпадения идентификаторов пользователя/группы с эффективными идентификаторами пользователя/группы.
Когда система выполнения определяет, что исполняемый файл имеет права setuid/setgid, она выполняет три основных действия:
- Проверяются стандартные дескрипторы файлов ввода/вывода (0, 1, 2). Если любой из них закрыт, они открываются, указывая на /dev/null.
- Значение переменной окружения GOTRACEBACK устанавливается в 'none'.
- При получении сигнала, завершающего программу, или при обнаружении невосстановимой паники, которая в противном случае переопределяла бы значение GOTRACEBACK, информация о стеке горутины, регистрах и другой памяти опускается.
Индекс
Примеры
Файлы пакета
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 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 env_posix.go error.go extern.go fastlog2.go fastlog2table.go fds_unix.go float.go hash64.go heapdump.go histogram.go iface.go lfstack.go linkname.go linkname_swiss.go linkname_unix.go lock_futex.go lock_spinbit.go lockrank.go lockrank_off.go malloc.go map_fast32_swiss.go map_fast64_swiss.go map_faststr_swiss.go map_swiss.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 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_linux_generic.go os_linux_noauxv.go os_linux_x86.go os_nonopenbsd.go os_unix.go panic.go pinner.go plugin.go preempt.go preempt_nonwindows.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 rwmutex.go security_linux.go security_unix.go select.go sema.go signal_amd64.go signal_linux_amd64.go signal_unix.go sigqueue.go sigqueue_note.go sigtab_linux_generic.go sizeclasses.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 traceexp.go tracemap.go traceregion.go traceruntime.go tracestack.go tracestatus.go tracestring.go tracetime.go tracetype.go type.go typekind.go unsafe.go utf8.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
Функция 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 напрямую.
Функция Breakpoint
func Breakpoint()
Breakpoint выполняет перехват точки останова.
Функция CPUProfile
func CPUProfile() []byte
CPUProfile вызывает панику. Раньше он предоставлял прямой доступ к фрагментам профиля в формате pprof, сгенерированному временем выполнения. Детали генерации этого формата изменились, поэтому эта функциональность была удалена.
Устаревший: используйте пакет runtime/pprof, или обработчики в пакете net/http/pprof, или флаг -test.cpuprofile пакета testing вместо него.
Функция Caller
func Caller(skip int) (pc uintptr, file string, line int, ok bool)
Caller сообщает информацию о файле и строке номера вызовов функций в стеке потока вызывающей горутины. Аргумент skip — количество стековых кадров, которое нужно подняться, где 0 идентифицирует вызывающую функцию Caller. (По историческим причинам значение skip отличается между Caller и Callers.) Возвращаемые значения сообщают о программе-счетчике, имени файла (используя прямые косые черты в качестве разделителя пути, даже в Windows) и номере строки в файле соответствующего вызова. Логическое значение ok равно false, если не удалось получить информацию.
Функция Callers
func Callers(skip int, pc []uintptr) int
Callers заполняет срез pc возвращаемыми программами-счетчиками вызовов функций в стеке вызывающей горутины. Аргумент skip — количество стековых кадров, которые нужно пропустить, прежде чем записывать в pc, где 0 идентифицирует кадр для Callers, а 1 — вызывающую функцию Callers. Возвращает количество записей, добавленных в pc.
Чтобы перевести эти PC в символьную информацию, такую как имена функций и номера строк, используйте CallersFrames. CallersFrames учитывает вложенные функции и корректирует возвращаемые значения счетчиков программы в счетчики вызова программы. Не рекомендуется напрямую итерировать возвращаемый срез PC, а также использовать FuncForPC для любого из возвращенных PC, так как это не может учесть встраивание или корректировку счетчиков возвращаемой программы.
Функция GC
func GC()
GC запускает сборку мусора и блокирует вызывающую функцию, пока сборка мусора не завершится. Может также заблокировать всю программу.
Функция GOMAXPROCS
func GOMAXPROCS(n int) int
GOMAXPROCS устанавливает максимальное количество ЦП, которые могут выполняться одновременно, и возвращает предыдущее значение. По умолчанию используется значение runtime.NumCPU. Если n < 1, текущее значение не изменяется. Этот вызов будет удален, когда планировщик улучшится.
Функция GOROOT
func GOROOT() string
GOROOT возвращает корень дерева Go. Использует переменную среды GOROOT, если она установлена при запуске процесса, или же корень, используемый во время сборки Go.
Устаревший: корень, используемый во время сборки Go, не будет иметь значения, если двоичный файл скопирован на другую машину. Используйте системный путь для поиска двоичного файла «go» и используйте «go env GOROOT» для поиска GOROOT.
Функция Goexit
func Goexit()
Goexit завершает горутину, которая ее вызывает. Другие горутины не затронуты. Goexit выполняет все отложенные вызовы перед завершением горутины. Поскольку Goexit не является паникой, все вызовы recover в этих отложенных функциях вернут nil.
Вызов Goexit из основной горутины завершает эту горутину без возвращения func main. Так как func main не возвратился, выполнение программы продолжается в других горутинах. Если все остальные горутины завершаются, программа завершается аварийно.
Возникает аварийное завершение, если вызывается из потока, не созданного временем выполнения Go.
Функция 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 напрямую.
Функция Gosched
func Gosched()
Gosched уступает процессор, позволяя другим горутинам выполняться. Она не приостанавливает текущую горутину, поэтому выполнение автоматически возобновляется.
Функция 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 по-прежнему применяются.
Функция LockOSThread
func LockOSThread()
LockOSThread привязывает вызывающую горутину к текущей операционной системе поток. Вызывающая горутина всегда будет выполняться в этом потоке, и никакая другая горутина не будет выполняться в нём, пока вызывающая горутина не выполнит столько вызовов UnlockOSThread, сколько вызовов LockOSThread. Если вызывающая горутина завершается без разблокирования потока, поток будет завершён.
Все функции инициализации выполняются в потоке запуска. Вызов LockOSThread из функции инициализации заставит основную функцию быть вызвана в этом потоке.
Горутина должна вызвать 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.
Возвращаемый профиль может быть не старше двух циклов сборки мусора. Это для того, чтобы избежать смещения профиля в сторону выделений; поскольку выделения происходят в реальном времени, но освобождения откладываются до тех пор, пока сборщик мусора не выполнит очистку, профиль учитывает только выделения, которые успели быть освобождены сборщиком мусора.
Большинство клиентов должны использовать пакет runtime/pprof или флаг -test.memprofile пакета тестирования вместо непосредственного вызова 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() []byte
ReadTrace возвращает следующий фрагмент бинарных данных трассировки, блокируя до тех пор, пока данные не станут доступны. Если трассировка выключена и все накопленные данные, пока она была включена, были возвращены, ReadTrace возвращает nil. Вызывающий код должен скопировать возвращённые данные перед повторным вызовом ReadTrace. ReadTrace должен вызываться из одной горутины за раз.
func SetBlockProfileRate 1.1
func SetBlockProfileRate(rate int)
SetBlockProfileRate контролирует долю событий блокирования горутин, которые отображаются в профиле блокирования. Профилировщик стремится к выборке в среднем одного события блокирования на каждый заданный интервал времени, потраченный на блокировку.
Чтобы включить каждое событие блокирования в профиль, установите rate = 1. Чтобы полностью отключить профилирование, установите rate <= 0.
func SetCPUProfileRate
func SetCPUProfileRate(hz int)
SetCPUProfileRate устанавливает скорость профилирования ЦП до hz выборок в секунду. Если hz <= 0, SetCPUProfileRate отключает профилирование. Если профилировщик включен, скорость не может быть изменена без предварительного отключения.
Большинство клиентов должны использовать пакет runtime/pprof или флаг testing пакета -test.cpuprofile вместо непосредственного вызова SetCPUProfileRate.
func SetCgoTraceback 1.7
func SetCgoTraceback(version int, traceback, context, symbolizer unsafe.Pointer)
SetCgoTraceback регистрирует три C-функции для сбора информации об отслеживании стека из C-кода и преобразования этой информации об отслеживании стека в символьные сведения. Они используются при выводе трасс стека для программы, использующей cgo.
Функции отслеживания и контекста могут вызываться из обработчика сигналов и, следовательно, должны использовать только функции, безопасные для асинхронных сигналов. Функция символизации может вызываться во время аварийного завершения программы, поэтому она должна быть осторожна при использовании памяти. Ни одна из функций не может вызывать обратные вызовы в Go.
Функция контекста будет вызываться с одним аргументом, указателем на структуру:
struct {
Context uintptr
}
В синтаксисе C эта структура будет
struct {
uintptr_t Context;
};
Если поле Context равно 0, функция контекста вызывается для записи текущего контекста отслеживания стека. Она должна записать в поле Context любую необходимую информацию о текущей точке выполнения, чтобы впоследствии сгенерировать трассу стека, вероятно, указатель стека и PC. В этом случае функция контекста будет вызываться из C-кода.
Если поле Context не равно 0, то это значение, возвращённое предыдущим вызовом функции контекста. Этот случай возникает, когда контекст больше не нужен; то есть, когда код Go возвращается к своему вызывающему C-коду. Это позволяет функции контекста освободить любые связанные ресурсы.
Хотя было бы правильно, чтобы функция контекста записывала полную трассу стека всякий раз, когда она вызывается, и просто копировала её во функцию отслеживания, в типичной программе функция контекста будет вызываться много раз, не записывая при этом трассу стека для этого контекста. Запись полной трассы стека в вызове функции контекста, вероятно, будет неэффективной.
Функция отслеживания будет вызываться с одним аргументом, указателем на структуру:
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; обычно целесообразно кэшировать результат, если это возможно, в первый раз, когда это вызывается для определённого значения контекста.
Если функция отслеживания вызывается из обработчика сигналов на системе 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, функция символизации никогда не будет вызвана. Функция контекста может быть nil, в этом случае функция отслеживания будет вызываться только с полем контекста, установленным в ноль. Если функция контекста равна nil, вызовы из Go в C, а затем обратно в Go не будут отображать трассу стека для C-части вызова стека.
SetCgoTraceback следует вызывать только один раз, желательно из функции инициализации.
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/скорость событий отображаются.
Возвращается предыдущая скорость.
Чтобы полностью отключить профилирование, передайте скорость 0. Чтобы просто прочитать текущую скорость, передайте скорость < 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 после последней точки, где объект должен оставаться доступным.
func (Cleanup) Stop 1.24
func (c Cleanup) Stop()
Stop отменяет вызов очистки. Stop не повлияет, если вызов очистки уже помещен в очередь для выполнения (потому что ptr стал недоступным). Чтобы гарантировать, что Stop удалит функцию очистки, вызывающий поток должен убедиться, что указатель, который был передан в AddCleanup, остается доступным в вызове Stop.
type Error
Интерфейс Error идентифицирует ошибку во время выполнения.
type Error interface {
error
// RuntimeError is a no-op function but
// serves to distinguish types that are run time
// errors from ordinary errors: a type is a
// run time 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
}
тип 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
функция CallersFrames 1.7
func CallersFrames(callers []uintptr) *Frames
CallersFrames принимает набор значений PC, возвращённых функцией Callers, и готовится вернуть информацию о функции/файле/строке. Не изменяйте набор до завершения работы с Frames.
функция (*Frames) Next 1.7
func (ci *Frames) Next() (frame Frame, more bool)
Next возвращает Frame, представляющую следующий кадр вызова в наборе значений PC. Если все кадры вызовов уже возвращены, Next возвращает нулевой Frame.
Результат (больше или меньше) указывает, вернёт ли следующее обращение к Next действительный Frame. Он не обязательно указывает, возвращает ли это обращение один.
См. пример Frames для использования по образцу.
тип Func
Func представляет функцию Go в исполняемом файле.
type Func struct {
// contains filtered or unexported fields
}
функция FuncForPC
func FuncForPC(pc uintptr) *Func
FuncForPC возвращает *Func, описывающий функцию, содержащую заданный адрес программного счётчика, или nil в противном случае.
Если pc соответствует нескольким функциям из-за встраивания, возвращается *Func, описывающий внутреннюю функцию, но с записью внешней функции.
функция (*Func) Entry
func (f *Func) Entry() uintptr
Entry возвращает адрес входа в функцию.
функция (*Func) FileLine
func (f *Func) FileLine(pc uintptr) (file string, line int)
FileLine возвращает имя файла и номер строки исходного кода, соответствующие программному счётчику pc. Результат будет неточным, если pc не является программным счётчиком внутри f.
функция (*Func) Name
func (f *Func) Name() string
Name возвращает имя функции.
тип 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
}
функция (*MemProfileRecord) InUseBytes
func (r *MemProfileRecord) InUseBytes() int64
InUseBytes возвращает количество байтов в использовании (AllocBytes - FreeBytes).
функция (*MemProfileRecord) InUseObjects
func (r *MemProfileRecord) InUseObjects() int64
InUseObjects возвращает количество объектов в использовании (AllocObjects - FreeObjects).
функция (*MemProfileRecord) Stack
func (r *MemProfileRecord) Stack() []uintptr
Stack возвращает стек-трейс, связанный с записью, префикс r.Stack0.
тип 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
}
}
тип 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
}
функция (*PanicNilError) Error 1.21
func (*PanicNilError) Error() string
функция (*PanicNilError) RuntimeError 1.21
func (*PanicNilError) RuntimeError()
тип Pinner 1.21
Pinner — это набор объектов Go, каждый из которых закреплён в фиксированном месте памяти. Метод Pinner.Pin закрепляет один объект, а Pinner.Unpin открепляет все закреплённые объекты. Более подробную информацию см. в их комментариях.
type Pinner struct {
// contains filtered or unexported fields
}
функция (*Pinner) Pin 1.21
func (p *Pinner) Pin(pointer any)
Pin закрепляет объект Go, предотвращая его перемещение или освобождение сборщиком мусора до вызова метода Pinner.Unpin.
Указатель на закреплённый объект можно напрямую хранить в C-памяти или он может содержаться в Go-памяти, передаваемой в C-функции. Если закреплённый объект сам содержит указатели на объекты Go, эти объекты необходимо закрепить отдельно, если к ним предполагается доступ из C-кода.
Аргументом должно быть указатель любого типа или unsafe.Pointer. Безопасно вызывать Pin для не-Go указателей, в этом случае Pin ничего не сделает.
функция (*Pinner) Unpin 1.21
func (p *Pinner) Unpin()
Unpin открепляет все закреплённые объекты Pinner.
тип StackRecord
StackRecord описывает отдельный стек выполнения.
type StackRecord struct {
Stack0 [32]uintptr // stack trace for this record; ends at first 0 entry
}
функция (*StackRecord) Stack
func (r *StackRecord) Stack() []uintptr
Stack возвращает стек-трейс, связанный с записью, префикс r.Stack0.
тип TypeAssertionError
TypeAssertionError объясняет неудачное приведение типа.
type TypeAssertionError struct {
// contains filtered or unexported fields
}
функция (*TypeAssertionError) Error
func (e *TypeAssertionError) Error() string
функция (*TypeAssertionError) RuntimeError
func (*TypeAssertionError) RuntimeError()
Подкаталоги
| Имя | Описание |
|---|---|
| .. | |
| asan | |
| cgo | Пакет cgo содержит поддержку выполнения для кода, сгенерированного инструментом cgo. |
| coverage | Пакет coverage содержит API для записи данных профиля покрытия во время выполнения из долгоживущих и/или серверных программ, которые не завершаются через os.Exit. |
| debug | Пакет debug содержит средства для отладки программ во время их выполнения. |
| metrics | Пакет metrics предоставляет стабильный интерфейс для доступа к реализационно-зависимым метрикам, экспортируемым средой выполнения Go. |
| msan | |
| pprof | Пакет pprof записывает данные профилирования выполнения в формате, ожидаемом инструментом визуализации pprof. |
| race | Пакет race реализует логику обнаружения гонок данных. |
| trace | Пакет trace содержит средства для генерации следов для отслеживания выполнения Go. |
© Google, Inc.
Licensed under the Creative Commons Attribution License 3.0.
http://golang.org/pkg/runtime/
