{"id":107832,"date":"2023-02-15T07:00:00","date_gmt":"2023-02-15T15:00:00","guid":{"rendered":"https:\/\/devblogs.microsoft.com\/oldnewthing\/?p=107832"},"modified":"2023-02-14T20:44:21","modified_gmt":"2023-02-15T04:44:21","slug":"20230215-00","status":"publish","type":"post","link":"https:\/\/devblogs.microsoft.com\/oldnewthing\/20230215-00\/?p=107832","title":{"rendered":"What are the potentially-erroneous results if you don’t pass NULL as the lpNumberOfBytesRead when issuing overlapped I\/O?"},"content":{"rendered":"

The documentation for many I\/O functions that read or write bytes recommend that you pass NULL<\/code> as the lpNumber\u00adOf\u00adBytes\u00adRead<\/code> parameter when issuing overlapped I\/O to avoid “potentially erroneous results”. What are these potentially erroneous results the documentation is trying to warn against?<\/p>\n

For the purpose of this discussion, let’s use ReadFile<\/code> as our example, even though the same argument applies to Write\u00adFile<\/code>, WSASend<\/code>, and other functions which follow the same pattern.<\/p>\n

The race condition here is a race between the code that calls ReadFile<\/code> and the code that handles the asynchronous completion. If the variable passed as the output for ReadFile<\/code>‘s lpNumber\u00adOf\u00adBytes\u00adRead<\/code> parameter is the same variable used as the output for Get\u00adOverlapped\u00adResult<\/code>‘s lpNumber\u00adOf\u00adBytes\u00adTransferred<\/code> parameter, then there is a race because the completion might run concurrently with the exit out of Read\u00adFile<\/code>.<\/p>\n\n\n\n\n\n\n\n\n\n\n\n\n
Thread 1<\/td>\nThread 2<\/td>\n<\/tr>\n
ReadFile(..., &byteCount, ...);<\/code><\/td>\n <\/td>\n<\/tr>\n
ReadFile<\/code> begins<\/td>\n <\/td>\n<\/tr>\n
\u00a0\u00a0I\/O initiated asynchronously<\/td>\n <\/td>\n<\/tr>\n
\u00a0<\/td>\nI\/O completes asynchronously<\/td>\n<\/tr>\n
\u00a0<\/td>\nGet\u00adOverlapped\u00adResult(..., &byteCount, ...)<\/code><\/td>\n<\/tr>\n
\u00a0<\/td>\nGet\u00adOverlapped\u00adResult<\/code> sets byteCount = result<\/code><\/td>\n<\/tr>\n
\u00a0\u00a0set byteCount = 0<\/code><\/td>\n <\/td>\n<\/tr>\n
\u00a0\u00a0SetLastError(ERROR_IO_PENDING);<\/code><\/td>\n <\/td>\n<\/tr>\n
\u00a0\u00a0return FALSE;<\/code><\/td>\n <\/td>\n<\/tr>\n<\/tbody>\n<\/table>\n

If the I\/O completes very quickly, then the completion routine can run before Read\u00adFile<\/code> returns. And then when Read\u00adFile<\/code> tries to report the fact that the I\/O was initiated asynchronously, it overwrites the byteCount<\/code> that the completion routine had calculated.<\/p>\n

So it’s okay to pass a non-null lpNumberOfBytesRead<\/code> to Read\u00adFile<\/code>, even when issuing asynchronous I\/O, provided that you do so into a different variable from the one that the completion routine uses.<\/p>\n

Normally, however, there’s no reason to pass a non-null lpNumberOfBytesRead<\/code> because the result of the operation is going to be handled by the completion function. But there’s a case where it is advantageous to use a non-null value, and that’s where you have used Set\u00adFile\u00adCompletion\u00adNotification\u00adModes<\/code> to configure the handle as FILE_SKIP_COMPLETION_PORT_ON_SUCCESS<\/code>. In that case, a synchronous completion does not queue a call to the completion function on the I\/O completion thread. Instead, the code that called Read\u00adFile<\/code> is expected to deal with the synchronous completion inline. And one of the things it probably wants to know is how many bytes were read, so it would normally call Get\u00adOverlapped\u00adResult<\/code> to find out. You can avoid that extra call to Get\u00adOverlapped\u00adResult<\/code> by passing a non-null pointer to Read\u00adFile<\/code> so that in the case of a synchronous completion, you have your answer immediately.<\/p>\n

This is admittedly a micro-optimization. One of my colleagues was not aware of this trick and just followed the guidance in the documentation by passing NULL<\/code> and calling Get\u00adOverlapped\u00adResult<\/code>, and he says that his code can still stream data at 100Gbps over the network despite doing things “inefficiently”.<\/p>\n

So maybe you’re better off not knowing and just following the simple rule of “Use NULL<\/code> when issuing asynchronous I\/O.” It’s easier to explain and easier to remember.<\/p>\n","protected":false},"excerpt":{"rendered":"

It’s to avoid a self-inflicted race condition.<\/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-107832","post","type-post","status-publish","format-standard","has-post-thumbnail","hentry","category-oldnewthing","tag-code"],"acf":[],"blog_post_summary":"

It’s to avoid a self-inflicted race condition.<\/p>\n","_links":{"self":[{"href":"https:\/\/devblogs.microsoft.com\/oldnewthing\/wp-json\/wp\/v2\/posts\/107832","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=107832"}],"version-history":[{"count":0,"href":"https:\/\/devblogs.microsoft.com\/oldnewthing\/wp-json\/wp\/v2\/posts\/107832\/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=107832"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/oldnewthing\/wp-json\/wp\/v2\/categories?post=107832"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/oldnewthing\/wp-json\/wp\/v2\/tags?post=107832"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}