e3d4644 chore(callbacks): make diagnostics opt-in · purego

M README.md +11 -0


@@ -95,6 +95,17 @@ func main() {
95	95
96	96		Then to run: `CGO_ENABLED=0 go run main.go`
97	97
	98	+	## Callback diagnostics
	99	+
	100	+	Callback allocation diagnostics are disabled by default. When debugging callback slot
	101	+	exhaustion on Unix-like platforms, set `PUREGO_CALLBACK_LEDGER=1` to append JSONL
	102	+	callback lifecycle events to `/tmp/purego-callback-ledger-<pid>.jsonl`, or set
	103	+	`PUREGO_CALLBACK_LEDGER_FILE=/path/to/file.jsonl` to choose the output file. Stack
	104	+	capture is also disabled by default; set `PUREGO_CALLBACK_LEDGER_STACK=1` when call
	105	+	site attribution is needed. For ad-hoc stderr/file traces near callback exhaustion,
	106	+	set `PUREGO_CALLBACK_TRACE=1`; `PUREGO_CALLBACK_TRACE_FILE` overrides the default
	107	+	`/tmp/purego-callback-trace-<pid>.log` path.
	108	+
98	109		## Questions
99	110
100	111		If you have questions about how to incorporate purego in your project or want to discuss


@@ -95,6 +95,17 @@ func main() {
95		95
96	Then to run: `CGO_ENABLED=0 go run main.go`	96		Then to run: `CGO_ENABLED=0 go run main.go`
97		97
		98	+	## Callback diagnostics
		99	+
		100	+	Callback allocation diagnostics are disabled by default. When debugging callback slot
		101	+	exhaustion on Unix-like platforms, set `PUREGO_CALLBACK_LEDGER=1` to append JSONL
		102	+	callback lifecycle events to `/tmp/purego-callback-ledger-<pid>.jsonl`, or set
		103	+	`PUREGO_CALLBACK_LEDGER_FILE=/path/to/file.jsonl` to choose the output file. Stack
		104	+	capture is also disabled by default; set `PUREGO_CALLBACK_LEDGER_STACK=1` when call
		105	+	site attribution is needed. For ad-hoc stderr/file traces near callback exhaustion,
		106	+	set `PUREGO_CALLBACK_TRACE=1`; `PUREGO_CALLBACK_TRACE_FILE` overrides the default
		107	+	`/tmp/purego-callback-trace-<pid>.log` path.
		108	+
98	## Questions	109		## Questions
99		110
100	If you have questions about how to incorporate purego in your project or want to discuss	111		If you have questions about how to incorporate purego in your project or want to discuss

A callback_diagnostics_test.go +46 -0

@@ -0,0 +1,46 @@
	1	+	// SPDX-License-Identifier: Apache-2.0
	2	+	// SPDX-FileCopyrightText: 2022 The Ebitengine Authors
	3	+
	4	+	//go:build darwin \|\| freebsd \|\| (linux && (386 \|\| amd64 \|\| arm \|\| arm64 \|\| loong64 \|\| ppc64le \|\| riscv64 \|\| (cgo && s390x))) \|\| netbsd
	5	+
	6	+	package purego
	7	+
	8	+	import "testing"
	9	+
	10	+	func TestCallbackDiagnosticsDisabledByDefault(t *testing.T) {
	11	+	t.Setenv("PUREGO_CALLBACK_LEDGER", "")
	12	+	t.Setenv("PUREGO_CALLBACK_LEDGER_STACK", "")
	13	+	t.Setenv("PUREGO_CALLBACK_TRACE", "")
	14	+
	15	+	if callbackLedgerEnabled() {
	16	+	t.Fatal("callback ledger must be disabled by default")
	17	+	}
	18	+	if callbackLedgerStackEnabled() {
	19	+	t.Fatal("callback ledger stack capture must be disabled by default")
	20	+	}
	21	+	if callbackTraceEnabled() {
	22	+	t.Fatal("callback trace must be disabled by default")
	23	+	}
	24	+	}
	25	+
	26	+	func TestCallbackDiagnosticsExplicitOptIn(t *testing.T) {
	27	+	for _, value := range []string{"1", "true", "yes", "on", "TRUE", "On"} {
	28	+	t.Run(value, func(t *testing.T) {
	29	+	t.Setenv("PUREGO_CALLBACK_LEDGER", value)
	30	+	if !callbackLedgerEnabled() {
	31	+	t.Fatalf("callback ledger was not enabled by %q", value)
	32	+	}
	33	+	})
	34	+	}
	35	+	}
	36	+
	37	+	func TestCallbackDiagnosticsRejectsImplicitValues(t *testing.T) {
	38	+	for _, value := range []string{"0", "false", "no", "off", "anything-else"} {
	39	+	t.Run(value, func(t *testing.T) {
	40	+	t.Setenv("PUREGO_CALLBACK_LEDGER", value)
	41	+	if callbackLedgerEnabled() {
	42	+	t.Fatalf("callback ledger unexpectedly enabled by %q", value)
	43	+	}
	44	+	})
	45	+	}
	46	+	}

@@ -0,0 +1,46 @@
	1	+	// SPDX-License-Identifier: Apache-2.0
	2	+	// SPDX-FileCopyrightText: 2022 The Ebitengine Authors
	3	+
	4	+	//go:build darwin \|\| freebsd \|\| (linux && (386 \|\| amd64 \|\| arm \|\| arm64 \|\| loong64 \|\| ppc64le \|\| riscv64 \|\| (cgo && s390x))) \|\| netbsd
	5	+
	6	+	package purego
	7	+
	8	+	import "testing"
	9	+
	10	+	func TestCallbackDiagnosticsDisabledByDefault(t *testing.T) {
	11	+	t.Setenv("PUREGO_CALLBACK_LEDGER", "")
	12	+	t.Setenv("PUREGO_CALLBACK_LEDGER_STACK", "")
	13	+	t.Setenv("PUREGO_CALLBACK_TRACE", "")
	14	+
	15	+	if callbackLedgerEnabled() {
	16	+	t.Fatal("callback ledger must be disabled by default")
	17	+	}
	18	+	if callbackLedgerStackEnabled() {
	19	+	t.Fatal("callback ledger stack capture must be disabled by default")
	20	+	}
	21	+	if callbackTraceEnabled() {
	22	+	t.Fatal("callback trace must be disabled by default")
	23	+	}
	24	+	}
	25	+
	26	+	func TestCallbackDiagnosticsExplicitOptIn(t *testing.T) {
	27	+	for _, value := range []string{"1", "true", "yes", "on", "TRUE", "On"} {
	28	+	t.Run(value, func(t *testing.T) {
	29	+	t.Setenv("PUREGO_CALLBACK_LEDGER", value)
	30	+	if !callbackLedgerEnabled() {
	31	+	t.Fatalf("callback ledger was not enabled by %q", value)
	32	+	}
	33	+	})
	34	+	}
	35	+	}
	36	+
	37	+	func TestCallbackDiagnosticsRejectsImplicitValues(t *testing.T) {
	38	+	for _, value := range []string{"0", "false", "no", "off", "anything-else"} {
	39	+	t.Run(value, func(t *testing.T) {
	40	+	t.Setenv("PUREGO_CALLBACK_LEDGER", value)
	41	+	if callbackLedgerEnabled() {
	42	+	t.Fatalf("callback ledger unexpectedly enabled by %q", value)
	43	+	}
	44	+	})
	45	+	}
	46	+	}

M syscall_unix.go +29 -4


@@ -193,8 +193,25 @@ type callbackLedgerEvent struct {
193	193		Error string `json:"error,omitempty"`
194	194		}
195	195
	196	+	func callbackEnvEnabled(name string) bool {
	197	+	switch strings.ToLower(os.Getenv(name)) {
	198	+	case "1", "true", "yes", "on":
	199	+	return true
	200	+	default:
	201	+	return false
	202	+	}
	203	+	}
	204	+
196	205		func callbackLedgerEnabled() bool {
197		-	return os.Getenv("PUREGO_CALLBACK_LEDGER") != "0"
	206	+	return callbackEnvEnabled("PUREGO_CALLBACK_LEDGER")
	207	+	}
	208	+
	209	+	func callbackLedgerStackEnabled() bool {
	210	+	return callbackEnvEnabled("PUREGO_CALLBACK_LEDGER_STACK")
	211	+	}
	212	+
	213	+	func callbackTraceEnabled() bool {
	214	+	return callbackEnvEnabled("PUREGO_CALLBACK_TRACE")
198	215		}
199	216
200	217		func callbackLedgerPath() string {

@@ -268,8 +285,13 @@ func recordCallbackLedger(event string, idx int, addr uintptr, fnPtrKey uintptr,
268	285		if !callbackLedgerEnabled() {
269	286		return
270	287		}
271		-	stack := string(debug.Stack())
272		-	family, stackKey := classifyCallbackStack(stack)
	288	+	stack := ""
	289	+	family := "unknown"
	290	+	stackKey := "unknown"
	291	+	if callbackLedgerStackEnabled() {
	292	+	stack = string(debug.Stack())
	293	+	family, stackKey = classifyCallbackStack(stack)
	294	+	}
273	295		cbs.ledgerSeq++
274	296		occupied := cbs.numFn - len(cbs.holes)
275	297		entry := callbackLedgerEvent{

@@ -293,7 +315,7 @@ func recordCallbackLedger(event string, idx int, addr uintptr, fnPtrKey uintptr,
293	315		ReusedSlot: reused,
294	316		Error: errText,
295	317		}
296		-	if os.Getenv("PUREGO_CALLBACK_LEDGER_STACK") != "0" {
	318	+	if callbackLedgerStackEnabled() {
297	319		entry.Stack = stack
298	320		}
299	321		payload, err := json.Marshal(entry)

@@ -308,6 +330,9 @@ func recordCallbackLedger(event string, idx int, addr uintptr, fnPtrKey uintptr,
308	330		}
309	331
310	332		func traceCallbackAllocation(event string, val reflect.Value, remaining int) {
	333	+	if !callbackTraceEnabled() {
	334	+	return
	335	+	}
311	336		message := fmt.Sprintf("PUREGO-CALLBACK-TRACE event=%s remaining=%d live=%d type=%s\n%s\n", event, remaining, maxCB-remaining, val.Type(), debug.Stack())
312	337		fmt.Fprint(os.Stderr, message)
313	338		traceFile := os.Getenv("PUREGO_CALLBACK_TRACE_FILE")

 	Error      string `json:"error,omitempty"`
 }
+func callbackEnvEnabled(name string) bool {
+	switch strings.ToLower(os.Getenv(name)) {
+	case "1", "true", "yes", "on":
+		return true
+	default:
+		return false
+	}
+}
 func callbackLedgerEnabled() bool {
-	return os.Getenv("PUREGO_CALLBACK_LEDGER") != "0"
+	return callbackEnvEnabled("PUREGO_CALLBACK_LEDGER")
+}
+func callbackLedgerStackEnabled() bool {
+	return callbackEnvEnabled("PUREGO_CALLBACK_LEDGER_STACK")
+}
+func callbackTraceEnabled() bool {
+	return callbackEnvEnabled("PUREGO_CALLBACK_TRACE")
 }
 func callbackLedgerPath() string {
 	if !callbackLedgerEnabled() {
 		return
 	}
-	stack := string(debug.Stack())
+	stack := ""
-	family, stackKey := classifyCallbackStack(stack)
+	family := "unknown"
+	stackKey := "unknown"
+	if callbackLedgerStackEnabled() {
+		stack = string(debug.Stack())
+		family, stackKey = classifyCallbackStack(stack)
+	}
 	cbs.ledgerSeq++
 	occupied := cbs.numFn - len(cbs.holes)
 	entry := callbackLedgerEvent{
 		ReusedSlot: reused,
 		Error:      errText,
 	}
-	if os.Getenv("PUREGO_CALLBACK_LEDGER_STACK") != "0" {
+	if callbackLedgerStackEnabled() {
 		entry.Stack = stack
 	}
 	payload, err := json.Marshal(entry)
 }
 func traceCallbackAllocation(event string, val reflect.Value, remaining int) {
+	if !callbackTraceEnabled() {
+		return
+	}
 	message := fmt.Sprintf("PUREGO-CALLBACK-TRACE event=%s remaining=%d live=%d type=%s\n%s\n", event, remaining, maxCB-remaining, val.Type(), debug.Stack())
 	fmt.Fprint(os.Stderr, message)
 	traceFile := os.Getenv("PUREGO_CALLBACK_TRACE_FILE")