[{"data":1,"prerenderedAt":1196},["ShallowReactive",2],{"navigation_docs":3,"-advanced-go-unsafe-and-cgo":377,"-advanced-go-unsafe-and-cgo-surround":1191},[4,39,114,144,184,244,293,362],{"title":5,"icon":6,"path":7,"stem":8,"children":9,"page":6},"Getting Started",false,"\u002Fgetting-started","1.getting-started",[10,15,20,25,30,35],{"title":11,"path":12,"stem":13,"icon":14},"Learning Path","\u002Fgetting-started\u002Flearning-path","1.getting-started\u002F1.learning-path","i-lucide-map",{"title":16,"path":17,"stem":18,"icon":19},"Introduction","\u002Fgetting-started\u002Fintroduction","1.getting-started\u002F2.introduction","i-lucide-house",{"title":21,"path":22,"stem":23,"icon":24},"Installation","\u002Fgetting-started\u002Finstallation","1.getting-started\u002F3.installation","i-lucide-download",{"title":26,"path":27,"stem":28,"icon":29},"Your First Program","\u002Fgetting-started\u002Ffirst-program","1.getting-started\u002F4.first-program","i-lucide-play",{"title":31,"path":32,"stem":33,"icon":34},"Modules and Dependencies","\u002Fgetting-started\u002Fmodules-and-dependencies","1.getting-started\u002F5.modules-and-dependencies","i-lucide-package-open",{"title":36,"path":37,"stem":38,"icon":34},"Advanced Modules","\u002Fgetting-started\u002Fadvanced-modules","1.getting-started\u002F6.advanced-modules",{"title":40,"path":41,"stem":42,"children":43,"page":6},"Fundamentals","\u002Ffundamentals","2.fundamentals",[44,49,54,59,64,69,74,79,84,89,94,99,104,109],{"title":45,"path":46,"stem":47,"icon":48},"Program Structure","\u002Ffundamentals\u002Fprogram-structure","2.fundamentals\u002F1.program-structure","i-lucide-workflow",{"title":50,"path":51,"stem":52,"icon":53},"Structs and Methods","\u002Ffundamentals\u002Fstructs-and-methods","2.fundamentals\u002F10.structs-and-methods","i-lucide-box",{"title":55,"path":56,"stem":57,"icon":58},"Interfaces","\u002Ffundamentals\u002Finterfaces","2.fundamentals\u002F11.interfaces","i-lucide-plug",{"title":60,"path":61,"stem":62,"icon":63},"Error Handling","\u002Ffundamentals\u002Ferrors","2.fundamentals\u002F12.errors","i-lucide-triangle-alert",{"title":65,"path":66,"stem":67,"icon":68},"Defined Types and Type Aliases","\u002Ffundamentals\u002Fdefined-types","2.fundamentals\u002F13.defined-types","i-lucide-tags",{"title":70,"path":71,"stem":72,"icon":73},"Generics","\u002Ffundamentals\u002Fgenerics","2.fundamentals\u002F14.generics","i-lucide-blocks",{"title":75,"path":76,"stem":77,"icon":78},"Project Structure","\u002Ffundamentals\u002Fproject-structure","2.fundamentals\u002F2.project-structure","i-lucide-folder-tree",{"title":80,"path":81,"stem":82,"icon":83},"Project Layout","\u002Ffundamentals\u002Fproject-layout","2.fundamentals\u002F3.project-layout","i-lucide-layout",{"title":85,"path":86,"stem":87,"icon":88},"Variables and Data Types","\u002Ffundamentals\u002Fvariables-and-types","2.fundamentals\u002F4.variables-and-types","i-lucide-variable",{"title":90,"path":91,"stem":92,"icon":93},"Functions","\u002Ffundamentals\u002Ffunctions","2.fundamentals\u002F5.functions","i-lucide-braces",{"title":95,"path":96,"stem":97,"icon":98},"Control Statements","\u002Ffundamentals\u002Fcontrol-statements","2.fundamentals\u002F6.control-statements","i-lucide-git-branch",{"title":100,"path":101,"stem":102,"icon":103},"Pointers","\u002Ffundamentals\u002Fpointers","2.fundamentals\u002F7.pointers","i-lucide-mouse-pointer-2",{"title":105,"path":106,"stem":107,"icon":108},"Arrays and Slices","\u002Ffundamentals\u002Farrays-and-slices","2.fundamentals\u002F8.arrays-and-slices","i-lucide-list",{"title":110,"path":111,"stem":112,"icon":113},"Maps","\u002Ffundamentals\u002Fmaps","2.fundamentals\u002F9.maps","i-lucide-table-properties",{"title":115,"path":116,"stem":117,"children":118,"page":6},"Concurrency","\u002Fconcurrency","3.concurrency",[119,124,129,134,139],{"title":120,"path":121,"stem":122,"icon":123},"Concurrency Model","\u002Fconcurrency\u002Fconcurrency-model","3.concurrency\u002F1.concurrency-model","i-lucide-network",{"title":125,"path":126,"stem":127,"icon":128},"Goroutines","\u002Fconcurrency\u002Fgoroutines","3.concurrency\u002F2.goroutines","i-lucide-git-fork",{"title":130,"path":131,"stem":132,"icon":133},"Channels","\u002Fconcurrency\u002Fchannels","3.concurrency\u002F3.channels","i-lucide-arrow-left-right",{"title":135,"path":136,"stem":137,"icon":138},"Select and Cancellation","\u002Fconcurrency\u002Fselect-and-cancellation","3.concurrency\u002F4.select-and-cancellation","i-lucide-circle-stop",{"title":140,"path":141,"stem":142,"icon":143},"Synchronization","\u002Fconcurrency\u002Fsynchronization","3.concurrency\u002F5.synchronization","i-lucide-lock-keyhole",{"title":145,"path":146,"stem":147,"children":148,"page":6},"Standard Library","\u002Fstandard-library","4.standard-library",[149,154,159,164,169,174,179],{"title":150,"path":151,"stem":152,"icon":153},"Standard Library Overview","\u002Fstandard-library\u002Foverview","4.standard-library\u002F1.overview","i-lucide-library",{"title":155,"path":156,"stem":157,"icon":158},"Text and Formatting","\u002Fstandard-library\u002Ftext-and-formatting","4.standard-library\u002F2.text-and-formatting","i-lucide-text",{"title":160,"path":161,"stem":162,"icon":163},"Files and JSON","\u002Fstandard-library\u002Ffiles-and-json","4.standard-library\u002F3.files-and-json","i-lucide-file-json",{"title":165,"path":166,"stem":167,"icon":168},"HTTP Clients and Servers","\u002Fstandard-library\u002Fhttp","4.standard-library\u002F4.http","i-lucide-server",{"title":170,"path":171,"stem":172,"icon":173},"Testing","\u002Fstandard-library\u002Ftesting","4.standard-library\u002F5.testing","i-lucide-flask-conical",{"title":175,"path":176,"stem":177,"icon":178},"Command-Line Tools and Configuration","\u002Fstandard-library\u002Fcommand-line-and-configuration","4.standard-library\u002F6.command-line-and-configuration","i-lucide-terminal-square",{"title":180,"path":181,"stem":182,"icon":183},"Structured Logging","\u002Fstandard-library\u002Fstructured-logging","4.standard-library\u002F7.structured-logging","i-lucide-scroll-text",{"title":185,"path":186,"stem":187,"children":188,"page":6},"Backend Development","\u002Fbackend-development","5.backend-development",[189,194,199,204,209,214,219,224,229,234,239],{"title":190,"path":191,"stem":192,"icon":193},"Backend Roadmap","\u002Fbackend-development\u002Fbackend-roadmap","5.backend-development\u002F1.backend-roadmap","i-lucide-route",{"title":195,"path":196,"stem":197,"icon":198},"Graceful Shutdown","\u002Fbackend-development\u002Fgraceful-shutdown","5.backend-development\u002F10.graceful-shutdown","i-lucide-power",{"title":200,"path":201,"stem":202,"icon":203},"Production Checklist","\u002Fbackend-development\u002Fproduction-checklist","5.backend-development\u002F11.production-checklist","i-lucide-clipboard-check",{"title":205,"path":206,"stem":207,"icon":208},"HTTP API Design","\u002Fbackend-development\u002Fhttp-api-design","5.backend-development\u002F2.http-api-design","i-lucide-waypoints",{"title":210,"path":211,"stem":212,"icon":213},"Middleware","\u002Fbackend-development\u002Fmiddleware","5.backend-development\u002F3.middleware","i-lucide-layers-3",{"title":215,"path":216,"stem":217,"icon":218},"Validation","\u002Fbackend-development\u002Fvalidation","5.backend-development\u002F4.validation","i-lucide-list-checks",{"title":220,"path":221,"stem":222,"icon":223},"Application Wiring","\u002Fbackend-development\u002Fapplication-wiring","5.backend-development\u002F5.application-wiring","i-lucide-cable",{"title":225,"path":226,"stem":227,"icon":228},"Observability","\u002Fbackend-development\u002Fobservability","5.backend-development\u002F6.observability","i-lucide-activity",{"title":230,"path":231,"stem":232,"icon":233},"Database SQL","\u002Fbackend-development\u002Fdatabase-sql","5.backend-development\u002F7.database-sql","i-lucide-database",{"title":235,"path":236,"stem":237,"icon":238},"Transactions","\u002Fbackend-development\u002Ftransactions","5.backend-development\u002F8.transactions","i-lucide-repeat-2",{"title":240,"path":241,"stem":242,"icon":243},"Authentication and Authorization","\u002Fbackend-development\u002Fauthentication","5.backend-development\u002F9.authentication","i-lucide-shield-check",{"title":245,"path":246,"stem":247,"children":248,"page":6},"Advanced Go","\u002Fadvanced-go","6.advanced-go",[249,254,259,264,269,274,278,283,288],{"title":250,"path":251,"stem":252,"icon":253},"Advanced Go Roadmap","\u002Fadvanced-go\u002Fadvanced-roadmap","6.advanced-go\u002F1.advanced-roadmap","i-lucide-brain-circuit",{"title":255,"path":256,"stem":257,"icon":258},"Reflection","\u002Fadvanced-go\u002Freflection","6.advanced-go\u002F2.reflection","i-lucide-scan-search",{"title":260,"path":261,"stem":262,"icon":263},"Memory and Garbage Collection","\u002Fadvanced-go\u002Fmemory-and-garbage-collection","6.advanced-go\u002F3.memory-and-garbage-collection","i-lucide-memory-stick",{"title":265,"path":266,"stem":267,"icon":268},"Benchmarking and Profiling","\u002Fadvanced-go\u002Fbenchmarking-and-profiling","6.advanced-go\u002F4.benchmarking-and-profiling","i-lucide-gauge",{"title":270,"path":271,"stem":272,"icon":273},"Advanced Testing and Fuzzing","\u002Fadvanced-go\u002Fadvanced-testing-and-fuzzing","6.advanced-go\u002F5.advanced-testing-and-fuzzing","i-lucide-microscope",{"title":275,"path":276,"stem":277,"icon":48},"Advanced Concurrency","\u002Fadvanced-go\u002Fadvanced-concurrency","6.advanced-go\u002F6.advanced-concurrency",{"title":279,"path":280,"stem":281,"icon":282},"Unsafe and C Boundaries","\u002Fadvanced-go\u002Funsafe-and-cgo","6.advanced-go\u002F7.unsafe-and-cgo","i-lucide-radiation",{"title":284,"path":285,"stem":286,"icon":287},"Package and API Design","\u002Fadvanced-go\u002Fpackage-and-api-design","6.advanced-go\u002F8.package-and-api-design","i-lucide-boxes",{"title":289,"path":290,"stem":291,"icon":292},"Distributed Reliability","\u002Fadvanced-go\u002Fdistributed-reliability","6.advanced-go\u002F9.distributed-reliability","i-lucide-cloud-cog",{"title":294,"path":295,"stem":296,"children":297,"page":6},"Projects","\u002Fprojects","7.projects",[298,316,332,347],{"title":299,"path":300,"stem":301,"children":302,"icon":305},"CLI Task Manager","\u002Fprojects\u002Fcli-task-manager","7.projects\u002F1.cli-task-manager\u002Findex",[303,306,311],{"title":304,"path":300,"stem":301,"icon":305},"Project — CLI Task Manager","i-lucide-list-todo",{"title":307,"path":308,"stem":309,"icon":310},"CLI — Domain and Storage","\u002Fprojects\u002Fcli-task-manager\u002Fdomain-and-storage","7.projects\u002F1.cli-task-manager\u002F1.domain-and-storage","i-lucide-save",{"title":312,"path":313,"stem":314,"icon":315},"CLI — Commands and Tests","\u002Fprojects\u002Fcli-task-manager\u002Fcommands-and-tests","7.projects\u002F1.cli-task-manager\u002F2.commands-and-tests","i-lucide-terminal",{"title":317,"path":318,"stem":319,"children":320,"icon":323},"Concurrent URL Checker","\u002Fprojects\u002Fconcurrent-url-checker","7.projects\u002F2.concurrent-url-checker\u002Findex",[321,324,328],{"title":322,"path":318,"stem":319,"icon":323},"Project — Concurrent URL Checker","i-lucide-radar",{"title":325,"path":326,"stem":327,"icon":128},"URL Checker — Worker Pipeline","\u002Fprojects\u002Fconcurrent-url-checker\u002Fworker-pipeline","7.projects\u002F2.concurrent-url-checker\u002F1.worker-pipeline",{"title":329,"path":330,"stem":331,"icon":173},"URL Checker — Cancellation and Tests","\u002Fprojects\u002Fconcurrent-url-checker\u002Fcancellation-and-tests","7.projects\u002F2.concurrent-url-checker\u002F2.cancellation-and-tests",{"title":333,"path":334,"stem":335,"children":336},"File-backed API","\u002Fprojects\u002Ffile-backed-api","7.projects\u002F3.file-backed-api\u002Findex",[337,339,343],{"title":338,"path":334,"stem":335},"File-backed notes API",{"title":340,"path":341,"stem":342},"File store and concurrency","\u002Fprojects\u002Ffile-backed-api\u002Ffile-store-and-concurrency","7.projects\u002F3.file-backed-api\u002F1.file-store-and-concurrency",{"title":344,"path":345,"stem":346},"HTTP layer and tests","\u002Fprojects\u002Ffile-backed-api\u002Fhttp-and-tests","7.projects\u002F3.file-backed-api\u002F2.http-and-tests",{"title":348,"path":349,"stem":350,"children":351},"Production REST API","\u002Fprojects\u002Fproduction-rest-api","7.projects\u002F4.production-rest-api\u002Findex",[352,354,358],{"title":353,"path":349,"stem":350},"Production REST API capstone",{"title":355,"path":356,"stem":357},"Persistence and authentication","\u002Fprojects\u002Fproduction-rest-api\u002Fpersistence-and-auth","7.projects\u002F4.production-rest-api\u002F1.persistence-and-auth",{"title":359,"path":360,"stem":361},"Operations and release","\u002Fprojects\u002Fproduction-rest-api\u002Foperations-and-release","7.projects\u002F4.production-rest-api\u002F2.operations-and-release",{"title":363,"path":364,"stem":365,"children":366,"page":6},"Meta","\u002Fmeta","99.meta",[367,372],{"title":368,"path":369,"stem":370,"icon":371},"About","\u002Fmeta\u002Fabout","99.meta\u002F1.about","i-lucide-info",{"title":373,"path":374,"stem":375,"icon":376},"Acknowledgements","\u002Fmeta\u002Facknowledgements","99.meta\u002F2.acknowledgements","i-lucide-heart-handshake",{"id":378,"title":279,"body":379,"description":1183,"extension":1184,"links":1185,"meta":1186,"navigation":1187,"path":280,"seo":1188,"stem":281,"__hash__":1190},"docs\u002F6.advanced-go\u002F7.unsafe-and-cgo.md",{"type":380,"value":381,"toc":1168},"minimark",[382,388,393,397,421,425,431,434,442,447,450,473,476,480,486,523,526,530,533,543,563,569,573,576,579,599,602,606,609,629,632,636,643,650,762,765,769,787,790,794,837,841,844,1117,1121,1140,1158,1161,1164],[383,384],"learning-lesson-meta",{"level":385,"prerequisites":386,"time":387},"Advanced","Pointers, memory, reflection, testing, profiling, and systems programming basics","60–75 minutes",[389,390,392],"h2",{"id":391},"what-you-will-learn","What you will learn",[394,395,396],"p",{},"By the end of this lesson, you will be able to:",[398,399,400,409,412,415,418],"ul",{},[401,402,403,404,408],"li",{},"explain why ",[405,406,407],"code",{},"unsafe"," operations fall outside normal type guarantees;",[401,410,411],{},"identify lifetime, alignment, size, and garbage-collector hazards;",[401,413,414],{},"define ownership at a C boundary;",[401,416,417],{},"decide whether cgo cost and deployment constraints are acceptable;",[401,419,420],{},"isolate unavoidable unsafe code behind a small tested API.",[389,422,424],{"id":423},"begin-with-a-presumption-against-it","Begin with a presumption against it",[394,426,427,428,430],{},"Package ",[405,429,407],{}," allows operations that can bypass Go's type system and memory-safety assumptions. Code may depend on representation details that change across architectures or Go releases.",[394,432,433],{},"Use it only when a concrete requirement cannot be met clearly through normal Go, the standard library, maintained bindings, or code generation—and when tests and maintenance ownership are available.",[389,435,437,438,441],{"id":436},"what-unsafepointer-changes","What ",[405,439,440],{},"unsafe.Pointer"," changes",[394,443,444,446],{},[405,445,440],{}," is a special pointer type that permits certain conversions between pointer representations. Only documented conversion patterns are valid.",[394,448,449],{},"Risks include:",[398,451,452,455,458,461,464,467,470],{},[401,453,454],{},"pointing at storage after its valid lifetime;",[401,456,457],{},"constructing misaligned pointers;",[401,459,460],{},"reading or writing the wrong size;",[401,462,463],{},"violating garbage collector pointer-tracking rules;",[401,465,466],{},"depending on field layout or padding;",[401,468,469],{},"retaining pointers through integer conversions incorrectly;",[401,471,472],{},"breaking under a different architecture or compiler version.",[394,474,475],{},"Do not infer legal patterns from code that happens to work in one test.",[389,477,479],{"id":478},"prefer-safe-standard-helpers","Prefer safe standard helpers",[394,481,482,483,485],{},"Modern Go provides safe or narrowly specified APIs for many previous ",[405,484,407],{}," use cases:",[398,487,488,494,500,514,520],{},[401,489,490,493],{},[405,491,492],{},"encoding\u002Fbinary"," for binary representation;",[401,495,496,499],{},[405,497,498],{},"math.Float64bits"," and related functions for numeric bit patterns;",[401,501,502,505,506,509,510,513],{},[405,503,504],{},"slices",", ",[405,507,508],{},"bytes",", and ",[405,511,512],{},"strings"," for common conversions and operations;",[401,515,516,519],{},[405,517,518],{},"reflect"," when runtime inspection is truly required;",[401,521,522],{},"code generation for repetitive typed adapters.",[394,524,525],{},"These APIs document ownership and portability better than hand-written pointer conversion.",[389,527,529],{"id":528},"isolate-the-boundary","Isolate the boundary",[394,531,532],{},"If unsafe code is necessary:",[534,535,541],"pre",{"className":536,"code":538,"language":539,"meta":540},[537],"language-text","internal\u002Fplatform\u002F\n  fastpath_amd64.go\n  fallback.go\n  fastpath_test.go\n","text","",[405,542,538],{"__ignoreMap":540},[398,544,545,548,551,554,557,560],{},[401,546,547],{},"Keep the exported surface typed and safe.",[401,549,550],{},"Put assumptions in comments beside the operation.",[401,552,553],{},"Provide a safe fallback when practical.",[401,555,556],{},"Use build constraints only when platform differences are real and tested.",[401,558,559],{},"Test supported architectures and toolchain upgrades.",[401,561,562],{},"Benchmark the whole use case to prove the benefit.",[394,564,565,566,568],{},"The unsafe implementation should not leak ",[405,567,440],{}," into ordinary application code.",[389,570,572],{"id":571},"what-cgo-does","What cgo does",[394,574,575],{},"cgo lets Go packages call C code and lets C interact with generated bindings. It may be appropriate for an existing native library, operating-system API, or performance-critical implementation that cannot reasonably be replaced.",[394,577,578],{},"It also introduces:",[398,580,581,584,587,590,593,596],{},[401,582,583],{},"a C toolchain and platform-specific build requirements;",[401,585,586],{},"another memory-management system;",[401,588,589],{},"a boundary with calling and scheduling overhead;",[401,591,592],{},"more complex cross-compilation and distribution;",[401,594,595],{},"signal, thread, callback, and error-convention differences;",[401,597,598],{},"pointer-passing restrictions required by the Go garbage collector.",[394,600,601],{},"Measure boundary frequency. A small number of coarse calls can behave very differently from millions of tiny calls.",[389,603,605],{"id":604},"define-memory-ownership","Define memory ownership",[394,607,608],{},"For every pointer crossing the boundary, document:",[398,610,611,614,617,620,623,626],{},[401,612,613],{},"who allocated the memory;",[401,615,616],{},"which side may mutate it;",[401,618,619],{},"how long it remains valid;",[401,621,622],{},"who releases it and with which allocator;",[401,624,625],{},"whether the other side may retain the pointer after the call;",[401,627,628],{},"whether callbacks occur and on which thread assumptions.",[394,630,631],{},"Memory allocated by C generally must be released with the matching C API. Go memory follows Go's garbage collector and pointer-passing rules. Copy data when shared lifetime cannot be made safe and simple.",[389,633,635],{"id":634},"error-translation","Error translation",[394,637,638,639,642],{},"C APIs may use return codes, ",[405,640,641],{},"errno",", output parameters, or thread-local state. Translate these into stable Go errors at the boundary while preserving safe diagnostic context.",[394,644,645,646,649],{},"Never make callers manually combine a C pointer and a separate lifetime token if a typed Go wrapper can own both and expose ",[405,647,648],{},"Close",".",[534,651,655],{"className":652,"code":653,"language":654,"meta":540,"style":540},"language-go shiki shiki-themes solarized-light material-theme one-dark-pro","type Handle struct {\n    \u002F\u002F unexported native state\n}\n\nfunc Open(...) (*Handle, error)\nfunc (h *Handle) Close() error\n","go",[405,656,657,677,684,690,697,736],{"__ignoreMap":540},[658,659,662,666,670,673],"span",{"class":660,"line":661},"line",1,[658,663,665],{"class":664},"sEOdo","type",[658,667,669],{"class":668},"snwKR"," Handle",[658,671,672],{"class":664}," struct",[658,674,676],{"class":675},"shFME"," {\n",[658,678,680],{"class":660,"line":679},2,[658,681,683],{"class":682},"sJsHy","    \u002F\u002F unexported native state\n",[658,685,687],{"class":660,"line":686},3,[658,688,689],{"class":675},"}\n",[658,691,693],{"class":660,"line":692},4,[658,694,696],{"emptyLinePlaceholder":695},true,"\n",[658,698,700,703,707,710,714,717,720,723,726,729,733],{"class":660,"line":699},5,[658,701,702],{"class":664},"func",[658,704,706],{"class":705},"sisdC"," Open",[658,708,709],{"class":675},"(",[658,711,713],{"class":712},"sN42N","...",[658,715,716],{"class":675},")",[658,718,719],{"class":675}," (",[658,721,722],{"class":664},"*",[658,724,725],{"class":668},"Handle",[658,727,728],{"class":675},",",[658,730,732],{"class":731},"sF6sA"," error",[658,734,735],{"class":675},")\n",[658,737,739,741,743,747,749,751,753,756,759],{"class":660,"line":738},6,[658,740,702],{"class":664},[658,742,719],{"class":675},[658,744,746],{"class":745},"syre3","h ",[658,748,722],{"class":664},[658,750,725],{"class":668},[658,752,716],{"class":675},[658,754,755],{"class":705}," Close",[658,757,758],{"class":675},"()",[658,760,761],{"class":731}," error\n",[394,763,764],{},"Make repeated close behaviour explicit and prevent operations after close.",[389,766,768],{"id":767},"validation-tools","Validation tools",[398,770,771,774,781,784],{},[401,772,773],{},"Run tests on every supported target.",[401,775,776,777,780],{},"Use ",[405,778,779],{},"go vet",", the race detector where supported, platform sanitizers when applicable, and pointer checking offered by the current toolchain.",[401,782,783],{},"Fuzz safe parsing or marshalling layers around the boundary.",[401,785,786],{},"Test failure, empty input, maximum sizes, callbacks, cancellation, and repeated cleanup.",[394,788,789],{},"No tool proves unsafe code correct. Review invariants manually against current official rules.",[389,791,793],{"id":792},"common-mistakes","Common mistakes",[398,795,796,807,813,819,825,831],{},[401,797,798,806],{},[799,800,801,802,805],"strong",{},"Converting through ",[405,803,804],{},"uintptr"," and retaining it:"," an integer is not a collector-tracked pointer or lifetime guarantee.",[401,808,809,812],{},[799,810,811],{},"Returning a Go slice backed by temporary C memory:"," the slice outlives its storage.",[401,814,815,818],{},[799,816,817],{},"Freeing C memory with a different allocator:"," allocator ownership is violated.",[401,820,821,824],{},[799,822,823],{},"Making tiny cgo calls in a hot loop without measurement:"," boundary overhead dominates.",[401,826,827,830],{},[799,828,829],{},"Using finalizers as the only native cleanup:"," release timing becomes nondeterministic.",[401,832,833,836],{},[799,834,835],{},"Copying an unsafe snippet without its assumptions:"," context required for validity is lost.",[389,838,840],{"id":839},"practice","Practice",[394,842,843],{},"Review a hypothetical image-decoding C wrapper. Produce an ownership table for input bytes, native decoder handle, output pixels, errors, callbacks, and cleanup. Design a safe Go API without writing unsafe conversion code.",[845,846,847],"accordion",{},[848,849,852,972,1110],"accordion-item",{"icon":850,"label":851},"i-lucide-lightbulb","Show ownership design",[853,854,855,877],"table",{},[856,857,858],"thead",{},[859,860,861,865,868,871,874],"tr",{},[862,863,864],"th",{},"Resource",[862,866,867],{},"Allocator",[862,869,870],{},"Valid until",[862,872,873],{},"Released by",[862,875,876],{},"Go API choice",[878,879,880,898,919,939,955],"tbody",{},[859,881,882,886,889,892,895],{},[883,884,885],"td",{},"Encoded input",[883,887,888],{},"Go caller",[883,890,891],{},"Decode returns",[883,893,894],{},"Go GC",[883,896,897],{},"Copy into C if native code retains it",[859,899,900,903,906,910,913],{},[883,901,902],{},"Decoder handle",[883,904,905],{},"C library",[883,907,908],{},[405,909,648],{},[883,911,912],{},"Matching C destroy function",[883,914,915,916],{},"Unexported field in ",[405,917,918],{},"Decoder",[859,920,921,924,926,929,932],{},[883,922,923],{},"Output pixels",[883,925,905],{},[883,927,928],{},"Explicit free",[883,930,931],{},"Matching C free function",[883,933,934,935,938],{},"Copy into Go-owned ",[405,936,937],{},"[]byte"," before return",[859,940,941,944,946,949,952],{},[883,942,943],{},"Native error text",[883,945,905],{},[883,947,948],{},"Documented next call\u002Ffree",[883,950,951],{},"Boundary wrapper",[883,953,954],{},"Convert immediately to Go string\u002Ferror",[859,956,957,960,963,966,969],{},[883,958,959],{},"Progress callback",[883,961,962],{},"Go wrapper",[883,964,965],{},"Decode returns or cancellation completes",[883,967,968],{},"Registration cleanup",[883,970,971],{},"Document threading; avoid retaining Go pointers illegally",[534,973,975],{"className":652,"code":974,"language":654,"meta":540,"style":540},"type Decoder struct {\n    \u002F\u002F native handle remains private\n}\n\nfunc Open(options Options) (*Decoder, error)\nfunc (d *Decoder) Decode(ctx context.Context, encoded []byte) (image.Image, error)\nfunc (d *Decoder) Close() error\n",[405,976,977,988,993,997,1001,1029,1089],{"__ignoreMap":540},[658,978,979,981,984,986],{"class":660,"line":661},[658,980,665],{"class":664},[658,982,983],{"class":668}," Decoder",[658,985,672],{"class":664},[658,987,676],{"class":675},[658,989,990],{"class":660,"line":679},[658,991,992],{"class":682},"    \u002F\u002F native handle remains private\n",[658,994,995],{"class":660,"line":686},[658,996,689],{"class":675},[658,998,999],{"class":660,"line":692},[658,1000,696],{"emptyLinePlaceholder":695},[658,1002,1003,1005,1007,1009,1012,1015,1017,1019,1021,1023,1025,1027],{"class":660,"line":699},[658,1004,702],{"class":664},[658,1006,706],{"class":705},[658,1008,709],{"class":675},[658,1010,1011],{"class":745},"options",[658,1013,1014],{"class":668}," Options",[658,1016,716],{"class":675},[658,1018,719],{"class":675},[658,1020,722],{"class":664},[658,1022,918],{"class":668},[658,1024,728],{"class":675},[658,1026,732],{"class":731},[658,1028,735],{"class":675},[658,1030,1031,1033,1035,1038,1040,1042,1044,1047,1049,1052,1055,1057,1060,1062,1065,1068,1071,1073,1075,1078,1080,1083,1085,1087],{"class":660,"line":738},[658,1032,702],{"class":664},[658,1034,719],{"class":675},[658,1036,1037],{"class":745},"d ",[658,1039,722],{"class":664},[658,1041,918],{"class":668},[658,1043,716],{"class":675},[658,1045,1046],{"class":705}," Decode",[658,1048,709],{"class":675},[658,1050,1051],{"class":745},"ctx",[658,1053,1054],{"class":668}," context",[658,1056,649],{"class":675},[658,1058,1059],{"class":668},"Context",[658,1061,728],{"class":675},[658,1063,1064],{"class":745}," encoded",[658,1066,1067],{"class":675}," []",[658,1069,1070],{"class":731},"byte",[658,1072,716],{"class":675},[658,1074,719],{"class":675},[658,1076,1077],{"class":668},"image",[658,1079,649],{"class":675},[658,1081,1082],{"class":668},"Image",[658,1084,728],{"class":675},[658,1086,732],{"class":731},[658,1088,735],{"class":675},[658,1090,1092,1094,1096,1098,1100,1102,1104,1106,1108],{"class":660,"line":1091},7,[658,1093,702],{"class":664},[658,1095,719],{"class":675},[658,1097,1037],{"class":745},[658,1099,722],{"class":664},[658,1101,918],{"class":668},[658,1103,716],{"class":675},[658,1105,755],{"class":705},[658,1107,758],{"class":675},[658,1109,761],{"class":731},[394,1111,1112,1113,1116],{},"The public API uses normal Go types. ",[405,1114,1115],{},"Decode"," returns Go-owned image data, so callers do not manage C memory. The internal implementation must follow current cgo pointer rules and define whether cancellation can interrupt the native call or only discard its result.",[389,1118,1120],{"id":1119},"summary","Summary",[398,1122,1123,1128,1131,1134,1137],{},[401,1124,1125,1127],{},[405,1126,407],{}," trades away normal type and portability guarantees.",[401,1129,1130],{},"Use only conversion patterns documented by the current Go specification and package docs.",[401,1132,1133],{},"cgo adds a second toolchain, memory system, and lifecycle model.",[401,1135,1136],{},"Write down allocator, lifetime, mutation, retention, and cleanup for every crossing value.",[401,1138,1139],{},"Keep the risky core tiny and expose a safe typed API with extensive tests.",[394,1141,1142,1143,1152,1153,649],{},"Official references: ",[1144,1145,1149,1151],"a",{"href":1146,"rel":1147},"https:\u002F\u002Fpkg.go.dev\u002Funsafe",[1148],"nofollow",[405,1150,407],{}," package"," and ",[1144,1154,1157],{"href":1155,"rel":1156},"https:\u002F\u002Fpkg.go.dev\u002Fcmd\u002Fcgo",[1148],"cgo command documentation",[1159,1160],"learning-lesson-complete",{},[1162,1163],"learning-lesson-navigation",{"next":285,"next-label":284,"previous":276,"previous-label":275},[1165,1166,1167],"style",{},"html pre.shiki code .sEOdo, html code.shiki .sEOdo{--shiki-light:#859900;--shiki-default:#89DDFF;--shiki-dark:#C678DD}html pre.shiki code .snwKR, html code.shiki .snwKR{--shiki-light:#CB4B16;--shiki-default:#FFCB6B;--shiki-dark:#E5C07B}html pre.shiki code .shFME, html code.shiki .shFME{--shiki-light:#657B83;--shiki-default:#89DDFF;--shiki-dark:#ABB2BF}html pre.shiki code .sJsHy, html code.shiki .sJsHy{--shiki-light:#93A1A1;--shiki-light-font-style:italic;--shiki-default:#546E7A;--shiki-default-font-style:italic;--shiki-dark:#7F848E;--shiki-dark-font-style:italic}html pre.shiki code .sisdC, html code.shiki .sisdC{--shiki-light:#268BD2;--shiki-default:#82AAFF;--shiki-dark:#61AFEF}html pre.shiki code .sN42N, html code.shiki .sN42N{--shiki-light:#859900;--shiki-default:#89DDFF;--shiki-dark:#ABB2BF}html pre.shiki code .sF6sA, html code.shiki .sF6sA{--shiki-light:#586E75;--shiki-light-font-weight:bold;--shiki-default:#C792EA;--shiki-default-font-weight:inherit;--shiki-dark:#C678DD;--shiki-dark-font-weight:inherit}html pre.shiki code .syre3, html code.shiki .syre3{--shiki-light:#657B83;--shiki-light-font-style:inherit;--shiki-default:#EEFFFF;--shiki-default-font-style:italic;--shiki-dark:#E06C75;--shiki-dark-font-style:italic}html .light .shiki span {color: var(--shiki-light);background: var(--shiki-light-bg);font-style: var(--shiki-light-font-style);font-weight: var(--shiki-light-font-weight);text-decoration: var(--shiki-light-text-decoration);}html.light .shiki span {color: var(--shiki-light);background: var(--shiki-light-bg);font-style: var(--shiki-light-font-style);font-weight: var(--shiki-light-font-weight);text-decoration: var(--shiki-light-text-decoration);}html .default .shiki span {color: var(--shiki-default);background: var(--shiki-default-bg);font-style: var(--shiki-default-font-style);font-weight: var(--shiki-default-font-weight);text-decoration: var(--shiki-default-text-decoration);}html .shiki span {color: var(--shiki-default);background: var(--shiki-default-bg);font-style: var(--shiki-default-font-style);font-weight: var(--shiki-default-font-weight);text-decoration: var(--shiki-default-text-decoration);}html .dark .shiki span {color: var(--shiki-dark);background: var(--shiki-dark-bg);font-style: var(--shiki-dark-font-style);font-weight: var(--shiki-dark-font-weight);text-decoration: var(--shiki-dark-text-decoration);}html.dark .shiki span {color: var(--shiki-dark);background: var(--shiki-dark-bg);font-style: var(--shiki-dark-font-style);font-weight: var(--shiki-dark-font-weight);text-decoration: var(--shiki-dark-text-decoration);}",{"title":540,"searchDepth":679,"depth":679,"links":1169},[1170,1171,1172,1174,1175,1176,1177,1178,1179,1180,1181,1182],{"id":391,"depth":679,"text":392},{"id":423,"depth":679,"text":424},{"id":436,"depth":679,"text":1173},"What unsafe.Pointer changes",{"id":478,"depth":679,"text":479},{"id":528,"depth":679,"text":529},{"id":571,"depth":679,"text":572},{"id":604,"depth":679,"text":605},{"id":634,"depth":679,"text":635},{"id":767,"depth":679,"text":768},{"id":792,"depth":679,"text":793},{"id":839,"depth":679,"text":840},{"id":1119,"depth":679,"text":1120},"Understand what guarantees are lost when using unsafe or cgo and how to isolate the risk.","md",null,{},{"icon":282},{"description":1189,"title":279},"Learn when Go unsafe and cgo are justified, pointer and lifetime hazards, C memory ownership, callbacks, portability, and safe containment.","_icuti3b9YrfEvtW90EXkPZeVDoHMOq6UmBs8OBdFwY",[1192,1194],{"title":275,"path":276,"stem":277,"description":1193,"icon":48,"children":-1},"Design bounded pipelines with cancellation, backpressure, error propagation, and explicit ownership.",{"title":284,"path":285,"stem":286,"description":1195,"icon":287,"children":-1},"Build small, stable packages that are easy to understand, test, evolve, and use correctly.",1794118103840]