{"id":7813,"date":"2012-04-20T07:00:00","date_gmt":"2012-04-20T07:00:00","guid":{"rendered":"https:\/\/blogs.msdn.microsoft.com\/oldnewthing\/2012\/04\/20\/what-does-init_once_ctx_reserved_bits-mean\/"},"modified":"2012-04-20T07:00:00","modified_gmt":"2012-04-20T07:00:00","slug":"what-does-init_once_ctx_reserved_bits-mean","status":"publish","type":"post","link":"https:\/\/devblogs.microsoft.com\/oldnewthing\/20120420-00\/?p=7813","title":{"rendered":"What does INIT_ONCE_CTX_RESERVED_BITS mean?"},"content":{"rendered":"

\nWindows Vista adds the\n\nOne-Time Initialization<\/a>\nfamily of functions\nwhich address a common coding pattern:\nI want a specific chunk of code to run exactly once,\neven in the face of multiple calls from different threads.\nThere are many implementations of this pattern,\nsuch as the infamous\n\ndouble-checked lock<\/a>.\nThe double-checked lock is very easy to get wrong,\ndue to memory ordering and race conditions,\nso\n\nthe kernel folks<\/a>\ndecided to write it for you.\n<\/p>\n

\nThe straightforward way of using a one-time-initialization\nobject is to have it protect the initialization of some other\nobject.\nFor example, you might have it protect a static object:\n<\/p>\n

\nINIT_ONCE GizmoInitOnce = INIT_ONCE_STATIC_INIT;\nGizmo ProtectedGizmo;\nBOOL CALLBACK InitGizmoOnce(\n    PINIT_ONCE InitOnce,\n    PVOID Parameter,\n    PVOID *Context)\n{\n    Gizmo *pGizmo = reinterpret_cast<Gizmo*>(Parameter);\n    pGizmo->Initialize();\n    return TRUE;\n}\nSomeFunction(...)\n{\n    \/\/ Initialize ProtectedGizmo if not already initialized\n    InitOnceExecuteOnce(&GizmoInitOnce,\n                        InitGizmoOnce,\n                        &ProtectedGizmo,\n                        NULL);\n    \/\/ At this point, ProtectedGizmo has been initialized\n    ProtectedGizmo.Something();\n    ...\n}\n<\/pre>\n
\nOr you might have it protect a dynamic object:\n<\/p>\n
\nclass Widget\n{\n    Widget()\n    {\n        InitOnceInitialize(&m_InitOnce);\n    }\n    void Initialize();\n    ...\n    static BOOL CALLBACK InitWidgetOnce(\n        PINIT_ONCE InitOnce,\n        PVOID Parameter,\n        PVOID *Context)\n    {\n        Widget *pWidget = reinterpret_cast<Widget*>(Parameter);\n        pWidget->Initialize();\n        return TRUE;\n    }\n    SomeMethod(...)\n    {\n        \/\/ Initialize ourselves if not already initialized\n        InitOnceExecuteOnce(&InitWidgetOnce,\n                            this,\n                            NULL);\n        \/\/ At this point, we have been initialized\n        ... some other stuff ...\n    }\n}\n<\/pre>\n
\nBut it so happens that you can also have the INIT_ONCE<\/code>\nobject protect itself<\/i>.\n<\/p>\n
\nYou see, once the INIT_ONCE<\/code> object has entered the\n“initialization complete” state, the one-time initialization code\nonly needs a few bits of state.\nThe other bits are unused, so the kernel folks figured,\n“Well, since we’re not using them, maybe the application wants to use them.”\n<\/p>\n
\nThat’s where INIT_ONCE_CTX_RESERVED_BITS<\/code> comes in.\nThe\nINIT_ONCE_CTX_RESERVED_BITS<\/code> value is the number of bits\nthat the one-time initialization code uses after initialization is complete;\nthe other bits are free for you to use yourself.\nThe value of\nINIT_ONCE_CTX_RESERVED_BITS<\/code> is 2,\nwhich means that you can store any value that’s a multiple of 4.\nIf it’s a pointer, then the pointer must be DWORD<\/code>-aligned\nor better.\nThis requirement is usually easy to meet because heap-allocated objects\nsatisfy it, and the pointer you want to store is usually a pointer\nto a heap-allocated object.\nAs noted some time ago,\n\nkernel object handles are also multiples of four<\/a>,\nso those can also be safely stored inside the INIT_ONCE<\/code>\nobject.\n(On the other hand, USER and GDI handles are not<\/i> guaranteed\nto be multiples of four, so you cannot use this trick to store those\ntypes of handles.)\n<\/p>\n
\nHere’s an example.\nFirst, the code which uses the traditional method of having the\nINIT_ONCE<\/code> structure protect another variable:\n<\/p>\n
\n\/\/ using the static object pattern for simplicity\nINIT_ONCE PathInitOnce = INIT_ONCE_STATIC_INIT;\nLPWSTR PathToDatabase = NULL;\nBOOL CALLBACK InitPathOnce(\n    PINIT_ONCE InitOnce,\n    PVOID Parameter,\n    PVOID *Context)\n{\n    LPWSTR Path = (LPWSTR)LocalAlloc(LMEM_FIXED, ...);\n    if (Path == NULL) return FALSE;\n    ... get the path in Path...\n    PathToDatabase = Path;\n    return TRUE;\n}\nSomeFunction(...)\n{\n    \/\/ Get the database path (initializing if necessary)\n    if (!InitOnceExecuteOnce(&PathInitOnce,\n                             InitPathOnce,\n                             NULL,\n                             NULL)) {\n        return FALSE; \/\/ couldn't get the path for some reason\n    }\n    \/\/ The \"PathToDatabase\" variable now contains the path\n    \/\/ computed by InitPathOnce.\n    OtherFunction(PathToDatabase);\n    ...\n}\n<\/pre>\n
\nSince the object being protected is pointer-sized and satisfies\nthe necessary alignment constraints,\nwe can merge it into the INIT_ONCE<\/code> structure.\n<\/p>\n
\nINIT_ONCE PathInitOnce = INIT_ONCE_STATIC_INIT;\nBOOL CALLBACK InitPathOnce(\n    PINIT_ONCE InitOnce,\n    PVOID Parameter,\n    PVOID *Context)\n{\n    LPWSTR Path = (LPWSTR)LocalAlloc(LMEM_FIXED, ...);\n    if (Path == NULL) return FALSE;\n    ... get the path in Path...\n    *Context = Path;\n    return TRUE;\n}\nSomeFunction(...)\n{\n    LPWSTR PathToDatabase;\n    \/\/ Get the database path (initializing if necessary)\n    if (!InitOnceExecuteOnce(&PathInitOnce,\n                             InitPathOnce,\n                             NULL,\n                             &PathToDatabase)) {\n        return FALSE; \/\/ couldn't get the path for some reason\n    }\n    \/\/ The \"PathToDatabase\" variable now contains the path\n    \/\/ computed by InitPathOnce.\n    OtherFunction(PathToDatabase);\n    ...\n}\n<\/pre>\n
\nThis may seem like a bunch of extra work to save four bytes\n(or eight bytes on 64-bit Windows),\nbut\nif you use the asynchronous initialization model,\nthen you have no choice but to use context-based initialization,\nas we learned when we tried to\n\nwrite our own lock-free one-time initialization code<\/a>.<\/p>\n","protected":false},"excerpt":{"rendered":"
Windows Vista adds the One-Time Initialization family of functions which address a common coding pattern: I want a specific chunk of code to run exactly once, even in the face of multiple calls from different threads. There are many implementations of this pattern, such as the infamous double-checked lock. The double-checked lock is very easy […]<\/p>\n","protected":false},"author":1069,"featured_media":111744,"comment_status":"open","ping_status":"closed","sticky":false,"template":"","format":"standard","meta":{"_acf_changed":false,"footnotes":""},"categories":[1],"tags":[25],"class_list":["post-7813","post","type-post","status-publish","format-standard","has-post-thumbnail","hentry","category-oldnewthing","tag-code"],"acf":[],"blog_post_summary":"
Windows Vista adds the One-Time Initialization family of functions which address a common coding pattern: I want a specific chunk of code to run exactly once, even in the face of multiple calls from different threads. There are many implementations of this pattern, such as the infamous double-checked lock. The double-checked lock is very easy […]<\/p>\n","_links":{"self":[{"href":"https:\/\/devblogs.microsoft.com\/oldnewthing\/wp-json\/wp\/v2\/posts\/7813","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/devblogs.microsoft.com\/oldnewthing\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/devblogs.microsoft.com\/oldnewthing\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/oldnewthing\/wp-json\/wp\/v2\/users\/1069"}],"replies":[{"embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/oldnewthing\/wp-json\/wp\/v2\/comments?post=7813"}],"version-history":[{"count":0,"href":"https:\/\/devblogs.microsoft.com\/oldnewthing\/wp-json\/wp\/v2\/posts\/7813\/revisions"}],"wp:featuredmedia":[{"embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/oldnewthing\/wp-json\/wp\/v2\/media\/111744"}],"wp:attachment":[{"href":"https:\/\/devblogs.microsoft.com\/oldnewthing\/wp-json\/wp\/v2\/media?parent=7813"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/oldnewthing\/wp-json\/wp\/v2\/categories?post=7813"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/oldnewthing\/wp-json\/wp\/v2\/tags?post=7813"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}