{"id":21073,"date":"2008-08-27T10:00:00","date_gmt":"2008-08-27T10:00:00","guid":{"rendered":"https:\/\/blogs.msdn.microsoft.com\/oldnewthing\/2008\/08\/27\/what-possible-use-are-those-extra-bits-in-kernel-handles-part-1-sentinels\/"},"modified":"2008-08-27T10:00:00","modified_gmt":"2008-08-27T10:00:00","slug":"what-possible-use-are-those-extra-bits-in-kernel-handles-part-1-sentinels","status":"publish","type":"post","link":"https:\/\/devblogs.microsoft.com\/oldnewthing\/20080827-00\/?p=21073","title":{"rendered":"What possible use are those extra bits in kernel handles? Part 1: Sentinels"},"content":{"rendered":"

\n\nKernel handles are always a multiple of four<\/A>;\nthe bottom two bits are available for applications to use.\nBut why would an application need those bits anyway?\n<\/P>\n

\nThe short answer is extending the handle namespace<\/I>.\nThe long answer will take a few days to play out.\n(This series was written in response to\n\nIgor Levicki being unable to imagine “how this can save anything\n(in terms of performance)”<\/A>.\nThen again, who said that it had anything to do with performance?\nActually, I’m surprised that my dear readers weren’t familiar\nwith the techniques described in this series.\nPerhaps I shouldn’t have written this series and merely replied,\n“If you can’t think of how this could be useful, then you are not\nmy target audience.”\nOn the other hand, reader Aaargh! believes that\nwhoever thought to make the bottom two bits of handles available to\napplications\n\nshould receive an asswhooping<\/A>.)\n<\/P>\n

\nBut we’ll start with a warm-up.\nIf you need some sentinel values for a HANDLE<\/CODE>,\nyou need to make sure your chosen sentinel value will never\nconflict with a valid HANDLE<\/CODE> value.\nIf you decide that your sentinel value is something like\n<\/P>\n

\n\/\/ code in italics is wrong\n#define DEBUGWINDOW_HANDLE ((HANDLE)0x1234)<\/I>\n<\/PRE>\n
\nthen your program is going to start acting really strange\nif the kernel ever gave you handle value of 0x1234.\nKnowing that kernel handles are always multiples of four\nmeans that you can choose a value that isn’t<\/I>\na multiple of four and use it as your sentinel value.\n
\n#define DEBUGWINDOW_HANDLE ((HANDLE)0x1233)\n<\/PRE>\n
\nSince 0x1233 is not a multiple of four, you can rest assured\nthat no actual kernel handle will have this value,\nand you can write your logging function like this:\n<\/P>\n
\nvoid LogOutput(HANDLE hOutput, LPCVOID pv, DWORD cb)\n{\n if (hOutput == NULL) {\n   \/\/ logging disabled\n } else if (hOutput == DEBUGWINDOW_HANDLE) {\n  AddToDebugWindow(pv, cb);\n } else {\n  DWORD cbWritten;\n  WriteFile(hOutput, pv, cb, NULL, &cbWritten);\n }\n}\n<\/PRE>\n
\nSince you can’t WriteFile<\/CODE> to a window handle,\nyour logging function has to do something special if somebody\ndecided that their output should go to the debug window.\nBut if they chose to log to a normal kernel object (a file,\nthe console, a serial port, whatever) then you can just write\nthe data to that kernel object.\n<\/PRE>\n
\nYou’ve already seen this before; you just didn’t realize it.\nThe special values for INVALID_HANDLE_VALUE<\/CODE> and\nkernel pseudo-handles \n\nsuch as GetCurrentProcess<\/CODE><\/A>\nare not multiples of four for exactly this reason.\n<\/P>\n
\nNow, sure, you could have defined your own LogHandle<\/CODE>\ntype and have all the logging go through that type instead of just\nlogging to HANDLE<\/CODE>s:\n<\/P>\n
\nclass LogHandle {\npublic:\n  static LogHandle *GetDebugLogHandle();\n  BOOL IsDebugWindow();\n  HANDLE GetKernelHandle();\n  static LogHandle *CreateFromKernelHandle(HANDLE KernelHandle);\n  ~LogHandle() { }<\/p>\n
private:\n  LogHandle(BOOL IsDebugWindow, HANDLE KernelHandle);\n  static LogHandle DebugWindow;<\/p>\n
  BOOL IsLogToDebugWindow;\n  HANDLE RegularKernelHandle;\n};\n<\/PRE>\n
\nThroughout, your program would use pointers to\nLogHandle<\/CODE>s instead of actual handles,\nusing functions like these to convert between them:\n<\/P>\n
\n\/\/ Does not take ownership of the handle\nLogHandle::LogHandle(BOOL IsDebugWindow, HANDLE KernelHandle)\n    : IsLogToDebugWindow(IsDebugWindow)\n    , RegularKernelHandle(KernelHandle)\n{\n}<\/p>\n
LogHandle LogHandle::DebugWindow(TRUE, NULL);<\/p>\n
LogHandle* LogHandle::GetDebugWindowLogHandle()\n{\n  return &DebugWindow;\n}<\/p>\n
BOOL LogHandle::IsDebugWindow()\n{\n  return IsLogToDebugWindow;\n}<\/p>\n
HANDLE LogHandle::GetKernelHandle()\n{\n  assert(!IsDebugWindow());\n  return RegularKernelHandle;\n}<\/p>\n
LogHandle *LogHandle::CreateFromKernelHandle(HANDLE KernelHandle)\n{\n  return new LogHandle(FALSE, KernelHandle);\n}\n<\/PRE>\n
\nOr you could make everybody pass two parameters instead of one.\nFor example, a class that went\n<\/P>\n
\nclass SomeObject {\npublic:\n  SomeObject(int SomeParameter, BOOL SomeParameter,\n             HANDLE LogHandle);\n…\nprivate:\n  …\n  HANDLE LogHandle; \/\/ log to this handle\n};\n<\/PRE>\n
\nwould have to change to\n<\/P>\n
\nclass SomeObject {\npublic:\n  SomeObject(int SomeParameter, BOOL SomeParameter,\n             BOOL LogToDebugWindow, HANDLE LogHandle);\n…\nprivate:\n  …\n  BOOL LogToDebugWindow; \/\/ if TRUE, log to window\n  HANDLE LogHandle; \/\/ if not logging to window, then log to here\n};\n<\/PRE>\n
\nEither way is an awful lot of work just to define a sentinel value.\nBut still, at least you can avoid the need for a sentinel value\nby just passing more parameters.\nBut sometimes that option isn’t available.\nWe’ll look at that next time.\n<\/P><\/p>\n","protected":false},"excerpt":{"rendered":"
Kernel handles are always a multiple of four; the bottom two bits are available for applications to use. But why would an application need those bits anyway? The short answer is extending the handle namespace. The long answer will take a few days to play out. (This series was written in response to Igor Levicki […]<\/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-21073","post","type-post","status-publish","format-standard","has-post-thumbnail","hentry","category-oldnewthing","tag-code"],"acf":[],"blog_post_summary":"
Kernel handles are always a multiple of four; the bottom two bits are available for applications to use. But why would an application need those bits anyway? The short answer is extending the handle namespace. The long answer will take a few days to play out. (This series was written in response to Igor Levicki […]<\/p>\n","_links":{"self":[{"href":"https:\/\/devblogs.microsoft.com\/oldnewthing\/wp-json\/wp\/v2\/posts\/21073","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=21073"}],"version-history":[{"count":0,"href":"https:\/\/devblogs.microsoft.com\/oldnewthing\/wp-json\/wp\/v2\/posts\/21073\/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=21073"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/oldnewthing\/wp-json\/wp\/v2\/categories?post=21073"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/oldnewthing\/wp-json\/wp\/v2\/tags?post=21073"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}