{"id":10983,"date":"2011-04-08T07:00:01","date_gmt":"2011-04-08T14:00:01","guid":{"rendered":"https:\/\/blogs.msdn.microsoft.com\/oldnewthing\/2011\/04\/08\/patterns-for-using-the-initonce-functions\/"},"modified":"2011-04-08T07:00:01","modified_gmt":"2011-04-08T14:00:01","slug":"patterns-for-using-the-initonce-functions","status":"publish","type":"post","link":"https:\/\/devblogs.microsoft.com\/oldnewthing\/20110408-01\/?p=10983","title":{"rendered":"Patterns for using the InitOnce functions"},"content":{"rendered":"

\nSince writing lock-free code is is\n\nsuch a headache-inducer<\/a>,\nyou’re probably best off making some other people suffer the headaches\nfor you.\nAnd those other people are the kernel folks, who have developed\nquite a few lock-free building blocks so you don’t have to.\nFor example, there’s a collection of functions for manipulating\n\ninterlocked lists<\/a>.\nBut today we’re going to look at the\n\none-time initialization<\/a> functions.\n<\/p>\n

\nThe simplest version of the one-time initialization functions\nisn’t actually lock-free,\nbut it does implement the double-checked-lock pattern for you\nso you don’t have to worry about the details.\nThe usage pattern for the\n\nInit­Once­Execute­Once<\/code> function<\/a>\nis pretty simple.\nHere it is in its simplest form:\n<\/p>\n

\nint SomeGlobalInteger;\nBOOL CALLBACK ThisRunsAtMostOnce(\n    PINIT_ONCE initOnce,\n    PVOID Parameter,\n    PVOID *Context)\n{\n    calculate_an_integer(&SomeGlobalInteger);\n    return TRUE;\n}\nvoid InitializeThatGlobalInteger()\n{\n    static INIT_ONCE initOnce = INIT_ONCE_STATIC_INIT;\n    InitOnceExecuteOnce(&initOnce,\n                        ThisRunsAtMostOnce,\n                        nullptr, nullptr);\n}\n<\/pre>\n
\nIn the simplest form, you give\nInit­Once­Execute­Once<\/code> an\nINIT_ONCE<\/code> structure (where it records\nits state),\nand a callback.\nIf this is the first time that\nInit­Once­Execute­Once<\/code> is called\nfor a particular\nINIT_ONCE<\/code> structure,\nit calls the callback.\nThe callback can do whatever it likes,\nbut presumably it’s doing some one-time initialization.\nIf another thread calls\nInit­Once­Execute­Once<\/code> on the same\nINIT_ONCE<\/code> structure,\nthat other thread will wait until the first thread is finished\nits one-time execution.\n<\/p>\n
\nWe can make this a tiny bit fancier by supposing that\nthe calculation of the integer can fail.\n<\/p>\n
\nBOOL CALLBACK ThisSucceedsAtMostOnce(\n    PINIT_ONCE initOnce,\n    PVOID Parameter,\n    PVOID *Context)\n{\n    return SUCCEEDED(calculate_an_integer(&SomeGlobalInteger));\n}\nBOOL TryToInitializeThatGlobalInteger()\n{\n    static INIT_ONCE initOnce = INIT_ONCE_STATIC_INIT;\n    return InitOnceExecuteOnce(&initOnce,\n                               ThisSucceedsAtMostOnce,\n                               nullptr, nullptr);\n}\n<\/pre>\n
\nIf your initialization function returns FALSE<\/code>,\nthen the initialization is considered to have failed,\nand the next time somebody calls\nInit­Once­Execute­Once<\/code>,\nit will try to initialize again.\n<\/p>\n
\nA slightly fancier use of the\nInit­Once­Execute­Once<\/code> function\ntakes advantage of the Context<\/code> parameter.\nThe kernel folks noticed that an\nINIT_ONCE<\/code> structure in the “initialized”\nstate has a lot of unused bits,\nand they’ve offered to let you use them.\nThis is convenient if the thing you’re initializing is a pointer\nto a C++ object, because it means that there’s only one thing\nyou need to worry about instead of two.\n<\/p>\n
\nBOOL CALLBACK AllocateAndInitializeTheThing(\n    PINIT_ONCE initOnce,\n    PVOID Parameter,\n    PVOID *Context)\n{\n    *Context = new(nothrow) Thing();\n    return *Context != nullptr;\n}\nThing *GetSingletonThing(int arg1, int arg2)\n{\n    static INIT_ONCE initOnce = INIT_ONCE_STATIC_INIT;\n    void *Result;\n    if (InitOnceExecuteOnce(&initOnce,\n                            AllocateAndInitializeTheThing,\n                            nullptr, &Result))\n    {\n        return static_cast<Thing*>(Result);\n    }\n    return nullptr;\n}\n<\/pre>\n
\nThe final parameter to\nInit­Once­Execute­Once<\/code> function\nreceives the magic almost-pointer-sized data that the function\nwill remember for you.\nYour callback function passes this magic value back through\nthe Context<\/code> parameter,\nand then\nInit­Once­Execute­Once<\/code> gives it\nback to you as the Result<\/code>.\n<\/p>\n
\nAs before, if two threads call\nInit­Once­Execute­Once<\/code> simultaneously\non an uninitialized INIT_ONCE<\/code> structure,\none of them will call the initialization function and the other will wait.\n<\/p>\n
\nUp until now, we’ve been looking at the synchronous initialization\npatterns.\nThey aren’t lock-free:\nIf you call Init­Once­Execute­Once<\/code>\nand initialization of the the INIT_ONCE<\/code> structure is\nalready in progress, your call will wait until that initialization\nattempt completes (either successfully or unsuccessfully).\n<\/p>\n
\nMore interesting is the asynchronous pattern.\nHere it is, as applied to our Singleton­Manager<\/code> exercise:\n<\/p>\n
\n SingletonManager(const SINGLETONINFO *rgsi, UINT csi)\n               : m_rgsi(rgsi), m_csi(csi),\n                 m_rgio(new INITONCE[csi]) {\n   for (UINT iio = 0; iio < csi; iio++) {\n    InitOnceInitialize(&m_rgio[iio]);\n   }\n }\n ...\n \/\/ Array that describes objects we've created\n \/\/ runs parallel to m_rgsi\n INIT_ONCE *m_rgio;\n};\nITEMCONTROLLER *SingletonManager::Lookup(DWORD dwId)\n{\n ... same as before until we reach the "singleton constructor pattern"\n void *pv = NULL;\n BOOL fPending;\n if (!InitOnceBeginInitialize(&m_rgio[i], INIT_ONCE_ASYNC,\n                              &fPending, &pv)) return NULL;\n if (fPending) {\n  ITEMCONTROLLER *pic = m_rgsi[i].pfnCreateController();\n  if (pic && InitOnceComplete(&m_rgio[i],\n                              INIT_ONCE_ASYNC, pic)) {\n   pv = pic;\n  } else {\n   \/\/ lost the race - discard ours and retrieve the winner\n   delete pic;\n   InitOnceBeginInitialize(&m_rgio[i], INIT_ONCE_CHECK_ONLY,\n                           &fPending, &pv);\n  }\n }\n return static_cast<ITEMCONTROLLER *>(pv);\n}\n<\/pre>\n
\nThe pattern for asynchronous initialization is as follows:\n<\/p>\n