{"id":5703,"date":"2012-12-28T07:00:00","date_gmt":"2012-12-28T07:00:00","guid":{"rendered":"https:\/\/blogs.msdn.microsoft.com\/oldnewthing\/2012\/12\/28\/what-do-heaplock-and-heapunlock-do-and-when-do-i-need-to-call-them\/"},"modified":"2012-12-28T07:00:00","modified_gmt":"2012-12-28T07:00:00","slug":"what-do-heaplock-and-heapunlock-do-and-when-do-i-need-to-call-them","status":"publish","type":"post","link":"https:\/\/devblogs.microsoft.com\/oldnewthing\/20121228-00\/?p=5703","title":{"rendered":"What do HeapLock and HeapUnlock do, and when do I need to call them?"},"content":{"rendered":"

\nYou never need to call the Heap­Lock<\/code> and\nHeap­Unlock<\/code> functions under normal operation.\nAssuming the heap is serialized\n(which is the default),\nall the standard heap functions like\nHeap­Allocate<\/code> and Heap­Free<\/code>\nwill automatically serialize.\n<\/p>\n

\nIn fact, the way they serialize is by calling\nthe¹ Heap­Lock<\/code> and\nHeap­Unlock<\/code> functions!\n<\/p>\n

\nNearly all heap operations complete in a single call.\nIf your heap is serialized, this means that the heap operation\ntakes the heap lock,\ndoes its work,\nand then releases the heap lock and returns.\nIf all<\/i> heap operations were like this,\nthen there would be no need for\nHeap­Lock<\/code> or\nHeap­Unlock<\/code>.\n<\/p>\n

\nUnfortunately, there is also the\nHeap­Walk<\/code> function,\nwhich does a little bit of work, and then returns\nwith a partial result.\nThe design for Heap­Walk<\/code> is that\nthe application calls the function repeatedly\nuntil it either gets all the results it wants, or gets bored and gives up.\nBut wait, what if the heap changes while the application is\ntrying to walk through it?\nTo prevent that from happening,\nthe program can call\nHeap­Lock<\/code> before starting the enumeration,\nand\nHeap­Unlock<\/code> when it is done.\nDuring the time the heap is locked,\nother threads which attempt to call a\nHeap­Xxx<\/code> function with that same heap\nwill block until the heap is unlocked.\n<\/p>\n

\nThe ability to lock the heap creates a lot of potential for craziness,\nbecause the heap is a high-traffic area.\nAs a result, it is very important that any code which calls\nHeap­Lock<\/code> do very little while the lock is held.\nTake the lock, do your thing, and get out quickly.\n<\/p>\n

\nBut wait, there’s more.\nHolding the heap lock blocks all other threads from\nallocating or freeing memory.\nThis puts the heap lock very low in your lock hierarchy.\nTherefore,\nwhile you hold the heap lock,\nyou cannot block on synchronization objects whose owners might\ntry to access the heap you just locked.\nConsider the following:\n<\/p>\n

\n\/\/ Code in italics is wrong.\nvoid BadIdea()\n{\n HeapLock(GetProcessHeap());\n SendMessage(...);\n HeapUnlock(GetProcessHeap());\n}<\/i>\n<\/pre>\n
\nSending a message is a big deal.\nThe thread that is the target of the message\nmay be waiting for the heap lock,\nand now you’ve created a deadlock.\nYou won’t proceed until that thread processes the message,\nbut that thread can’t process the message until you unlock the heap.\n<\/p>\n
\nYou might accidentally do something wrong while hold the heap lock\nif you happen to trigger a delay-loaded DLL,\nin which case your call into that other DLL turns into a call\nto Load­Library<\/code>, and now you’ve lost control.\nIn practice,\nthe only thing you should be doing while holding the heap lock\nis calling Heap­Walk<\/code> and saving the results\nlocally, and in a way that doesn’t allocate or free memory\non the heap you are walking!\nWait until after you unlock the heap to\nstart studying the results you\ncollected or transfer the raw data into a more suitable data structure.\n<\/p>\n
\nBonus chatter<\/b>\n<\/p>\n
\nNote that if you call\nHeap­Lock<\/code> or Heap­Unlock<\/code>\non a heap that was created without serialization\n(HEAP_NO_SERIALIZATION<\/code>),\nthen the results are undefined.\nThat’s because passing the\nHEAP_NO_SERIALIZATION<\/code> flag means\n“Hey, Heap Manager,\ndon’t bother locking this heap.\nI will take responsibility for ensuring that only one thread\noperates on this heap at a time.”\nIf you later call\nHeap­Lock<\/code> on a no-serialization heap,\nthe heap manager will say,\n“Wha?\nYou said that you<\/i> would take care of serialization, not me!”\n<\/p>\n
\nIt’s like ordering a car and saying,\n“Don’t bother installing door locks.\nI will take responsibility for ensuring the safety of the car.\n(Say, by never letting the car leave a secured facility.)”\nAnd then a month later, calling OnStar and saying,\n“Hi, can you remotely lock my car for me? Thanks.”\nDude, you explicitly opted out of door locks.\n<\/p>\n
\n(Amazingly, I encountered one developer who thought that\ncalling Heap­Lock<\/code> on a no-serialization heap\nwould cause other heap operations on the heap to be blocked,\neven if they passed the\nHEAP_NO_SERIALIZATION<\/code> flag to those operations.\nUm, no, the Heap­Lock<\/code> function cannot lock a\nno-serialization heap because a no-serialization heap doesn’t have\nlock in the first place, at your request<\/i>.)\n<\/p>\n
\nNitpicker’s corner<\/b>\n<\/p>\n
\n¹ s\/the\/the functional equivalents of\/<\/p>\n","protected":false},"excerpt":{"rendered":"
You never need to call the Heap­Lock and Heap­Unlock functions under normal operation. Assuming the heap is serialized (which is the default), all the standard heap functions like Heap­Allocate and Heap­Free will automatically serialize. In fact, the way they serialize is by calling the¹ Heap­Lock and Heap­Unlock functions! Nearly all heap operations complete in a […]<\/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-5703","post","type-post","status-publish","format-standard","has-post-thumbnail","hentry","category-oldnewthing","tag-code"],"acf":[],"blog_post_summary":"
You never need to call the Heap­Lock and Heap­Unlock functions under normal operation. Assuming the heap is serialized (which is the default), all the standard heap functions like Heap­Allocate and Heap­Free will automatically serialize. In fact, the way they serialize is by calling the¹ Heap­Lock and Heap­Unlock functions! Nearly all heap operations complete in a […]<\/p>\n","_links":{"self":[{"href":"https:\/\/devblogs.microsoft.com\/oldnewthing\/wp-json\/wp\/v2\/posts\/5703","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=5703"}],"version-history":[{"count":0,"href":"https:\/\/devblogs.microsoft.com\/oldnewthing\/wp-json\/wp\/v2\/posts\/5703\/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=5703"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/oldnewthing\/wp-json\/wp\/v2\/categories?post=5703"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/oldnewthing\/wp-json\/wp\/v2\/tags?post=5703"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}