{"id":948,"date":"2025-05-05T11:52:42","date_gmt":"2025-05-05T03:52:42","guid":{"rendered":"https:\/\/www.hyy.net\/?p=948"},"modified":"2025-05-05T11:52:42","modified_gmt":"2025-05-05T03:52:42","slug":"c-concurrency-asynchronous-and-multithreaded-programming","status":"publish","type":"post","link":"https:\/\/diji.net\/?p=948","title":{"rendered":"C# Concurrency Asynchronous and multithreaded programming"},"content":{"rendered":"<style>\n  @page {\n    margin-bottom: 5pt;\n    margin-top: 5pt\n    }<\/p>\n<p>.calibre {\n    -ms-text-size-adjust: 100%;\n    -webkit-text-size-adjust: 100%;\n    font-size: 1em\n    }\n.calibre1 {\n    display: block;\n    font-size: 1em;\n    margin-bottom: 0;\n    margin-left: 5pt;\n    margin-right: 5pt;\n    margin-top: 0;\n    padding-left: 0;\n    padding-right: 0\n    }\n.calibre2 {\n    display: block;\n    font-family: Noto Serif, serif;\n    margin-bottom: 80px\n    }\n.calibre3 {\n    display: block\n    }\n.calibre4 {\n    border-bottom-color: currentColor;\n    border-bottom-style: none;\n    border-bottom-width: 0;\n    border-left-color: currentColor;\n    border-left-style: none;\n    border-left-width: 0;\n    border-right-color: currentColor;\n    border-right-style: none;\n    border-right-width: 0;\n    border-top-color: currentColor;\n    border-top-style: none;\n    border-top-width: 0;\n    height: 227px;\n    line-height: 1.4;\n    max-width: 100%;\n    width: 227px\n    }\n.calibre5 {\n    color: #d3002d;\n    font-family: \"Noto serif\", serif;\n    font-size: 1em;\n    text-decoration: underline\n    }\n.calibre6 {\n    border-bottom-color: currentColor;\n    border-bottom-style: none;\n    border-bottom-width: 0;\n    border-left-color: currentColor;\n    border-left-style: none;\n    border-left-width: 0;\n    border-right-color: currentColor;\n    border-right-style: none;\n    border-right-width: 0;\n    border-top-color: currentColor;\n    border-top-style: none;\n    border-top-width: 0;\n    height: auto;\n    line-height: 1.4;\n    max-width: 100%;\n    width: 40px\n    }\n.calibre7 {\n    border-bottom-color: currentColor;\n    border-bottom-style: none;\n    border-bottom-width: 0;\n    border-left-color: currentColor;\n    border-left-style: none;\n    border-left-width: 0;\n    border-right-color: currentColor;\n    border-right-style: none;\n    border-right-width: 0;\n    border-top-color: currentColor;\n    border-top-style: none;\n    border-top-width: 0;\n    height: 71px;\n    margin-bottom: 0;\n    margin-left: auto;\n    margin-right: auto;\n    margin-top: 0;\n    max-width: 100%;\n    padding-bottom: 1.25em;\n    padding-left: 0;\n    padding-right: 0;\n    padding-top: 1.25em;\n    text-align: center;\n    width: 100px\n    }\n.calibre8 {\n    color: #d3002d;\n    font-family: \"Noto serif\", serif;\n    font-size: 1em;\n    line-height: 1.4;\n    text-decoration: underline\n    }\n.calibre9 {\n    -webkit-margin-after: 0;\n    -webkit-margin-before: 0;\n    display: block;\n    line-height: 1.5rem;\n    list-style-image: none;\n    list-style-position: outside;\n    list-style-type: none;\n    margin-bottom: 24px;\n    margin-left: 24px;\n    margin-right: 0;\n    margin-top: 24px;\n    padding-bottom: 0;\n    padding-left: 0;\n    padding-right: 0;\n    padding-top: 0\n    }\n.calibre10 {\n    border-bottom-color: currentColor;\n    border-bottom-style: none;\n    border-bottom-width: 0;\n    border-left-color: currentColor;\n    border-left-style: none;\n    border-left-width: 0;\n    border-right-color: currentColor;\n    border-right-style: none;\n    border-right-width: 0;\n    border-top-color: currentColor;\n    border-top-style: none;\n    border-top-width: 0;\n    height: 282px;\n    line-height: 1.2;\n    max-width: 100%;\n    width: 282px\n    }\n.calibre11 {\n    border-bottom-color: currentColor;\n    border-bottom-style: none;\n    border-bottom-width: 0;\n    border-left-color: currentColor;\n    border-left-style: none;\n    border-left-width: 0;\n    border-right-color: currentColor;\n    border-right-style: none;\n    border-right-width: 0;\n    border-top-color: currentColor;\n    border-top-style: none;\n    border-top-width: 0;\n    height: 532px;\n    line-height: 1.2;\n    max-width: 100%;\n    width: 275px\n    }\n.calibre12 {\n    border-bottom-color: currentColor;\n    border-bottom-style: none;\n    border-bottom-width: 0;\n    border-left-color: currentColor;\n    border-left-style: none;\n    border-left-width: 0;\n    border-right-color: currentColor;\n    border-right-style: none;\n    border-right-width: 0;\n    border-top-color: currentColor;\n    border-top-style: none;\n    border-top-width: 0;\n    height: 886px;\n    line-height: 1.2;\n    max-width: 100%;\n    width: 877px\n    }\n.calibre13 {\n    border-bottom-color: currentColor;\n    border-bottom-style: none;\n    border-bottom-width: 0;\n    border-left-color: currentColor;\n    border-left-style: none;\n    border-left-width: 0;\n    border-right-color: currentColor;\n    border-right-style: none;\n    border-right-width: 0;\n    border-top-color: currentColor;\n    border-top-style: none;\n    border-top-width: 0;\n    height: 767px;\n    line-height: 1.2;\n    max-width: 100%;\n    width: 596px\n    }\n.calibre14 {\n    border-bottom-color: currentColor;\n    border-bottom-style: none;\n    border-bottom-width: 0;\n    border-left-color: currentColor;\n    border-left-style: none;\n    border-left-width: 0;\n    border-right-color: currentColor;\n    border-right-style: none;\n    border-right-width: 0;\n    border-top-color: currentColor;\n    border-top-style: none;\n    border-top-width: 0;\n    height: 741px;\n    line-height: 1.2;\n    max-width: 100%;\n    width: 842px\n    }\n.calibre15 {\n    border-bottom-color: currentColor;\n    border-bottom-style: none;\n    border-bottom-width: 0;\n    border-left-color: currentColor;\n    border-left-style: none;\n    border-left-width: 0;\n    border-right-color: currentColor;\n    border-right-style: none;\n    border-right-width: 0;\n    border-top-color: currentColor;\n    border-top-style: none;\n    border-top-width: 0;\n    height: 509px;\n    line-height: 1.2;\n    max-width: 100%;\n    width: 841px\n    }\n.calibre16 {\n    border-bottom-color: currentColor;\n    border-bottom-style: none;\n    border-bottom-width: 0;\n    border-left-color: currentColor;\n    border-left-style: none;\n    border-left-width: 0;\n    border-right-color: currentColor;\n    border-right-style: none;\n    border-right-width: 0;\n    border-top-color: currentColor;\n    border-top-style: none;\n    border-top-width: 0;\n    height: 777px;\n    line-height: 1.2;\n    max-width: 100%;\n    width: 908px\n    }\n.calibre17 {\n    border-bottom-color: currentColor;\n    border-bottom-style: none;\n    border-bottom-width: 0;\n    border-left-color: currentColor;\n    border-left-style: none;\n    border-left-width: 0;\n    border-right-color: currentColor;\n    border-right-style: none;\n    border-right-width: 0;\n    border-top-color: currentColor;\n    border-top-style: none;\n    border-top-width: 0;\n    height: 703px;\n    line-height: 1.2;\n    max-width: 100%;\n    width: 904px\n    }\n.calibre18 {\n    border-bottom-color: currentColor;\n    border-bottom-style: none;\n    border-bottom-width: 0;\n    border-left-color: currentColor;\n    border-left-style: none;\n    border-left-width: 0;\n    border-right-color: currentColor;\n    border-right-style: none;\n    border-right-width: 0;\n    border-top-color: currentColor;\n    border-top-style: none;\n    border-top-width: 0;\n    height: 438px;\n    line-height: 1.2;\n    max-width: 100%;\n    width: 724px\n    }\n.calibre19 {\n    -webkit-margin-after: 0;\n    -webkit-margin-before: 0;\n    display: block;\n    line-height: 1.5rem;\n    list-style-image: none;\n    list-style-position: outside;\n    list-style-type: none;\n    margin-bottom: 0;\n    margin-left: 24px;\n    margin-right: 0;\n    margin-top: 0;\n    padding-bottom: 0;\n    padding-left: 0;\n    padding-right: 0;\n    padding-top: 0\n    }\n.calibre20 {\n    border-bottom-color: currentColor;\n    border-bottom-style: none;\n    border-bottom-width: 0;\n    border-left-color: currentColor;\n    border-left-style: none;\n    border-left-width: 0;\n    border-right-color: currentColor;\n    border-right-style: none;\n    border-right-width: 0;\n    border-top-color: currentColor;\n    border-top-style: none;\n    border-top-width: 0;\n    height: 446px;\n    line-height: 1.2;\n    max-width: 100%;\n    width: 679px\n    }\n.calibre21 {\n    color: #d3002d;\n    font-family: \"Noto serif\", serif;\n    font-size: 1em;\n    line-height: 1.2;\n    text-decoration: underline\n    }\n.calibre22 {\n    border-bottom-color: currentColor;\n    border-bottom-style: none;\n    border-bottom-width: 0;\n    border-left-color: currentColor;\n    border-left-style: none;\n    border-left-width: 0;\n    border-right-color: currentColor;\n    border-right-style: none;\n    border-right-width: 0;\n    border-top-color: currentColor;\n    border-top-style: none;\n    border-top-width: 0;\n    height: 546px;\n    line-height: 1.2;\n    max-width: 100%;\n    width: 722px\n    }\n.calibre23 {\n    border-bottom-color: currentColor;\n    border-bottom-style: none;\n    border-bottom-width: 0;\n    border-left-color: currentColor;\n    border-left-style: none;\n    border-left-width: 0;\n    border-right-color: currentColor;\n    border-right-style: none;\n    border-right-width: 0;\n    border-top-color: currentColor;\n    border-top-style: none;\n    border-top-width: 0;\n    height: 302px;\n    line-height: 1.2;\n    max-width: 100%;\n    width: 750px\n    }\n.calibre24 {\n    border-bottom-color: currentColor;\n    border-bottom-style: none;\n    border-bottom-width: 0;\n    border-left-color: currentColor;\n    border-left-style: none;\n    border-left-width: 0;\n    border-right-color: currentColor;\n    border-right-style: none;\n    border-right-width: 0;\n    border-top-color: currentColor;\n    border-top-style: none;\n    border-top-width: 0;\n    height: 436px;\n    line-height: 1.2;\n    max-width: 100%;\n    width: 788px\n    }\n.calibre25 {\n    border-bottom-color: currentColor;\n    border-bottom-style: none;\n    border-bottom-width: 0;\n    border-left-color: currentColor;\n    border-left-style: none;\n    border-left-width: 0;\n    border-right-color: currentColor;\n    border-right-style: none;\n    border-right-width: 0;\n    border-top-color: currentColor;\n    border-top-style: none;\n    border-top-width: 0;\n    height: 453px;\n    line-height: 1.2;\n    max-width: 100%;\n    width: 666px\n    }\n.calibre26 {\n    border-bottom-color: currentColor;\n    border-bottom-style: none;\n    border-bottom-width: 0;\n    border-left-color: currentColor;\n    border-left-style: none;\n    border-left-width: 0;\n    border-right-color: currentColor;\n    border-right-style: none;\n    border-right-width: 0;\n    border-top-color: currentColor;\n    border-top-style: none;\n    border-top-width: 0;\n    height: 455px;\n    line-height: 1.2;\n    max-width: 100%;\n    width: 647px\n    }\n.calibre27 {\n    border-bottom-color: currentColor;\n    border-bottom-style: none;\n    border-bottom-width: 0;\n    border-left-color: currentColor;\n    border-left-style: none;\n    border-left-width: 0;\n    border-right-color: currentColor;\n    border-right-style: none;\n    border-right-width: 0;\n    border-top-color: currentColor;\n    border-top-style: none;\n    border-top-width: 0;\n    height: 421px;\n    line-height: 1.2;\n    max-width: 100%;\n    width: 379px\n    }\n.calibre28 {\n    border-bottom-color: currentColor;\n    border-bottom-style: none;\n    border-bottom-width: 0;\n    border-left-color: currentColor;\n    border-left-style: none;\n    border-left-width: 0;\n    border-right-color: currentColor;\n    border-right-style: none;\n    border-right-width: 0;\n    border-top-color: currentColor;\n    border-top-style: none;\n    border-top-width: 0;\n    height: 565px;\n    line-height: 1.2;\n    max-width: 100%;\n    width: 788px\n    }\n.calibre29 {\n    border-bottom-color: currentColor;\n    border-bottom-style: none;\n    border-bottom-width: 0;\n    border-left-color: currentColor;\n    border-left-style: none;\n    border-left-width: 0;\n    border-right-color: currentColor;\n    border-right-style: none;\n    border-right-width: 0;\n    border-top-color: currentColor;\n    border-top-style: none;\n    border-top-width: 0;\n    height: 94px;\n    line-height: 1.2;\n    max-width: 100%;\n    width: 782px\n    }\n.calibre30 {\n    border-bottom-color: currentColor;\n    border-bottom-style: none;\n    border-bottom-width: 0;\n    border-left-color: currentColor;\n    border-left-style: none;\n    border-left-width: 0;\n    border-right-color: currentColor;\n    border-right-style: none;\n    border-right-width: 0;\n    border-top-color: currentColor;\n    border-top-style: none;\n    border-top-width: 0;\n    height: 92px;\n    line-height: 1.2;\n    max-width: 100%;\n    width: 782px\n    }\n.calibre31 {\n    border-bottom-color: currentColor;\n    border-bottom-style: none;\n    border-bottom-width: 0;\n    border-left-color: currentColor;\n    border-left-style: none;\n    border-left-width: 0;\n    border-right-color: currentColor;\n    border-right-style: none;\n    border-right-width: 0;\n    border-top-color: currentColor;\n    border-top-style: none;\n    border-top-width: 0;\n    height: 19px;\n    line-height: 1.2;\n    max-width: 100%;\n    width: 198px\n    }\n.calibre32 {\n    border-bottom-color: currentColor;\n    border-bottom-style: none;\n    border-bottom-width: 0;\n    border-left-color: currentColor;\n    border-left-style: none;\n    border-left-width: 0;\n    border-right-color: currentColor;\n    border-right-style: none;\n    border-right-width: 0;\n    border-top-color: currentColor;\n    border-top-style: none;\n    border-top-width: 0;\n    height: 66px;\n    line-height: 1.2;\n    max-width: 100%;\n    width: 353px\n    }\n.calibre33 {\n    border-bottom-color: currentColor;\n    border-bottom-style: none;\n    border-bottom-width: 0;\n    border-left-color: currentColor;\n    border-left-style: none;\n    border-left-width: 0;\n    border-right-color: currentColor;\n    border-right-style: none;\n    border-right-width: 0;\n    border-top-color: currentColor;\n    border-top-style: none;\n    border-top-width: 0;\n    height: 101px;\n    line-height: 1.2;\n    max-width: 100%;\n    width: 346px\n    }\n.calibre34 {\n    border-bottom-color: currentColor;\n    border-bottom-style: none;\n    border-bottom-width: 0;\n    border-left-color: currentColor;\n    border-left-style: none;\n    border-left-width: 0;\n    border-right-color: currentColor;\n    border-right-style: none;\n    border-right-width: 0;\n    border-top-color: currentColor;\n    border-top-style: none;\n    border-top-width: 0;\n    height: 131px;\n    line-height: 1.2;\n    max-width: 100%;\n    width: 348px\n    }\n.calibre35 {\n    border-bottom-color: currentColor;\n    border-bottom-style: none;\n    border-bottom-width: 0;\n    border-left-color: currentColor;\n    border-left-style: none;\n    border-left-width: 0;\n    border-right-color: currentColor;\n    border-right-style: none;\n    border-right-width: 0;\n    border-top-color: currentColor;\n    border-top-style: none;\n    border-top-width: 0;\n    height: 310px;\n    line-height: 1.2;\n    max-width: 100%;\n    width: 788px\n    }\n.co-summary-bullet {\n    -moz-hyphens: auto;\n    -webkit-hyphens: auto;\n    color: #005;\n    display: list-item;\n    font-family: \"Noto serif\", serif;\n    font-size: 1em;\n    font-weight: 400;\n    hyphens: auto;\n    line-height: 1.75;\n    list-style-image: none;\n    list-style-position: outside;\n    list-style-type: disc;\n    margin-bottom: 0;\n    margin-left: 0;\n    margin-right: 0;\n    margin-top: 0;\n    page-break-inside: avoid;\n    text-align: left\n    }\n.contenttable-0-col {\n    display: table-column\n    }\n.contenttable-0-colgroup {\n    display: table-column-group\n    }\n.contenttable-1-table {\n    background-color: #fff;\n    border-bottom-color: currentColor;\n    border-bottom-style: none;\n    border-bottom-width: 0;\n    border-collapse: collapse;\n    border-left-color: currentColor;\n    border-left-style: none;\n    border-left-width: 0;\n    border-right-color: currentColor;\n    border-right-style: none;\n    border-right-width: 0;\n    border-spacing: 0;\n    border-top-color: currentColor;\n    border-top-style: none;\n    border-top-width: 0;\n    display: block;\n    font-size: 1em;\n    line-height: 1.4;\n    margin-bottom: 24px;\n    margin-left: 0;\n    margin-right: 0;\n    margin-top: 0;\n    max-width: 100%;\n    overflow: auto;\n    padding-bottom: 0;\n    padding-left: 0;\n    padding-right: 0;\n    padding-top: 0;\n    page-break-inside: avoid;\n    text-align: left;\n    text-indent: 0;\n    width: 100%\n    }\n.contenttable-1-td {\n    -webkit-margin-after: 0;\n    -webkit-margin-before: 0;\n    border-bottom-color: currentColor;\n    border-bottom-style: none;\n    border-bottom-width: 0;\n    border-left-color: currentColor;\n    border-left-style: none;\n    border-left-width: 0;\n    border-right-color: currentColor;\n    border-right-style: none;\n    border-right-width: 0;\n    border-top-color: currentColor;\n    border-top-style: none;\n    border-top-width: 0;\n    display: table-cell;\n    font-family: \"Noto serif\", serif;\n    font-size: 1em;\n    font-weight: 400;\n    line-height: 1.75;\n    margin-bottom: 0;\n    margin-left: 0;\n    margin-right: 0;\n    margin-top: 0;\n    overflow-wrap: break-word;\n    padding-bottom: 0.875em;\n    padding-left: 0.875em;\n    padding-right: 0.875em;\n    padding-top: 0.875em;\n    text-align: left;\n    vertical-align: top;\n    word-wrap: break-word\n    }\n.contenttable-1-th {\n    -webkit-margin-after: 0;\n    -webkit-margin-before: 0;\n    background-color: #e7f0f9;\n    border-bottom-color: currentColor;\n    border-bottom-style: none;\n    border-bottom-width: 0;\n    border-left-color: currentColor;\n    border-left-style: none;\n    border-left-width: 0;\n    border-right-color: currentColor;\n    border-right-style: none;\n    border-right-width: 0;\n    border-top-color: currentColor;\n    border-top-style: none;\n    border-top-width: 0;\n    display: table-cell;\n    font-family: \"Noto serif\", serif;\n    font-size: 1em;\n    font-style: normal;\n    font-weight: bold;\n    line-height: 1.75;\n    margin-bottom: 0;\n    margin-left: 0;\n    margin-right: 0;\n    margin-top: 0;\n    padding-bottom: 0.875em;\n    padding-left: 0.875em;\n    padding-right: 0.875em;\n    padding-top: 0.875em;\n    text-align: left;\n    vertical-align: middle\n    }\n.contenttable-1-thead {\n    background-color: #EEF2F6;\n    border-bottom-color: currentColor;\n    border-bottom-style: none;\n    border-bottom-width: 0;\n    border-left-color: currentColor;\n    border-left-style: none;\n    border-left-width: 0;\n    border-right-color: currentColor;\n    border-right-style: none;\n    border-right-width: 0;\n    border-top-color: currentColor;\n    border-top-style: none;\n    border-top-width: 0;\n    display: table-row-group;\n    font-family: \"Noto serif\", serif;\n    font-size: 1em;\n    font-weight: bold;\n    line-height: 1.75;\n    padding-bottom: 0.875em;\n    padding-left: 0.875em;\n    padding-right: 0.875em;\n    padding-top: 0.875em;\n    vertical-align: middle\n    }\n.contenttable-1-thead1 {\n    display: table-row-group;\n    vertical-align: middle\n    }\n.contenttable-c-col {\n    display: table-column;\n    line-height: 1.4\n    }\n.contenttable-c-colgroup {\n    display: table-column-group;\n    line-height: 1.4\n    }\n.contenttable-c-table {\n    background-color: #fff;\n    border-bottom-color: currentColor;\n    border-bottom-style: none;\n    border-bottom-width: 0;\n    border-collapse: collapse;\n    border-left-color: currentColor;\n    border-left-style: none;\n    border-left-width: 0;\n    border-right-color: currentColor;\n    border-right-style: none;\n    border-right-width: 0;\n    border-spacing: 0;\n    border-top-color: currentColor;\n    border-top-style: none;\n    border-top-width: 0;\n    display: block;\n    font-size: 1em;\n    line-height: 1.4;\n    margin-bottom: 24px;\n    margin-left: 0;\n    margin-right: 0;\n    margin-top: 0;\n    max-width: 100%;\n    overflow: auto;\n    padding-bottom: 0;\n    padding-left: 0;\n    padding-right: 0;\n    padding-top: 0;\n    text-align: left;\n    text-indent: 0;\n    vertical-align: top;\n    width: 100%\n    }\n.contenttable-c-tbody {\n    display: table-row-group;\n    line-height: 1.4;\n    vertical-align: middle\n    }\n.contenttable-c-td {\n    -webkit-margin-after: 0;\n    -webkit-margin-before: 0;\n    border-bottom-color: currentColor;\n    border-bottom-style: none;\n    border-bottom-width: 0;\n    border-left-color: currentColor;\n    border-left-style: none;\n    border-left-width: 0;\n    border-right-color: currentColor;\n    border-right-style: none;\n    border-right-width: 0;\n    border-top-color: currentColor;\n    border-top-style: none;\n    border-top-width: 0;\n    display: table-cell;\n    font-family: \"Noto serif\", serif;\n    font-size: 1em;\n    font-weight: 400;\n    line-height: 1.75;\n    margin-bottom: 0;\n    margin-left: 0;\n    margin-right: 0;\n    margin-top: 0;\n    overflow-wrap: break-word;\n    padding-bottom: 0.875em;\n    padding-left: 0.875em;\n    padding-right: 0.875em;\n    padding-top: 0.875em;\n    text-align: inherit;\n    vertical-align: inherit;\n    word-wrap: break-word\n    }\n.contenttable-c-tr {\n    border-bottom-color: currentColor;\n    border-bottom-style: none;\n    border-bottom-width: 0;\n    border-left-color: currentColor;\n    border-left-style: none;\n    border-left-width: 0;\n    border-right-color: currentColor;\n    border-right-style: none;\n    border-right-width: 0;\n    border-top-color: currentColor;\n    border-top-style: none;\n    border-top-width: 0;\n    display: table-row;\n    vertical-align: inherit\n    }\n.contenttable-c-tr1 {\n    background-color: #EEF2F6;\n    border-bottom-color: currentColor;\n    border-bottom-style: none;\n    border-bottom-width: 0;\n    border-left-color: currentColor;\n    border-left-style: none;\n    border-left-width: 0;\n    border-right-color: currentColor;\n    border-right-style: none;\n    border-right-width: 0;\n    border-top-color: currentColor;\n    border-top-style: none;\n    border-top-width: 0;\n    display: table-row;\n    vertical-align: inherit\n    }\n.copyrighta {\n    background-color: transparent;\n    border-bottom-color: currentColor;\n    border-bottom-style: none;\n    border-bottom-width: medium;\n    border-left-color: currentColor;\n    border-left-style: none;\n    border-left-width: medium;\n    border-right-color: currentColor;\n    border-right-style: none;\n    border-right-width: medium;\n    border-top-color: currentColor;\n    border-top-style: none;\n    border-top-width: medium;\n    color: #3d3b49;\n    display: block;\n    font-family: \"Noto Serif\", serif;\n    font-size: 1.83333em;\n    font-style: normal;\n    font-weight: 100;\n    line-height: 1.5;\n    margin-bottom: 32px;\n    margin-left: 0;\n    margin-right: 0;\n    margin-top: 0;\n    padding-bottom: 0;\n    padding-left: 0;\n    padding-right: 0;\n    padding-top: 0;\n    text-align: left;\n    word-wrap: break-word\n    }\n.copyrightb {\n    -moz-hyphens: auto;\n    -webkit-hyphens: auto;\n    -webkit-margin-after: 0;\n    -webkit-margin-before: 0;\n    color: unset;\n    display: block;\n    font-family: \"Noto serif\", serif;\n    font-size: 1em;\n    font-variant: small-caps;\n    font-weight: 400;\n    hyphens: auto;\n    line-height: 1.75;\n    margin-bottom: 24px;\n    margin-left: 0;\n    margin-right: 0;\n    margin-top: 0;\n    padding-bottom: 0;\n    padding-left: 0;\n    padding-right: 0;\n    padding-top: 0;\n    text-align: left;\n    text-indent: unset\n    }\n.copyrightbody {\n    -moz-hyphens: auto;\n    -webkit-hyphens: auto;\n    -webkit-margin-after: 0;\n    -webkit-margin-before: 0;\n    color: unset;\n    display: block;\n    font-family: \"Noto serif\", serif;\n    font-size: 1em;\n    font-weight: 400;\n    hyphens: auto;\n    line-height: 1.75;\n    margin-bottom: 24px;\n    margin-left: 0;\n    margin-right: 0;\n    margin-top: 0;\n    padding-bottom: 0;\n    padding-left: 0;\n    padding-right: 0;\n    padding-top: 0;\n    text-align: left;\n    text-indent: unset\n    }\n.copyrightfiguresb {\n    -moz-hyphens: auto;\n    -webkit-hyphens: auto;\n    -webkit-margin-after: 0;\n    -webkit-margin-before: 0;\n    color: unset;\n    display: block;\n    font-family: \"Noto serif\", serif;\n    font-size: 1em;\n    font-weight: 400;\n    hyphens: auto;\n    line-height: 1.75;\n    margin-bottom: 0;\n    margin-left: 0;\n    margin-right: 0;\n    margin-top: 0;\n    overflow-wrap: break-word;\n    padding-bottom: 0;\n    padding-left: 0;\n    padding-right: 0;\n    padding-top: 0;\n    text-align: left;\n    text-indent: unset;\n    word-wrap: break-word\n    }\n.figure {\n    -webkit-margin-after: 0;\n    -webkit-margin-before: 0;\n    background-color: inherit;\n    border-bottom-color: currentColor;\n    border-bottom-style: none;\n    border-bottom-width: medium;\n    border-left-color: currentColor;\n    border-left-style: none;\n    border-left-width: medium;\n    border-right-color: currentColor;\n    border-right-style: none;\n    border-right-width: medium;\n    border-top-color: currentColor;\n    border-top-style: none;\n    border-top-width: medium;\n    display: block;\n    line-height: 1.5rem;\n    margin-bottom: 32px;\n    margin-left: 0;\n    margin-right: 0;\n    margin-top: 32px;\n    padding-bottom: 0;\n    padding-left: 0;\n    padding-right: 0;\n    padding-top: 0;\n    page-break-inside: avoid\n    }\n.figure1 {\n    -moz-hyphens: auto;\n    -webkit-hyphens: auto;\n    -webkit-margin-after: 0;\n    -webkit-margin-before: 0;\n    color: unset;\n    display: block;\n    font-family: \"Noto serif\", serif;\n    font-size: 0.75em;\n    font-weight: 400;\n    hyphens: auto;\n    line-height: 1.2;\n    margin-bottom: 24px;\n    margin-left: 0;\n    margin-right: 0;\n    margin-top: 0;\n    padding-bottom: 0;\n    padding-left: 0;\n    padding-right: 0;\n    padding-top: 0.5em;\n    text-align: left;\n    text-indent: unset\n    }\n.fm-bold {\n    font-weight: Bold\n    }\n.fm-code-continuation-arrow {\n    color: #b2b2b2;\n    font-family: monospace\n    }\n.fm-code-in-text {\n    -webkit-margin-after: 0;\n    -webkit-margin-before: 0;\n    background-color: #EEF2F6;\n    font-family: \"Consolas\", Courier, monospace;\n    font-size: 1em;\n    font-style: inherit;\n    font-weight: normal;\n    line-height: 1.5;\n    margin-bottom: 0;\n    margin-left: 0;\n    margin-right: 0;\n    margin-top: 0;\n    padding-bottom: 0.25em;\n    padding-left: 0.25em;\n    padding-right: 0.25em;\n    padding-top: 0.375em\n    }\n.fm-code-in-text1 {\n    -webkit-margin-after: 0;\n    -webkit-margin-before: 0;\n    background-color: #EEF2F6;\n    color: #3d3b49;\n    font-family: \"Consolas\", Courier, monospace;\n    font-size: 1em;\n    font-style: inherit;\n    font-weight: normal;\n    line-height: 1.5;\n    margin-bottom: 0;\n    margin-left: 0;\n    margin-right: 0;\n    margin-top: 0;\n    padding-bottom: 0.25em;\n    padding-left: 0.25em;\n    padding-right: 0.25em;\n    padding-top: 0.375em\n    }\n.fm-code-in-text2 {\n    -webkit-margin-after: 0;\n    -webkit-margin-before: 0;\n    background-color: #fff;\n    font-family: \"Consolas\", Courier, monospace;\n    font-size: 1em;\n    font-style: inherit;\n    font-weight: normal;\n    line-height: 1.5;\n    margin-bottom: 0;\n    margin-left: 0;\n    margin-right: 0;\n    margin-top: 0;\n    padding-bottom: 0.25em;\n    padding-left: 0.25em;\n    padding-right: 0.25em;\n    padding-top: 0.375em\n    }\n.fm-code-listing-caption {\n    -moz-hyphens: auto;\n    -webkit-hyphens: auto;\n    -webkit-margin-after: 0;\n    -webkit-margin-before: 0;\n    background-color: #005;\n    color: #EAEAEA;\n    display: block;\n    font-family: \"Noto serif\", serif;\n    font-size: 1em;\n    font-weight: 400;\n    hyphens: auto;\n    line-height: 1.75;\n    margin-bottom: 24px;\n    margin-left: 0;\n    margin-right: 0;\n    margin-top: 0;\n    padding-bottom: 0;\n    padding-left: 0;\n    padding-right: 0;\n    padding-top: 0;\n    text-align: left;\n    text-indent: unset\n    }\n.fm-code-listing-captione {\n    -moz-hyphens: auto;\n    -webkit-hyphens: auto;\n    -webkit-margin-after: 0;\n    -webkit-margin-before: 0;\n    background-color: #005;\n    color: unset;\n    display: block;\n    font-family: \"Noto serif\", serif;\n    font-size: 1em;\n    font-weight: 400;\n    hyphens: auto;\n    line-height: 1.75;\n    margin-bottom: 24px;\n    margin-left: 0;\n    margin-right: 0;\n    margin-top: 0;\n    padding-bottom: 0;\n    padding-left: 0;\n    padding-right: 0;\n    padding-top: 0;\n    text-align: left;\n    text-indent: unset\n    }\n.fm-combinumeral {\n    color: #005;\n    font-family: \"Cambria Math\", sans-serif;\n    font-size: 1em;\n    line-height: 1.4\n    }\n.fm-head {\n    -webkit-margin-after: 0;\n    -webkit-margin-before: 0;\n    background-color: transparent;\n    border-bottom-color: currentColor;\n    border-bottom-style: none;\n    border-bottom-width: medium;\n    border-left-color: currentColor;\n    border-left-style: none;\n    border-left-width: medium;\n    border-right-color: currentColor;\n    border-right-style: none;\n    border-right-width: medium;\n    border-top-color: currentColor;\n    border-top-style: none;\n    border-top-width: medium;\n    color: #3d3b49;\n    display: block;\n    font-family: \"Noto Serif\", serif;\n    font-size: 1.29167em;\n    font-style: normal;\n    font-weight: bold;\n    line-height: 1.5;\n    margin-bottom: 24px;\n    margin-left: 0;\n    margin-right: 0;\n    margin-top: 0;\n    padding-bottom: 0;\n    padding-left: 0;\n    padding-right: 0;\n    padding-top: 0;\n    text-indent: -3em;\n    word-wrap: break-word\n    }\n.fm-head-2toc {\n    -moz-hyphens: auto;\n    -webkit-hyphens: auto;\n    -webkit-margin-after: 0;\n    -webkit-margin-before: 0;\n    color: unset;\n    display: block;\n    font-family: \"Noto serif\", serif;\n    font-size: 1em;\n    font-style: italic;\n    font-weight: 400;\n    hyphens: auto;\n    line-height: 1.75;\n    margin-bottom: 24px;\n    margin-left: 0;\n    margin-right: 0;\n    margin-top: 0;\n    padding-bottom: 0;\n    padding-left: 0;\n    padding-right: 0;\n    padding-top: 0;\n    text-align: left;\n    text-indent: unset\n    }\n.fm-italics {\n    font-style: Italic;\n    text-transform: none\n    }\n.fm-list-bullet {\n    -moz-hyphens: auto;\n    -webkit-hyphens: auto;\n    display: list-item;\n    font-family: \"Noto serif\", serif;\n    font-size: 1em;\n    font-weight: 400;\n    hyphens: auto;\n    line-height: 1.75;\n    list-style-image: none;\n    list-style-position: outside;\n    list-style-type: disc;\n    margin-bottom: 0;\n    margin-left: 0;\n    margin-right: 0;\n    margin-top: 0;\n    page-break-inside: avoid;\n    text-align: left\n    }\n.fm-list-bullet1 {\n    -moz-hyphens: auto;\n    -webkit-hyphens: auto;\n    display: list-item;\n    font-family: \"Noto serif\", serif;\n    font-size: 1em;\n    font-weight: 400;\n    hyphens: auto;\n    line-height: 1.75;\n    list-style-image: none;\n    list-style-position: outside;\n    list-style-type: decimal;\n    margin-bottom: 0;\n    margin-left: 0;\n    margin-right: 0;\n    margin-top: 0;\n    page-break-inside: avoid;\n    text-align: left\n    }\n.fm-list-bullet2 {\n    -moz-hyphens: auto;\n    -webkit-hyphens: auto;\n    color: black;\n    display: list-item;\n    font-family: \"Noto serif\", serif;\n    font-size: 1em;\n    font-weight: 400;\n    hyphens: auto;\n    line-height: 1.75;\n    list-style-image: none;\n    list-style-position: outside;\n    list-style-type: disc;\n    margin-bottom: 0;\n    margin-left: 0;\n    margin-right: 0;\n    margin-top: 0;\n    text-align: left\n    }\n.fm-part-initial-cap {\n    color: #476b84;\n    font-family: \"Verdana\", sans-serif;\n    font-size: 2em;\n    line-height: 1.4\n    }\n.fm-quote {\n    -moz-hyphens: auto;\n    -webkit-hyphens: auto;\n    -webkit-margin-after: 0;\n    -webkit-margin-before: 0;\n    color: unset;\n    display: block;\n    font-family: \"Noto serif\", serif;\n    font-size: 1em;\n    font-style: Italic;\n    font-weight: 400;\n    hyphens: auto;\n    line-height: 1.75;\n    margin-bottom: 24px;\n    margin-left: 0;\n    margin-right: 0;\n    margin-top: 0;\n    padding-bottom: 0;\n    padding-left: 0;\n    padding-right: 0;\n    padding-top: 0;\n    text-align: left;\n    text-indent: unset\n    }\n.fm-sidebar-block {\n    -webkit-margin-after: 0;\n    -webkit-margin-before: 0;\n    background-color: inherit;\n    border-bottom-style: solid;\n    border-left-style: solid;\n    border-radius: 12px 12px 12px 12px;\n    border-right-style: solid;\n    border-top-style: solid;\n    bottom: 25px;\n    color: #8fb1d0;\n    display: block;\n    left: 25px;\n    line-height: 1.5rem;\n    margin-bottom: 0;\n    margin-left: 0;\n    margin-right: 0;\n    margin-top: 0;\n    padding-bottom: 0;\n    padding-left: 0;\n    padding-right: 0;\n    padding-top: 0;\n    right: 25px;\n    top: 35px\n    }\n.fm-sidebar-title {\n    -moz-hyphens: auto;\n    -webkit-hyphens: auto;\n    -webkit-margin-after: 0;\n    -webkit-margin-before: 0;\n    border-bottom-color: currentColor;\n    border-bottom-style: none;\n    border-bottom-width: 0;\n    border-left-color: currentColor;\n    border-left-style: none;\n    border-left-width: 0;\n    border-right-color: currentColor;\n    border-right-style: none;\n    border-right-width: 0;\n    border-top-color: currentColor;\n    border-top-style: none;\n    border-top-width: 0;\n    color: unset;\n    display: block;\n    font-family: \"Noto serif\", serif;\n    font-size: 1em;\n    font-weight: 400;\n    hyphens: auto;\n    line-height: 1.75;\n    margin-bottom: 24px;\n    margin-left: 0;\n    margin-right: 0;\n    margin-top: 0;\n    padding-bottom: 0;\n    padding-left: 0;\n    padding-right: 0;\n    padding-top: 0;\n    text-align: left;\n    text-indent: unset;\n    vertical-align: top;\n    z-index: 1\n    }\n.list {\n    -moz-hyphens: auto;\n    -webkit-hyphens: auto;\n    -webkit-margin-after: 0;\n    -webkit-margin-before: 0;\n    color: unset;\n    display: block;\n    font-family: \"Noto serif\", serif;\n    font-size: 1em;\n    font-weight: 400;\n    hyphens: auto;\n    line-height: 1.75;\n    margin-bottom: 0;\n    margin-left: 0;\n    margin-right: 0;\n    margin-top: 0;\n    padding-bottom: 0;\n    padding-left: 0;\n    padding-right: 0;\n    padding-top: 0;\n    page-break-inside: avoid;\n    text-align: left;\n    text-indent: unset\n    }\n.mc-small-caps {\n    color: #005;\n    font-family: \"Arial\", sans-serif;\n    font-size: 1em;\n    font-variant: small-caps;\n    font-weight: Bold\n    }\n.programlisting {\n    -webkit-hyphens: none;\n    -webkit-margin-after: 0;\n    -webkit-margin-before: 0;\n    background-color: #EEF2F6;\n    border-radius: 8px 8px 8px 8px;\n    bottom: 25px;\n    color: #3D3B49;\n    display: block;\n    font-family: \"Consolas\", Courier, monospace;\n    font-size: 1em;\n    left: 25px;\n    line-height: 1.5;\n    margin-bottom: 24px;\n    margin-left: 0;\n    margin-right: 0;\n    margin-top: 24px;\n    overflow-x: auto;\n    overflow-y: hidden;\n    padding-bottom: 0.75em;\n    padding-left: 1.5em;\n    padding-right: 1.5em;\n    padding-top: 0.75em;\n    right: 25px;\n    text-indent: 0;\n    top: 25px;\n    white-space: pre;\n    word-break: keep-all;\n    word-wrap: initial;\n    z-index: 1\n    }\n.segoe {\n    font-family: \"Segoe UI Symbol\", sans-serif\n    }\n.pcalibre:link {\n    color: #d3002d;\n    font-family: \"Noto serif\", serif;\n    font-size: inherit;\n    text-decoration: underline\n    }\n.pcalibre1:visited {\n    color: #d3002d;\n    font-family: \"Noto serif\", serif;\n    font-size: inherit;\n    text-decoration: underline\n    }\n.pcalibre2:focus {\n    color: #9f0027;\n    font-size: inherit;\n    text-decoration-line: underline;\n    text-decoration-style: solid\n    }\n.pcalibre3:hover {\n    color: #9f0027;\n    font-size: inherit;\n    text-decoration-line: underline;\n    text-decoration-style: solid\n    }<\/p>\n<\/style>\n<h1 class=\"copyrighta\" id=\"calibre_link-307\">C# Concurrency<\/h1>\n<p class=\"copyrightb\">Asynchronous and multithreaded programming<\/p>\n<p class=\"copyrightbody\">&nbsp;<\/p>\n<p class=\"copyrightbody\"><a id=\"calibre_link-308\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a>Nir Dobovizki<\/p>\n<p class=\"copyrightbody\">\u00a92025 by Manning Publications Co. All rights reserved.<\/p>\n<div class=\"calibre1\" id=\"calibre_link-2\">\n<div id=\"calibre_link-312\" class=\"calibre2\">\n<div id=\"calibre_link-313\" class=\"calibre3\">\n<h1 class=\"copyrighta\" id=\"calibre_link-314\">dedication<\/h1>\n<p class=\"fm-quote\">To my wonderful wife, Analia<\/p>\n<\/div>\n<\/div>\n<\/div>\n<div class=\"calibre1\" id=\"calibre_link-3\">\n<div id=\"calibre_link-315\" class=\"calibre2\">\n<div id=\"calibre_link-316\" class=\"calibre3\">\n<h1 class=\"copyrighta\" id=\"calibre_link-317\">contents<\/h1>\n<p class=\"fm-head-2toc\">&nbsp;&nbsp;<\/p>\n<p class=\"fm-head-2toc\">&nbsp;&nbsp; &nbsp; &nbsp;&nbsp;<a class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\" href=\"\/#calibre_link-4\">Front matter<\/a><\/p>\n<p class=\"copyrightbody\"><a class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\" href=\"\/#calibre_link-5\">preface<\/a><\/p>\n<p class=\"copyrightbody\"><a class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\" href=\"\/#calibre_link-6\">acknowledgments<\/a><\/p>\n<p class=\"copyrightbody\"><a class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\" href=\"\/#calibre_link-7\">about this book<\/a><\/p>\n<p class=\"copyrightbody\"><a class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\" href=\"\/#calibre_link-8\">about the author<\/a><\/p>\n<p class=\"copyrightbody\"><a class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\" href=\"\/#calibre_link-9\">about the cover illustration<\/a><\/p>\n<p class=\"fm-head-2toc\">&nbsp;&nbsp;<\/p>\n<p class=\"copyrightbody\">Part 1. &nbsp;<a class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\" href=\"\/#calibre_link-10\">Asynchronous programming and multithreading basics<\/a><\/p>\n<p class=\"fm-head-2toc\">&nbsp;&nbsp;1&nbsp;&nbsp; <a class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\" href=\"\/#calibre_link-11\">Asynchronous programming and multithreading<\/a><\/p>\n<p class=\"copyrightbody\">&nbsp;&nbsp;1.1&nbsp;&nbsp; <a class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\" href=\"\/#calibre_link-12\">What is multithreading?<\/a><\/p>\n<p class=\"copyrightbody\">&nbsp;&nbsp;1.2&nbsp;&nbsp; <a class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\" href=\"\/#calibre_link-13\">Introducing multicore CPUs<\/a><\/p>\n<p class=\"copyrightbody\">&nbsp;&nbsp;1.3&nbsp;&nbsp; <a class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\" href=\"\/#calibre_link-14\">Asynchronous programming<\/a><\/p>\n<p class=\"copyrightbody\">&nbsp;&nbsp;1.4&nbsp;&nbsp; <a class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\" href=\"\/#calibre_link-15\">Using multithreading and asynchronous programming together<\/a><\/p>\n<p class=\"copyrightbody\">&nbsp;&nbsp;1.5&nbsp;&nbsp; <a class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\" href=\"\/#calibre_link-16\">Software efficiency and cloud computing<\/a><\/p>\n<p class=\"fm-head-2toc\">&nbsp;&nbsp;2&nbsp;&nbsp; <a class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\" href=\"\/#calibre_link-17\">The compiler rewrites your code<\/a><\/p>\n<p class=\"copyrightbody\">&nbsp;&nbsp;2.1&nbsp;&nbsp; <a class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\" href=\"\/#calibre_link-18\">Lambda functions<\/a><\/p>\n<p class=\"copyrightbody\">&nbsp;&nbsp;2.2&nbsp;&nbsp; <a class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\" href=\"\/#calibre_link-19\">Yield return<\/a><\/p>\n<p class=\"fm-head-2toc\">&nbsp;&nbsp;3&nbsp;&nbsp; <a class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\" href=\"\/#calibre_link-20\">The async and await keywords<\/a><\/p>\n<p class=\"copyrightbody\">&nbsp;&nbsp;3.1&nbsp;&nbsp; <a class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\" href=\"\/#calibre_link-21\">Asynchronous code complexity<\/a><\/p>\n<p class=\"copyrightbody\">&nbsp;&nbsp;3.2&nbsp;&nbsp; <a class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\" href=\"\/#calibre_link-22\">Introducing Task and Task&lt;T&gt;<\/a><\/p>\n<p class=\"fm-head-2toc\"><a class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\" href=\"\/#calibre_link-23\">Are we there yet?<\/a><\/p>\n<p class=\"fm-head-2toc\"><a class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\" href=\"\/#calibre_link-24\">Wake me up when we get there<\/a><\/p>\n<p class=\"fm-head-2toc\"><a class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\" href=\"\/#calibre_link-25\">The synchronous option<\/a><\/p>\n<p class=\"fm-head-2toc\"><a class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\" href=\"\/#calibre_link-26\">After the task has completed<\/a><\/p>\n<p class=\"copyrightbody\">&nbsp;&nbsp;3.3&nbsp;&nbsp; <a class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\" href=\"\/#calibre_link-27\">How does async\/await work?<\/a><\/p>\n<p class=\"copyrightbody\">&nbsp;&nbsp;3.4&nbsp;&nbsp; <a class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\" href=\"\/#calibre_link-28\">async void methods<\/a><\/p>\n<p class=\"copyrightbody\">&nbsp;&nbsp;3.5&nbsp;&nbsp; <a class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\" href=\"\/#calibre_link-29\">ValueTask and ValueTask&lt;T&gt;<\/a><\/p>\n<p class=\"copyrightbody\">&nbsp;&nbsp;3.6&nbsp;&nbsp; <a class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\" href=\"\/#calibre_link-30\">What about multithreading?<\/a><\/p>\n<p class=\"fm-head-2toc\">&nbsp;&nbsp;4&nbsp;&nbsp; <a class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\" href=\"\/#calibre_link-31\">Multithreading basics<\/a><\/p>\n<p class=\"copyrightbody\">&nbsp;&nbsp;4.1&nbsp;&nbsp; <a class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\" href=\"\/#calibre_link-32\">Different ways to run in another thread<\/a><\/p>\n<p class=\"fm-head-2toc\"><a class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\" href=\"\/#calibre_link-33\">Thread.Start<\/a><\/p>\n<p class=\"fm-head-2toc\"><a class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\" href=\"\/#calibre_link-34\">The thread pool<\/a><\/p>\n<p class=\"fm-head-2toc\"><a class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\" href=\"\/#calibre_link-35\">Task.Run<\/a><\/p>\n<p class=\"copyrightbody\">&nbsp;&nbsp;4.2&nbsp;&nbsp; <a class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\" href=\"\/#calibre_link-36\">Accessing the same variables from multiple threads<\/a><\/p>\n<p class=\"fm-head-2toc\"><a class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\" href=\"\/#calibre_link-37\">No shared data<\/a><\/p>\n<p class=\"fm-head-2toc\"><a class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\" href=\"\/#calibre_link-38\">Immutable shared data<\/a><\/p>\n<p class=\"fm-head-2toc\"><a class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\" href=\"\/#calibre_link-39\">Locks and mutexes<\/a><\/p>\n<p class=\"fm-head-2toc\"><a class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\" href=\"\/#calibre_link-40\">Deadlocks<\/a><\/p>\n<p class=\"copyrightbody\">&nbsp;&nbsp;4.3&nbsp;&nbsp; <a class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\" href=\"\/#calibre_link-41\">Special considerations for native UI apps<\/a><\/p>\n<p class=\"copyrightbody\">&nbsp;&nbsp;4.4&nbsp;&nbsp; <a class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\" href=\"\/#calibre_link-42\">Waiting for another thread<\/a><\/p>\n<p class=\"copyrightbody\">&nbsp;&nbsp;4.5&nbsp;&nbsp; <a class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\" href=\"\/#calibre_link-43\">Other synchronization methods<\/a><\/p>\n<p class=\"copyrightbody\">&nbsp;&nbsp;4.6&nbsp;&nbsp; <a class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\" href=\"\/#calibre_link-44\">Thread settings<\/a><\/p>\n<p class=\"fm-head-2toc\"><a class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\" href=\"\/#calibre_link-45\">Thread background status<\/a><\/p>\n<p class=\"fm-head-2toc\"><a class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\" href=\"\/#calibre_link-46\">Language and locale<\/a><\/p>\n<p class=\"fm-head-2toc\"><a class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\" href=\"\/#calibre_link-47\">COM Apartment<\/a><\/p>\n<p class=\"fm-head-2toc\"><a class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\" href=\"\/#calibre_link-48\">Current user<\/a><\/p>\n<p class=\"fm-head-2toc\"><a class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\" href=\"\/#calibre_link-49\">Thread priority<\/a><\/p>\n<p class=\"fm-head-2toc\">&nbsp;&nbsp;5&nbsp;&nbsp; <a class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\" href=\"\/#calibre_link-50\">async\/await and multithreading<\/a><\/p>\n<p class=\"copyrightbody\">&nbsp;&nbsp;5.1&nbsp;&nbsp; <a class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\" href=\"\/#calibre_link-51\">Asynchronous programming and multithreading<\/a><\/p>\n<p class=\"copyrightbody\">&nbsp;&nbsp;5.2&nbsp;&nbsp; <a class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\" href=\"\/#calibre_link-52\">Where does code run after await?<\/a><\/p>\n<p class=\"copyrightbody\">&nbsp;&nbsp;5.3&nbsp;&nbsp; <a class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\" href=\"\/#calibre_link-53\">Locks and async\/await<\/a><\/p>\n<p class=\"copyrightbody\">&nbsp;&nbsp;5.4&nbsp;&nbsp; <a class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\" href=\"\/#calibre_link-54\">UI threads<\/a><\/p>\n<p class=\"fm-head-2toc\">&nbsp;&nbsp;6&nbsp;&nbsp; <a class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\" href=\"\/#calibre_link-55\">When to use async\/await<\/a><\/p>\n<p class=\"copyrightbody\">&nbsp;&nbsp;6.1&nbsp;&nbsp; <a class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\" href=\"\/#calibre_link-56\">Asynchronous benefits on servers<\/a><\/p>\n<p class=\"copyrightbody\">&nbsp;&nbsp;6.2&nbsp;&nbsp; <a class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\" href=\"\/#calibre_link-57\">Asynchronous benefits on native client applications<\/a><\/p>\n<p class=\"copyrightbody\">&nbsp;&nbsp;6.3&nbsp;&nbsp; <a class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\" href=\"\/#calibre_link-58\">The downside of async\/await<\/a><\/p>\n<p class=\"fm-head-2toc\"><a class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\" href=\"\/#calibre_link-59\">Asynchronous programming is contagious<\/a><\/p>\n<p class=\"fm-head-2toc\"><a class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\" href=\"\/#calibre_link-60\">Asynchronous programming has more edge cases<\/a><\/p>\n<p class=\"fm-head-2toc\"><a class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\" href=\"\/#calibre_link-61\">Multithreading has even more edge cases<\/a><\/p>\n<p class=\"fm-head-2toc\"><a class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\" href=\"\/#calibre_link-62\">async\/await is expensive<\/a><\/p>\n<p class=\"copyrightbody\">&nbsp;&nbsp;6.4&nbsp;&nbsp; <a class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\" href=\"\/#calibre_link-63\">When to use async await<\/a><\/p>\n<p class=\"fm-head-2toc\">&nbsp;&nbsp;7&nbsp;&nbsp; <a class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\" href=\"\/#calibre_link-64\">Classic multithreading pitfalls and how to avoid them<\/a><\/p>\n<p class=\"copyrightbody\">&nbsp;&nbsp;7.1&nbsp;&nbsp; <a class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\" href=\"\/#calibre_link-65\">Partial updates<\/a><\/p>\n<p class=\"copyrightbody\">&nbsp;&nbsp;7.2&nbsp;&nbsp; <a class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\" href=\"\/#calibre_link-66\">Memory access reordering<\/a><\/p>\n<p class=\"copyrightbody\">&nbsp;&nbsp;7.3&nbsp;&nbsp; <a class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\" href=\"\/#calibre_link-67\">Deadlocks<\/a><\/p>\n<p class=\"copyrightbody\">&nbsp;&nbsp;7.4&nbsp;&nbsp; <a class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\" href=\"\/#calibre_link-68\">Race conditions<\/a><\/p>\n<p class=\"copyrightbody\">&nbsp;&nbsp;7.5&nbsp;&nbsp; <a class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\" href=\"\/#calibre_link-69\">Synchronization<\/a><\/p>\n<p class=\"copyrightbody\">&nbsp;&nbsp;7.6&nbsp;&nbsp; <a class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\" href=\"\/#calibre_link-70\">Starvation<\/a><\/p>\n<p class=\"copyrightbody\">Part 2. &nbsp;<a class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\" href=\"\/#calibre_link-71\">Advanced uses of async\/await and multithreading<\/a><\/p>\n<p class=\"fm-head-2toc\">&nbsp;&nbsp;8&nbsp;&nbsp; <a class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\" href=\"\/#calibre_link-72\">Processing a sequence of items in the background<\/a><\/p>\n<p class=\"copyrightbody\">&nbsp;&nbsp;8.1&nbsp;&nbsp; <a class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\" href=\"\/#calibre_link-73\">Processing items in parallel<\/a><\/p>\n<p class=\"fm-head-2toc\"><a class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\" href=\"\/#calibre_link-74\">Processing items in parallel with the Thread class<\/a><\/p>\n<p class=\"fm-head-2toc\"><a class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\" href=\"\/#calibre_link-75\">Processing items in parallel with the thread pool<\/a><\/p>\n<p class=\"fm-head-2toc\"><a class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\" href=\"\/#calibre_link-76\">Asynchronously processing items in parallel<\/a><\/p>\n<p class=\"fm-head-2toc\"><a class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\" href=\"\/#calibre_link-77\">The Parallel class<\/a><\/p>\n<p class=\"copyrightbody\">&nbsp;&nbsp;8.2&nbsp;&nbsp; <a class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\" href=\"\/#calibre_link-78\">Processing items sequentially in the background<\/a><\/p>\n<p class=\"fm-head-2toc\"><a class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\" href=\"\/#calibre_link-79\">Processing items sequentially in the background with the Thread class<\/a><\/p>\n<p class=\"fm-head-2toc\"><a class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\" href=\"\/#calibre_link-80\">The work queue pattern and BlockingCollection<\/a><\/p>\n<p class=\"fm-head-2toc\"><a class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\" href=\"\/#calibre_link-81\">Processing important items with persistent queues<\/a><\/p>\n<p class=\"fm-head-2toc\">&nbsp;&nbsp;9&nbsp;&nbsp; <a class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\" href=\"\/#calibre_link-82\">Canceling background tasks<\/a><\/p>\n<p class=\"copyrightbody\">&nbsp;&nbsp;9.1&nbsp;&nbsp; <a class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\" href=\"\/#calibre_link-83\">Introducing CancellationToken<\/a><\/p>\n<p class=\"copyrightbody\">&nbsp;&nbsp;9.2&nbsp;&nbsp; <a class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\" href=\"\/#calibre_link-84\">Canceling using an exception<\/a><\/p>\n<p class=\"copyrightbody\">&nbsp;&nbsp;9.3&nbsp;&nbsp; <a class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\" href=\"\/#calibre_link-85\">Getting a callback when the caller cancels our operation<\/a><\/p>\n<p class=\"copyrightbody\">&nbsp;&nbsp;9.4&nbsp;&nbsp; <a class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\" href=\"\/#calibre_link-86\">Implementing timeouts<\/a><\/p>\n<p class=\"copyrightbody\">&nbsp;&nbsp;9.5&nbsp;&nbsp; <a class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\" href=\"\/#calibre_link-87\">Combining cancellation methods<\/a><\/p>\n<p class=\"copyrightbody\">&nbsp;&nbsp;9.6&nbsp;&nbsp; <a class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\" href=\"\/#calibre_link-88\">Special cancellation tokens<\/a><\/p>\n<p class=\"fm-head-2toc\">10&nbsp;&nbsp; <a class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\" href=\"\/#calibre_link-89\">Await your own events<\/a><\/p>\n<p class=\"copyrightbody\">10.1&nbsp;&nbsp; <a class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\" href=\"\/#calibre_link-90\">Introducing TaskCompletionSource<\/a><\/p>\n<p class=\"copyrightbody\">10.2&nbsp;&nbsp; <a class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\" href=\"\/#calibre_link-91\">Choosing where continuations run<\/a><\/p>\n<p class=\"copyrightbody\">10.3&nbsp;&nbsp; <a class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\" href=\"\/#calibre_link-92\">Example: Waiting for initialization<\/a><\/p>\n<p class=\"copyrightbody\">10.4&nbsp;&nbsp; <a class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\" href=\"\/#calibre_link-93\">Example: Adapting old APIs<\/a><\/p>\n<p class=\"copyrightbody\">10.5&nbsp;&nbsp; <a class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\" href=\"\/#calibre_link-94\">Old-style asynchronous operations (BeginXXX, EndXXX)<\/a><\/p>\n<p class=\"copyrightbody\">10.6&nbsp;&nbsp; <a class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\" href=\"\/#calibre_link-95\">Example: Asynchronous data structures<\/a><\/p>\n<p class=\"fm-head-2toc\">11&nbsp;&nbsp; <a class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\" href=\"\/#calibre_link-96\">Controlling on which thread your asynchronous code runs<\/a><\/p>\n<p class=\"copyrightbody\">11.1&nbsp;&nbsp; <a class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\" href=\"\/#calibre_link-97\">await-threading behavior<\/a><\/p>\n<p class=\"fm-head-2toc\"><a class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\" href=\"\/#calibre_link-98\">await in UI threads<\/a><\/p>\n<p class=\"fm-head-2toc\"><a class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\" href=\"\/#calibre_link-99\">await in non-UI threads<\/a><\/p>\n<p class=\"copyrightbody\">11.2&nbsp;&nbsp; <a class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\" href=\"\/#calibre_link-100\">Synchronization contexts<\/a><\/p>\n<p class=\"copyrightbody\">11.3&nbsp;&nbsp; <a class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\" href=\"\/#calibre_link-101\">Breaking away&mdash;ConfigureAwait(false)<\/a><\/p>\n<p class=\"copyrightbody\">11.4&nbsp;&nbsp; <a class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\" href=\"\/#calibre_link-102\">More ConfigureAwait options<\/a><\/p>\n<p class=\"copyrightbody\">11.5&nbsp;&nbsp; <a class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\" href=\"\/#calibre_link-103\">Letting other code run: Task.Yield<\/a><\/p>\n<p class=\"copyrightbody\">11.6&nbsp;&nbsp; <a class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\" href=\"\/#calibre_link-104\">Task schedulers<\/a><\/p>\n<p class=\"fm-head-2toc\">12&nbsp;&nbsp; <a class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\" href=\"\/#calibre_link-105\">Exceptions and async\/await<\/a><\/p>\n<p class=\"copyrightbody\">12.1&nbsp;&nbsp; <a class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\" href=\"\/#calibre_link-106\">Exceptions and asynchronous code<\/a><\/p>\n<p class=\"copyrightbody\">12.2&nbsp;&nbsp; <a class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\" href=\"\/#calibre_link-107\">await and AggregateException<\/a><\/p>\n<p class=\"copyrightbody\">12.3&nbsp;&nbsp; <a class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\" href=\"\/#calibre_link-108\">The case of the lost exception<\/a><\/p>\n<p class=\"copyrightbody\">12.4&nbsp;&nbsp; <a class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\" href=\"\/#calibre_link-109\">Exceptions and async void methods<\/a><\/p>\n<p class=\"fm-head-2toc\">13&nbsp;&nbsp; <a class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\" href=\"\/#calibre_link-110\">Thread-safe collections<\/a><\/p>\n<p class=\"copyrightbody\">13.1&nbsp;&nbsp; <a class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\" href=\"\/#calibre_link-111\">The problems with using regular collections<\/a><\/p>\n<p class=\"copyrightbody\">13.2&nbsp;&nbsp; <a class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\" href=\"\/#calibre_link-112\">The concurrent collections<\/a><\/p>\n<p class=\"fm-head-2toc\"><a class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\" href=\"\/#calibre_link-113\">ConcurrentDictionary&lt;TKey,TValue&gt;<\/a><\/p>\n<p class=\"fm-head-2toc\"><a class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\" href=\"\/#calibre_link-114\">BlockingCollection&lt;T&gt;<\/a><\/p>\n<p class=\"fm-head-2toc\"><a class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\" href=\"\/#calibre_link-115\">Async alternatives for BlockingCollection<\/a><\/p>\n<p class=\"fm-head-2toc\"><a class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\" href=\"\/#calibre_link-116\">ConcurrentQueue&lt;T&gt; and ConcurrentStack&lt;T&gt;<\/a><\/p>\n<p class=\"fm-head-2toc\"><a class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\" href=\"\/#calibre_link-117\">ConcurrentBag&lt;T&gt;<\/a><\/p>\n<p class=\"fm-head-2toc\"><a class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\" href=\"\/#calibre_link-118\">When to use the concurrent collections<\/a><\/p>\n<p class=\"fm-head-2toc\"><a class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\" href=\"\/#calibre_link-119\">When not to use the concurrent collections<\/a><\/p>\n<p class=\"copyrightbody\">13.3&nbsp;&nbsp; <a class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\" href=\"\/#calibre_link-120\">The immutable collections<\/a><\/p>\n<p class=\"fm-head-2toc\"><a class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\" href=\"\/#calibre_link-121\">How immutable collections work<\/a><\/p>\n<p class=\"fm-head-2toc\"><a class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\" href=\"\/#calibre_link-122\">How to use the immutable collections<\/a><\/p>\n<p class=\"fm-head-2toc\"><a class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\" href=\"\/#calibre_link-123\">ImmutableInterlocked<\/a><\/p>\n<p class=\"fm-head-2toc\"><a class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\" href=\"\/#calibre_link-124\">ImmutableDictionary&lt;TKey,TValue&gt;<\/a><\/p>\n<p class=\"fm-head-2toc\"><a class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\" href=\"\/#calibre_link-125\">ImmutableHashSet&lt;T&gt; and ImmutableSortedSet&lt;T&gt;<\/a><\/p>\n<p class=\"fm-head-2toc\"><a class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\" href=\"\/#calibre_link-126\">ImmutableList&lt;T&gt;<\/a><\/p>\n<p class=\"fm-head-2toc\"><a class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\" href=\"\/#calibre_link-127\">ImmutableQueue&lt;T&gt; and ImmutableStack&lt;T&gt;<\/a><\/p>\n<p class=\"fm-head-2toc\"><a class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\" href=\"\/#calibre_link-128\">ImmutableArray&lt;T&gt;<\/a><\/p>\n<p class=\"fm-head-2toc\"><a class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\" href=\"\/#calibre_link-129\">When to use the immutable collections<\/a><\/p>\n<p class=\"copyrightbody\">13.4&nbsp;&nbsp; <a class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\" href=\"\/#calibre_link-130\">The frozen collections<\/a><\/p>\n<p class=\"fm-head-2toc\"><a class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\" href=\"\/#calibre_link-131\">When to use the frozen collections<\/a><\/p>\n<p class=\"fm-head-2toc\">14&nbsp;&nbsp; <a class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\" href=\"\/#calibre_link-132\">Generating collections asynchronously\/await foreach and IAsyncEnumerable<\/a><\/p>\n<p class=\"copyrightbody\">14.1&nbsp;&nbsp; <a class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\" href=\"\/#calibre_link-133\">Iterating over an asynchronous collection<\/a><\/p>\n<p class=\"copyrightbody\">14.2&nbsp;&nbsp; <a class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\" href=\"\/#calibre_link-134\">Generating an asynchronous collection<\/a><\/p>\n<p class=\"copyrightbody\">14.3&nbsp;&nbsp; <a class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\" href=\"\/#calibre_link-135\">Canceling an asynchronous collection<\/a><\/p>\n<p class=\"copyrightbody\">14.4&nbsp;&nbsp; <a class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\" href=\"\/#calibre_link-136\">Other options<\/a><\/p>\n<p class=\"copyrightbody\">14.5&nbsp;&nbsp; <a class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\" href=\"\/#calibre_link-137\">IAsyncEnumerable&lt;T&gt; and LINQ<\/a><\/p>\n<p class=\"copyrightbody\">14.6&nbsp;&nbsp; <a class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\" href=\"\/#calibre_link-138\">Example: Iterating over asynchronously retrieved data<\/a><\/p>\n<p class=\"copyrightbody\">14.7&nbsp;&nbsp; <a class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\" href=\"\/#calibre_link-139\">Example: BlockingCollection&lt;T&gt;-like asynchronous queue<\/a><\/p>\n<p class=\"fm-head-2toc\">&nbsp;&nbsp;<\/p>\n<p class=\"fm-head-2toc\">&nbsp;&nbsp; &nbsp; &nbsp;&nbsp;<a class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\" href=\"\/#calibre_link-140\">index<\/a><\/p>\n<\/div>\n<\/div>\n<\/div>\n<div class=\"calibre1\" id=\"calibre_link-4\">\n<div id=\"calibre_link-318\" class=\"calibre2\">\n<div id=\"calibre_link-319\" class=\"calibre3\">\n<h1 class=\"copyrighta\" id=\"calibre_link-320\">front matter<\/h1>\n<h2 class=\"fm-head\" id=\"calibre_link-5\">preface<\/h2>\n<p class=\"copyrightbody\">I\u2019ve been a software developer for over 30 years now and have been developing high-performance servers using multithreading and asynchronous programming since the late 1990s. I\u2019ve been using C# since 2003. For the last decade and a bit, I\u2019ve worked as a consultant, coming into a project for a short period of time and helping solve a specific problem. Over that decade, I\u2019ve had the privilege of visiting many companies, and I\u2019ve gotten to see and help with a lot of projects.<\/p>\n<p class=\"copyrightbody\">While every project is obviously completely different, with each company inventing its own innovative, disruptive, and one-of-a-kind technology, after you encounter enough projects, you start to see some similarities. And one thing I\u2019ve seen time and time again are problems arising from incorrect usage of multithreading and asynchronous programming.<\/p>\n<p class=\"copyrightbody\">Multithreading is a straightforward concept: it involves running multiple tasks simultaneously. It is notoriously difficult to get it right, but despite this difficulty, it has been widely used for a long time. Developers like you, who take the time to study multithreading through books, are able to use it effectively.<\/p>\n<p class=\"copyrightbody\">Asynchronous programming has existed since the invention of the microprocessor and has long been used in high-performance servers. However, it gained wider popularity among average developers when the <code class=\"fm-code-in-text\">async\/<a class=\"pcalibre2 pcalibre pcalibre3 pcalibre1 calibre8\" id=\"calibre_link-321\"><\/a>await<\/code> feature was introduced in C# in 2012. (It was introduced in JavaScript earlier, but in a limited way.) Based on my observations of various projects and my experience conducting job interviews, I\u2019ve found that very few people understand how <code class=\"fm-code-in-text\">async\/await<\/code> works.<\/p>\n<p class=\"copyrightbody\">The problems arising from a lack of knowledge in multithreading and asynchronous programming are quite apparent. In just the month or so that I discussed publishing this book with Manning, I taught multithreading and <code class=\"fm-code-in-text\">async\/await<\/code> at three different companies.<\/p>\n<p class=\"copyrightbody\">And this is how this book was born. What followed was a little more than two years of very deep diving into multithreading and asynchronous programming in C#. During this time, I\u2019ve learned a lot. There is truly no better way to learn something than teaching it, and I hope this book will be at least as beneficial to you as writing it was to me.<\/p>\n<h2 class=\"fm-head\" id=\"calibre_link-6\">acknowledgments<\/h2>\n<p class=\"copyrightbody\">I truly believe this is a very good book, but I didn\u2019t write it alone. Writing a book is a team effort, and it takes an enormous amount of work by many people. Without all those people, this book wouldn\u2019t be as good and, most likely, it wouldn\u2019t exist at all.<\/p>\n<p class=\"copyrightbody\">First, I want to thank my development editor at Manning, Doug Rudder, who had the patience to teach this first-time author how to write a technical book. Associate publisher Mike Stephens, who agreed to publish my idea of a book, helped with support and feedback. Using a food analogy in the first chapter was his idea. And technical editor Paul Grebenc was the first line of defense against technical mistakes. Paul is a Principal Software Developer at OpenText.&nbsp;He has over 25 years of professional experience in software development, working primarily with C# and Java.&nbsp;His primary interests are systems involving multithreading, asynchronous programming, and networking.<\/p>\n<p class=\"copyrightbody\">Next, I also want to thank all the reviewers who reviewed drafts of this book and everyone who commented while the book was in MEAP: your comments have been invaluable to improving the book. To all the reviewers&mdash;Aldo Biondo, Alexandre Santos Costa, Allan Tabilog, Amrah Umudlu, Andriy Stosyk, Barry Wallis, Chriss Barnard, David Paccoud, Dustin Metzgar, Geert Van Laethem, Jason Down, Jason Hales, Jean-Paul Malherbe, Jeff Shergalis, Jeremy Caney, Jim Welch, Ji\u0159\u00ed \u010cin\u010dura, Joe Cuevas, Jonathan Blair, Jort Rodenburg, Jose Antonio Martinez, Julien Pohie, Krishna Chaitanya Anipindi, Marek Petak, Mark Elston, Markus Wolff, Mikkel Arentoft, Milorad Imbra, Oliver Korten, Onofrei George, Sachin Handiekar, Simon Seyag, Stefan Turalski, Sumit Singh, and Vincent Delcoigne&mdash;your suggestions helped make this book better.<\/p>\n<p class=\"copyrightbody\">I also want to give my personal thanks to everyone who bought the book while in early access. Seeing that people are interested enough to spend their hard-earned money on a book I wrote is a wonderful feeling, and it was an important part of the motivation to complete the book.<\/p>\n<p class=\"copyrightbody\">And last, but most important, I want to thank my family, and especially my wife, who put up with all my nonsense in general and, in particular, with me spending a lot of our free time in my office writing.<\/p>\n<h2 class=\"fm-head\" id=\"calibre_link-7\">about this book<\/h2>\n<p class=\"copyrightbody\">This book is designed to help C# developers write safe and efficient multithreaded and asynchronous application code. It focuses on practical techniques and features you are likely to encounter in normal day-to-day software development.<\/p>\n<p class=\"copyrightbody\">It delves into all the details you need to know to write and debug multithreaded and asynchronous code. It leaves out the exotic, fun techniques that are only applicable if you need to build something like your own database server, but that are too complicated for normal application code and will probably get you into trouble if you try to use them in normal code, because normal multithreading is difficult enough as it is.<\/p>\n<h3 class=\"fm-head\" id=\"calibre_link-322\">Who should read this book<\/h3>\n<p class=\"copyrightbody\">This book is for any C# developer who wants to improve their knowledge of multithreading and asynchronous programming. The information in this book is applicable to any version of .NET, .NET Core, and .NET Framework released since 2012 and to both Windows and Linux (obviously only for .NET Core and .NET 5 and later, since earlier versions do not support Linux).<\/p>\n<p class=\"copyrightbody\">The book focuses more on backend development but also covers what you need to know to write UI applications.<\/p>\n<h3 class=\"fm-head\" id=\"calibre_link-323\">How this book is organized: A road map<\/h3>\n<p class=\"copyrightbody\">This book has two parts that include 14 chapters.<\/p>\n<p class=\"copyrightbody\">Part 1 covers the basics of multithreading and <code class=\"fm-code-in-text\">async<\/code>\/<code class=\"fm-code-in-text\">await<\/code> in C#:<\/p>\n<ul class=\"calibre9\">\n<li class=\"fm-list-bullet\">\n<p class=\"list\">Chapter 1 introduces the concepts and terminology of multithreading and asynchronous programming.<\/p>\n<\/li>\n<li class=\"fm-list-bullet\">\n<p class=\"list\">Chapter 2 covers the techniques that the .NET compiler uses to implement advanced functionality.<\/p>\n<\/li>\n<li class=\"fm-list-bullet\">\n<p class=\"list\">Chapter 3 is a deep dive into how <code class=\"fm-code-in-text\">async<\/code>\/<code class=\"fm-code-in-text\">await<\/code> works.<\/p>\n<\/li>\n<li class=\"fm-list-bullet\">\n<p class=\"list\">Chapter 4 explains multithreading.<\/p>\n<\/li>\n<li class=\"fm-list-bullet\">\n<p class=\"list\">Chapter 5 ties chapters 3 and 4 together and shows how <code class=\"fm-code-in-text\">async<\/code>\/<code class=\"fm-code-in-text\">await<\/code> interacts with multithreading.<\/p>\n<\/li>\n<li class=\"fm-list-bullet\">\n<p class=\"list\">Chapter 6 talks about when you should use <code class=\"fm-code-in-text\">async<\/code>\/<code class=\"fm-code-in-text\">await<\/code>&mdash;just because you can use it doesn\u2019t mean you should use it everywhere.<\/p>\n<\/li>\n<li class=\"fm-list-bullet\">\n<p class=\"list\">Chapter 7 closes the first part with information about the common multithreading pitfalls, and more importantly, what you have to do to avoid them.<\/p>\n<\/li>\n<\/ul>\n<p class=\"copyrightbody\">Part 2 is about how to use the information you learned about in part 1:<\/p>\n<ul class=\"calibre9\">\n<li class=\"fm-list-bullet\">\n<p class=\"list\">Chapter 8 is about processing data in the background.<\/p>\n<\/li>\n<li class=\"fm-list-bullet\">\n<p class=\"list\">Chapter 9 is about stopping background processing.<\/p>\n<\/li>\n<li class=\"fm-list-bullet\">\n<p class=\"list\">Chapter 10 teaches how to build advanced asynchronous components that do more than just combine built-in asynchronous operations.<\/p>\n<\/li>\n<li class=\"fm-list-bullet\">\n<p class=\"list\">Chapter 11 discusses advanced use cases of <code class=\"fm-code-in-text\">async<\/code>\/<code class=\"fm-code-in-text\">await<\/code> and threading.<\/p>\n<\/li>\n<li class=\"fm-list-bullet\">\n<p class=\"list\">Chapter 12 helps you debug a problem with exceptions in asynchronous code.<\/p>\n<\/li>\n<li class=\"fm-list-bullet\">\n<p class=\"list\">Chapter 13 goes over thread-safe collections.<\/p>\n<\/li>\n<li class=\"fm-list-bullet\">\n<p class=\"list\">Chapter 14 shows how you can build things that work like asynchronous collections yourself.<\/p>\n<\/li>\n<\/ul>\n<h3 class=\"fm-head\" id=\"calibre_link-324\">About the code<\/h3>\n<p class=\"copyrightbody\">This book contains many examples of source code both in numbered listings and in line with normal text. In both cases, source code is formatted in a <code class=\"fm-code-in-text\">fixed-width<\/code> <code class=\"fm-code-in-text\">font like<\/code> <code class=\"fm-code-in-text\">this<\/code> to separate it from ordinary text. Sometimes code is also <b class=\"fm-bold\"><code class=\"fm-code-in-text\">in<\/code> <code class=\"fm-code-in-text\">bold<\/code><\/b> to highlight code that has changed from previous steps in the chapter, such as when a new feature adds to an existing line of code.<\/p>\n<p class=\"copyrightbody\">In many cases, the original source code has been reformatted; we\u2019ve added line breaks and reworked indentation to accommodate the available page space in the book. In rare cases, even this was not enough, and listings include line-continuation markers (<span class=\"fm-code-continuation-arrow\">\u27a5<\/span>). Additionally, comments in the source code have often been removed from the listings when the code is described in the text. Code annotations accompany many of the listings, highlighting important concepts.<\/p>\n<p class=\"copyrightbody\">You can get executable snippets of code from the liveBook (online) version of this book at <a class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\" href=\"https:\/\/livebook.manning.com\/book\/csharp-concurrency\">https:\/\/livebook.manning.com\/book\/csharp-concurrency<\/a>.<\/p>\n<p class=\"copyrightbody\">Source code for the examples in this book is available for download from <a class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\" href=\"https:\/\/github.com\/nirdobovizki\/AsynchronousAndMultithreadedProgrammingInCSharp\">https:\/\/github.com\/nirdobovizki\/AsynchronousAndMultithreadedProgrammingInCSharp<\/a> and the author web site at <a class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\" href=\"https:\/\/nirdobovizki.com\">https:\/\/nirdobovizki.com<\/a>. The complete code for the examples in the book is also available for download from the Manning website at <a class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\" href=\"https:\/\/www.manning.com\/books\/csharp-concurrency\">https:\/\/www.manning.com\/books\/csharp-concurrency<\/a>.<\/p>\n<h3 class=\"fm-head\" id=\"calibre_link-325\">liveBook discussion forum<\/h3>\n<p class=\"copyrightbody\">Purchase of <i class=\"fm-italics\">C# Concurrency<\/i> includes free access to liveBook, Manning\u2019s online reading platform. Using liveBook\u2019s exclusive discussion features, you can attach comments to the book globally or to specific sections or paragraphs. It\u2019s a snap to make notes for yourself, ask and answer technical questions, and receive help from the author and other users. To access the f<a id=\"calibre_link-326\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a>orum, go to <a class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\" href=\"https:\/\/livebook.manning.com\/book\/csharp-concurrency\/discussion\">https:\/\/livebook.manning.com\/book\/csharp-concurrency\/discussion<\/a>. You can also learn more about Manning\u2019s forums and the rules of conduct at <a class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\" href=\"https:\/\/livebook.manning.com\/discussion\">https:\/\/livebook.manning.com\/discussion<\/a>.<\/p>\n<p class=\"copyrightbody\">Manning\u2019s commitment to our readers is to provide a venue where a meaningful dialogue between individual readers and between readers and the author can take place. It is not a commitment to any specific amount of participation on the part of the author, whose contribution to the forum remains voluntary (and unpaid). We suggest you try asking the author some challenging questions lest his interest stray! The forum and the archives of previous discussions will be accessible from the publisher\u2019s website as long as the book is in print.<\/p>\n<h2 class=\"fm-head\" id=\"calibre_link-8\">about the author<\/h2>\n<div class=\"figure\">\n<p class=\"figure1\"><img decoding=\"async\" alt=\"\" class=\"calibre10\" src=\"\/images\/CSConcurrency_Asynchronous\/000024.jpg\" \/><\/p>\n<\/p><\/div>\n<p class=\"copyrightbody\"><span class=\"mc-small-caps\">Nir Dobovizki<\/span> is a software architect and a senior consultant. He\u2019s worked on concurrent and asynchronous systems, mostly high-performance servers, since the late 1990s. He\u2019s used both in native code and, since the introduction of .NET 1.1 in 2003, .NET and C#. He has worked with multiple companies in the medical, defense, and manufacturing industries to solve problems arising&nbsp;from incorrect usage of multithreading and asynchronous programming.<\/p>\n<h2 class=\"fm-head\" id=\"calibre_link-9\">about the cover illustration<\/h2>\n<p class=\"copyrightbody\">The figure on the cover of <i class=\"fm-italics\">C# Concurrency<\/i> is \u201cHomme Tatar de Tobolsk\u201d or \u201cTatar man from Tobolsk,\u201d taken from a collection by Jacques Grasset de Saint-Sauveur, published in 1788. Each illustration is finely drawn and colored by hand.<\/p>\n<p class=\"copyrightbody\">In those days, it was easy to identify where people lived and what their trade or station in life was just by their dress. Manning celebrates the inventiveness and initiative of the computer business with book covers based on the rich diversity of regional culture centuries ago, brought back to life by pictures from collections such as this one.<\/p>\n<\/div>\n<\/div>\n<\/div>\n<div class=\"calibre1\" id=\"calibre_link-10\">\n<div id=\"calibre_link-327\" class=\"calibre2\">\n<div id=\"calibre_link-328\" class=\"calibre3\">\n<h1 class=\"copyrighta\" id=\"calibre_link-329\">Part 1. Asynchronous programming and multithreading basics<\/h1>\n<p class=\"copyrightbody\"><span class=\"fm-part-initial-cap\">T<\/span>he first part of this book covers asynchronous programming and multi-threading in C#, explaining what they are and how to implement them. This part highlights common pitfalls and provides guidance on how to avoid them.<\/p>\n<p class=\"copyrightbody\">We start with the concepts and terminology of multithreading and asynchronous programming, as used in computer science generally and in C# specifically (chapter 1). Next, we\u2019ll dive right into how asynchronous programming with <code class=\"fm-code-in-text\">async<\/code>\/<code class=\"fm-code-in-text\">await<\/code> works in C# (chapters 2 and 3). Then, we\u2019ll discuss multithreading in C# (chapter 4) and how multithreading and asynchronous programming work together (chapter 5). Finally, we\u2019ll talk about when to use <code class=\"fm-code-in-text\">async<\/code>\/<code class=\"fm-code-in-text\">await<\/code> (chapter 6) and how to use multithreading properly (chapter 7).<\/p>\n<p class=\"copyrightbody\">By the end of part 1, you will learn how to write correct multithread code and use <code class=\"fm-code-in-text\">async<\/code>\/<code class=\"fm-code-in-text\">await<\/code> properly.<\/p>\n<\/div>\n<\/div>\n<\/div>\n<div class=\"calibre1\" id=\"calibre_link-11\">\n<div id=\"calibre_link-330\" class=\"calibre2\">\n<div id=\"calibre_link-331\" class=\"calibre3\">\n<h1 class=\"copyrighta\" id=\"calibre_link-332\">1 <a id=\"calibre_link-333\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a>Asynchronous programming and multithreading<\/h1>\n<p class=\"copyrightbody\"><a id=\"calibre_link-274\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a>This chapter covers<a id=\"calibre_link-334\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><\/p>\n<ul class=\"calibre9\">\n<li class=\"co-summary-bullet\">Introduction to multithreading<\/li>\n<li class=\"co-summary-bullet\">Introduction to asynchronous programming<\/li>\n<li class=\"co-summary-bullet\">Asynchronous programming and multithreading used together<\/li>\n<\/ul>\n<p class=\"copyrightbody\">As software developers, we often strive to make our applications faster, more responsive, and more efficient. One way to achieve this is by enabling the computer to perform multiple tasks simultaneously, maximizing the use of existing CPU cores. Multithreading and asynchronous programming are two techniques commonly used for this task.<\/p>\n<p class=\"copyrightbody\">Multithreading allows a computer to appear as if it is executing several tasks at once, even when the number of tasks exceeds the number of CPU cores. In contrast, asynchronous programming focuses on optimizing CPU usage during operations that would typically make it wait, which ensures the CPU remains active and productive.<\/p>\n<p class=\"copyrightbody\">Enabling a computer to perform multiple tasks simultaneously is extremely useful. It helps keep native applications responsive while they work and is essential for building high-performance servers that can interact with many clients at the same time.<\/p>\n<p class=\"copyrightbody\">Both techniques can be employed to create responsive client applications or servers that handle a few clients. But when combined, they can greatly boost performance, allowing servers to handle thousands of clients at once.<\/p>\n<p class=\"copyrightbody\">This chapter will introduce you to multithreading and asynchronous programming and illustrate why they are important. In the rest of the book, we\u2019ll talk about how to use them correctly in .NET and C#, especially focusing on the C# <code class=\"fm-code-in-text\">async<\/code>\/<code class=\"fm-code-in-text\">await<\/code> feature. You will learn how these technologies work, go over the common pitfalls, and see how to use them correctly.<\/p>\n<h2 class=\"fm-head\" id=\"calibre_link-12\">1.1 What is multithreading?<\/h2>\n<p class=\"copyrightbody\"><a id=\"calibre_link-335\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a>Before we begin talking about <code class=\"fm-code-in-text\">async<\/code>\/<code class=\"fm-code-in-text\">await<\/code>, we need to understand what multithreading and asynchronous programming are. To do so, we are going to talk a bit about web servers and pizza making. We\u2019ll start with the pizza (because it\u2019s tastier than a web server). <a id=\"calibre_link-336\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><\/p>\n<p class=\"copyrightbody\">The high-level process of pizza making in a takeout place is typically as follows:<\/p>\n<ol class=\"calibre9\">\n<li class=\"fm-list-bullet1\">\n<p class=\"list\">The cook receives an order.<\/p>\n<\/li>\n<li class=\"fm-list-bullet1\">\n<p class=\"list\">The cook does stuff&mdash;takes preprepared dough, shapes it, and adds sauce, cheese, and toppings.<\/p>\n<\/li>\n<li class=\"fm-list-bullet1\">\n<p class=\"list\">The cook places the pizza in the oven and waits for it to bake (this is the longest bit).<\/p>\n<\/li>\n<li class=\"fm-list-bullet1\">\n<p class=\"list\">The cook then does more stuff&mdash;takes the pizza out of the oven, cuts it, and places it in a box.<\/p>\n<\/li>\n<li class=\"fm-list-bullet1\">\n<p class=\"list\">The cook hands the pizza to the delivery person.<\/p>\n<\/li>\n<\/ol>\n<p class=\"copyrightbody\">This is not a cookbook, so obviously, our pizza baking is a metaphor for one of the simplest server scenarios out there&mdash;a web server serving static files. The high-level process for a simple web server is as follows:<\/p>\n<ol class=\"calibre9\">\n<li class=\"fm-list-bullet1\">\n<p class=\"list\">The server receives a web request.<\/p>\n<\/li>\n<li class=\"fm-list-bullet1\">\n<p class=\"list\">The server performs some processing to figure out what needs to be done.<\/p>\n<\/li>\n<li class=\"fm-list-bullet1\">\n<p class=\"list\">The server reads a file (this is the longest bit).<\/p>\n<\/li>\n<li class=\"fm-list-bullet1\">\n<p class=\"list\">The server does some more processing (such as packaging the file content).<\/p>\n<\/li>\n<li class=\"fm-list-bullet1\">\n<p class=\"list\">The server sends the file content back to the browser.<\/p>\n<\/li>\n<\/ol>\n<p class=\"copyrightbody\">For most of the chapter, we are going to ignore the first and last steps because, in most backend web frameworks (including ASP.NET and ASP.NET Core), they are handled by the framework and not by our code. We will talk about them briefly near the end of this chapter. Figure 1.1 illustrates the web request process.<\/p>\n<div class=\"figure\">\n<p class=\"figure1\"><img decoding=\"async\" alt=\"\" class=\"calibre11\" src=\"\/images\/CSConcurrency_Asynchronous\/000000.png\" \/><\/p>\n<p class=\"figure1\">Figure 1.1 Single-threaded, single-request flow<\/p>\n<\/p><\/div>\n<p class=\"copyrightbody\">Now back to the pizza. In the simplest case, the cook will follow the steps in order, completely finishing one pizza before starting the next one. While the pizza is baking, the cook will just stand there staring at the oven and do nothing (this is a fully synchronous single-threaded version of the process).<\/p>\n<p class=\"copyrightbody\">In the world of web servers, the cook is the CPU. In this single-threaded web server, we have straightforward code that performs the operations required to complete the web request, and while the file is read from disk, the CPU is frozen doing nothing (in practice, the operating system will suspend our thread while this happens and hand over the CPU to another program, but from our program point of view, it looks like the CPU is frozen).<\/p>\n<p class=\"copyrightbody\">This version of the process has some advantages&mdash;it is simple and easy to understand. You can look at the current step and know exactly where we are in the process. As two things are never taking place at the same time, different jobs can\u2019t interfere with each other. Finally, this version requires the least amount of space and uses fewer resources at any one time because we only handle one web request (or pizza) at a time.<\/p>\n<p class=\"copyrightbody\">This single-threaded synchronous version of the process is apparently wasteful because the cook\/CPU spends most of their time doing nothing while the pizza is baking in the oven (or the file is retrieved from disk), and if our pizzeria isn\u2019t going out of business, we are going to receive new orders faster than we can fulfill them.<\/p>\n<p class=\"copyrightbody\">For this reason, we want the cook to make more than one pizza at the same time. One approach might be to use a timer and have it beep every few seconds. Every time the timer beeps, the cook will stop whatever they are doing and make a note of what they did when they stopped. The cook will then start a new pizza or continue making the previous one (ignoring the unready pizzas in the oven) until the timer beeps again.<\/p>\n<p class=\"copyrightbody\">In this version, the cook is attempting to do multiple things at the same time, and each of those things is called a <i class=\"fm-italics\">thread<\/i>. Each thread represents a sequence of operations that can happen in parallel with other similar or different sequences.<\/p>\n<p class=\"copyrightbody\"><a id=\"calibre_link-224\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a>This example may seem silly, as it is obviously inefficient, and our cook will spend too much time putting things away and picking up stuff. Yet this is exactly how multithreading works. Inside the CPU, there\u2019s a timer that signals when the CPU should switch to the next thread, and with every switch, the CPU needs to store whatever it was doing and load the other thread\u2019s status (this is called a <i class=\"fm-italics\">context switch<\/i>).<a id=\"calibre_link-337\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><\/p>\n<p class=\"copyrightbody\">For example, when your code reads a file, the thread can\u2019t do anything until the file\u2019s data is retrieved from disk. During this time, we say the thread is <i class=\"fm-italics\">blocked<\/i>. Having the system allocate CPU time to a blocked thread would obviously be wasteful, so when a thread begins reading a file, it is switched to a blocked state by the operating system. When entering this state, the thread will immediately release the CPU to the next waiting thread (possibly from another program), and the operating system will not assign any CPU time to the thread while in this state. When the system finishes reading the file, the thread exits the blocked state and is again eligible for CPU time.<\/p>\n<p class=\"copyrightbody\">The operations that can cause the thread to become blocked are called <i class=\"fm-italics\">blocking operations<\/i>. All file and network access operations are blocking, as is anything else that communicates with anything outside the CPU and memory; moreover, all operations that wait for another thread can block.<a id=\"calibre_link-338\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><\/p>\n<p class=\"copyrightbody\">Back in the pizzeria, in addition to the time we spend switching between pizzas, there\u2019s also all the information the cook needs to get back to exactly the same place they were before switching tasks. In our software, every thread, even if not running, consumes some memory, so while it\u2019s possible to create a large number of threads, each of them executing a blocking operation (so they are blocked most of the time and not consuming CPU time), this is wasteful of memory. It will slow the program down as we increase the number of threads because we must manage all the threads. At some point, we will either spend so much time managing threads that no useful work will get done or we will just run out of memory and crash.<\/p>\n<p class=\"copyrightbody\">Even with all this inefficiency, the multithreading cook, who jumps from one pizza to another like a crazy person, will make more pizzas in the same amount of time, unless they can\u2019t make progress or crash (I know, a cook can\u2019t crash; no metaphor is perfect). This mostly happens because the single-threaded cooks from before spent most of their time waiting while the pizza was in the oven.<\/p>\n<p class=\"copyrightbody\">As illustrated in figure 1.2, because we only have one CPU core (I know, everyone has multicore CPUs nowadays; we\u2019ll talk about them soon), we can\u2019t really do two things simultaneously. All the processing parts happen one after the other and are not truly in parallel; however, the CPU can wait as many times as you like in parallel. And that\u2019s why our multithread version managed to process three requests in significantly less time than it took the single-threaded version to process two.<\/p>\n<div class=\"figure\">\n<p class=\"figure1\"><img decoding=\"async\" alt=\"\" class=\"calibre12\" src=\"\/images\/CSConcurrency_Asynchronous\/000001.png\" \/><\/p>\n<p class=\"figure1\">Figure 1.2 Single-threaded versus multithread with multiple requests<\/p>\n<\/p><\/div>\n<p class=\"copyrightbody\">If you look closely at figure 1.2, you can see that while the single-threaded version handled the first request faster, the multithreaded version completed all three before the single-threaded version managed to complete the second request. This shows us the big advantage of multithreading, which is a much better utilization of the CPU in scenarios that involve waiting. It also shows the price we pay&mdash;just a little bit of extra overhead every step of the way.<\/p>\n<p class=\"copyrightbody\">Until now, we\u2019ve talked about single-core CPUs, but all modern CPUs are multicore. How does that change things?<a id=\"calibre_link-188\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-339\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><\/p>\n<h2 class=\"fm-head\" id=\"calibre_link-13\">1.2 Introducing multicore CPUs<\/h2>\n<p class=\"copyrightbody\">Multicore CPUs are conceptually simple. They are just multiple single-core CPUs packed into the same physical chip.<a id=\"calibre_link-340\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-341\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-342\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><\/p>\n<p class=\"copyrightbody\">In our pizzeria, having an eight-core CPU is equivalent to having eight cooks carrying out the pizza-making tasks. In the previous example, we had one cook who could only do one thing at a time but pretended to do multiple things by switching between them quickly. Now we have eight cooks, each able to do one task at the same time (for a total of eight tasks at once), and each pretending to do multiple things by switching between tasks quickly.<a id=\"calibre_link-343\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><\/p>\n<p class=\"copyrightbody\">In software terms, with multicore CPUs, you can really have multiple threads running simultaneously. When we had a single-core CPU, we sliced the work into tiny parts and interleaved them to make it seem like they were running at the same time (while, in fact, only one thing could run). Now, with our example eight-core CPU, we still slice the work into tiny parts and interleave them, but we can run eight of those parts at the same time.<\/p>\n<p class=\"copyrightbody\">Theoretically, eight cooks can make more pizzas than only one; however, multiple cooks may unintentionally interfere with each other\u2019s work. For example, they might bump into each other, try to put a pizza in the oven at the same time, or need to use the same pizza cutter&mdash;the more cooks we have, the greater the chance of this happening.<\/p>\n<p class=\"copyrightbody\">Figure 1.3 takes the same multithreaded work we had in figure 1.2 and shows how it would run on a dual-core CPU (just two cores because a diagram with enough work for an eight-core CPU would be too big to illustrate here).<\/p>\n<div class=\"figure\">\n<p class=\"figure1\"><img decoding=\"async\" alt=\"\" class=\"calibre13\" src=\"\/images\/CSConcurrency_Asynchronous\/000002.png\" \/><\/p>\n<p class=\"figure1\">Figure 1.3 Three requests on a dual-core CPU<\/p>\n<\/p><\/div>\n<p class=\"copyrightbody\">Note that by default, there is no persistent relation between threads and cores. A thread can jump between cores at any time (you can set threads to run on specific cores, which is called \u201cthread affinity,\u201d and except in really special circumstances, something you shouldn\u2019t do).<\/p>\n<p class=\"copyrightbody\">The dual-core CPU cut the time we spent processing by half compared to the single-core version but didn\u2019t affect the time we spent waiting. So while we did get a significant speedup, it did not cut the total time in half. Until now, we\u2019ve gotten most of the performance improvement from doing other stuff while waiting for the hard drive to read the file, but we\u2019ve paid for it with all the overhead and complexity of multithreading. Maybe we can reduce this overhead.<\/p>\n<h2 class=\"fm-head\" id=\"calibre_link-14\">1.3 Asynchronous programming<\/h2>\n<p class=\"copyrightbody\">Back in the pizzeria, there\u2019s a rational solution we ignored. The cook should make a single pizza without stopping and switching to other pizzas, but when the pizza is in the oven, they can start the next pizza instead of just sitting there. Later, whenever the cook finishes something, they can check whether the pizza in the oven is ready, and if it is, they can take it out, cut it, put it in a box, and hand it over to the delivery person.<a id=\"calibre_link-344\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-173\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><\/p>\n<p class=\"copyrightbody\">This is an example of asynchronous programming. Whenever the CPU needs to do something that happens outside the CPU itself (for example, reading a file), it sends the job to the component that handles it (the disk controller) and asks this component to notify the CPU when it\u2019s done.<\/p>\n<p class=\"copyrightbody\">The asynchronous (also called nonblocking) version of the file function just queues the operation with the operating system (that will then queue it with the disk controller) and returns immediately, letting the same thread do other stuff instead of waiting (figure 1.4). Later, we can check whether the operation has been completed and access the resulting data.<a id=\"calibre_link-345\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><\/p>\n<p class=\"copyrightbody\">If you compare all the diagrams in this chapter, you will see that this single-threaded asynchronous version is the fastest of all the options. It completes the first request almost as fast as the first single-threaded version while also completing the last request almost as fast as the dual-core multithreaded version (without even using a second core), which makes it the most performant version so far.<\/p>\n<div class=\"figure\">\n<p class=\"figure1\"><img decoding=\"async\" alt=\"\" class=\"calibre14\" src=\"\/images\/CSConcurrency_Asynchronous\/000003.png\" \/><\/p>\n<p class=\"figure1\">Figure 1.4 Single-threaded asynchronous web server with three web requests<\/p>\n<\/p><\/div>\n<p class=\"copyrightbody\">You can also clearly see that figure 1.4 is kind of a mess and is more difficult to read than the previous diagrams, and that is even without indicating in the diagram that the \u201csecond processing\u201d steps depend on completing the read operations. The thing that makes the diagram more difficult to understand is that you can no longer see the entire process; the work done for every request is broken up into parts, and unlike the threading example, those parts are not connected to each other.<a id=\"calibre_link-346\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><\/p>\n<p class=\"copyrightbody\">This is the reason that while multithreading is widely used, until the introduction of <code class=\"fm-code-in-text\">async<\/code>\/<code class=\"fm-code-in-text\">await<\/code>, asynchronous programming has only been used by people building high-performance servers (or using environments where you have no other choice; for example, JavaScript). Like in figure 1.4, the code must be broken into parts that are written separately, which made the code difficult to write and even more difficult to understand&mdash;until C# introduced the <code class=\"fm-code-in-text\">async<\/code>\/<code class=\"fm-code-in-text\">await<\/code> feature that lets one write asynchronous code as if it were normal synchronous code.<a id=\"calibre_link-347\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><\/p>\n<p class=\"copyrightbody\">Also, in figure 1.4, I indicated that I use the same asynchronous techniques as for reading the file when sending the response back to the browser. That\u2019s because the first and last steps in our web request sequence, \u201cget web request\u201d and \u201csend response to browser,\u201d are both performed mostly by the network card and not the CPU, just like reading the file is done by the hard drive, so the two can be performed asynchronously without making the CPU wait.<a id=\"calibre_link-159\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><\/p>\n<p class=\"copyrightbody\">Even with multithreading only, without asynchronous programming, it\u2019s completely possible to write servers that can handle low and medium loads by opening a thread for every connection. However, if you need to build a server that can serve thousands of connections at the same time, the overhead of so many threads will slow the server down to the point of not being able to handle the load or will crash the server outright.<\/p>\n<p class=\"copyrightbody\">We talked about asynchronous programming as a way to avoid multithreading, but we can\u2019t take advantage of the power of multicore CPUs without multithreading. Let\u2019s see whether we can use multithreading and asynchronous programming jointly to get even more performance.<a id=\"calibre_link-348\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><\/p>\n<h2 class=\"fm-head\" id=\"calibre_link-15\">1.4 Using multithreading and asynchronous programming together<\/h2>\n<p class=\"copyrightbody\">Let\u2019s jump back to the pizzeria one last time. We can improve our pizza making even more: instead of having the cook actively check the oven, just make the oven beep when the pizza is ready, and when the oven beeps, the cook can stop what they are doing, take the pizza out, put it in a box, hand it over to the delivery person, and then get back to what they were doing.<a id=\"calibre_link-349\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-350\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><\/p>\n<p class=\"copyrightbody\">The software equivalent is, when starting the asynchronous operation, to ask the operating system to notify our program by calling a callback function we registered when starting the asynchronous operation. That callback function will need to run on a new thread (actually, a thread pool thread; we will talk about the thread pool later in the book) because the original calling thread is not waiting and is currently doing something else. That\u2019s why asynchronous programming and multithreading work well together.<\/p>\n<h2 class=\"fm-head\" id=\"calibre_link-16\">1.5 Software efficiency and cloud computing<\/h2>\n<p class=\"copyrightbody\"><a id=\"calibre_link-174\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a>Today, we can just use our favorite cloud provider\u2019s \u201cserverless\u201d option and run 10,000 copies of our single-threaded code at the same time. So do we need to bother with all this multithreaded and asynchronous code?<a id=\"calibre_link-351\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-352\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><\/p>\n<p class=\"copyrightbody\">Well, theoretically, we can just throw a lot of processing power at the problem. With the modern cloud offerings, you can basically get infinite compute power whenever you want, but you do have to pay for it. Because you pay exactly for what you use, every bit of efficiency you get saves you money.<\/p>\n<p class=\"copyrightbody\">Before cloud computing, you would buy a server, and as long as you didn\u2019t max out the server you bought, the efficiency of your code didn\u2019t really matter. Today, shaving off a part of a second of every request in a high-load site can save a significant amount of money.<\/p>\n<p class=\"copyrightbody\">In the past, CPUs got faster all the time. The rule of thumb was that CPU speed doubled every two years, which meant that you could fix slow software by waiting a bit and buying a new computer. Unfortunately, this is no longer the case because the modern CPU got so close to the maximum number of transistors that can be put in a specific area that it is basically not possible to make a single core much faster. Consequently, the single-thread performance of CPUs now rises rather slowly, and our only choice to improve performance is to use more CPU cores (there\u2019s a very influential paper called \u201cThe Free Lunch Is Over\u201d by Herb Sutter covering this topic; see <a class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\" href=\"http:\/\/www.gotw.ca\/publications\/concurrency-ddj.htm\">www.gotw.ca\/publications\/concurrency-ddj.htm<\/a>).<\/p>\n<p class=\"copyrightbody\">Nonetheless, the modern CPU is still extremely fast, faster than other computer components, and obviously, much faster than any human. Therefore, a typical CPU spends most of its time waiting. Sometimes it\u2019s waiting for user input, and other times, it\u2019s waiting for the hard drive, but it\u2019s still waiting. Multithreading and asynchronous programming enable employing this waiting time to do useful work.<a id=\"calibre_link-353\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><\/p>\n<h2 class=\"fm-head\" id=\"calibre_link-354\">Summary<\/h2>\n<ul class=\"calibre9\">\n<li class=\"fm-list-bullet\">\n<p class=\"list\">Multithreading is switching between several things on the same CPU fast enough to make it feel like they are all running simultaneously.<\/p>\n<\/li>\n<li class=\"fm-list-bullet\">\n<p class=\"list\">A thread is one of those things running simultaneously.<\/p>\n<\/li>\n<li class=\"fm-list-bullet\">\n<p class=\"list\">A thread has significant overhead.<\/p>\n<\/li>\n<li class=\"fm-list-bullet\">\n<p class=\"list\">Switching between threads is called <i class=\"fm-italics\">context switching<\/i>, and it also has overhead.<\/p>\n<\/li>\n<li class=\"fm-list-bullet\">\n<p class=\"list\">When doing stuff that happens outside the CPU, such as reading a file or using a network, the thread must wait until the operation is complete to get the result and continue to operate on it, which is called a <i class=\"fm-italics\">blocking operation<\/i>.<\/p>\n<\/li>\n<li class=\"fm-list-bullet\">\n<p class=\"list\">Asynchronous programming frees up the thread while operations are taking place by asking the system to send a notification when the operation ends instead of waiting, which is called a <i class=\"fm-italics\">nonblocking operation<\/i>. The program then needs to pick up processing later when the data is available, usually on a different thread.<\/p>\n<\/li>\n<li class=\"fm-list-bullet\">\n<p class=\"list\">We need asynchronous and multithreading techniques because the complexity of our software grows faster than the single-thread performance of our CPUs.<\/p>\n<\/li>\n<li class=\"fm-list-bullet\">\n<p class=\"list\">Because in cloud computing we pay for the exact resources we use, asynchronous and multithreading techniques that increase efficiency can save us some money.<\/p>\n<\/li>\n<\/ul>\n<\/div>\n<\/div>\n<\/div>\n<div class=\"calibre1\" id=\"calibre_link-17\">\n<div id=\"calibre_link-355\" class=\"calibre2\">\n<div id=\"calibre_link-356\" class=\"calibre3\">\n<h1 class=\"copyrighta\" id=\"calibre_link-357\">2 <a class=\"pcalibre2 pcalibre pcalibre3 pcalibre1 calibre8\" id=\"calibre_link-358\"><\/a><a id=\"calibre_link-359\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a>The compiler rewrites your code<\/h1>\n<p class=\"copyrightbody\"><a id=\"calibre_link-160\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a>This chapter covers<\/p>\n<ul class=\"calibre9\">\n<li class=\"co-summary-bullet\">How the C# compiler supports features that do not exist in the .NET runtime<\/li>\n<li class=\"co-summary-bullet\">The implementation of lambda functions by the compiler<\/li>\n<li class=\"co-summary-bullet\">The implementation of <code class=\"fm-code-in-text\">yield return<\/code> by the compiler<\/li>\n<\/ul>\n<p class=\"copyrightbody\">The compiler modifies your code, which means that the output is not a direct representation of the source code. This is done for two main reasons: to reduce the amount of typing required by boilerplate code generation and to add features not supported by the underlying platform. One such feature is <code class=\"fm-code-in-text\">async<\/code>\/<code class=\"fm-code-in-text\">await<\/code>, which is primarily implemented by the C# compiler rather than the .NET runtime. To write correct asynchronous code, avoid the potential pitfalls, and especially to debug code, it\u2019s important to understand how the compiler transforms your code, that is, what happens when your code runs. <a id=\"calibre_link-360\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><\/p>\n<p class=\"copyrightbody\">This chapter discusses how the C# compiler rewrites your code during compilation. However, because <code class=\"fm-code-in-text\">async<\/code>\/<code class=\"fm-code-in-text\">await<\/code> is probably the most complicated code transformation in the current version of C#, we\u2019re going to start with lambda functions and <code class=\"fm-code-in-text\">yield return<\/code>, which are implemented using the same techniques as <code class=\"fm-code-in-text\">async<\/code>\/<code class=\"fm-code-in-text\">await<\/code>. By starting with simpler compiler features, we can learn the concepts behind <code class=\"fm-code-in-text\">async<\/code>\/<code class=\"fm-code-in-text\">await<\/code> without having to deal with the complexities of asynchronous programming and multithreading. The next chapter will show how everything translates directly to <code class=\"fm-code-in-text\">async<\/code>\/<code class=\"fm-code-in-text\">await<\/code>.<\/p>\n<p class=\"copyrightbody\">Now let\u2019s see how the C# compiler adds advanced features not supported by the underlying .NET runtime, starting with lambda functions (note that the C# lambda functions have nothing to do with the Amazon AWS Lambda service).<\/p>\n<h2 class=\"fm-head\" id=\"calibre_link-18\">2.1 Lambda functions<\/h2>\n<p class=\"copyrightbody\">Let\u2019s start with one of the simpler C# features implemented by the compiler&mdash;lambda functions. These functions are code blocks you can write inline, inside a larger method that can be used just like a standalone method. Lambda functions allow us to take code that, for technical reasons, needs to be a different method and write it in-line where it is used, making the code easier to read and understand. Lambda functions can also use local variables from the method that defined them.<a id=\"calibre_link-361\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-362\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-217\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><\/p>\n<p class=\"copyrightbody\">However, the .NET runtime does not have in-line functions&mdash;all code in .NET must be in the form of methods that are part of classes. So how do lambda functions work? Let\u2019s take a very simple example: we will create a timer, set it to call us in 1 second, and then write the string <code class=\"fm-code-in-text\">\"Elapsed\"<\/code> to the console.<\/p>\n<p class=\"fm-code-listing-caption\">Listing 2.1 Using lambda functions<\/p>\n<pre class=\"programlisting\">public class LambdaDemo1\n{\n   private System.Timers.Timer? _timer;\n \n   public void InitTimer()\n   {\n      _timer = new System.Timers.Timer(1000);\n      _timer.Elapsed += (sender,args) =&gt; Console.WriteLine(\"Elapsed\");\n      _timer.Enabled = true;\n   }\n}<\/pre>\n<p class=\"copyrightbody\">If we run this example, unsurprisingly, the program will print <code class=\"fm-code-in-text\">\"Elapsed\"<\/code> after 1 second. The line I want you to focus on is the one that sets the <code class=\"fm-code-in-text\">_timer.Elapsed<\/code> property. This line defines a lambda function and passes it the <code class=\"fm-code-in-text\">Elapsed<\/code> property.<a id=\"calibre_link-363\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-364\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><\/p>\n<p class=\"copyrightbody\">But I said that in .NET, all code must be in methods defined in classes, so how is this done? The answer is that the C# compiler rewrites your lambda function as a normal method. If you look at the compile output, it would be similar to<\/p>\n<pre class=\"programlisting\">public class LambdaDemo2\n{\n   private System.Timers.Timer? _timer;\n \n   private void HiddenMethodForLambda(                       <span class=\"fm-combinumeral\">\u2776<\/span>\n         object? sender, System.Timers.ElapsedEventArgs args)\n   {\n      Console.WriteLine(\"Elapsed\");\n   }\n \n   public void InitTimer()\n   {\n      _timer = new System.Timers.Timer(1000);\n      _timer.Elapsed += HiddenMethodForLambda;\n      _timer.Enabled = true;\n   }\n}<\/pre>\n<p class=\"copyrightbody\"><span class=\"fm-combinumeral\">\u2776<\/span> The lambda function becomes a regular method.<\/p>\n<p class=\"copyrightbody\">The compiler rearranged our code and moved the body of the lambda function into a new method. That way, we can write the code inline, and the runtime can treat it as a normal method.<\/p>\n<p class=\"copyrightbody\">But the lambda function can also use local variables from the method that defined them. Let\u2019s add a variable defined in the <code class=\"fm-code-in-text\">InitTimer<\/code> method and used inside the lambda function.<a id=\"calibre_link-365\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-366\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><\/p>\n<p class=\"fm-code-listing-caption\">Listing 2.2 Lambda function that uses local variables<\/p>\n<pre class=\"programlisting\">public class LambdaDemo3\n{\n   private System.Timers.Timer? _timer;\n \n   public void InitTimer()\n   {\n      int aVariable = 5;                                    <span class=\"fm-combinumeral\">\u2776<\/span>\n      _timer = new System.Timers.Timer(1000);\n      _timer.Elapsed += (sender,args) =&gt; Console.WriteLine(aVariable);\n      _timer.Enabled = true;\n   }\n}<\/pre>\n<p class=\"copyrightbody\"><span class=\"fm-combinumeral\">\u2776<\/span> The new variable<\/p>\n<p class=\"copyrightbody\">If we try to apply the same transformation on this code like in the previous example, we will get two methods that share a local variable. This is obviously not supported and doesn\u2019t even make sense. How can the compiler handle that? Well, it needs something that can hold data that can be accessed from two places, and we have such a thing in .NET: classes. So the compiler creates a class to hold our \u201clocal\u201d variable:<\/p>\n<pre class=\"programlisting\">public class LambdaDemo4\n{\n   private System.Timers.Timer? _timer;\n \n   private class HiddenClassForLambda                       <span class=\"fm-combinumeral\">\u2776<\/span>\n   {\n \n      public int aVariable;                                 <span class=\"fm-combinumeral\">\u2777<\/span>\n \n      public void HiddenMethodForLambda(                    <span class=\"fm-combinumeral\">\u2778<\/span>\n               object? sender,                              <span class=\"fm-combinumeral\">\u2778<\/span>\n               System.Timers.ElapsedEventArgs args)         <span class=\"fm-combinumeral\">\u2778<\/span>\n      {                                                     <span class=\"fm-combinumeral\">\u2778<\/span>\n         Console.WriteLine(aVariable);                      <span class=\"fm-combinumeral\">\u2778<\/span>\n      }                                                     <span class=\"fm-combinumeral\">\u2778<\/span>\n   }\n \n   public void InitTimer()\n   {\n      var hiddenObject = new HiddenClassForLambda();\n      hiddenObject.aVariable = 5;\n      _timer = new System.Timers.Timer(1000);\n      _timer.Elapsed += hiddenObject.HiddenMethodForLambda;\n      _timer.Enabled = true;\n   }\n}<\/pre>\n<p class=\"copyrightbody\"><span class=\"fm-combinumeral\">\u2776<\/span> The compiler creates a class for our lambda function.<\/p>\n<p class=\"copyrightbody\"><span class=\"fm-combinumeral\">\u2777<\/span> The local variable becomes a field of the class.<\/p>\n<p class=\"copyrightbody\"><span class=\"fm-combinumeral\">\u2778<\/span> The lambda function becomes a method inside that class.<\/p>\n<p class=\"copyrightbody\">Here, the compiler created a new method and an entirely new class. The local variable was moved to be a member of this class, and both the <code class=\"fm-code-in-text\">InitTimer<\/code> method and the lambda function reference this new class member. This changes the way the local variable is accessed outside the lambda function&mdash;some operation that only used local variables can turn into access to class member fields when you introduce a lambda. If there are multiple lambda functions defined in the same method, they are placed in the same class so they can share local variables. The important point is that there is no magic here&mdash;everything the compiler adds to the .NET runtime is done by just writing code that we can write ourselves because we have basically the same access to the runtime\u2019s functionality as the compiler.<a id=\"calibre_link-367\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><\/p>\n<p class=\"copyrightbody\">Now that we\u2019ve seen the lambda function transformation, let\u2019s take a look at something a bit more complicated.<a id=\"calibre_link-368\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-369\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-218\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><\/p>\n<h2 class=\"fm-head\" id=\"calibre_link-19\">2.2 Yield return<\/h2>\n<p class=\"copyrightbody\">The <code class=\"fm-code-in-text\">yield return<\/code> feature uses the same tricks we\u2019ve seen in the lambda function example to do even more advanced stuff. It\u2019s also somewhat similar to <code class=\"fm-code-in-text\">async<\/code>\/<code class=\"fm-code-in-text\">await<\/code>, but without the complexities of multithreading and asynchronous code, so it\u2019s a good way to learn the fundamentals of <code class=\"fm-code-in-text\">async<\/code>\/<code class=\"fm-code-in-text\">await<\/code>.<a id=\"calibre_link-370\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-371\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><\/p>\n<p class=\"copyrightbody\">What is <code class=\"fm-code-in-text\">yield return<\/code>? It basically lets you write functions that generate a sequence of values you can use in <code class=\"fm-code-in-text\">foreach<\/code> loops directly without using a collection such as a list or an array. Each value can be used without waiting for the entire sequence to be generated. Let\u2019s write something extremely simple&mdash;a method that returns a collection with two items, the numbers 1 and 2. The following listing shows what it looks like without <code class=\"fm-code-in-text\">yield return<\/code>.<\/p>\n<p class=\"fm-code-listing-caption\">Listing 2.3 Using a list<\/p>\n<pre class=\"programlisting\">private IEnumerable&lt;int&gt; NoYieldDemo()\n{\n   var result = new List&lt;int&gt;();\n   result.Add(1);\n   result.Add(2);\n   return result;\n}\n \npublic void UseNoYieldDemo()\n{\n   foreach(var current in NoYieldDemo())\n   {\n         Console.WriteLine($\"Got {current}\");\n   }\n}<\/pre>\n<p class=\"copyrightbody\">Unsurprisingly, this code will output two lines, <code class=\"fm-code-in-text\">Got 1<\/code> and <code class=\"fm-code-in-text\">Got 2<\/code>. The following listing shows the same functionality with <code class=\"fm-code-in-text\">yield return<\/code>.<a id=\"calibre_link-228\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><\/p>\n<p class=\"fm-code-listing-caption\">Listing 2.4 Using <code class=\"fm-code-in-text1\">yield return<\/code><\/p>\n<pre class=\"programlisting\">private IEnumerable&lt;int&gt; YieldDemo()\n{\n   yield return 1;\n   yield return 2;\n}\n \npublic void UseYieldDemo()\n{\n   foreach(var current in YieldDemo())\n   {\n         Console.WriteLine($\"Got {current}\");\n   }\n}<\/pre>\n<p class=\"copyrightbody\">The code looks very similar, and the results are the same. So what is the big difference? In the first example, all the values were generated first and then used, while in the second example, each value was generated just when it was needed, as illustrated in figure 2.1.<\/p>\n<div class=\"figure\">\n<p class=\"figure1\"><img decoding=\"async\" alt=\"\" class=\"calibre15\" src=\"\/images\/CSConcurrency_Asynchronous\/000004.png\" \/><\/p>\n<p class=\"figure1\">Figure 2.1 Using a collection versus using <code class=\"fm-code-in-text\">yield return<\/code><\/p>\n<\/p><\/div>\n<p class=\"copyrightbody\">In the non-<code class=\"fm-code-in-text\">yield return<\/code> version, the code ran normally. The <code class=\"fm-code-in-text\">NoYieldDemo<\/code> method started, did some stuff, and then returned. However, the <code class=\"fm-code-in-text\">YieldDemo<\/code> method behaved differently&mdash;it suspended at startup, and then, every time a value was needed, it resumed, ran the minimal amount of code to provide the next value (until the next <code class=\"fm-code-in-text\">yield return<\/code>), and suspended itself again. But .NET doesn\u2019t have a way to suspend and resume code. What kind of sorcery is that?<a id=\"calibre_link-372\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-373\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><\/p>\n<p class=\"copyrightbody\">Obviously, there is no sorcery, as magic does not exist in computer science. Just like in the case of the lambda function examples we\u2019ve seen before, the compiler just rewrote our code.<\/p>\n<p class=\"copyrightbody\">In computer science, code that can be suspended, resumed, and potentially return multiple values is called a <i class=\"fm-italics\">coroutine<\/i>. In C#, it is called <i class=\"fm-italics\">iterator methods<\/i> in relation to <code class=\"fm-code-in-text\">yield return<\/code> and <i class=\"fm-italics\">async methods<\/i> in relation to <code class=\"fm-code-in-text\">async<\/code>\/<code class=\"fm-code-in-text\">await<\/code>. This book uses the C# terminology.<a id=\"calibre_link-374\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-375\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-376\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><\/p>\n<p class=\"copyrightbody\">The <code class=\"fm-code-in-text\">IEnumerable&lt;T&gt;<\/code> interface that I used as the return type for the <code class=\"fm-code-in-text\">YieldDemo<\/code> method is the most basic interface for anything that can be treated as collections or sequences of items (including everything you can use <code class=\"fm-code-in-text\">foreach<\/code> to iterate over). Every generic collection in .NET implements this interface (older collections classes, from before generics were introduced in .NET 2.0, use the nongeneric <code class=\"fm-code-in-text\">IEnumerable<\/code> interface instead). This interface has just one method that returns an <code class=\"fm-code-in-text\">IEnumerator&lt;T&gt;<\/code>, and this enumerator does all the work. An enumerator can do two things: return the current value and move to the next one.<a id=\"calibre_link-377\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-378\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-250\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-379\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><\/p>\n<p class=\"copyrightbody\">The <code class=\"fm-code-in-text\">IEnumerator&lt;T&gt;<\/code> interface is important because it lets us (and the compiler) write code that handles a sequence of items without knowing anything about that sequence. Every collection in .NET implements <code class=\"fm-code-in-text\">IEnumerable&lt;T&gt;<\/code>, so constructs that deal with sequences (like the <code class=\"fm-code-in-text\">foreach<\/code> loop) don\u2019t need to know how to work with every type of collection&mdash;they just need to know how to work with <code class=\"fm-code-in-text\">IEnumerable&lt;T&gt;<\/code>. The inverse is also true&mdash;everything that implements <code class=\"fm-code-in-text\">IEnumerable&lt;T&gt;<\/code> is automatically a sequence of items that can be used with <code class=\"fm-code-in-text\">foreach<\/code> loops and all the other relevant parts of .NET and C#.<a id=\"calibre_link-380\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-381\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><\/p>\n<p class=\"copyrightbody\">Just like in the lambda example, the compiler rewrote the <code class=\"fm-code-in-text\">YieldDemo<\/code> method into a class, but this time, a class that implements <code class=\"fm-code-in-text\">IEnumerator&lt;int&gt;<\/code>, so the <code class=\"fm-code-in-text\">foreach<\/code> loop knows what to do with it. Let\u2019s rewrite the code ourselves to get the same result.<a id=\"calibre_link-382\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><\/p>\n<p class=\"copyrightbody\">To begin, <code class=\"fm-code-in-text\">YieldDemo<\/code> returned an <code class=\"fm-code-in-text\">IEnumerable&lt;int&gt;,<\/code> so obviously, we have a class that implements this interface, so it can be returned from <code class=\"fm-code-in-text\">YieldDemo<\/code>. Like I said before, the only thing the <code class=\"fm-code-in-text\">IEnumerable&lt;int&gt;<\/code> does is provide an <code class=\"fm-code-in-text\">IEnumerator&lt;int&gt;<\/code> (for historical reasons, to be compatible with code written before .NET 2.0, in addition to <code class=\"fm-code-in-text\">IEnumerator&lt;int&gt;<\/code>, we also need to provide a nongeneric <code class=\"fm-code-in-text\">IEnumerator<\/code>, and we will use the same class for both):<a id=\"calibre_link-383\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><\/p>\n<pre class=\"programlisting\">public class YieldDemo_Enumerable : IEnumerable&lt;int&gt;           <span class=\"fm-combinumeral\">\u2776<\/span>\n{\n   public IEnumerator&lt;int&gt; GetEnumerator()\n   {\n      return new YieldDemo_Enumerator();                       <span class=\"fm-combinumeral\">\u2777<\/span>\n   }\n   IEnumerator IEnumerable.GetEnumerator()\n   {\n      return new YieldDemo_Enumerator();                       <span class=\"fm-combinumeral\">\u2777<\/span>\n   }\n}<\/pre>\n<p class=\"copyrightbody\"><span class=\"fm-combinumeral\">\u2776<\/span> Our IEnumerable&lt;int&gt;<\/p>\n<p class=\"copyrightbody\"><span class=\"fm-combinumeral\">\u2777<\/span> Returns an IEnumerator&lt;int&gt;<\/p>\n<p class=\"copyrightbody\">Now we need to write our <code class=\"fm-code-in-text\">IEnumerator&lt;int&gt;<\/code> that will do all the work:<a id=\"calibre_link-384\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><\/p>\n<pre class=\"programlisting\">public class YieldDemo_Enumerator : IEnumerator&lt;int&gt;\n{<\/pre>\n<p class=\"copyrightbody\">We need a <code class=\"fm-code-in-text\">Current<\/code> property to hold the current value:<a id=\"calibre_link-385\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><\/p>\n<pre class=\"programlisting\">   public int Current { get; private set; }<\/pre>\n<p class=\"copyrightbody\"><a id=\"calibre_link-232\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a>Now comes the important part. Here, we divide our original code into chunks, breaking it just after each <code class=\"fm-code-in-text\">yield return<\/code>, and replace the <code class=\"fm-code-in-text\">yield return<\/code> with <code class=\"fm-code-in-text\">Current =<\/code>:<\/p>\n<pre class=\"programlisting\">   private void Step0()\n   {\n      Current = 1;\n   }\n   private void Step1()\n   {\n      Current = 2;\n   }<\/pre>\n<p class=\"copyrightbody\">The next part is the <code class=\"fm-code-in-text\">MoveNext<\/code> method. This method runs the correct chunk from the previous paragraph to update the <code class=\"fm-code-in-text\">Current<\/code> property. It uses the <code class=\"fm-code-in-text\">_step<\/code> field to remember which step to run, and when we run out of steps, it returns false to indicate we are done (if you have a computer science background, you may recognize this as a simple implementation of a finite state machine):<a id=\"calibre_link-386\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-387\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><\/p>\n<pre class=\"programlisting\">   private int _step = 0;                           <span class=\"fm-combinumeral\">\u2776<\/span>\n   public bool MoveNext()\n   {\n      switch(_step)\n      {\n         case 0:\n            Step0();\n            ++_step;\n            break;\n         case 1:\n            Step1();\n            ++_step;\n            break;\n         case 2:\n            return false;                           <span class=\"fm-combinumeral\">\u2777<\/span>\n      }\n      return true;\n   }<\/pre>\n<p class=\"copyrightbody\"><span class=\"fm-combinumeral\">\u2776<\/span> A variable to keep track of where we are<\/p>\n<p class=\"copyrightbody\"><span class=\"fm-combinumeral\">\u2777<\/span> We\u2019re done; return false.<\/p>\n<p class=\"copyrightbody\">Now there\u2019s some necessary technical stuff not relevant to this example:<\/p>\n<pre class=\"programlisting\">   object IEnumerator.Current =&gt; Current;\n   public void Dispose() { }\n   public void Reset() { }\n}<\/pre>\n<p class=\"copyrightbody\">And finally, wrap the classes we generated in a method so we can call it:<\/p>\n<pre class=\"programlisting\">public IEnumerable&lt;int&gt; YieldDemo()\n{\n   return new YieldDemo_Enumerable();\n}<\/pre>\n<p class=\"copyrightbody\">The actual compiler-generated code is longer and more complicated, mostly because I completely ignored all the possible error conditions. However, conceptually, this is what the compiler does. The compiler rewrote our code into chunks and called each chunk in turn when needed, giving us an illusion of code that suspends and resumes.<\/p>\n<p class=\"copyrightbody\">For the yield return feature to work, we need<\/p>\n<ul class=\"calibre9\">\n<li class=\"fm-list-bullet\">\n<p class=\"list\">The code transformation that divided our code into chunks and simulated a single method that can be suspended and resumed<\/p>\n<\/li>\n<li class=\"fm-list-bullet\">\n<p class=\"list\">A standard representation for anything collection-like (<code class=\"fm-code-in-text\">IEnumerable&lt;T&gt;<\/code>) so that everyone can use the results of this transformation<\/p>\n<\/li>\n<\/ul>\n<p class=\"copyrightbody\">That brings us directly to <code class=\"fm-code-in-text\">async<\/code>\/<code class=\"fm-code-in-text\">await<\/code> and the <code class=\"fm-code-in-text\">Task<\/code> class in the next chapter.<a id=\"calibre_link-388\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-219\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-389\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><\/p>\n<h2 class=\"fm-head\" id=\"calibre_link-390\">Summary<\/h2>\n<ul class=\"calibre9\">\n<li class=\"fm-list-bullet\">\n<p class=\"list\">The C# compiler will rearrange and rewrite your code to add features that do not exist in .NET.<\/p>\n<\/li>\n<li class=\"fm-list-bullet\">\n<p class=\"list\">For lambda functions, the compiler moves code into a new method and shared data into a new class.<\/p>\n<\/li>\n<li class=\"fm-list-bullet\">\n<p class=\"list\">For <code class=\"fm-code-in-text\">yield return<\/code>, the compiler also divides your code into chunks and wraps them in a class that runs the correct chunk at the correct time to simulate a function that can be suspended and resumed.<\/p>\n<\/li>\n<\/ul>\n<\/div>\n<\/div>\n<\/div>\n<div class=\"calibre1\" id=\"calibre_link-20\">\n<div id=\"calibre_link-391\" class=\"calibre2\">\n<div id=\"calibre_link-392\" class=\"calibre3\">\n<h1 class=\"copyrighta\" id=\"calibre_link-393\">3 <a id=\"calibre_link-394\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-395\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-396\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a>The async and await keywords<\/h1>\n<p class=\"copyrightbody\"><a id=\"calibre_link-161\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a>This chapter covers<a id=\"calibre_link-397\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><\/p>\n<ul class=\"calibre9\">\n<li class=\"co-summary-bullet\">Using <code class=\"fm-code-in-text\">Task<\/code> and <code class=\"fm-code-in-text\">Task&lt;T&gt;<\/code> to check whether an operation has completed<\/li>\n<li class=\"co-summary-bullet\">Using <code class=\"fm-code-in-text\">Task<\/code> and <code class=\"fm-code-in-text\">Task&lt;T&gt;<\/code> to notify your code when the operation has completed<\/li>\n<li class=\"co-summary-bullet\">Using <code class=\"fm-code-in-text\">Task<\/code> and <code class=\"fm-code-in-text\">Task&lt;T&gt;<\/code> in synchronous code<\/li>\n<li class=\"co-summary-bullet\">How <code class=\"fm-code-in-text\">async\/await<\/code> works<\/li>\n<\/ul>\n<p class=\"copyrightbody\">In the previous chapter, we saw how the compiler can transform our code to add language features. In this chapter, we\u2019ll learn how it applies to <code class=\"fm-code-in-text\">async<\/code>\/<code class=\"fm-code-in-text\">await<\/code>.<\/p>\n<p class=\"copyrightbody\"><code class=\"fm-code-in-text\">async<\/code>\/<code class=\"fm-code-in-text\">await<\/code> is a feature that lets us write asynchronous code as if it were normal synchronous code. With asynchronous programming, when we perform an operation that would normally make the CPU wait (usually for data to arrive from some device&mdash;for example, reading a file), instead of waiting, we just do something else. Making asynchronous code look like normal code is kind of a big deal because traditionally, you had to divide each sequence of operations into small parts (breaking at each asynchronous operation) and call the right part at the right time. Unsurprisingly, this makes the code confusing to write.<\/p>\n<h2 class=\"fm-head\" id=\"calibre_link-21\">3.1 Asynchronous code complexity<\/h2>\n<p class=\"copyrightbody\">To demonstrate this, I placed figures 1.1 and 1.4 side by side (figure 3.1).<a id=\"calibre_link-398\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-399\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><\/p>\n<div class=\"figure\">\n<p class=\"figure1\"><img decoding=\"async\" alt=\"\" class=\"calibre16\" src=\"\/images\/CSConcurrency_Asynchronous\/000005.png\" \/><\/p>\n<p class=\"figure1\">Figure 3.1 Logical flow versus code running asynchronously<\/p>\n<\/p><\/div>\n<p class=\"copyrightbody\">Clearly, the left side describing the logical flow is simple, linear, and easy to understand, while the right side that describes how the asynchronous version is running is none of those things (it\u2019s also very difficult to debug).<\/p>\n<p class=\"copyrightbody\">Traditionally, asynchronous programming requires us to design and write our code for the right diagram, as well as divide our code into chunks that do not represent the logical flow of the code. Also, we need code to manage the whole mess and decide what to run when.<\/p>\n<p class=\"copyrightbody\">The <code class=\"fm-code-in-text\">async<\/code>\/<code class=\"fm-code-in-text\">await<\/code> feature lets us write code that describes the logical flow, and the compiler will transform it to something that can run asynchronously automatically&mdash;it lets us write our code as shown on the left side of the diagram and have it run like the right side.<\/p>\n<p class=\"copyrightbody\">Let\u2019s illustrate this through a simple example&mdash;a method that reads the image width (in pixels) of a BMP image file. I\u2019ve chosen BMP because unlike more modern image file formats, all the data in the BMP file is at a fixed location, which makes it easy to extract. We\u2019ll read the image width in two steps:<\/p>\n<ol class=\"calibre9\">\n<li class=\"fm-list-bullet1\">\n<p class=\"list\">First, we check whether the file is a BMP image file at all. We do that by looking at the beginning of the file: BMP image files start with \u201cBM.\u201d<\/p>\n<\/li>\n<li class=\"fm-list-bullet1\">\n<p class=\"list\">We will then jump to the eighteenth byte in the file where the width is stored as a 32-bit (4 bytes) integer.<\/p>\n<\/li>\n<\/ol>\n<p class=\"copyrightbody\">Our method will return the image width in pixels or throw an exception if the file is not a BMP image and if there are other errors. Because we haven\u2019t talked about how to write asynchronous code yet, the first version of this example will be simple, old-style, synchronous code.<a id=\"calibre_link-164\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><\/p>\n<p class=\"fm-code-listing-caption\">Listing 3.1 Reading BMP width, non-asynchronous version<\/p>\n<pre class=\"programlisting\">int GetBitmapWidth(string path)\n{\n    using (var file = new FileStream(path, FileMode.Open, FileAccess.Read))\n    {\n        var fileId = new byte[2];                                   <span class=\"fm-combinumeral\">\u2776<\/span>\n        var read = file.Read(fileId, 0, 2);                         <span class=\"fm-combinumeral\">\u2776<\/span>\n        if (read != 2 || fileId[0] != 'B' || fileId[1] != 'M')      <span class=\"fm-combinumeral\">\u2776<\/span>\n           throw new Exception(\"Not a BMP file\");                   <span class=\"fm-combinumeral\">\u2776<\/span>\n        \n        file.Seek(18, SeekOrigin.Begin);                            <span class=\"fm-combinumeral\">\u2777<\/span>\n        var widthBuffer = new byte[4];                              <span class=\"fm-combinumeral\">\u2777<\/span>\n        read = file.Read(widthBuffer, 0, 4);                        <span class=\"fm-combinumeral\">\u2777<\/span>\n        if(read != 4) throw new Exception(\"Not a BMP file\");        <span class=\"fm-combinumeral\">\u2777<\/span>\n        return BitConverter.ToInt32(widthBuffer, 0);                <span class=\"fm-combinumeral\">\u2777<\/span>\n    }\n}<\/pre>\n<p class=\"copyrightbody\"><span class=\"fm-combinumeral\">\u2776<\/span> The file should start with \u201cBM.\u201d<\/p>\n<p class=\"copyrightbody\"><span class=\"fm-combinumeral\">\u2777<\/span> Reads the width from byte 18<\/p>\n<p class=\"copyrightbody\">As you can see, the code is straightforward. We read the first two bytes and check whether their value is \u201cBM.\u201d Next, we skip to the eighteenth byte and read the image width.<\/p>\n<h2 class=\"fm-head\" id=\"calibre_link-22\">3.2 Introducing Task and Task&lt;T&gt;<\/h2>\n<p class=\"copyrightbody\">Now let\u2019s make this code asynchronous. We have two excellent reasons for doing so: <a id=\"calibre_link-400\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-401\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-402\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-403\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><\/p>\n<ul class=\"calibre9\">\n<li class=\"fm-list-bullet\">\n<p class=\"list\">The first and most important reason is that this is a book about asynchronous programming.<\/p>\n<\/li>\n<li class=\"fm-list-bullet\">\n<p class=\"list\">The second reason is that the main thing our code does is read a file, and reading a file is a blocking operation that will make our thread wait for data to arrive from the hard disk. That means we can improve efficiency by using our thread to do other stuff while waiting instead of making the operating system switch to another thread (or another process entirely).<\/p>\n<\/li>\n<\/ul>\n<p class=\"copyrightbody\">The main thing our method does is read a file using the <code class=\"fm-code-in-text\">Stream.Read<\/code> method, and luckily, there\u2019s an asynchronous version of the <code class=\"fm-code-in-text\">Stream.Read<\/code> method called <code class=\"fm-code-in-text\">Stream.ReadAsync<\/code>. Let\u2019s take a look at the difference in the method signature between those two methods:<a id=\"calibre_link-404\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-210\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-405\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><\/p>\n<pre class=\"programlisting\">public int Read(byte[] buffer, int offset, int count);\n\npublic Task&lt;int&gt; ReadAsync(byte[] buffer, int offset, int count,\n   CancellationToken cancellationToken);<\/pre>\n<p class=\"copyrightbody\">We can see the following two differences in the method signature:<\/p>\n<ul class=\"calibre9\">\n<li class=\"fm-list-bullet\">\n<p class=\"list\">While <code class=\"fm-code-in-text\">Read<\/code> returns an <code class=\"fm-code-in-text\">int<\/code>, <code class=\"fm-code-in-text\">ReadAsync<\/code> returns <code class=\"fm-code-in-text\">Task&lt;int&gt;.<\/code> The <code class=\"fm-code-in-text\">Task<\/code> and <code class=\"fm-code-in-text\">Task&lt;T&gt;<\/code> classes are an important part of modern asynchronous programming in C#, and we will explore their usage here.<a id=\"calibre_link-406\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-407\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><\/p>\n<\/li>\n<li class=\"fm-list-bullet\">\n<p class=\"list\"><code class=\"fm-code-in-text\">ReadAsync<\/code> also accepts a <code class=\"fm-code-in-text\">CancellationToken<\/code>, but we\u2019re going to ignore it for now because there\u2019s an entire chapter about it later in this book. <a id=\"calibre_link-408\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><\/p>\n<\/li>\n<\/ul>\n<p class=\"copyrightbody\">Earlier in this chapter, I wrote that for asynchronous code, we need to divide our code into parts, and we also need a system to manage the execution of those parts. <code class=\"fm-code-in-text\">Task<\/code> is the class that we use to interact with that system. A <code class=\"fm-code-in-text\">Task<\/code> does multiple things: it represents an ongoing asynchronous operation, lets us schedule code to run when an asynchronous operation ends (we\u2019ll talk about these two in this chapter), and lets us create and compose asynchronous operations (we\u2019ll talk about those later in this book).<\/p>\n<p class=\"copyrightbody\">Chapter 2 introduced us to <code class=\"fm-code-in-text\">IEnumerable&lt;T&gt;<\/code> and how it enables <code class=\"fm-code-in-text\">yield return<\/code>. The <code class=\"fm-code-in-text\">Task<\/code> and <code class=\"fm-code-in-text\">Task&lt;T&gt;<\/code> classes are the <code class=\"fm-code-in-text\">IEnumerable&lt;T&gt;<\/code> of async programming. They are a standard way to represent the <code class=\"fm-code-in-text\">async<\/code> stuff, so everyone knows how to work with it.<a id=\"calibre_link-409\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-410\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><\/p>\n<p class=\"copyrightbody\">The name of the <code class=\"fm-code-in-text\">Task<\/code> class is confusing; the word \u201ctask\u201d implies there\u2019s an operation, something that runs, but this is not the only meaning of <code class=\"fm-code-in-text\">Task<\/code>. A <code class=\"fm-code-in-text\">Task<\/code> represents an event that may happen in the future, while <code class=\"fm-code-in-text\">Task&lt;T&gt;<\/code> represents a value that may be available in the future. Those events and values may or may not be the results of something we will describe using the English word task. In computer science, those concepts are often called <i class=\"fm-italics\">future<\/i>, <i class=\"fm-italics\">promise<\/i>, or <i class=\"fm-italics\">deferred value<\/i>, but in this book, we\u2019ll refer to them using the .NET\/C# term <code class=\"fm-code-in-text\">Task<\/code>.<a id=\"calibre_link-411\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-412\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><\/p>\n<p class=\"copyrightbody\">It\u2019s important to note that while it is common to create a <code class=\"fm-code-in-text\">Task<\/code> or a <code class=\"fm-code-in-text\">Task&lt;T&gt;<\/code> for code we run in the background (as we\u2019ll see in the next chapter), some classes and methods in .NET use the word task to refer to this code or to manage context information related to it. The <code class=\"fm-code-in-text\">Task<\/code> or <code class=\"fm-code-in-text\">Task&lt;T&gt;<\/code> objects themselves do not let you manage the background operation and do not carry context related to it. A <code class=\"fm-code-in-text\">Task<\/code> just lets you know when that background operation finishes running (the <code class=\"fm-code-in-text\">Task<\/code> object represents the event of the background operation ending), and <code class=\"fm-code-in-text\">Task&lt;T&gt;<\/code> adds the ability to get the result of the background operation (<code class=\"fm-code-in-text\">Task&lt;T&gt;<\/code> represents the value produced by the background operation). A <code class=\"fm-code-in-text\">Task<\/code> is not a thread or a background operation, but it is sometimes used to convey the results of a background operation. <a id=\"calibre_link-413\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-414\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-415\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-416\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><\/p>\n<p class=\"copyrightbody\">In .NET\/C# terminology, we say that the task is completed when the event represented by a <code class=\"fm-code-in-text\">Task<\/code> happens or the value represented by a <code class=\"fm-code-in-text\">Task&lt;T&gt;<\/code> is available. The <code class=\"fm-code-in-text\">Task<\/code> is also considered completed if it is marked as canceled or faulted.<a id=\"calibre_link-417\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-418\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><\/p>\n<p class=\"copyrightbody\">For example, when we call <code class=\"fm-code-in-text\">Task.Delay(1000)<\/code>, we get an object that represents an event that will happen in 1 second but has no corresponding thread or activity. In the same way, if we call <code class=\"fm-code-in-text\">File.ReadAllBytesAsync<\/code>, and, for example, there is no thread reading in the background, the system asks the disk controller (a different hardware device than the CPU) to load data and calls us when it\u2019s done, so we get back a <code class=\"fm-code-in-text\">Task&lt;byte[]&gt;<\/code> object that represents the data that will be received from the disk in the future.<a id=\"calibre_link-419\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-420\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-421\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><\/p>\n<p class=\"copyrightbody\">The <code class=\"fm-code-in-text\">Read<\/code> method we used in our example fills the buffer we gave it and returns the number of bytes that were successfully read. For compatibility and performance reasons, the <code class=\"fm-code-in-text\">ReadAsync<\/code> method works in the same way, except it returns a <code class=\"fm-code-in-text\">Task&lt;int&gt;<\/code> instead of an <code class=\"fm-code-in-text\">int<\/code>. The returned <code class=\"fm-code-in-text\">Task&lt;int&gt;<\/code> represents the number of bytes successfully read that will be available after the operation completes. Note that we should not touch the buffer we passed <code class=\"fm-code-in-text\">ReadAsync<\/code> until the operation is complete.<a id=\"calibre_link-422\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-423\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><\/p>\n<p class=\"copyrightbody\">So a <code class=\"fm-code-in-text\">Task<\/code> or <code class=\"fm-code-in-text\">Task&lt;T&gt;<\/code> object represents an event or a value that may be available in the future. When we want to know whether this event happened or the value is available yet, there are two asynchronous approaches supported by <code class=\"fm-code-in-text\">Task<\/code> and <code class=\"fm-code-in-text\">Task&lt;T&gt;<\/code>&mdash;to use a travel metaphor, there are the \u201cAre we there yet\u201d model and the \u201cWake me up when we arrive\u201d model. Furthermore, there is also the synchronous approach if you can\u2019t or don\u2019t want to use asynchronous programming.<a id=\"calibre_link-424\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-425\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-245\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><\/p>\n<h3 class=\"fm-head\" id=\"calibre_link-23\">3.2.1 Are we there yet?<\/h3>\n<p class=\"copyrightbody\">In the \u201cAre we there yet\u201d model, you are responsible for asking the <code class=\"fm-code-in-text\">Task<\/code> whether it has completed yet, usually in a loop that does other things between those checks (this is called <i class=\"fm-italics\">polling<\/i>), which is done by reading the <code class=\"fm-code-in-text\">IsCompleted<\/code> property. Note that <code class=\"fm-code-in-text\">IsCompleted<\/code> is <code class=\"fm-code-in-text\">true<\/code> even if the task has errored out or was canceled. <a id=\"calibre_link-426\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-427\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-428\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-429\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-430\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><\/p>\n<p class=\"copyrightbody\"><code class=\"fm-code-in-text\">Task<\/code> also has a <code class=\"fm-code-in-text\">Status<\/code> property we can use. The task has completed if <code class=\"fm-code-in-text\">Status<\/code> is <code class=\"fm-code-in-text\">RanToCompletion<\/code>, <code class=\"fm-code-in-text\">Canceled<\/code>, or <code class=\"fm-code-in-text\">Faulted<\/code>. Using the <code class=\"fm-code-in-text\">IsCompleted<\/code> property is better than using the <code class=\"fm-code-in-text\">Status<\/code> property because checking one condition as opposed to three is more concise and less error-prone (we will talk about canceled and faulted tasks later in this book).<a id=\"calibre_link-431\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-432\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-433\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-434\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><\/p>\n<p class=\"copyrightbody\">You should not check <code class=\"fm-code-in-text\">IsCompleted<\/code> or <code class=\"fm-code-in-text\">Status<\/code> in a loop unless you are doing other work between the checks. If most of what you do is just waiting for the task to complete, you are not only using up a thread for waiting, completely negating the advantages of asynchronous techniques, but you are also wasting CPU cycles, thus wasting resources that other code on the computer (including the work you are waiting for) could utilize for useful stuff.<\/p>\n<p class=\"copyrightbody\">This is just like asking \u201cAre we there yet?\u201d in a car. If you do it too often, you are interfering with what everyone else in the car is doing and might even arrive later if you annoy the driver.<\/p>\n<p class=\"copyrightbody\">Here\u2019s an example of using <code class=\"fm-code-in-text\">IsCompleted<\/code> in a loop to check whether the task has completed:<\/p>\n<pre class=\"programlisting\">var readCompleted = File.ReadAllBytesAsync(\"example.bin\");\nwhile(!readCompleted.IsCompleted)\n{\n   UpdateCounter();\n}\nvar bytes = readCompleted.Result;\n\/\/ do something with bytes<\/pre>\n<p class=\"copyrightbody\">In this example, the program needs to continuously update a counter while waiting for the data to arrive from the disk. So it updates the counter and checks whether the read has completed in a loop. When the data is available, it exits the loop to process the data it just received.<\/p>\n<p class=\"copyrightbody\">Most of the time, we don\u2019t have anything useful to do while waiting for <code class=\"fm-code-in-text\">IsCompleted<\/code> to become true, so this model is rarely used. In most cases (and most of this book), we will let the .NET runtime schedule and run our tasks and will not use the \u201cAre we there yet\u201d model. This is only beneficial when we have something to do while waiting and don\u2019t want to return and release the thread for some reason (we will see an example with UI threads later in this book).<\/p>\n<h3 class=\"fm-head\" id=\"calibre_link-24\">3.2.2 Wake me up when we get there<\/h3>\n<p class=\"copyrightbody\">In the \u201cWake me up when we get there\u201d model, you pass a callback method to the task, and it will call you when it\u2019s complete (or errored out or canceled). This is done by passing the callback to the <code class=\"fm-code-in-text\">ContinueWith<\/code> method.<a id=\"calibre_link-435\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-436\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-437\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-438\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-225\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-439\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><\/p>\n<p class=\"copyrightbody\">The task is passed as a parameter to the callback, so you can use it to check whether the operation completed successfully and, in the case of <code class=\"fm-code-in-text\">Task&lt;T&gt;<\/code>, read the result value:<\/p>\n<pre class=\"programlisting\">var readCompleted = File.ReadAllBytesAsync(\"example.bin\");\nreadCompleted.ContinueWith( t =&gt;\n   {\n      if(t.IsCompletedSuccessfully)\n      {\n         byte[] bytes = t.Result;\n         \/\/ do something with bytes\n      }\n   });<\/pre>\n<p class=\"copyrightbody\">Unlike the previous model, this fits the needs of our example code very well. If we take a look at just the code immediately around the first <code class=\"fm-code-in-text\">Read<\/code> call, it changes from<\/p>\n<pre class=\"programlisting\">var fileId = new byte[2];\nvar read = file.Read(fileId, 0, 2);\nif (read != 2 || fileId[0] != 'B' || fileId[1] != 'M')\n\u2026<\/pre>\n<p class=\"copyrightbody\">to<\/p>\n<pre class=\"programlisting\">var fileId = new byte[2];\nvar read = file.ReadAsync(fileId, 0, 2, CancellationToken.None).\n   ContinueWith(t=&gt;\n   {\n      if (t.Result != 2 || fileId[0] != 'B' || fileId[1] != 'M')\n\u2026<\/pre>\n<p class=\"copyrightbody\">In this case, we only replaced <code class=\"fm-code-in-text\">Read<\/code> with <code class=\"fm-code-in-text\">ReadAsync<\/code> and passed all the code that was after the <code class=\"fm-code-in-text\">Read<\/code> call into <code class=\"fm-code-in-text\">ContinueWith<\/code> as a lambda function (doing some more required changes if we use <code class=\"fm-code-in-text\">using<\/code> or <code class=\"fm-code-in-text\">throw<\/code>, but fortunately, it doesn\u2019t affect the three lines of code in this snippet&mdash;we\u2019ll talk about it later in this chapter).<\/p>\n<p class=\"copyrightbody\">Technically speaking, you can make multiple asynchronous calls by chaining <code class=\"fm-code-in-text\">ContinueWith<\/code> calls with lambdas, as shown in the example, although this tends to be unreadable and creates extremely long lines of code. For example, reading 3 bytes from a file 1 byte at a time will look like this:<\/p>\n<pre class=\"programlisting\">f.ReadAsync(buffer, 0, 1, CancellationToken.None).\n   ContinueWith( t1 =&gt;\n   {\n      f.ReadAsync(buffer, 1, 1, CancellationToken.None).\n         ContinueWith( t1 =&gt;\n         {\n             f.ReadAsync(buffer, 2, 1, CancellationToken.None).\n                ContinueWith( t1 =&gt;\n                {\n                   \/\/ finished readin 3 bytes!\n                });\n         });\n   });<\/pre>\n<p class=\"copyrightbody\">The code isn\u2019t very readable, and each <code class=\"fm-code-in-text\">ContinueWith<\/code> pushes our code farther to the right. If I wanted to change this example to read 4 or more bytes in the same way, it wouldn\u2019t fit within the width of the book\u2019s page. (Spoiler: Later in this chapter, we\u2019ll see how <code class=\"fm-code-in-text\">async<\/code>\/<code class=\"fm-code-in-text\">await<\/code> solves this problem.)<a id=\"calibre_link-440\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><\/p>\n<h3 class=\"fm-head\" id=\"calibre_link-25\">3.2.3 The synchronous option<\/h3>\n<p class=\"copyrightbody\">There is also the possibility that you will want to wait for a task in a non-asynchronous way. For example, if you write old fashion synchronous code that uses an API that only has a <code class=\"fm-code-in-text\">Task<\/code>-based asynchronous method, the best way is to call the <code class=\"fm-code-in-text\">Task.Wait<\/code> method or read the <code class=\"fm-code-in-text\">Task&lt;T&gt;.Result<\/code> property. The <code class=\"fm-code-in-text\">Wait<\/code> method and <code class=\"fm-code-in-text\">Result<\/code> property will block the current thread until the task is complete and will throw an exception if the task is canceled or errored out, making it behave like synchronous code. Note that using the <code class=\"fm-code-in-text\">Wait<\/code> method or the <code class=\"fm-code-in-text\">Result<\/code> property to wait for a task to complete is inefficient and negates the advantages of using asynchronous programming in the first place. It also might cause deadlocks in some scenarios (deadlocks make your program become stuck, and we will talk about them extensively later in the book):<a id=\"calibre_link-441\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-442\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-443\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-444\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-445\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-446\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-447\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-448\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-449\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-450\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><\/p>\n<pre class=\"programlisting\">var readCompleted = File.ReadAllBytesAsync(\"example.bin\");\nvar bytes = readCompleted.Result;                           <span class=\"fm-combinumeral\">\u2776<\/span>\n\/\/ do something with bytes<\/pre>\n<p class=\"copyrightbody\"><span class=\"fm-combinumeral\">\u2776<\/span> This will wait until the read has completed.<\/p>\n<p class=\"copyrightbody\">Generally, you would only use this approach when you had no other choice (mostly when integrating asynchronous and non-asynchronous code).<\/p>\n<h3 class=\"fm-head\" id=\"calibre_link-26\">3.2.4 After the task has completed<\/h3>\n<p class=\"copyrightbody\">After the task is completed, you need to check whether it completed successfully or not; both <code class=\"fm-code-in-text\">Task<\/code> and <code class=\"fm-code-in-text\">Task&lt;T&gt;<\/code> have the <code class=\"fm-code-in-text\">IsFaulted<\/code>, <code class=\"fm-code-in-text\">IsCanceled<\/code>, and <code class=\"fm-code-in-text\">IsCompletedSuccessfully<\/code> properties that do exactly what their name suggests. They can be used after the task is complete to check the status of the task. (It\u2019s okay to call them before the task completes; in that case, they just return <code class=\"fm-code-in-text\">false<\/code>.) If <code class=\"fm-code-in-text\">IsFaulted<\/code> is true, you can read the <code class=\"fm-code-in-text\">Exception<\/code> property to see what went wrong. <a id=\"calibre_link-451\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-452\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-453\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-454\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-455\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-456\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-457\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-241\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-458\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><\/p>\n<p class=\"copyrightbody\">In case the task is faulted, the easiest way to throw the error stored in a task so you can handle it with a normal try-catch block is to call <code class=\"fm-code-in-text\">Wait<\/code>. Calling <code class=\"fm-code-in-text\">Wait<\/code> after the task has completed is safe and will not block the thread (because the event it is waiting for has already happened). It will just return immediately if the task completed successfully or throw an exception if the task was canceled or has errored out. Because of this behavior, you don\u2019t even have to check that the task is in a faulted or canceled state (it will throw an exception if the task was completed unsuccessfully).<\/p>\n<p class=\"copyrightbody\">So if you want to check whether the task has errored out and check the exception object without throwing, you would use<\/p>\n<pre class=\"programlisting\">if(task.IsFaulted)\n   HandleError(task.Exception);<\/pre>\n<p class=\"copyrightbody\">However, if you want to check whether the task has errored out and throw the exception <i class=\"fm-italics\">only after the task has completed<\/i>, you could just use<\/p>\n<pre class=\"programlisting\">task.Wait();<\/pre>\n<p class=\"copyrightbody\">This works because, like we said, calling <code class=\"fm-code-in-text\">Task.Wait<\/code> when the task has already completed will either do nothing and return immediately or throw an exception. Note that the last two code snippets behave differently if the task was canceled (there is an entire chapter about cancellation later in the book).<\/p>\n<p class=\"copyrightbody\">The exception in the <code class=\"fm-code-in-text\">Task.Exception<\/code> property (or the exception thrown by the <code class=\"fm-code-in-text\">Wait<\/code> method or <code class=\"fm-code-in-text\">Result<\/code> property if the task is in a faulted state) will be an <code class=\"fm-code-in-text\">AggregateException<\/code>. The <code class=\"fm-code-in-text\">AggregateException<\/code> will contain the original exception in its <code class=\"fm-code-in-text\">InnerExceptions<\/code> (plural) property, which should not be confused with the <code class=\"fm-code-in-text\">InnerException<\/code> (singular) property that is inherited from <code class=\"fm-code-in-text\">Exception<\/code> and is not used in this case. <code class=\"fm-code-in-text\">AggregateException<\/code> is used here to support situations where the task represents the combination of several operations.<a id=\"calibre_link-459\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-460\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-461\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-462\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-463\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-464\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><\/p>\n<p class=\"copyrightbody\">If you know there is just one exception, and you want to access it and not the <code class=\"fm-code-in-text\">AggregateException<\/code>, you use something like<\/p>\n<pre class=\"programlisting\">If(task.IsFaulted)\n   HandleError(task.Exception.InnerExceptions[0]);<\/pre>\n<p class=\"copyrightbody\"><code class=\"fm-code-in-text\">Task&lt;T&gt;<\/code> (but not <code class=\"fm-code-in-text\">Task<\/code>) also has a <code class=\"fm-code-in-text\">Result<\/code> property that is used to get the value stored in the task. Typically, we will only read the <code class=\"fm-code-in-text\">Result<\/code> property after the task has completed (<code class=\"fm-code-in-text\">IsCompleted<\/code> is true or <code class=\"fm-code-in-text\">ContinueWith<\/code> is called). If we try to read the <code class=\"fm-code-in-text\">Result<\/code> property before the task is completed, the <code class=\"fm-code-in-text\">Result<\/code> property will block and wait until the task is completed. This is equivalent to calling <code class=\"fm-code-in-text\">Wait<\/code> and has all the same inefficiencies and dangers we talked about. If the task is in an error or canceled state, then reading <code class=\"fm-code-in-text\">Result<\/code> will throw an exception.<a id=\"calibre_link-465\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-466\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-467\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-468\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><\/p>\n<p class=\"copyrightbody\">To summarize, when using tasks without <code class=\"fm-code-in-text\">async<\/code>\/<code class=\"fm-code-in-text\">await<\/code>, you can use the <code class=\"fm-code-in-text\">IsCompleted<\/code> or <code class=\"fm-code-in-text\">Status<\/code> properties to ask \u201cAre we there yet?\u201d And just like in a car, you don\u2019t want to ask too often. You can use <code class=\"fm-code-in-text\">ContinueWith<\/code> to make the task call you when it completes (\u201cWake me up when we arrive\u201d). Finally, you can call <code class=\"fm-code-in-text\">Wait<\/code> or <code class=\"fm-code-in-text\">Result<\/code> to make the task synchronous, but that\u2019s inefficient and dangerous because it will block the thread until the task is complete (calling <code class=\"fm-code-in-text\">Wait<\/code> or <code class=\"fm-code-in-text\">Result<\/code> after the task has completed is perfectly efficient and safe because the result is already available, and there\u2019s no need for blocking).<a id=\"calibre_link-469\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-470\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><\/p>\n<p class=\"copyrightbody\">Now that we understand how <code class=\"fm-code-in-text\">Task<\/code> and <code class=\"fm-code-in-text\">Task&lt;T&gt;<\/code> work, let\u2019s see how <code class=\"fm-code-in-text\">async<\/code>\/<code class=\"fm-code-in-text\">await<\/code> makes it easier to use.<a id=\"calibre_link-471\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-472\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-473\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-474\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-475\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-476\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-477\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-478\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-147\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><\/p>\n<h2 class=\"fm-head\" id=\"calibre_link-27\">3.3 How does async\/await work?<\/h2>\n<p class=\"copyrightbody\">We\u2019ve already seen that <code class=\"fm-code-in-text\">Task<\/code> and <code class=\"fm-code-in-text\">Task&lt;T&gt;<\/code> are all we need to write asynchronous code, but writing any nontrivial code using <code class=\"fm-code-in-text\">ContinueWith<\/code> and lambdas (like in the \u201cWake me up when we get there\u201d example) gets tedious and unreadable pretty quickly. Let\u2019s copy just the part that reads the file from our \u201cget BMP width\u201d example and convert it to use <code class=\"fm-code-in-text\">ReadAsync<\/code> and <code class=\"fm-code-in-text\">ContinueWith.<\/code><code class=\"fm-code-in-text\"><a class=\"pcalibre2 pcalibre pcalibre3 pcalibre1 calibre8\" id=\"calibre_link-479\"><\/a><\/code><\/p>\n<p class=\"copyrightbody\">We will do the simplest mechanical conversion possible. Every time there is a call to <code class=\"fm-code-in-text\">Read<\/code>, we will replace it with a call to <code class=\"fm-code-in-text\">Rea<a class=\"pcalibre2 pcalibre pcalibre3 pcalibre1 calibre8\" id=\"calibre_link-480\"><\/a>dAsync<\/code> and just pass the rest of the code as a lambda function to <code class=\"fm-code-in-text\">ContinueWith<\/code>:<\/p>\n<pre class=\"programlisting\">file.ReadAsync(fileId, 0, 2,CancellationToken.None).\n   ContinueWith(firstReadTask =&gt;\n   {\n      int read = firstReadTask.Result;\n      if (read != 2 || fileId[0] != 'B' || fileId[1] != 'M')\n      {\n         \/\/ get error to caller somehow\n      }\n      file.Seek(18, SeekOrigin.Begin);\n      var widthBuffer = new byte[4];\n      file.ReadAsync(widthBuffer, 0, 4, CancellationToken.None).\n         ContinueWith(secondReadTask =&gt;\n         {\n            read = secondReadTask.Result;\n            if(read != 4) throw new Exception(\"Not a BMP file\");\n            var result = BitConverter.ToInt32(widthBuffer, 0);\n            \/\/ get result back to our caller somehow\n         });\n    });<\/pre>\n<p class=\"copyrightbody\">What a mess! What was a simple and readable method looks awful now. It is less readable because the code is divided by the <code class=\"fm-code-in-text\">async<\/code> calls and no longer follows the logic of our algorithm. And worst of all, our conversion isn\u2019t even correct! The original code had a using statement that disposed of the file on completion and on exception, so to get the same behavior, we have to wrap everything in try-catch blocks and do it ourselves (I didn\u2019t add those to the code because it\u2019s difficult to read even without it). We also need to get the exception and results to the caller, and because the lambdas are running asynchronously, we can no longer use <code class=\"fm-code-in-text\">return<\/code> and <code class=\"fm-code-in-text\">throw<\/code> to communicate with the caller of the method. Fortunately, we have <code class=\"fm-code-in-text\">async<\/code>\/<code class=\"fm-code-in-text\">await<\/code> that takes care of this for us.<a id=\"calibre_link-481\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><\/p>\n<p class=\"copyrightbody\">To rewrite our example with <code class=\"fm-code-in-text\">async<\/code>\/<code class=\"fm-code-in-text\">await<\/code> and <code class=\"fm-code-in-text\">ReadAsync<\/code>, we need to make the following changes:<\/p>\n<ul class=\"calibre9\">\n<li class=\"fm-list-bullet\">\n<p class=\"list\">First, we start by marking our method with the <code class=\"fm-code-in-text\">async<\/code> keyword, and as we\u2019ll see a bit later, this by itself does nothing.<\/p>\n<\/li>\n<li class=\"fm-list-bullet\">\n<p class=\"list\">We can no longer return an <code class=\"fm-code-in-text\">int<\/code> because as an asynchronous method, our method will return immediately and complete its work later. It\u2019s not possible to return an <code class=\"fm-code-in-text\">int<\/code> because we don\u2019t know the correct value at the time the method returns! Fortunately, we do have a way to return \u201can <code class=\"fm-code-in-text\">int<\/code> that will be available in the future\u201d&mdash;<code class=\"fm-code-in-text\">Task&lt;int&gt;<\/code>.<\/p>\n<\/li>\n<li class=\"fm-list-bullet\">\n<p class=\"list\">And finally, insert the <code class=\"fm-code-in-text\">await<\/code> keyword before every <code class=\"fm-code-in-text\">ReadAsync<\/code> call. The <code class=\"fm-code-in-text\">await<\/code> keyword tells the compiler that the code needs to be suspended at this point and resumed when whatever <code class=\"fm-code-in-text\">async<\/code> operation you are waiting for completes.<\/p>\n<\/li>\n<\/ul>\n<p class=\"copyrightbody\">The following listing shows our method with <code class=\"fm-code-in-text\">async<\/code>\/<code class=\"fm-code-in-text\">await<\/code>. Changes from the original non-<code class=\"fm-code-in-text\">async<\/code> version are in bold.<\/p>\n<p class=\"fm-code-listing-caption\">Listing 3.2 Reading the BMP width (<code class=\"fm-code-in-text1\">async<\/code> version)<\/p>\n<pre class=\"programlisting\">public <b class=\"fm-bold\">async Task&lt;<\/b>int<b class=\"fm-bold\">&gt;<\/b> GetBitmapWidth(string path)\n{\n    using (var file = new FileStream(path, FileMode.Open, FileAccess.Read))\n    {\n        var fileId = new byte[2];\n        var read = <b class=\"fm-bold\">await<\/b> file.Read<b class=\"fm-bold\">Async<\/b>(fileId, 0, 2);\n        if (read != 2 || fileId[0] != 'B' || fileId[1] != 'M')\n           throw new Exception(\"Not a BMP file\");\n        \n        file.Seek(18, SeekOrigin.Begin);\n        var widthBuffer = new byte[4];\n        read = <b class=\"fm-bold\">await<\/b> file.Read<b class=\"fm-bold\">Async<\/b>(widthBuffer, 0, 4);\n        if(read != 4) throw new Exception(\"Not a BMP file\");\n        return BitConverter.ToInt32(widthBuffer, 0);\n    }\n}<\/pre>\n<p class=\"copyrightbody\">It looks basically the same as the original non-<code class=\"fm-code-in-text\">async<\/code> version, only with the <code class=\"fm-code-in-text\">async<\/code> and <code class=\"fm-code-in-text\">await<\/code> keywords added, but it\u2019s actually very different. Let\u2019s see what the code really does.<\/p>\n<p class=\"copyrightbody\">Note that the code in listing 3.3 describes what the compiler does conceptually. The actual code generated by the compiler is very different and much more complex. I\u2019m using this simplified version because it is easier to understand while giving a good mental model of what the compiler does. At the end of this section, I\u2019ll talk about the major differences between my version and the actual compiler code.<\/p>\n<p class=\"copyrightbody\"><code class=\"fm-code-in-text\">asynch<\/code>\/<code class=\"fm-code-in-text\">await<\/code> uses the \u201cWake me up when we arrive\u201d model. It breaks the code into chunks (like the <code class=\"fm-code-in-text\">yield<\/code> <code class=\"fm-code-in-text\">return<\/code> feature from the previous chapter) and uses the task\u2019s <code class=\"fm-code-in-text\">ContinueWith<\/code> method to run the chunks at the correct time.<a id=\"calibre_link-482\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><\/p>\n<p class=\"copyrightbody\">Let\u2019s see how the compiler rewrites our code. But before exploring what the compiler does, we\u2019ll make just one tiny change: in the <code class=\"fm-code-in-text\">async<\/code>\/<code class=\"fm-code-in-text\">await<\/code> example, we returned <code class=\"fm-code-in-text\">Task&lt;int&gt;<\/code>, but we didn\u2019t talk about how you can create a <code class=\"fm-code-in-text\">Task<\/code> yet (don\u2019t worry, there is a whole chapter about it later). Instead, we\u2019re going to pass two callbacks to our method: <code class=\"fm-code-in-text\">setResult<\/code>, which will be called when our code completes successfully, and <code class=\"fm-code-in-text\">setException<\/code>, which will be called in case we get an exception.<a id=\"calibre_link-483\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-484\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><\/p>\n<p class=\"copyrightbody\">What the compiler does is separate the code after an <code class=\"fm-code-in-text\">await<\/code> into a different method (like we did with <code class=\"fm-code-in-text\">yield<\/code> <code class=\"fm-code-in-text\">return<\/code> in the previous chapter) and pass it to the Task\u2019s <code class=\"fm-code-in-text\">ContinueWith<\/code> method. To be able to share variables between the methods, we will move the local variables into a class like we did with lambda functions.<a id=\"calibre_link-226\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-485\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><\/p>\n<p class=\"fm-code-listing-caption\">Listing 3.3 Reading the BMP width (<code class=\"fm-code-in-text1\">async<\/code> with <code class=\"fm-code-in-text1\">ContinueWith<\/code> only)<\/p>\n<pre class=\"programlisting\">public void GetBitmapWidth(string path, \n        Action&lt;int&gt; setResult, Action&lt;Exception&gt; setException)\n{\n    var data = new ClassForGetBitmapWidth();\n    data.setResult = setResult;\n    data.setException = setException;\n    data.file = new FileStream(path, FileMode.Open, FileAccess.Read); <span class=\"fm-combinumeral\">\u2776<\/span>\n    try\n    {\n        data.fileId = new byte[2];                                    <span class=\"fm-combinumeral\">\u2776<\/span>\n        var read = data.file.ReadAsync(data.fileId, 0, 2).            <span class=\"fm-combinumeral\">\u2776<\/span>\n           ContinueWith(data.GetBitmapWidthStep2);                    <span class=\"fm-combinumeral\">\u2776<\/span>\n    }\n    catch(Exception ex)                                               <span class=\"fm-combinumeral\">\u2777<\/span>\n    {                                                                 <span class=\"fm-combinumeral\">\u2777<\/span>\n        data.file.Dispose();                                          <span class=\"fm-combinumeral\">\u2777<\/span>\n        setException(ex);                                             <span class=\"fm-combinumeral\">\u2777<\/span>\n    }                                                                 <span class=\"fm-combinumeral\">\u2777<\/span>\n}<\/pre>\n<p class=\"copyrightbody\"><span class=\"fm-combinumeral\">\u2776<\/span> Code from listing 3.2<\/p>\n<p class=\"copyrightbody\"><span class=\"fm-combinumeral\">\u2777<\/span> Code added to simulate the using statement<\/p>\n<p class=\"copyrightbody\">This took care of the code before the first <code class=\"fm-code-in-text\">await<\/code>. Note that our changes didn\u2019t make this part run asynchronously at all. Everything before the first <code class=\"fm-code-in-text\">await<\/code> runs like normal non-<code class=\"fm-code-in-text\">async<\/code> code. And if you have a method marked with the <code class=\"fm-code-in-text\">async<\/code> keyword without an <code class=\"fm-code-in-text\">await<\/code>, then the entire method will run as if it weren\u2019t an <code class=\"fm-code-in-text\">async<\/code> method (except that the return value will be wrapped in a <code class=\"fm-code-in-text\">Task<\/code>).<\/p>\n<p class=\"copyrightbody\">We had to replace the using statement with try-catch to make sure the file is disposed properly on exception (not try-finally because, if this part of the code succeeds, we need to keep the file open until the next part finishes).<\/p>\n<p class=\"copyrightbody\">Now for the class that we need to store the \u201clocal\u201d variables, we use<\/p>\n<pre class=\"programlisting\">private class ClassForGetBitmapWidth\n{\n   public Stream file;\n   public byte[] fileId;\n   public byte[] widthBuffer;\n   public Action&lt;int&gt; setResult;\n   public Action&lt;Exception&gt; setException;<\/pre>\n<p class=\"copyrightbody\"><a id=\"calibre_link-257\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a>In this class, the code between the first and second <code class=\"fm-code-in-text\">await<\/code> is<\/p>\n<pre class=\"programlisting\">   public void GetBitmapWidthStep2(Task&lt;int&gt; task)\n   {\n      try\n      {\n           var read = task.Result;                                <span class=\"fm-combinumeral\">\u2776<\/span>\n           if (read != 2 || fileId[0] != 'B' || fileId[1] != 'M') <span class=\"fm-combinumeral\">\u2776<\/span>\n              throw new Exception(\"Not a BMP file\");              <span class=\"fm-combinumeral\">\u2776<\/span>\n        \n           file.Seek(18, SeekOrigin.Begin);                       <span class=\"fm-combinumeral\">\u2776<\/span>\n           widthBuffer = new byte[4];                             <span class=\"fm-combinumeral\">\u2776<\/span>\n           file.ReadAsync(widthBuffer, 0, 4).                     <span class=\"fm-combinumeral\">\u2776<\/span>\n              ContinueWith(GetBitmapWidthStep3);\n       }\n       catch(Exception ex)                                        <span class=\"fm-combinumeral\">\u2777<\/span>\n       {                                                          <span class=\"fm-combinumeral\">\u2777<\/span>\n          file.Dispose();                                         <span class=\"fm-combinumeral\">\u2777<\/span>\n          setException(ex);                                       <span class=\"fm-combinumeral\">\u2777<\/span>\n       }                                                          <span class=\"fm-combinumeral\">\u2777<\/span>\n   }<\/pre>\n<p class=\"copyrightbody\"><span class=\"fm-combinumeral\">\u2776<\/span> Code from listing 3.2<\/p>\n<p class=\"copyrightbody\"><span class=\"fm-combinumeral\">\u2777<\/span> Code added to simulate the using statement<\/p>\n<p class=\"copyrightbody\">It looks like we didn\u2019t check the result of the previous operation. We didn\u2019t read the <code class=\"fm-code-in-text\">Task<\/code> <code class=\"fm-code-in-text\">IsCompletedSuccessfully<\/code> property or the <code class=\"fm-code-in-text\">Task.Status<\/code> property. Thus, we don\u2019t know if there was an error. However, reading <code class=\"fm-code-in-text\">Task.Result<\/code> will throw an exception if the task was completed unsuccessfully, so writing code to explicitly check for errors is not required. Also note that because this was called from <code class=\"fm-code-in-text\">ContinueWith<\/code>, we know the task has already completed, and we are guaranteed the task is completed and reading <code class=\"fm-code-in-text\">Result<\/code> is a nice, safe, and fast nonblocking operation.<a id=\"calibre_link-486\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-487\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><\/p>\n<p class=\"copyrightbody\">Now for the part after the last <code class=\"fm-code-in-text\">await<\/code>, we have<\/p>\n<pre class=\"programlisting\">   public void GetBitmapWidthStep3(Task&lt;int&gt; task)\n   {\n       try\n       {\n          var read = task.Result;                               <span class=\"fm-combinumeral\">\u2776<\/span>\n          if(read != 4) throw new Exception(\"Not a BMP file\");  <span class=\"fm-combinumeral\">\u2776<\/span>\n          file.Dispose();                                       <span class=\"fm-combinumeral\">\u2776<\/span>\n          var result = BitConverter.ToInt32(widthBuffer, 0);    <span class=\"fm-combinumeral\">\u2776<\/span>\n          setResult(result);                                    <span class=\"fm-combinumeral\">\u2777<\/span>\n       }\n       catch(Exception ex)                                      <span class=\"fm-combinumeral\">\u2778<\/span>\n       {                                                        <span class=\"fm-combinumeral\">\u2778<\/span>\n          file.Dispose();                                       <span class=\"fm-combinumeral\">\u2778<\/span>\n          setException(ex);                                     <span class=\"fm-combinumeral\">\u2778<\/span>\n       }                                                        <span class=\"fm-combinumeral\">\u2778<\/span>\n   }\n}<\/pre>\n<p class=\"copyrightbody\"><span class=\"fm-combinumeral\">\u2776<\/span> Code from listing 3.2<\/p>\n<p class=\"copyrightbody\"><span class=\"fm-combinumeral\">\u2777<\/span> Instead of a return statement<\/p>\n<p class=\"copyrightbody\"><span class=\"fm-combinumeral\">\u2778<\/span> Code added to simulate the using statement<\/p>\n<p class=\"copyrightbody\"><a id=\"calibre_link-163\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a>Just like we\u2019ve seen with <code class=\"fm-code-in-text\">yield return<\/code> in chapter 2, the compiler divided our function into chunks and added code to call them at the correct time. We\u2019ve also seen that the correct time for the first chunk, before the first <code class=\"fm-code-in-text\">await<\/code>, is when the method was called. Marking the method as <code class=\"fm-code-in-text\">async<\/code> does not make it asynchronous. It\u2019s just a compiler flag to tell the compiler to look for <code class=\"fm-code-in-text\">await<\/code> keywords and divide the method into chunks. In the same way, <code class=\"fm-code-in-text\">await<\/code> does not wait&mdash;it actually ends the current chunk and returns control to the caller.<\/p>\n<p class=\"copyrightbody\">As promised, here are the major differences between the code we just talked about and the code the compiler really generates:<\/p>\n<ul class=\"calibre9\">\n<li class=\"fm-list-bullet\">\n<p class=\"list\">The compiler does not divide your code into different methods. It builds a single state machine method that keeps track of the current position using a variable and uses a big switch statement to run the correct piece of code.<\/p>\n<\/li>\n<li class=\"fm-list-bullet\">\n<p class=\"list\">The compiler does not use <code class=\"fm-code-in-text\">ContinueWith<\/code>; instead, it uses an internal object called an <i class=\"fm-italics\">awaiter<\/i>. I\u2019ve chosen to use <code class=\"fm-code-in-text\">ContinueWith<\/code> because it\u2019s conceptually similar, and unless you are writing a compiler or a replacement of the .NET asynchronous framework, you don\u2019t need to know about it.<\/p>\n<\/li>\n<li class=\"fm-list-bullet\">\n<p class=\"list\"><code class=\"fm-code-in-text\">await<\/code> actually does much more than <code class=\"fm-code-in-text\">ContinueWith<\/code>. <code class=\"fm-code-in-text\">ContinueWith<\/code> just makes the callback run when the <code class=\"fm-code-in-text\">Task<\/code> is complete, while the former has other useful features that we will talk about later in this book.<a id=\"calibre_link-488\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><\/p>\n<\/li>\n<\/ul>\n<h2 class=\"fm-head\" id=\"calibre_link-28\">3.4 async void methods<\/h2>\n<p class=\"copyrightbody\">Let\u2019s say we are writing a WinForms app, and we want to add a feature that copies all the text from one file into another file when the user clicks a button. Let\u2019s also say we know those are small files, so we can just load the entire contents into memory. The code for that feature will look something like the one in the following listing.<a id=\"calibre_link-489\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><\/p>\n<p class=\"fm-code-listing-caption\">Listing 3.4 <code class=\"fm-code-in-text1\">async<\/code> event handler<\/p>\n<pre class=\"programlisting\">private async void Button1_Click(object sender, EventArgs ea)\n{\n   var text = await File.ReadAllTextAsync(\"source.txt\");\n   await File.WriteAllTextAsync(\"dest.txt\", text);\n}<\/pre>\n<p class=\"copyrightbody\">This code just asynchronously loads all the content of a file into a variable and then asynchronously writes the contents of the variable into another file. Now let\u2019s use what we\u2019ve learned in this chapter and transform it like we transformed the <code class=\"fm-code-in-text\">GetBitmapWidth<\/code> method in listing 3.3, except that this time, we must keep the event handler signature. We can\u2019t add the <code class=\"fm-code-in-text\">setResult<\/code> and <code class=\"fm-code-in-text\">setException<\/code> parameters (this is analogous to how in the <code class=\"fm-code-in-text\">async<\/code> version we had to return <code class=\"fm-code-in-text\">void<\/code> and couldn\u2019t return <code class=\"fm-code-in-text\">Task<\/code>).<a id=\"calibre_link-490\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-491\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-294\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-492\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><\/p>\n<p class=\"fm-code-listing-caption\">Listing 3.5 Compiler transformation for <code class=\"fm-code-in-text1\">async<\/code> event handler<\/p>\n<pre class=\"programlisting\">private void Button1_Click(object sender, EventArgs ea)\n{\n   var data = new ClassForButton1_Click();\n   File.ReadAllTextAsync(\"source.txt\").\n      ContinueWith(data.Button1_ClickStep2);\n}\n \nprivate class ClassForButton1_Click\n{\n   public void Button1_ClickStep2(Task&lt;string&gt; task)\n   {\n      try\n      {\n         var text = task.Result;\n         File.WriteAllTextAsync(\"dest.txt\", text).\n            ContinueWith(Button1_ClickStep3);\n      }\n      catch\n      {\n         \/\/ ?                                          <span class=\"fm-combinumeral\">\u2776<\/span>\n      }\n   }\n \n   public void Button1_ClickStep3(Task task)\n   {\n      if(task.IsFaulted)\n      {\n         \/\/ ?                                          <span class=\"fm-combinumeral\">\u2777<\/span>\n      }\n      else\n      {\n         \/\/ ?                                          <span class=\"fm-combinumeral\">\u2778<\/span>\n      }\n   }\n \n}<\/pre>\n<p class=\"copyrightbody\"><span class=\"fm-combinumeral\">\u2776<\/span> We have no way to notify that we had an exception<\/p>\n<p class=\"copyrightbody\"><span class=\"fm-combinumeral\">\u2777<\/span> We have no way to notify that we had an exception (again).<\/p>\n<p class=\"copyrightbody\"><span class=\"fm-combinumeral\">\u2778<\/span> We have no way to notify that we are done.<\/p>\n<p class=\"copyrightbody\">Because this method is simple, the transformation was also simple (but maybe just a bit tedious). We didn\u2019t even have to move any local variables into the class. However, we do have a problem: after we finish copying the data, we don\u2019t have any way to notify the rest of the program that we are done. Even worse, if there is any error, we also have no way to notify anyone. We have the three question mark comments in the code, and we don\u2019t know what to write there.<\/p>\n<p class=\"copyrightbody\">This is exactly what happens with <code class=\"fm-code-in-text\">async<\/code> methods with a <code class=\"fm-code-in-text\">void<\/code> return type. Because there is no <code class=\"fm-code-in-text\">Task<\/code>, the caller of the method has no way of knowing when the method finished running (all the ways we talked about&mdash;<code class=\"fm-code-in-text\">await<\/code>, <code class=\"fm-code-in-text\">Wait<\/code>, <code class=\"fm-code-in-text\">IsCompleted<\/code>, and even <code class=\"fm-code-in-text\">ContinueWith<\/code>&mdash;require a <code class=\"fm-code-in-text\">Task<\/code> object). This is not a problem in this case because event handlers are usually \u201cfire-and-forget\u201d operations where the caller doesn\u2019t care what the handler does or when it finishes (as long as it returns control to the caller quickly, which our code does).<a id=\"calibre_link-493\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-158\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><\/p>\n<p class=\"copyrightbody\">There is also no way to report the exception to the caller (like in the success case, there\u2019s no access to the <code class=\"fm-code-in-text\">Task.Exception<\/code> property or any other way to get to the exception because there is no <code class=\"fm-code-in-text\">Task<\/code>), but unlike the success case, this is a real problem. Some code is going to get an exception it didn\u2019t expect and most likely crash. We\u2019ll talk about all the details in the chapter about exceptions, but the solution is just to not let <code class=\"fm-code-in-text\">async void<\/code> methods throw exceptions&mdash;if you write an <code class=\"fm-code-in-text\">async void<\/code> method, you need to catch all exceptions and handle them yourself. <a id=\"calibre_link-494\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><\/p>\n<p class=\"copyrightbody\">So if this feature is so problematic, why do we have <code class=\"fm-code-in-text\">async<\/code> <code class=\"fm-code-in-text\">void<\/code> methods to begin with? The reason for <code class=\"fm-code-in-text\">async void<\/code> is event handlers. By convention, just like in our example, event handlers always have a <code class=\"fm-code-in-text\">void<\/code> return type, so if <code class=\"fm-code-in-text\">async<\/code> methods didn\u2019t support <code class=\"fm-code-in-text\">void<\/code>, we couldn\u2019t use <code class=\"fm-code-in-text\">async<\/code>\/<code class=\"fm-code-in-text\">await<\/code> in event handlers.<\/p>\n<p class=\"copyrightbody\">This brings us to the official guidance about <code class=\"fm-code-in-text\">async<\/code> <code class=\"fm-code-in-text\">void<\/code> methods: you should only use <code class=\"fm-code-in-text\">async<\/code> <code class=\"fm-code-in-text\">void<\/code> for event handlers and avoid throwing exceptions from <code class=\"fm-code-in-text\">async<\/code> <code class=\"fm-code-in-text\">void<\/code> methods. So the correct way to write the event handler from listing 3.4 is as follows.<a id=\"calibre_link-495\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><\/p>\n<p class=\"fm-code-listing-caption\">Listing 3.6 <code class=\"fm-code-in-text1\">async<\/code> event handler with error handling<\/p>\n<pre class=\"programlisting\">private async void Button1_Click(object sender, EventArgs ea)\n{\n   try\n   {\n      var text = await File.ReadAllTextAsync(\"source.txt\");\n      await File.WriteAllTextAsync(\"dest.txt\", text);\n   }\n   catch(Exception ex)\n   {\n      \/\/ Do something with the exception\n   }\n}<\/pre>\n<h2 class=\"fm-head\" id=\"calibre_link-29\">3.5 ValueTask and ValueTask&lt;T&gt;<\/h2>\n<p class=\"copyrightbody\">Certain methods are sometimes (but not always) asynchronous. For example, let\u2019s say we have a method that performs an asynchronous operation but only if it can\u2019t satisfy the request from a cache:<a id=\"calibre_link-496\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-497\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><\/p>\n<pre class=\"programlisting\">public async Task&lt;int&gt; GetValue(string request)\n{\n   if(_cache.TryGetValue(request, out var fromCache))\n   {\n      return fromCache;                                        <span class=\"fm-combinumeral\">\u2776<\/span>\n   }\n   int newValue = await GetValueFromServer(request);           <span class=\"fm-combinumeral\">\u2777<\/span>\n   return newValue;\n}<\/pre>\n<p class=\"copyrightbody\"><span class=\"fm-combinumeral\">\u2776<\/span> Returns value from cache if possible<\/p>\n<p class=\"copyrightbody\"><span class=\"fm-combinumeral\">\u2777<\/span> Otherwise performs async operation<\/p>\n<p class=\"copyrightbody\">Note that <code class=\"fm-code-in-text\">_cache<\/code> is not a <code class=\"fm-code-in-text\">Dictionary<\/code>. <code class=\"fm-code-in-text\">Dictionary<\/code> is not thread safe and is unsuitable to be used with <code class=\"fm-code-in-text\">async<\/code> methods. We\u2019ll talk about thread-safe data structures that can be used to build a thread-safe cache in chapter 13.<\/p>\n<p class=\"copyrightbody\">The <code class=\"fm-code-in-text\">GetValue<\/code> method first checks whether the requested value is in the cache. If so, it will return the value before the first time it uses <code class=\"fm-code-in-text\">await<\/code>. As we\u2019ve seen in this chapter, the code before the first <code class=\"fm-code-in-text\">await<\/code> runs non-asynchronously, so if the value is in the cache, it will be returned immediately, making the <code class=\"fm-code-in-text\">Task&lt;int&gt;<\/code> returned by the method just a very complicated wrapper for an <code class=\"fm-code-in-text\">int<\/code>. <a id=\"calibre_link-498\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><\/p>\n<p class=\"copyrightbody\">Allocating the entire <code class=\"fm-code-in-text\">Task&lt;int&gt;<\/code> object when it\u2019s not required is obviously wasteful, and it would have been better if we could return an <code class=\"fm-code-in-text\">int<\/code> if the value could be returned immediately and only return the full <code class=\"fm-code-in-text\">Task<\/code> when we need to perform an asynchronous operation. This is what <code class=\"fm-code-in-text\">ValueTask&lt;T&gt;<\/code> is. <code class=\"fm-code-in-text\">ValueTask&lt;T&gt;<\/code> is a <code class=\"fm-code-in-text\">struct<\/code> that contains the value directly if the value is available immediately and a reference to a <code class=\"fm-code-in-text\">Task&lt;T&gt;<\/code> otherwise. The nongeneric <code class=\"fm-code-in-text\">ValueTask<\/code> is the same, except it only contains a flag saying the operation has completed and not the value.<a id=\"calibre_link-499\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><\/p>\n<p class=\"copyrightbody\">You can await a <code class=\"fm-code-in-text\">ValueTask<\/code> or a <code class=\"fm-code-in-text\">ValueTask&lt;T&gt;<\/code>, just like <code class=\"fm-code-in-text\">Task<\/code> and <code class=\"fm-code-in-text\">Task&lt;T&gt;<\/code>. They also have most of the properties of <code class=\"fm-code-in-text\">Task<\/code> and <code class=\"fm-code-in-text\">Task&lt;T&gt;<\/code>. If you want to use a feature of <code class=\"fm-code-in-text\">Task<\/code> that is not available in <code class=\"fm-code-in-text\">ValueTask<\/code> (for example, <code class=\"fm-code-in-text\">Wait<\/code>), you can use the <code class=\"fm-code-in-text\">ValueTask.AsTask()<\/code> method to get the <code class=\"fm-code-in-text\">Task<\/code> stored inside a <code class=\"fm-code-in-text\">ValueTask<\/code>.<a id=\"calibre_link-500\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><\/p>\n<p class=\"copyrightbody\"><code class=\"fm-code-in-text\">ValueTask<\/code> and <code class=\"fm-code-in-text\">ValueTask&lt;T&gt;<\/code> are slightly less efficient than <code class=\"fm-code-in-text\">Task<\/code> and <code class=\"fm-code-in-text\">Task&lt;T&gt;<\/code> if there is an asynchronous operation, but much more efficient if the result was available immediately. It is recommended to return a <code class=\"fm-code-in-text\">ValueTask<\/code> in methods that usually return a value without performing an asynchronous operation, especially if those methods are called often.<\/p>\n<h2 class=\"fm-head\" id=\"calibre_link-30\">3.6 What about multithreading?<\/h2>\n<p class=\"copyrightbody\"><a id=\"calibre_link-157\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a>In chapter 1, I said that asynchronous programming and multithreading work very well together. Yet in this entire chapter, we didn\u2019t talk about multithreading at all. Also, I said the callback you pass to <code class=\"fm-code-in-text\">ContinueWith<\/code> will run later, but we completely ignored how and where the callback will run. This leads us to the next chapter, which covers multithreading. <a id=\"calibre_link-501\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-502\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><\/p>\n<h2 class=\"fm-head\" id=\"calibre_link-503\">Summary<\/h2>\n<ul class=\"calibre9\">\n<li class=\"fm-list-bullet\">\n<p class=\"list\"><code class=\"fm-code-in-text\">Task<\/code> represents an event that may happen in the future.<\/p>\n<\/li>\n<li class=\"fm-list-bullet\">\n<p class=\"list\"><code class=\"fm-code-in-text\">Task&lt;T&gt;<\/code> represents a value that may be available in the future.<\/p>\n<\/li>\n<li class=\"fm-list-bullet\">\n<p class=\"list\">When the event happens or the value is available, we say that the <code class=\"fm-code-in-text\">Task<\/code> or <code class=\"fm-code-in-text\">Task&lt;T&gt;<\/code> has completed.<\/p>\n<\/li>\n<li class=\"fm-list-bullet\">\n<p class=\"list\">The <code class=\"fm-code-in-text\">IsCompleted<\/code> or <code class=\"fm-code-in-text\">Status<\/code> properties can be used to test whether the task has completed.<\/p>\n<\/li>\n<li class=\"fm-list-bullet\">\n<p class=\"list\">Use <code class=\"fm-code-in-text\">ContinueWith<\/code> to make the task call you when it completes.<\/p>\n<\/li>\n<li class=\"fm-list-bullet\">\n<p class=\"list\">You can call <code class=\"fm-code-in-text\">Wait<\/code> or <code class=\"fm-code-in-text\">Result<\/code> to make the task synchronous, but that\u2019s inefficient and dangerous.<\/p>\n<\/li>\n<li class=\"fm-list-bullet\">\n<p class=\"list\">Calling <code class=\"fm-code-in-text\">Wait<\/code> or <code class=\"fm-code-in-text\">Result<\/code> after the task has completed is perfectly efficient and safe.<\/p>\n<\/li>\n<li class=\"fm-list-bullet\">\n<p class=\"list\"><code class=\"fm-code-in-text\">async<\/code> is just a compiler flag. It tells the compiler that the method needs to be broken into chunks whenever there\u2019s an <code class=\"fm-code-in-text\">await<\/code> keyword.<\/p>\n<\/li>\n<li class=\"fm-list-bullet\">\n<p class=\"list\">The <code class=\"fm-code-in-text\">async<\/code> keyword does not make the code run in the background. Without <code class=\"fm-code-in-text\">await<\/code>, it does nothing (except make the compiler generate an awful lot of boilerplate code).<\/p>\n<\/li>\n<li class=\"fm-list-bullet\">\n<p class=\"list\">The compiler breaks the method after each <code class=\"fm-code-in-text\">await<\/code> and passes the next chunk to <code class=\"fm-code-in-text\">ContinueWith<\/code> (conceptually).<\/p>\n<\/li>\n<li class=\"fm-list-bullet\">\n<p class=\"list\"><code class=\"fm-code-in-text\">await<\/code> does not wait but ends the current chunk and returns to the caller.<\/p>\n<\/li>\n<li class=\"fm-list-bullet\">\n<p class=\"list\"><code class=\"fm-code-in-text\">async<\/code> methods can be <code class=\"fm-code-in-text\">void<\/code>, but then there\u2019s no way to know when the method has finished, and you should catch and handle all exceptions inside the method.<\/p>\n<\/li>\n<li class=\"fm-list-bullet\">\n<p class=\"list\">If an <code class=\"fm-code-in-text\">async<\/code> method often returns a result immediately without doing anything asynchronous, you can improve the efficiency by returning <code class=\"fm-code-in-text\">ValueTask<\/code> or <code class=\"fm-code-in-text\">ValueTask&lt;T&gt;<\/code> instead of <code class=\"fm-code-in-text\">Task<\/code> or <code class=\"fm-code-in-text\">Task&lt;T&gt;<\/code>.<a id=\"calibre_link-504\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><\/p>\n<\/li>\n<\/ul>\n<\/div>\n<\/div>\n<\/div>\n<div class=\"calibre1\" id=\"calibre_link-31\">\n<div id=\"calibre_link-505\" class=\"calibre2\">\n<div id=\"calibre_link-506\" class=\"calibre3\">\n<h1 class=\"copyrighta\" id=\"calibre_link-507\">4 <a id=\"calibre_link-508\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-509\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-510\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-511\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a>Multithreading basics<\/h1>\n<p class=\"copyrightbody\"><a id=\"calibre_link-275\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a>This chapter covers<a id=\"calibre_link-512\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><\/p>\n<ul class=\"calibre9\">\n<li class=\"co-summary-bullet\">The basics of threads<\/li>\n<li class=\"co-summary-bullet\">Starting threads<\/li>\n<li class=\"co-summary-bullet\">Waiting for threads<\/li>\n<li class=\"co-summary-bullet\">Accessing shared data and using locks<\/li>\n<li class=\"co-summary-bullet\">The basics of deadlocks<\/li>\n<\/ul>\n<p class=\"copyrightbody\">Chapter 1 discussed how a system can run multiple pieces of code simultaneously&mdash;much more than the number of CPU cores&mdash;by quickly switching between them. This functionality is made possible by a hardware timer inside the CPU. Each time the timer ticks, the operating system can pause the currently running code and switch to another piece of code. If the switching is fast enough, it creates the illusion that all threads are running simultaneously.<\/p>\n<p class=\"copyrightbody\">This chapter explores how to use threads for parallel execution and discusses key aspects of concurrent programming. In the next chapter, we will connect these topics to the <code class=\"fm-code-in-text\">async<\/code>\/<code class=\"fm-code-in-text\">await<\/code> feature.<\/p>\n<p class=\"copyrightbody\">When a process starts, it begins with one thread that runs the <code class=\"fm-code-in-text\">Main<\/code> method (along with a few other system-controlled threads, which we will set aside for now). This initial thread is referred to as the main thread. We will now look at how to utilize additional threads to allow multiple pieces of code to run simultaneously.<a id=\"calibre_link-513\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><\/p>\n<h2 class=\"fm-head\" id=\"calibre_link-32\">4.1 Different ways to run in another thread<\/h2>\n<p class=\"copyrightbody\">Now that we\u2019ve decided we want to run code in parallel, we need to talk about how to do it. This section covers the three most common ways to run code in another thread in C#. We will start with the oldest and most flexible option&mdash;creating your own thread.<a id=\"calibre_link-514\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-515\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-272\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><\/p>\n<h3 class=\"fm-head\" id=\"calibre_link-33\">4.1.1 Thread.Start<\/h3>\n<p class=\"copyrightbody\">In .NET, a thread is represented by the appropriately named <code class=\"fm-code-in-text\">System.Threading.Thread<\/code> class. This class lets you inspect and control existing threads, as well as create new ones.<a id=\"calibre_link-516\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-517\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-518\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-519\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><\/p>\n<p class=\"copyrightbody\">To create a new thread, you first create a new <code class=\"fm-code-in-text\">Thread<\/code> object, passing a callback with the code you want to run in the new thread to the constructor. After that, you have a chance to configure the thread before it starts running. Finally, you call <code class=\"fm-code-in-text\">Thread.Start<\/code> to start the thread. In the following listing, we are going to create and configure a thread.<\/p>\n<p class=\"fm-code-listing-caption\">Listing 4.1 Creating a thread<\/p>\n<pre class=\"programlisting\">public void RunInBackground()\n{\n   var newThread = new Thread(CodeToRunInBackgroundThread);        <span class=\"fm-combinumeral\">\u2776<\/span>\n   newThread.IsBackground = true;                                  <span class=\"fm-combinumeral\">\u2777<\/span>\n   newThread.Start();                                              <span class=\"fm-combinumeral\">\u2778<\/span>\n} \n  \nprivate void CodeToRunInBackgroundThread()                         <span class=\"fm-combinumeral\">\u2779<\/span>\n{\n   Console.WriteLine(\"Do stuff\");\n}<\/pre>\n<p class=\"copyrightbody\"><span class=\"fm-combinumeral\">\u2776<\/span> Creates thread object<\/p>\n<p class=\"copyrightbody\"><span class=\"fm-combinumeral\">\u2777<\/span> Configures thread<\/p>\n<p class=\"copyrightbody\"><span class=\"fm-combinumeral\">\u2778<\/span> Starts running<\/p>\n<p class=\"copyrightbody\"><span class=\"fm-combinumeral\">\u2779<\/span> Code to run in new thread<\/p>\n<p class=\"copyrightbody\">As you can see, this code example follows exactly the described steps:<\/p>\n<ol class=\"calibre9\">\n<li class=\"fm-list-bullet1\">\n<p class=\"list\">We created a thread, passing the method we want to run in that thread to the constructor.<\/p>\n<\/li>\n<li class=\"fm-list-bullet1\">\n<p class=\"list\">We configured the thread, in this case by making it a background thread (we\u2019ll talk about background threads later in the book). This step is optional.<\/p>\n<\/li>\n<li class=\"fm-list-bullet1\">\n<p class=\"list\">We started the thread by calling <code class=\"fm-code-in-text\">Thread.Start<\/code>.<\/p>\n<\/li>\n<\/ol>\n<p class=\"copyrightbody\">The <code class=\"fm-code-in-text\">Thread<\/code> class constructor has two versions that each accept a different delegate. There\u2019s the simple version we used in this example that accepts a <code class=\"fm-code-in-text\">void<\/code> method with no parameters, and there is also a parameterized version that accepts a <code class=\"fm-code-in-text\">void<\/code> method that takes one parameter of type <code class=\"fm-code-in-text\">object<\/code>. <a id=\"calibre_link-520\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-521\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><\/p>\n<p class=\"copyrightbody\">The <code class=\"fm-code-in-text\">Thread.Start<\/code> method also has two corresponding versions: one that has no parameters and one that accepts a parameter of type <code class=\"fm-code-in-text\">object<\/code>. If you use the second version of both, you can pass whatever object you want to your thread code by passing it to <code class=\"fm-code-in-text\">Thread.Start<\/code>. <a id=\"calibre_link-522\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><\/p>\n<p class=\"copyrightbody\">This option lets you write a single method for threads doing slightly different things and pass a different parameter value to each thread to differentiate between them. For example, let\u2019s create 100 threads and pass a different number to each.<\/p>\n<p class=\"fm-code-listing-caption\">Listing 4.2 Creating a thread with a parameter<\/p>\n<pre class=\"programlisting\">public void RunLotsOfThreads()\n{\n   var threads = new Thread[100];\n   for(int i=0;i&lt;100;++i)\n   {\n      threads[i] = new Thread(MyThread);\n      threads[i].Start(i);                                   <span class=\"fm-combinumeral\">\u2776<\/span>\n   }\n}\nprivate void MyThread(object? parameter)\n{\n   Console.WriteLine($\"Hello from thread {parameter}\");      <span class=\"fm-combinumeral\">\u2777<\/span>\n}<\/pre>\n<p class=\"copyrightbody\"><span class=\"fm-combinumeral\">\u2776<\/span> Passes a value per thread<\/p>\n<p class=\"copyrightbody\"><span class=\"fm-combinumeral\">\u2777<\/span> Uses that value<\/p>\n<p class=\"copyrightbody\">In this listing, we just passed our loop index to <code class=\"fm-code-in-text\">Thread.Start<\/code>, and it was conveniently provided to our <code class=\"fm-code-in-text\">MyThread<\/code> method when it started running in the new thread.<a id=\"calibre_link-265\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-523\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><\/p>\n<p class=\"copyrightbody\">Mixing it up by passing a non-parameterized method to the <code class=\"fm-code-in-text\">Thread<\/code> constructor and then using the parameterized version of <code class=\"fm-code-in-text\">Thread.Start<\/code>, or vice versa, doesn\u2019t make much sense but is fully supported. If you use the parameterized delegate and the non-parametrized <code class=\"fm-code-in-text\">Thread.Start<\/code>, your method parameter value will be <code class=\"fm-code-in-text\">null<\/code>. If you use the non-parametrized delegate and the parameterized <code class=\"fm-code-in-text\">Thread.Start<\/code>, the value will be ignored.<\/p>\n<p class=\"copyrightbody\">The <code class=\"fm-code-in-text\">Thread<\/code> class also contains a method that will wait until the thread completes its work, called <code class=\"fm-code-in-text\">Join<\/code>. <i class=\"fm-italics\">Join<\/i> is the standard computer science term for waiting for a thread. I\u2019ve found conflicting stories about the origin of this term, all of them using metaphors that I don\u2019t want to repeat here because they don\u2019t work that well. We\u2019ll just have to accept that in this context, <i class=\"fm-italics\">join<\/i> means <i class=\"fm-italics\">wait<\/i>.<a id=\"calibre_link-524\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><\/p>\n<p class=\"copyrightbody\">The <code class=\"fm-code-in-text\">Join<\/code> method is very useful when we want to run several threads in parallel and then, after they all finish, do something like combining the results from multiple threads. <code class=\"fm-code-in-text\">Thread.Join<\/code> will return immediately if the thread has already finished. In the following listing, we run three threads and wait for them all to finish before notifying the user we are done.<a id=\"calibre_link-525\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><\/p>\n<p class=\"fm-code-listing-caption\">Listing 4.3 Waiting for threads to finish<\/p>\n<pre class=\"programlisting\">public void RunAndWait()\n{\n   var threads = new Thread[3];\n   for(int i=0;i&lt;3;++i)                                      <span class=\"fm-combinumeral\">\u2776<\/span>\n   {\n      threads[i] = new Thread(DoWork);\n      threads[i].Start();\n   }\n   foreach(var current in threads)                           <span class=\"fm-combinumeral\">\u2777<\/span>\n   {\n      current.Join();\n   }\n   Console.WriteLine(\"Finished\");\n}\n \nprivate void DoWork()\n{\n   Console.WriteLine(\"Doing work\");\n}<\/pre>\n<p class=\"copyrightbody\"><span class=\"fm-combinumeral\">\u2776<\/span> Runs all threads<\/p>\n<p class=\"copyrightbody\"><span class=\"fm-combinumeral\">\u2777<\/span> Waits for threads to finish<\/p>\n<p class=\"copyrightbody\">Here we start three threads in one loop and then wait for them in a second loop. It\u2019s important that those are two separate loops because we want to start all threads and only then wait for all of them. We don\u2019t want to start and wait repeatedly, as that would cause sequential execution, just with threading overhead (this problem is called <i class=\"fm-italics\">synchronization<\/i>, and we will discuss it in chapter 7).<\/p>\n<p class=\"copyrightbody\">The second loop looks like it depends on the order of the threads in the list, but it doesn\u2019t. It doesn\u2019t matter in what order we wait for the threads. If the longest-running thread is the first, we will wait for it to complete, and then the <code class=\"fm-code-in-text\">Join<\/code> calls for the other already finished threads will return immediately. If the longest-running thread is the last, the loop will wait for the first thread, and when it finishes, it will wait for the next one until it gets to the last one. In both cases, the loop will wait until the longest running of the threads finishes.<\/p>\n<p class=\"copyrightbody\">The <code class=\"fm-code-in-text\">Thread<\/code> class also has other methods that let us control threads: <code class=\"fm-code-in-text\">Suspend<\/code>, <code class=\"fm-code-in-text\">Resume<\/code>, and <code class=\"fm-code-in-text\">Abort<\/code>. Those may seem handy at first, but they are in fact extremely dangerous, and you should never use them. You will discover why later in the chapter.<a id=\"calibre_link-526\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-527\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-528\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-141\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-529\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><\/p>\n<p class=\"copyrightbody\">Using the <code class=\"fm-code-in-text\">Thread<\/code> class and <code class=\"fm-code-in-text\">Thread.Start<\/code> is the only way to get a thread that is completely under your control, and you can do whatever you want with it without interfering with other code running in your app.<\/p>\n<p class=\"copyrightbody\">Creating and destroying threads is relatively resource intensive, and if you create a lot of threads where each thread does just a little bit of work, your app might spend more time managing threads than doing actual useful work.<\/p>\n<p class=\"copyrightbody\">This affects asynchronous code because even if it takes a long time to complete, it is usually composed of many short parts. For example, the following method performs two asynchronous operations:<\/p>\n<pre class=\"programlisting\">private async Task SoSomethingComplicated()\n{\n   await DoFirstPart();\n   await DoSecondPart();\n}<\/pre>\n<p class=\"copyrightbody\">When this method starts, it will get to the <code class=\"fm-code-in-text\">DoFirstPart<\/code> call and then return control to its caller as soon as <code class=\"fm-code-in-text\">DoFirstPart<\/code> does something asynchronous (and the caller is likely to be using <code class=\"fm-code-in-text\">await<\/code> and do the same until there are no more callers and the thread is released). When the asynchronous operation is complete, the method will resume, requiring a thread run for just long enough to get to the <code class=\"fm-code-in-text\">DoSecondPart<\/code> call and release the thread again. Later, when <code class=\"fm-code-in-text\">DoSecondPart<\/code> completes, the method will resume, requiring a thread again. If this involved creating and destroying threads, there would have been two thread destructions and two thread creations involved. <a id=\"calibre_link-530\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-531\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><\/p>\n<p class=\"copyrightbody\">Short tasks have the same problem. If we spin up a thread to run just a quick, tiny calculation, we can easily find ourselves wasting a significant amount of time creating and destroying the thread relative to actually doing useful work. And that brings us to our next topic&mdash;the thread pool.<a id=\"calibre_link-532\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-533\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-534\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><\/p>\n<div class=\"fm-sidebar-block\">\n<p class=\"fm-sidebar-title\">When to use Thread.Start<\/p>\n<p class=\"copyrightbody\">Use <code class=\"fm-code-in-text\">Thread.Start<\/code> for<\/p>\n<ul class=\"calibre9\">\n<li class=\"fm-list-bullet2\">\n<p class=\"list\">Long-running code.<\/p>\n<\/li>\n<li class=\"fm-list-bullet2\">\n<p class=\"list\">If you need to change the thread properties such as language and locale information, background status, COM apartment, etc. (We\u2019ll talk about all the thread settings near the end of this chapter.)<\/p>\n<\/li>\n<\/ul>\n<p class=\"copyrightbody\">Do not use <code class=\"fm-code-in-text\">Thread.Start<\/code> for<\/p>\n<ul class=\"calibre9\">\n<li class=\"fm-list-bullet2\">\n<p class=\"list\">Asynchronous code<\/p>\n<\/li>\n<li class=\"fm-list-bullet2\">\n<p class=\"list\">Short tasks<\/p>\n<\/li>\n<\/ul><\/div>\n<h3 class=\"fm-head\" id=\"calibre_link-34\">4.1.2 The thread pool<\/h3>\n<p class=\"copyrightbody\"><a id=\"calibre_link-288\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a>The thread pool is the solution for the thread creation and destruction overhead we talked about. With the thread pool, the system keeps a small number of threads waiting in the background, and whenever you have something to run, you can use one of those pre-existing threads to run it. The system automatically manages those threads and creates new ones when needed (between a minimum and maximum number of threads you control).<a id=\"calibre_link-535\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-536\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-537\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><\/p>\n<p class=\"copyrightbody\">The thread pool is optimized for short-running tasks where the same thread can pick up multiple tasks one after the other. If you use the thread pool for a long-running task, you are taking a thread out of rotation for a long time, and when all the threads in the pool are busy, new work must wait until one of the threads frees up.<\/p>\n<p class=\"copyrightbody\">Also, because you are \u201cborrowing\u201d a thread, you should not change any of its properties, since any change will affect future code that runs in that same thread (just like you wouldn\u2019t rearrange someone\u2019s furniture if you\u2019re just visiting). If you need to change the thread properties, you must create the thread with the <code class=\"fm-code-in-text\">Thread<\/code> class.<\/p>\n<p class=\"copyrightbody\">The thread pool is controlled by the appropriately named <code class=\"fm-code-in-text\">System.Threading.ThreadPool<\/code> class. To run something on the thread pool, you will use the less-appropriately named <code class=\"fm-code-in-text\">QueueUserWorkItem<\/code> method.<a id=\"calibre_link-538\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-539\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><\/p>\n<p class=\"fm-code-listing-caption\">Listing 4.4 Running in the thread pool<\/p>\n<pre class=\"programlisting\">public void RunInBackground()\n{\n   ThreadPool.QueueUserWorkItem(RunInPool);           <span class=\"fm-combinumeral\">\u2776<\/span>\n} \n \nprivate void RunInPool(object? state)                 <span class=\"fm-combinumeral\">\u2777<\/span>\n{\n   Console.WriteLine(\"Do stuff\");\n}<\/pre>\n<p class=\"copyrightbody\"><span class=\"fm-combinumeral\">\u2776<\/span> Queues code to run in thread pool<\/p>\n<p class=\"copyrightbody\"><span class=\"fm-combinumeral\">\u2777<\/span> Code to run<\/p>\n<p class=\"copyrightbody\">The code is similar to that in listing 4.1, but we can\u2019t change the thread configuration (because we are borrowing an existing thread) and don\u2019t have to manually start the thread (because the thread is already running).<\/p>\n<p class=\"copyrightbody\">Like <code class=\"fm-code-in-text\">Thread.Start<\/code>, <code class=\"fm-code-in-text\">QueueUserWorkItem<\/code> also has a parametrized and a non-parametrized version. But unlike the <code class=\"fm-code-in-text\">Thread<\/code> class, the method that runs on the thread pool always accepts an object parameter; if you use the non-parameterized <code class=\"fm-code-in-text\">QueueUserWorkItem<\/code>, the parameter will be <code class=\"fm-code-in-text\">null<\/code>. Let\u2019s rewrite the code from listing 4.2 to use the thread pool.<a id=\"calibre_link-266\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><\/p>\n<p class=\"fm-code-listing-caption\">Listing 4.5 Running in the thread pool with a parameter<\/p>\n<pre class=\"programlisting\">public void RunInBackground()\n{\n   for(int i=0;i&lt;10;++i)\n   {\n      ThreadPool.QueueUserWorkItem(RunInPool,i);           <span class=\"fm-combinumeral\">\u2776<\/span>\n   }\n}\n \nprivate void RunInPool(object? parameter)                  <span class=\"fm-combinumeral\">\u2777<\/span>\n{\n   Console.WriteLine($\"Hello from thread {parameter}\");\n}<\/pre>\n<p class=\"copyrightbody\"><span class=\"fm-combinumeral\">\u2776<\/span> Passes a value to the thread<\/p>\n<p class=\"copyrightbody\"><span class=\"fm-combinumeral\">\u2777<\/span> The value is received in the parameter.<\/p>\n<p class=\"copyrightbody\">The code in this example is unsurprising&mdash;it\u2019s exactly like code from listing 4.2, except we don\u2019t have to start the thread manually.<\/p>\n<p class=\"copyrightbody\">Unlike the <code class=\"fm-code-in-text\">Thread<\/code> class with its <code class=\"fm-code-in-text\">Join<\/code> method, the thread pool does not give us a built-in way to wait until the code we run on it ends. We will see later in this chapter how we can build our own way to wait until the background code completes.<a id=\"calibre_link-540\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-541\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><\/p>\n<p class=\"copyrightbody\">This chapter talks about the thread pool. There is one thread pool created for you by the framework, and all the examples here use it. However, you can easily create your own thread pools, but you probably shouldn\u2019t.<\/p>\n<p class=\"copyrightbody\">The thread pool interface is old and clunky (for example, you use a method named <code class=\"fm-code-in-text\">QueueUserWorkItem<\/code>) and doesn\u2019t work well with <code class=\"fm-code-in-text\">Tasks<\/code> and <code class=\"fm-code-in-text\">async<\/code>-<code class=\"fm-code-in-text\">await<\/code> (because it predates them by a decade), which is why we have <code class=\"fm-code-in-text\">Task.Run.<\/code><\/p>\n<div class=\"fm-sidebar-block\">\n<p class=\"fm-sidebar-title\">When to use ThreadPool.QueueUesrWorkItem<\/p>\n<p class=\"copyrightbody\">Use <code class=\"fm-code-in-text\">ThreadPool.QueueUesrWorkItem<\/code> for<\/p>\n<ul class=\"calibre9\">\n<li class=\"fm-list-bullet2\">\n<p class=\"list\">Short-running tasks<\/p>\n<\/li>\n<\/ul>\n<p class=\"copyrightbody\">Do not use <code class=\"fm-code-in-text\">ThreadPool.QueueUesrWorkItem<\/code><\/p>\n<ul class=\"calibre9\">\n<li class=\"fm-list-bullet2\">\n<p class=\"list\">For long-running tasks<\/p>\n<\/li>\n<li class=\"fm-list-bullet2\">\n<p class=\"list\">When you need to change the thread properties<\/p>\n<\/li>\n<li class=\"fm-list-bullet2\">\n<p class=\"list\">With <code class=\"fm-code-in-text\">Task<\/code>-based asynchronous operations<\/p>\n<\/li>\n<li class=\"fm-list-bullet2\">\n<p class=\"list\">With <code class=\"fm-code-in-text\">async<\/code>\/<code class=\"fm-code-in-text\">await<\/code><\/p>\n<\/li>\n<\/ul><\/div>\n<h3 class=\"fm-head\" id=\"calibre_link-35\">4.1.3 Task.Run<\/h3>\n<p class=\"copyrightbody\">We\u2019ve seen that the thread pool is optimized to run many short-running tasks, and we know that asynchronous tasks are actually a sequence of short tasks, so the thread pool is ideal for running asynchronous code, except that the <code class=\"fm-code-in-text\">QueueUserWorkItem<\/code> method doesn\u2019t use the <code class=\"fm-code-in-text\">Ta<a class=\"pcalibre2 pcalibre pcalibre3 pcalibre1 calibre8\" id=\"calibre_link-542\"><\/a>sk<\/code> class (because it predates <code class=\"fm-code-in-text\">async<\/code>\/<code class=\"fm-code-in-text\">await<\/code> and <code class=\"fm-code-in-text\">Task<\/code> by about a decade). This is why we have <code class=\"fm-code-in-text\">Task.Run<\/code>.<a id=\"calibre_link-543\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-544\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-545\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-546\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-289\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><\/p>\n<p class=\"copyrightbody\">The <code class=\"fm-code-in-text\">Task.Run<\/code> method runs code on the thread pool, just like <code class=\"fm-code-in-text\">ThreadPool.QueueUserWorkItem<\/code>, but it has a nicer interface that works well with <code class=\"fm-code-in-text\">async<\/code>\/<code class=\"fm-code-in-text\">await<\/code>. For the simple scenario, it works basically the same as in the previous example.<\/p>\n<p class=\"fm-code-listing-caption\">Listing 4.6 Running in the thread pool with <code class=\"fm-code-in-text1\">Task.Run<\/code><\/p>\n<pre class=\"programlisting\">public void RunInBackground()\n{\n    Task.Run(RunInPool);                           <span class=\"fm-combinumeral\">\u2776<\/span>\n} \n \nprivate void RunInPool()                           <span class=\"fm-combinumeral\">\u2777<\/span>\n{\n   Console.WriteLine(\"Do stuff\");\n}<\/pre>\n<p class=\"copyrightbody\"><span class=\"fm-combinumeral\">\u2776<\/span> Queue code to run in thread pool<\/p>\n<p class=\"copyrightbody\"><span class=\"fm-combinumeral\">\u2777<\/span> Code to run<\/p>\n<p class=\"copyrightbody\">The code is the same as the thread pool example in listing 4.4, except <code class=\"fm-code-in-text\">ThreadPool<\/code><code class=\"fm-code-in-text\">.<\/code><code class=\"fm-code-in-text\">QueueUserWorkIte<\/code><code class=\"fm-code-in-text\">m<\/code> was replaced with <code class=\"fm-code-in-text\">Task.Run<\/code>. But unlike with the <code class=\"fm-code-in-text\">ThreadPool<\/code> class, <code class=\"fm-code-in-text\">Task.Run<\/code> works very well with <code class=\"fm-code-in-text\">async<\/code>\/<code class=\"fm-code-in-text\">await<\/code> (and other methods that return a <code class=\"fm-code-in-text\">Task<\/code>).<a id=\"calibre_link-547\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><\/p>\n<p class=\"fm-code-listing-caption\">Listing 4.7 Running <code class=\"fm-code-in-text1\">async<\/code> code with <code class=\"fm-code-in-text1\">Task.Run<\/code><\/p>\n<pre class=\"programlisting\">public void RunInBackground()\n{\n   Task.Run(RunInPool);                            <span class=\"fm-combinumeral\">\u2776<\/span>\n} \n \nprivate async Task RunInPool()                     <span class=\"fm-combinumeral\">\u2777<\/span>\n{\n   await Task.Delay(500);\n   Console.WriteLine(\"Did async stuff\");\n}<\/pre>\n<p class=\"copyrightbody\"><span class=\"fm-combinumeral\">\u2776<\/span> Queues code to run in thread pool<\/p>\n<p class=\"copyrightbody\"><span class=\"fm-combinumeral\">\u2777<\/span> Code to run<\/p>\n<p class=\"copyrightbody\">As you can see from the code, it just works. We didn\u2019t have to do anything special to run an <code class=\"fm-code-in-text\">async<\/code> method with <code class=\"fm-code-in-text\">Task.Run<\/code>.<a id=\"calibre_link-548\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><\/p>\n<p class=\"copyrightbody\">Also, <code class=\"fm-code-in-text\">Task.Run<\/code> returns a <code class=\"fm-code-in-text\">Task<\/code> itself, and we can use it to know when the code we run on the thread pool is finished&mdash;a feature the <code class=\"fm-code-in-text\">ThreadPool<\/code> class does not have. Here\u2019s an adaptation of the example from listing 4.3 that creates multiple threads with the <code class=\"fm-code-in-text\">Thread<\/code> class and waits for all of them to finish.<a id=\"calibre_link-549\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-300\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-550\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><\/p>\n<p class=\"fm-code-listing-caption\">Listing 4.8 Waiting for tasks to finish with <code class=\"fm-code-in-text1\">Task.Run<\/code><\/p>\n<pre class=\"programlisting\">public async Task RunInBackground()\n{\n   var tasks = new Task[10];\n   for(int i=0;i&lt;10;++i) \n   {\n      tasks[i] = Task.Run(RunInPool);                   <span class=\"fm-combinumeral\">\u2776<\/span>\n   }\n   await Task.WhenAll(tasks);                           <span class=\"fm-combinumeral\">\u2777<\/span>\n   Console.WriteLine(\"All finished\");\n}\n \nprivate void RunInPool() \n{\n   Console.WriteLine(\"Do stuff\");\n}<\/pre>\n<p class=\"copyrightbody\"><span class=\"fm-combinumeral\">\u2776<\/span> Queues tasks to run on thread pool<\/p>\n<p class=\"copyrightbody\"><span class=\"fm-combinumeral\">\u2777<\/span> Waits for tasks to complete<\/p>\n<p class=\"copyrightbody\">Here we can wait with the <code class=\"fm-code-in-text\">Task.WhenAll<\/code> method that is much more elegant than the <code class=\"fm-code-in-text\">Thread.Join<\/code> loop. Not only does it not require a loop, but it also waits asynchronously. <a id=\"calibre_link-551\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-552\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><\/p>\n<p class=\"copyrightbody\">Note that when you use <code class=\"fm-code-in-text\">Task.Run<\/code> without waiting for it, the compiler will generate a warning, but adding an <code class=\"fm-code-in-text\">await<\/code> is almost never the right thing to do. If you <code class=\"fm-code-in-text\">await<\/code> <code class=\"fm-code-in-text\">Task.Run<\/code>, you are telling your compiler to wait for the task to complete before moving to the next line of code, essentially making it run sequentially, which defeats the purpose of using <code class=\"fm-code-in-text\">Task.Run<\/code>. If you <code class=\"fm-code-in-text\">await Task.Run<\/code>, you\u2019re taking on the overhead of managing different tasks without getting any benefits; it\u2019s more efficient to just run the code without <code class=\"fm-code-in-text\">Task.Run<\/code>. The exception to this rule is the UI thread, and we will talk about it near the end of this chapter.<\/p>\n<p class=\"copyrightbody\">To get rid of the warning, you can assign the <code class=\"fm-code-in-text\">Task<\/code> returned by <code class=\"fm-code-in-text\">Task.Run<\/code> to a discard variable:<\/p>\n<pre class=\"programlisting\">Task.Run(MethodToRunInBackground);                     <span class=\"fm-combinumeral\">\u2776<\/span>\n_ =  Task.Run(MethodToRunInBackground);                <span class=\"fm-combinumeral\">\u2777<\/span><\/pre>\n<p class=\"copyrightbody\"><span class=\"fm-combinumeral\">\u2776<\/span> Might generate a warning<\/p>\n<p class=\"copyrightbody\"><span class=\"fm-combinumeral\">\u2777<\/span> No warning<\/p>\n<p class=\"copyrightbody\"><code class=\"fm-code-in-text\">Task.Run<\/code> doesn\u2019t have a parameterized version like <code class=\"fm-code-in-text\">Thread.Start<\/code> and <code class=\"fm-code-in-text\">ThreadPool.QueueUserWorkItem<\/code>, but we can easily use lambdas to simulate it and pass data to the code we run.<\/p>\n<p class=\"fm-code-listing-caption\">Listing 4.9 Using lambdas to create a parametrized <code class=\"fm-code-in-text1\">Task.Run<\/code><\/p>\n<pre class=\"programlisting\">public void RunInBackground()\n{\n   for(int i=0;i&lt;10;++i)\n   {\n     var icopy = i;\n     Task.Run(()=&gt;\n        {\n            Console.WriteLine($\"Hello from thread {icopy}\");\n        });\n   }\n}<\/pre>\n<p class=\"copyrightbody\">Here we used the lambda\u2019s feature of capturing local variables to pass a unique value to each task. Note that we had to use the <code class=\"fm-code-in-text\">icopy<\/code> variable that is scoped inside the loop because otherwise, all threads would have shared the same <code class=\"fm-code-in-text\">i<\/code> variable as the <code class=\"fm-code-in-text\">for<\/code> loop, and because it takes time for the task to start, by the time tasks run, the loop will have finished, so all tasks will have only the final value of <code class=\"fm-code-in-text\">i<\/code> (10 in this case).<a id=\"calibre_link-553\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-554\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-247\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><\/p>\n<div class=\"fm-sidebar-block\">\n<p class=\"fm-sidebar-title\">When to use Task.Run<\/p>\n<p class=\"copyrightbody\">Use <code class=\"fm-code-in-text\">Task.Run<\/code> for<\/p>\n<ul class=\"calibre9\">\n<li class=\"fm-list-bullet2\">\n<p class=\"list\">Code that uses async-await<\/p>\n<\/li>\n<li class=\"fm-list-bullet2\">\n<p class=\"list\">Short running tasks<\/p>\n<\/li>\n<\/ul>\n<p class=\"copyrightbody\">Do not use <code class=\"fm-code-in-text\">Task.Run<\/code> for<\/p>\n<ul class=\"calibre9\">\n<li class=\"fm-list-bullet2\">\n<p class=\"list\">Non-asynchronous long running tasks<\/p>\n<\/li>\n<\/ul><\/div>\n<p class=\"copyrightbody\">In this case, we could create a different copy of <code class=\"fm-code-in-text\">i<\/code> for each thread, but in many cases, we have shared data that multiple threads need to access, and that brings us to accessing the same variables from multiple threads.<a id=\"calibre_link-555\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-556\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-557\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-558\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-559\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><\/p>\n<h2 class=\"fm-head\" id=\"calibre_link-36\">4.2 Accessing the same variables from multiple threads<\/h2>\n<p class=\"copyrightbody\">Now that we know how to run code in parallel, we must deal with the consequences. Most programs manipulate data in memory, and the problem with manipulating data in a multithreaded program is that data access is often not a single uninterruptable operation, even when it\u2019s just one line of code or even one operator.<a id=\"calibre_link-560\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-561\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><\/p>\n<p class=\"copyrightbody\">Let\u2019s take the simplest data manipulation operation I can think of&mdash;incrementing an integer:<\/p>\n<pre class=\"programlisting\">int n=0;\n++n;<\/pre>\n<p class=\"copyrightbody\">The <code class=\"fm-code-in-text\">++n<\/code> line sure looks like it does a single thing. It\u2019s just one variable and one operator, and it\u2019s just three characters long. How many distinct operations can we do in just three characters? Well, it\u2019s actually three distinct operations:<\/p>\n<ol class=\"calibre9\">\n<li class=\"fm-list-bullet1\">\n<p class=\"list\">Read the value from the memory location allocated for the <code class=\"fm-code-in-text\">n<\/code> variable into the CPU.<\/p>\n<\/li>\n<li class=\"fm-list-bullet1\">\n<p class=\"list\">Increment the value inside the CPU.<\/p>\n<\/li>\n<li class=\"fm-list-bullet1\">\n<p class=\"list\">Save the new value from the CPU back into the memory location allocated for the <code class=\"fm-code-in-text\">n<\/code> variable.<\/p>\n<\/li>\n<\/ol>\n<p class=\"copyrightbody\">In a single-threaded program, this looks like a single operation because I can never accidentally break this sequence or sneak some code that runs in the middle of the sequence; however, in a multithreaded program, I can.<\/p>\n<p class=\"copyrightbody\">Operations that can\u2019t be interrupted in a multithreaded application, usually because they are a single operation at the hardware level, are called atomic operations. Figure 4.1 compares incrementing a variable twice in a single-threaded application, where everything is sane and works as expected; in a multithreaded application on a single-core CPU, where the way the system simulates multithreading can and will suspend threads at the wrong time; and finally, multithreaded on multicore CPUs, where things really happen in parallel. <a id=\"calibre_link-562\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-191\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><\/p>\n<div class=\"figure\">\n<p class=\"figure1\"><img decoding=\"async\" alt=\"\" class=\"calibre17\" src=\"\/images\/CSConcurrency_Asynchronous\/000006.png\" \/><\/p>\n<p class=\"figure1\">Figure 4.1 Operations can be interrupted at the wrong time and produce wrong results.<\/p>\n<\/p><\/div>\n<p class=\"copyrightbody\">As figure 4.1 illustrates, only in single-threaded applications, or applications that don\u2019t share data between threads, does our simple operation act like an operation that can\u2019t be interrupted. In all other configurations, anything can happen.<\/p>\n<p class=\"copyrightbody\">Let\u2019s write code that demonstrates that point. In this example, we will create two threads and increment the same variable from both. We will increment the variable five million times in each thread.<\/p>\n<p class=\"fm-code-listing-caption\">Listing 4.10 Incorrect <a id=\"calibre_link-563\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a>value when accessing shared data without locking<\/p>\n<pre class=\"programlisting\">public void GetIncorrectValue()\n{\n \n   int theValue = 0;\n \n   var threads = new Thread[2];\n   for(int i=0;i&lt;2;++i)\n   {\n      threads[i] = new Thread(()=&gt;\n      {\n         for(int j=0;j&lt;5000000;++j)\n            ++theValue;\n      });\n      threads[i].Start();\n   }\n \n   foreach(var current in threads) \n   {\n      current.Join();\n   }\n   Console.WriteLine(theValue);\n}<\/pre>\n<p class=\"copyrightbody\">If we run this code, we may expect it to print 10000000, but after reading what I wrote before the code sample, you already know that won\u2019t be the case. In fact, the result will change every time we run code, but it but will be around 6000000 most of the time.<\/p>\n<p class=\"copyrightbody\">So how do we solve this problem?<\/p>\n<h3 class=\"fm-head\" id=\"calibre_link-37\">4.2.1 No shared data<\/h3>\n<p class=\"copyrightbody\">The simplest solution is to never share any data between threads. If each thread has its own set of variables that can only be accessed by that thread, we never get a chance to read or write the variable from another thread, and we are safe.<a id=\"calibre_link-564\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-565\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-303\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><\/p>\n<p class=\"copyrightbody\">This is possible some of the time. For example, if we are writing a server that accepts data from the client, calculates something based solely on that data, and then returns results, each thread can operate without ever touching any value accessible to other threads. However, this isn\u2019t possible most of the time because our app is usually all about manipulating shared data.<\/p>\n<p class=\"copyrightbody\">But what if we bypass the problem another way, for example, by not modifying the shared data?<\/p>\n<h3 class=\"fm-head\" id=\"calibre_link-38\">4.2.2 Immutable shared data<\/h3>\n<p class=\"copyrightbody\">If our problem is that it is not safe for one thread to access data while another is modifying it, we can eliminate the problem completely if we just never modify any shared data. A common example is a web server serving static files; because those files never change, you can read them as many times as you like in parallel without causing any problems.<a id=\"calibre_link-566\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-567\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><\/p>\n<p class=\"copyrightbody\">For most applications, it isn\u2019t as easy as that, but this is the standard solution in functional languages and can be done in C#. However, this is not how we usually write C#.<\/p>\n<p class=\"copyrightbody\">Making all the shared data immutable, which might seem impractical to developers who aren\u2019t used to functional programming, is actually not only possible but technically an extremely good solution. The only problem is that it requires us to write our code completely differently than we usually do in C#. I\u2019m going to ignore it here because I could fill an entire book on the subject (and Manning has actually published a book on this topic; see <i class=\"fm-italics\">Concurrency in .NET<\/i> by Riccardo Terrell), and you would still not use this approach because it would feel alien to the way we usually write C#. However, .NET does have some built-in immutable data structures, which we\u2019ll discuss in chapter 13.<\/p>\n<p class=\"copyrightbody\">And that brings us to the standard solution&mdash;locks and mutexes.<\/p>\n<h3 class=\"fm-head\" id=\"calibre_link-39\">4.2.3 Locks and mutexes<\/h3>\n<p class=\"copyrightbody\"><a id=\"calibre_link-267\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a>What we are left with is synchronizing access to the shared state&mdash;whenever a thread needs to access the shared state, it \u201clocks\u201d it, and when it is finished with the data, it \u201creleases\u201d the lock. If another thread tries to lock the data while it is already locked, it must wait until the data is released by the current user.<a id=\"calibre_link-568\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-569\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-570\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-571\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><\/p>\n<p class=\"copyrightbody\">In computer science, this is called a <i class=\"fm-italics\">mutex<\/i> (short for <i class=\"fm-italics\">mutual exclusion<\/i>). In C#, we have the <code class=\"fm-code-in-text\">Mutex<\/code> class that represents the operating system\u2019s mutex implementation and the <code class=\"fm-code-in-text\">lock<\/code> statement that uses an internal .NET implementation. The <code class=\"fm-code-in-text\">lock<\/code> statement is easier to use and faster (because it doesn\u2019t require a system call), so we will prefer to use it. Let\u2019s rewrite our program from before using a lock.<a id=\"calibre_link-572\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><\/p>\n<p class=\"fm-code-listing-caption\">Listing 4.11 Adding locks to avoid simultaneous access problems<\/p>\n<pre class=\"programlisting\">public void GetCorrectValue() \n{\n   int theValue = 0;\n   object theLock = new Object();\n \n   var threads = new Thread[2];\n   for(int i=0;i&lt;2;++i)\n   {\n      threads[i] = new Thread(()=&gt;\n      {\n         for(int j=0;j&lt;5000000;++j)\n         {\n            lock(theLock)                                   <span class=\"fm-combinumeral\">\u2776<\/span>\n            {                                               <span class=\"fm-combinumeral\">\u2776<\/span>\n               ++theValue;                                  <span class=\"fm-combinumeral\">\u2776<\/span>\n            }                                               <span class=\"fm-combinumeral\">\u2776<\/span>\n         }\n      });\n      threads[i].Start();\n   }\n \n   foreach(var current in threads) \n   { \n      current.Join();\n   }\n   Console.WriteLine(theValue);\n}<\/pre>\n<p class=\"copyrightbody\"><span class=\"fm-combinumeral\">\u2776<\/span> Locks for the duration of the modification<\/p>\n<p class=\"copyrightbody\">We can see that the <code class=\"fm-code-in-text\">lock<\/code> statement is followed by a code block, and the lock is released when we exit the block, so we can\u2019t accidentally forget to release the lock. (The lock will also be released if we exit the code block because of an exception, which is nice.)<\/p>\n<p class=\"copyrightbody\">We can also see that the <code class=\"fm-code-in-text\">lock<\/code> statement accepts an object. We can use any .NET object; however, the best practice is to utilize an internal object that is used just for the lock and is accessible only to the code that needs it. Usually, it will be a private class member of your code.<\/p>\n<div class=\"fm-sidebar-block\">\n<p class=\"fm-sidebar-title\">Why use lock with an object<\/p>\n<p class=\"copyrightbody\">In .NET 8 and earlier, the best practice is to use an object of type <code class=\"fm-code-in-text\">Object<\/code> (that can also be used with the keyword <code class=\"fm-code-in-text\">object<\/code>) because we\u2019re not going to use this object for anything else, and an object of type <code class=\"fm-code-in-text\">Object<\/code> has the lowest overhead of all reference type objects.<a id=\"calibre_link-573\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-235\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><\/p>\n<p class=\"copyrightbody\">In .NET 9 and later, it\u2019s better to use an object of type <code class=\"fm-code-in-text\">System.Threading.Lock<\/code>. Using a <code class=\"fm-code-in-text\">lock<\/code> statement with the new <code class=\"fm-code-in-text\">Lock<\/code> class is clearer (because it\u2019s obviously a lock) and may be faster in newer versions. <a id=\"calibre_link-574\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-575\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><\/p>\n<p class=\"copyrightbody\">Using the <code class=\"fm-code-in-text\">lock<\/code> statement with an <code class=\"fm-code-in-text\">Object<\/code> is still supported, safe, and correct in .NET 9 and later. In this book, all the examples will use an <code class=\"fm-code-in-text\">Object<\/code> and not a <code class=\"fm-code-in-text\">Lock<\/code> for backward compatibility.<\/p>\n<\/p><\/div>\n<p class=\"copyrightbody\">Using <code class=\"fm-code-in-text\">lock<\/code> in this example was required to make our program produce the correct result, and synchronization objects such as <code class=\"fm-code-in-text\">lock<\/code> and <code class=\"fm-code-in-text\">Mutex<\/code> are needed for multithreaded programming. Those same objects also introduce a number of new failure modes, the biggest of them being the deadlock.<\/p>\n<h3 class=\"fm-head\" id=\"calibre_link-40\">4.2.4 Deadlocks<\/h3>\n<p class=\"copyrightbody\">A deadlock is the situation where a thread or multiple threads are stuck waiting for something that will never happen. The simplest example is where one thread locked mutex A and is waiting for mutex B, while a second thread locked mutex B and is waiting for mutex A. Thus, thread A is waiting for thread B to complete, which is waiting for thread A to complete, that we already established is waiting for thread B, which we said is waiting for thread A, and so on&mdash;forever(figure 4.2). <a id=\"calibre_link-576\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-577\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-578\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><\/p>\n<div class=\"figure\">\n<p class=\"figure1\"><img decoding=\"async\" alt=\"\" class=\"calibre18\" src=\"\/images\/CSConcurrency_Asynchronous\/000007.png\" \/><\/p>\n<p class=\"figure1\">Figure 4.2 Deadlock that occurs when one thread has locked mutex A and is waiting for mutex B, while another thread has locked mutex B and is waiting for mutex A. This creates a situation where thread A is dependent on thread B to finish, but thread B is also dependent on thread A, which leads to an endless cycle of waiting.<\/p>\n<\/p><\/div>\n<p class=\"copyrightbody\"><a id=\"calibre_link-277\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a>Now you can see why the best practice for the <code class=\"fm-code-in-text\">lock<\/code> statement is to use a private object that is only accessible by the code that needs it. It\u2019s because external code could, otherwise, accidentally or intentionally lock the same object we\u2019ve locked at a time we don\u2019t expect and cause a deadlock. If we use a private object, we can still cause a deadlock, but with both sides under our control, there are techniques we can use to prevent deadlocks. There is an entire chapter on deadlocks and other typical multithreading problems in this book, including on how to prevent them.<\/p>\n<p class=\"copyrightbody\">This is also why I said earlier that <code class=\"fm-code-in-text\">Thread.Suspend<\/code>, <code class=\"fm-code-in-text\">Thread.Resume<\/code>, and <code class=\"fm-code-in-text\">Thread.Abort<\/code> are so dangerous. Let\u2019s say you wrote a very clever system to manage your program\u2019s work that uses <code class=\"fm-code-in-text\">Suspend<\/code> and <code class=\"fm-code-in-text\">Resume<\/code> to control threads. From the thread\u2019s point of view, your calls to <code class=\"fm-code-in-text\">Suspend<\/code> can happen at any time (for example, when the thread is in the middle of allocating memory and is holding a lock inside the memory manager). Normally this lock would be completely safe because it is released quickly, and the code never waits for anything while holding the lock, but now you\u2019ve made the memory manager\u2019s code wait until you call <code class=\"fm-code-in-text\">Resume<\/code>. In the meantime, no one can allocate memory, including the thread that is supposed to call <code class=\"fm-code-in-text\">Resume<\/code>. If this thread tries to allocate memory (a very common operation), you\u2019ve just created a deadlock.<\/p>\n<p class=\"copyrightbody\">A deadlock can even happen without using locks or mutexes when two threads share other resources; in some cases, this resource might even be the thread itself. This is especially common with special-purpose threads, and the most common special-purpose thread is the UI thread in native applications.<a id=\"calibre_link-579\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-580\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><\/p>\n<h2 class=\"fm-head\" id=\"calibre_link-41\">4.3 Special considerations for native UI apps<\/h2>\n<p class=\"copyrightbody\">In all Windows desktop application technologies (WinForms, WPF, UWP, and WinAPI), UI windows and controls can only be accessed from the thread that created them. Trying to access the UI elements from a different thread might produce potentially incorrect results, error codes, or exceptions, depending on the UI technology you are using.<a id=\"calibre_link-581\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-582\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><\/p>\n<p class=\"copyrightbody\">When the program starts, you set up the main window and then call <code class=\"fm-code-in-text\">Dispatcher.Run<\/code> or <code class=\"fm-code-in-text\">Application.Run<\/code> (depending on UI technology). This is typically done in boilerplate code generated by Visual Studio. When you call <code class=\"fm-code-in-text\">Run<\/code>, the thread enters a loop that waits for UI events and, if needed, calls your code to handle them. If you block the thread or perform any long activity in your UI event handlers, you are preventing the thread from handling the UI events, and the program\u2019s UI will freeze until your event handler is complete.<\/p>\n<p class=\"copyrightbody\">You can take advantage of the fact that the UI thread is waiting and handing events and inject your own events. This lets other threads ask for code to run on the UI thread, which is useful because otherwise, it would have been difficult to update the UI due to activity done in background threads (since the only thread that can access the UI directly is the UI thread). You can do this by using the <code class=\"fm-code-in-text\">Control.BeginInvoke<\/code> or <code class=\"fm-code-in-text\">Control.Invoke<\/code> method in WinForms and <code class=\"fm-code-in-text\">Dispatcher.BeginInvoke<\/code> or <code class=\"fm-code-in-text\">Dispatcher.Invoke<\/code> methods in WPF or the generic <code class=\"fm-code-in-text\">SynchronizationContext<\/code> interface.<a id=\"calibre_link-583\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-584\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-585\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-586\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-587\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-227\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><\/p>\n<p class=\"copyrightbody\">In a typical workflow, in an event handler you write that is called in response to a UI event such as a button click, the event handler uses the <code class=\"fm-code-in-text\">Thread<\/code> class or the thread pool to run code in the background, and when it finishes doing its work, this background code calls <code class=\"fm-code-in-text\">BeginInvoke<\/code> to make the UI thread update the UI with the results.<a id=\"calibre_link-588\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><\/p>\n<p class=\"copyrightbody\">You must be extra careful with code that is running on the UI thread because you can get into a situation where code is blocked or busy waiting for something that happens in response to an <code class=\"fm-code-in-text\">Invoke<\/code>\/<code class=\"fm-code-in-text\">BeginInvoke<\/code> call (or in some cases, and as we will see in the next chapter, <code class=\"fm-code-in-text\">await<\/code>). But because the thread is blocked or busy, the code passed to <code class=\"fm-code-in-text\">Invoke<\/code>\/<code class=\"fm-code-in-text\">BeginInvoke<\/code> never runs, which creates a deadlock situation and a frozen UI.<\/p>\n<h2 class=\"fm-head\" id=\"calibre_link-42\">4.4 Waiting for another thread<\/h2>\n<p class=\"copyrightbody\">Sometimes, one thread must wait for another thread to do something. If we are waiting for a thread we created to complete its work and terminate, we can use <code class=\"fm-code-in-text\">Thread.Join<\/code> (as discussed earlier in this chapter). But if the thread we are waiting for needs to continue running after notifying us, we can\u2019t use <code class=\"fm-code-in-text\">Thread.Join<\/code>, and we need some mechanism for one thread to send a signal to another thread and for that other thread to wait until such a signal arrives. This mechanism is called <code class=\"fm-code-in-text\">ManualResetEventSlim<\/code> and is a newer, faster, and simpler implementation of <code class=\"fm-code-in-text\">ManualResetEvent<\/code>. Like all the classes that end with <code class=\"fm-code-in-text\">Slim<\/code>, it forgoes some functionality, mostly cross-process capabilities and compatibility with native code, in exchange for better performance.<a id=\"calibre_link-589\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-590\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-591\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><\/p>\n<p class=\"copyrightbody\"><code class=\"fm-code-in-text\">ManualResetEventSlim<\/code> works like a gate. When the event is in the unset state, the gate is closed, and any thread calling its <code class=\"fm-code-in-text\">Wait<\/code> method will wait. When the event is in the set stage, the gate is open, and the <code class=\"fm-code-in-text\">Wait<\/code> method will return immediately for any thread currently waiting and for all future calls (until the event is reset to the unset state).<a id=\"calibre_link-592\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><\/p>\n<p class=\"copyrightbody\">The <code class=\"fm-code-in-text\">ManualResetEventSlim<\/code> constructor has a single parameter that can be <code class=\"fm-code-in-text\">false<\/code> to create the event in the unset state (gate closed) or <code class=\"fm-code-in-text\">true<\/code> to create the event in the set state (gate open). The <code class=\"fm-code-in-text\">Set<\/code> method switches to the set state and opens the gate, while the <code class=\"fm-code-in-text\">Reset<\/code> method switches to the unset state and closes the gate. Let\u2019s write code with one thread waiting for another using <code class=\"fm-code-in-text\">ManualResetEventSlim<\/code>.<a id=\"calibre_link-593\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-594\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><\/p>\n<p class=\"fm-code-listing-caption\">Listing 4.12 Waiting for another thread<\/p>\n<pre class=\"programlisting\">var myEvent = new ManualResetEventSlim(false);                  <span class=\"fm-combinumeral\">\u2776<\/span>\nvar threadWeWaitFor = new Thread(()=&gt;\n   {\n       Console.WriteLine(\"Doing something\");\n       Thread.Sleep(5000);\n       Console.WriteLine(\"Finished\");\n       myEvent.Set();                                           <span class=\"fm-combinumeral\">\u2777<\/span>\n   });\nvar waitingThread = new Thread(()=&gt;\n   {\n       Console.WriteLine(\"Waiting for other thread to do something\");\n       myEvent.Wait();                                          <span class=\"fm-combinumeral\">\u2778<\/span>\n       Console.WriteLine(\"Other thread finished, we can continue\");\n   });\nthreadWeWaitFor.Start();\nwaitingThread.Start();<\/pre>\n<p class=\"copyrightbody\"><span class=\"fm-combinumeral\">\u2776<\/span> Creates a \u201cgate closed\u201d event<\/p>\n<p class=\"copyrightbody\"><span class=\"fm-combinumeral\">\u2777<\/span> Opens gate<\/p>\n<p class=\"copyrightbody\"><span class=\"fm-combinumeral\">\u2778<\/span> Waits for gate to open<\/p>\n<p class=\"copyrightbody\">In this example, we create two threads. The first simulates running a long operation by waiting, and after completing the operation, it sets an event. The second thread uses the event to wait for the first thread to complete.<\/p>\n<h2 class=\"fm-head\" id=\"calibre_link-43\">4.5 Other synchronization methods<\/h2>\n<p class=\"copyrightbody\">In addition to the two multithreading synchronization methods discussed in this chapter&mdash;the <code class=\"fm-code-in-text\">lock<\/code> statement and <code class=\"fm-code-in-text\">ManualRestEventSlim<\/code>&mdash;.NET contains a vast collection of other multithreading primitives. Each of those was written for a reason and is extremely useful in some circumstances. All of them have something in common: in most cases, you should avoid using them.<a id=\"calibre_link-595\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-282\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-596\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><\/p>\n<p class=\"copyrightbody\">The <code class=\"fm-code-in-text\">lock<\/code> statement is the simplest and safest thread synchronization construct in .NET, and even it may have the deadlock problem we talked about earlier and a whole lot of other pitfalls we\u2019ll examine in chapter 7. For this reason, I recommend staying with the <code class=\"fm-code-in-text\">lock<\/code> statement and using the more advanced, and more dangerous, mechanisms only if you have to&mdash;that is, only after you\u2019ve profiled the code and discovered that there is a real bottleneck in your code that can be solved by switching to another thread synchronization technique.<\/p>\n<p class=\"copyrightbody\">For example, let\u2019s take everyone\u2019s favorite thread synchronization tool&mdash;the <code class=\"fm-code-in-text\">Interlocked<\/code> class&mdash;which provides operations that are both thread safe and do not require locking. Seemingly, this is a magical class that solves all our problems; however, it, too, has its pitfalls, the most common being<\/p>\n<ul class=\"calibre9\">\n<li class=\"fm-list-bullet\">\n<p class=\"list\">It supports only a limited set of operations, namely <code class=\"fm-code-in-text\">Increment<\/code>, <code class=\"fm-code-in-text\">Decrement<\/code>, and <code class=\"fm-code-in-text\">Add<\/code>, as well as bitwise <code class=\"fm-code-in-text\">And<\/code> and <code class=\"fm-code-in-text\">Or<\/code> for some integer types (<code class=\"fm-code-in-text\">int<\/code>, <code class=\"fm-code-in-text\">uint<\/code>, <code class=\"fm-code-in-text\">long<\/code>, and <code class=\"fm-code-in-text\">ulong<\/code>).<\/p>\n<\/li>\n<li class=\"fm-list-bullet\">\n<p class=\"list\">All other operations can be implemented by the <code class=\"fm-code-in-text\">Exchange<\/code> and <code class=\"fm-code-in-text\">CompareExchange<\/code> methods, and these methods must be used in a very specific way (you\u2019ll see some examples in chapter 13).<\/p>\n<\/li>\n<li class=\"fm-list-bullet\">\n<p class=\"list\">It protects the operation, not the variable. If anyone accesses the variable \u201cprotected\u201d by an interlocked operation by anything other than members of the <code class=\"fm-code-in-text\">Interlocked<\/code> class, all bets are off, and your code is no longer thread safe, even the parts of the code that do use the <code class=\"fm-code-in-text\">Interlocked<\/code> class. If you just want to read the variable without modifying it, you must use <code class=\"fm-code-in-text\">Interlocked.Read<\/code> and not use the variable directly.<\/p>\n<\/li>\n<li class=\"fm-list-bullet\">\n<p class=\"list\">While the value you get from the interlocked methods is guaranteed to be correct when the interlocked method runs, by the time you use it, even if it\u2019s in the same line of code, it might already be outdated.<\/p>\n<\/li>\n<li class=\"fm-list-bullet\">\n<p class=\"list\">Only a single interlocked method call is thread safe. If you call <code class=\"fm-code-in-text\">Interlocked.Increment<\/code> twice for two variables, for example, it is possible for another thread (even one also using the <code class=\"fm-code-in-text\">Interlocked<\/code> class) to read or modify any of the variables between those two operations. This is a special case of the \u201ccomposing thread-safe operations rarely results in a thread-safe operation\u201d problem we\u2019ll discuss in chapter 7.<\/p>\n<\/li>\n<li class=\"fm-list-bullet\">\n<p class=\"list\">While the <code class=\"fm-code-in-text\">Interlocked<\/code> class members are faster than using a <code class=\"fm-code-in-text\">lock<\/code>, they might be significantly slower than using the normal operations (using the <code class=\"fm-code-in-text\">+=<\/code>, <code class=\"fm-code-in-text\">++<\/code>, <code class=\"fm-code-in-text\">--<\/code>, <code class=\"fm-code-in-text\">&amp;<\/code>, and <code class=\"fm-code-in-text\">|<\/code> operators).<\/p>\n<\/li>\n<\/ul>\n<p class=\"copyrightbody\">With all those pitfalls (and more), it\u2019s easier and safer to use the <code class=\"fm-code-in-text\">lock<\/code> statement and only use the <code class=\"fm-code-in-text\">Interlocked<\/code> class (carefully) in code that is very performance sensitive. The same goes for all the other multithreading primitives we didn\u2019t discuss&mdash;avoid using them unless you absolutely have to because they are complicated and not as safe and easy to use as the <code class=\"fm-code-in-text\">lock<\/code> statement.<\/p>\n<h2 class=\"fm-head\" id=\"calibre_link-44\">4.6 Thread settings<\/h2>\n<p class=\"copyrightbody\">When talking about the <code class=\"fm-code-in-text\">Thread<\/code> class, I said that you should only change the settings of threads you create yourself using the <code class=\"fm-code-in-text\">Thread<\/code> class (or the main thread if you are writing the application and not a library) and never change the settings of a thread pool or a thread created by another component. The reason is that the component that created the thread probably relies on the thread settings, and changing them would interfere with the operation of the component.<a id=\"calibre_link-597\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-598\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-283\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-599\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><\/p>\n<p class=\"copyrightbody\">Note that none of those settings works well with asynchronous code because any time you use <code class=\"fm-code-in-text\">await<\/code> (or <code class=\"fm-code-in-text\">ContinueWith<\/code>), execution can continue on another thread that has different settings. Here are the settings you can change using the <code class=\"fm-code-in-text\">Thread<\/code> class in the order of usefulness.<\/p>\n<h3 class=\"fm-head\" id=\"calibre_link-45\">4.6.1 Thread background status<\/h3>\n<p class=\"copyrightbody\">This is the most commonly used of all the thread settings. It is set by using the <code class=\"fm-code-in-text\">Thread.IsBackground<\/code> property, and it controls when your application exits. An application exits when all the non-background threads exit. That means that if you start a thread using the <code class=\"fm-code-in-text\">Thread<\/code> class (and don\u2019t set its <code class=\"fm-code-in-text\">IsBackground<\/code> property), and your <code class=\"fm-code-in-text\">Main<\/code> method ends, the application will keep running until the thread exits. If you don\u2019t want the thread you created to keep the application running, you can just set the <code class=\"fm-code-in-text\">IsBackgroud<\/code> property to <code class=\"fm-code-in-text\">true<\/code>.<a id=\"calibre_link-600\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-601\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-602\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-603\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-604\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-605\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><\/p>\n<p class=\"copyrightbody\">This property must be set before calling <code class=\"fm-code-in-text\">Thread.Start<\/code>. It has no effect when the application is deliberately terminated (for example, by using <code class=\"fm-code-in-text\">Environment.Exit<\/code> or <code class=\"fm-code-in-text\">Environment.FailFast<\/code>) or if the application exits due to an unhandled exception.<\/p>\n<h3 class=\"fm-head\" id=\"calibre_link-46\">4.6.2 Language and locale<\/h3>\n<p class=\"copyrightbody\">You can change the thread language and locale using the <code class=\"fm-code-in-text\">Thread.CurrentCulture<\/code> property, which affects how values, mostly numbers and dates, are formatted (if you don\u2019t pass a <code class=\"fm-code-in-text\">CultureInfo<\/code> object to the specific formatting method). It also affects the selection of UI resources in GUI applications. The default is the language and formatting used on the user\u2019s computer.<a id=\"calibre_link-606\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-607\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-608\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-230\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-609\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><\/p>\n<p class=\"copyrightbody\">You should only use this property if your application has a way for the user to change the language. Otherwise, you should respect the user\u2019s computer settings.<\/p>\n<h3 class=\"fm-head\" id=\"calibre_link-47\">4.6.3 COM Apartment<\/h3>\n<p class=\"copyrightbody\">You can use the <code class=\"fm-code-in-text\">Thread.SetApartmentState<\/code> and <code class=\"fm-code-in-text\">Thread.TrySetApartmentState<\/code> methods to control the thread\u2019s COM apartment type. This is only relevant to applications utilizing COM components in threads you create using the <code class=\"fm-code-in-text\">Thread<\/code> class (for the main thread, you should probably use the <code class=\"fm-code-in-text\">STAThread<\/code> or <code class=\"fm-code-in-text\">MTAThread<\/code> attributes on your <code class=\"fm-code-in-text\">Main<\/code> method).<a id=\"calibre_link-610\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-611\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-612\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-613\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-614\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-615\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-616\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><\/p>\n<p class=\"copyrightbody\">COM is a huge topic and outside the scope of this book. The short explanation for readers who are lucky and don\u2019t use COM is that COM has a concept of <i class=\"fm-italics\">apartment type<\/i>, and most COM objects can only run as a specific apartment type. Reading or setting the COM apartment is only supported on Windows because other operating systems don\u2019t use COM.<\/p>\n<h3 class=\"fm-head\" id=\"calibre_link-48\">4.6.4 Current user<\/h3>\n<p class=\"copyrightbody\">This property is mostly (but not officially) obsolete. You can use the static <code class=\"fm-code-in-text\">Thread.CurrentPrincipal<\/code> property to attach identity and permissions to the thread, which does not change the thread\u2019s permissions at the operating system level. It\u2019s just a place for you (or a library you are using) to store user information for your own permission system.<a id=\"calibre_link-617\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-618\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-619\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><\/p>\n<p class=\"copyrightbody\">In ASP.NET classic (.NET Framework 4.x and earlier), if you used the built-in authentication system, the current web user information was stored in the <code class=\"fm-code-in-text\">CurrentPrincipal<\/code> property. This is no longer the case in ASP.NET Core (.NET Core and .NET 5 and later); in the newer version, the current user is in <code class=\"fm-code-in-text\">HttpContext.User<\/code> only.<a id=\"calibre_link-620\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><\/p>\n<h3 class=\"fm-head\" id=\"calibre_link-49\">4.6.5 Thread priority<\/h3>\n<p class=\"copyrightbody\">Setting the thread priority is dangerous, and you shouldn\u2019t do it. Unless you are extremely careful, setting the thread priority is likely to cause performance degradation and\/or deadlocks.<a id=\"calibre_link-621\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-622\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-231\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><\/p>\n<p class=\"copyrightbody\">The problem is that it\u2019s too easy to get into some variation of a high-priority thread that is waiting for a resource held by a lower-priority thread, but that lower-priority thread can\u2019t release the resource because the higher-priority thread is taking all the CPU time.<\/p>\n<p class=\"copyrightbody\">Controlling the thread\u2019s priority is required for some kinds of system programming, but you should never set thread priorities in normal applications. The priority is controlled by the <code class=\"fm-code-in-text\">Thread.Priority<\/code> property. The system is allowed to ignore the priority you set.<a id=\"calibre_link-623\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-624\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-625\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><\/p>\n<h2 class=\"fm-head\" id=\"calibre_link-626\">Summary<\/h2>\n<ul class=\"calibre9\">\n<li class=\"fm-list-bullet\">\n<p class=\"list\">You can run multiple things in parallel. Each one of these things is called a thread.<\/p>\n<\/li>\n<li class=\"fm-list-bullet\">\n<p class=\"list\">The program starts with one thread running the <code class=\"fm-code-in-text\">Main<\/code> method. This thread is called the main thread.<\/p>\n<\/li>\n<li class=\"fm-list-bullet\">\n<p class=\"list\">You can create dedicated threads that are completely under your control with the <code class=\"fm-code-in-text\">Thread<\/code> class by creating a <code class=\"fm-code-in-text\">Thread<\/code> object, optionally reconfiguring it, and calling the <code class=\"fm-code-in-text\">Thread.Start<\/code> method to start running it.<\/p>\n<\/li>\n<li class=\"fm-list-bullet\">\n<p class=\"list\">The thread pool is a collection of threads managed by the system and is available for use when you have code to run. It is optimized for short-running tasks and can create new threads as needed.<\/p>\n<\/li>\n<li class=\"fm-list-bullet\">\n<p class=\"list\">Traditionally, you run code in the thread pool by using the <code class=\"fm-code-in-text\">ThreadPool.QueueUserWorkItem<\/code> method.<\/p>\n<\/li>\n<li class=\"fm-list-bullet\">\n<p class=\"list\">A simpler and more <code class=\"fm-code-in-text\">async<\/code>\/<code class=\"fm-code-in-text\">await<\/code> friendly way to run code in the thread pool is using <code class=\"fm-code-in-text\">Task.Run<\/code>.<\/p>\n<\/li>\n<li class=\"fm-list-bullet\">\n<p class=\"list\">The main thread and threads you create with the <code class=\"fm-code-in-text\">Thread<\/code> class are the only threads that are completely under your control and that you can reconfigure any way you want. However, you should never reconfigure threads created by other components, especially threads managed by the thread pool.<\/p>\n<\/li>\n<li class=\"fm-list-bullet\">\n<p class=\"list\">When you access data shared by more than one thread, you have to use a lock; otherwise, different threads may overwrite data written by other threads, leading to incorrect results.<\/p>\n<\/li>\n<li class=\"fm-list-bullet\">\n<p class=\"list\">The same also applies to reading shared data. If you don\u2019t use locks to synchronize reads as well as writes, you may get stale data and even the results of incomplete writes.<\/p>\n<\/li>\n<li class=\"fm-list-bullet\">\n<p class=\"list\">In native UI applications, the thread running the UI is called the UI thread. It is typically the main thread, but it can be a different thread if needed. The UI thread is the only thread that may access windows and other UI controls.<\/p>\n<\/li>\n<li class=\"fm-list-bullet\">\n<p class=\"list\">You should avoid blocking the UI thread because this makes the UI freeze.<a id=\"calibre_link-627\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><\/p>\n<\/li>\n<\/ul>\n<\/div>\n<\/div>\n<\/div>\n<div class=\"calibre1\" id=\"calibre_link-50\">\n<div id=\"calibre_link-628\" class=\"calibre2\">\n<div id=\"calibre_link-629\" class=\"calibre3\">\n<h1 class=\"copyrighta\" id=\"calibre_link-630\">5 <a id=\"calibre_link-631\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-632\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-633\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-634\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a>async\/await and multithreading<\/h1>\n<p class=\"copyrightbody\"><a id=\"calibre_link-276\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a>This chapter covers<a id=\"calibre_link-635\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><\/p>\n<ul class=\"calibre9\">\n<li class=\"co-summary-bullet\">Using <code class=\"fm-code-in-text\">async\/await<\/code> and multithreading together<\/li>\n<li class=\"co-summary-bullet\">Running code after <code class=\"fm-code-in-text\">await<\/code><\/li>\n<li class=\"co-summary-bullet\">Using locks with <code class=\"fm-code-in-text\">async\/await<\/code><\/li>\n<\/ul>\n<p class=\"copyrightbody\">Asynchronous programming is about doing stuff (such as reading a file or waiting for data to arrive over the network) that doesn\u2019t require the CPU in the background while using the CPU to do something else. Multithreading is about doing stuff that may or may not require the CPU in the background while using the CPU to do something else. Those two things are obviously similar, and we use the same tools to interact with them.<\/p>\n<p class=\"copyrightbody\">In chapter 3, we talked about <code class=\"fm-code-in-text\">async<\/code>\/<code class=\"fm-code-in-text\">await<\/code> but didn\u2019t mention threads; we especially ignored where the callback passed to <code class=\"fm-code-in-text\">ContinueWith<\/code> runs. In chapter 4, we talked about multithreading and almost didn\u2019t mention <code class=\"fm-code-in-text\">async<\/code>\/<code class=\"fm-code-in-text\">await<\/code> at all. In this chapter, we\u2019ll connect these two together.<\/p>\n<h2 class=\"fm-head\" id=\"calibre_link-51\">5.1 Asynchronous programming and multithreading<\/h2>\n<p class=\"copyrightbody\">To demonstrate the interaction between asynchronous programming and multithreading, we\u2019ll start with a method that reads 10 files in parallel using asynchronous operations and then waits for all the read operations to complete. And just for the fun of it, we won\u2019t make the method itself <code class=\"fm-code-in-text\">async<\/code> but just use asynchronous operations.<a id=\"calibre_link-636\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-189\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-637\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><\/p>\n<p class=\"fm-code-listing-caption\">Listing 5.1 Reading 10 files<\/p>\n<pre class=\"programlisting\">public void Read10Files()\n{\n   var tasks = new Task[10];\n   for(int i=0;i&lt;10;++i)\n   {\n      tasks[i] = File.ReadAllBytesAsync($\"{i}.txt\");\n   }\n   Task.WaitAll(tasks);\n}<\/pre>\n<p class=\"copyrightbody\">This is obviously asynchronous programming. Reading a file is a textbook example of work done mostly outside the CPU (and yes, I completely ignored the data we loaded from the file&mdash;this is just a demonstration of the mechanics of <code class=\"fm-code-in-text\">Task<\/code> and asynchronous operations). But what would it look like if instead we wrote code to compute 10 values (or, for simplicity\u2019s sake, let\u2019s print text claiming we are calculating) in parallel and wait for the results? We\u2019ll use <code class=\"fm-code-in-text\">Task.Run<\/code>, which runs our code in a thread pool thread (see chapter 4).<\/p>\n<p class=\"fm-code-listing-caption\">Listing 5.2 Calculating 10 values<\/p>\n<pre class=\"programlisting\">public void Compute10Values()\n{\n   var tasks = new Task[10];\n   for(int i=0;i&lt;10;++i)\n   {\n      tasks[i] = Task.Run(()=&gt;Console.WriteLine(\"Calculating\"));\n   }\n   Task.WaitAll(tasks);\n}<\/pre>\n<p class=\"copyrightbody\">I literally changed just one line and didn\u2019t even change the entire text of the line. This demonstrates that the same tools used for asynchronous operations work in the exact same way for multithreading. Let\u2019s take it one step further and use multithreading to read the files in parallel.<\/p>\n<p class=\"fm-code-listing-caption\">Listing 5.3 Reading 10 files using multithreading<\/p>\n<pre class=\"programlisting\">public void Read10Files()\n{\n   var tasks = new Task[10];\n   for(int i=0;i&lt;10;++i)\n   {\n      var icopy = i;\n      tasks[i] = Task.Run(()=&gt;File.ReadAllBytes($\"{icopy}.txt\"));\n   }\n   Task.WaitAll(tasks);\n}<\/pre>\n<p class=\"copyrightbody\">We needed to create a local variable inside the loop. Otherwise, all the threads would have shared the same <code class=\"fm-code-in-text\">i<\/code> variable, and by the time the threads ran, the loop would have finished already, so <code class=\"fm-code-in-text\">i<\/code> would have its final value of 10. That would have made all the threads try to read 10.txt and fail because our files are 0.txt&ndash;9.txt.<\/p>\n<p class=\"copyrightbody\">Other than that, the code looks almost the same as the one in listing 5.1, and it does exactly the same thing. However, it does it in a much more wasteful way because this example uses up to 10 separate threads (depending on how quickly the system can read the files). Furthermore, each and every one of them is stuck waiting for the file to arrive from the hard drive, while listing 5.1 uses just one thread waiting for all the files.<\/p>\n<p class=\"copyrightbody\"><a id=\"calibre_link-298\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a>But a real program wouldn\u2019t read files and ignore the data. A real program would read the file and then do something with the file\u2019s content. Let\u2019s fix the latest example to also do something (or just write to the console that we are doing something).<\/p>\n<p class=\"fm-code-listing-caption\">Listing 5.4 Reading 10 files and doing something with the data<\/p>\n<pre class=\"programlisting\">public void Process10Files()\n{\n   var tasks = new Task[10];\n   for(int i=0;i&lt;10;++i)\n   {\n      var icopy = i;\n      tasks[i] = Task.Run(()=&gt;\n      { \n         File.ReadAllBytes($\"{icopy}.txt\");\n         Console.WriteLine(\"Doing something with the file's content\");\n      );\n   }\n   Task.WaitAll(tasks);\n}<\/pre>\n<p class=\"copyrightbody\">This will use up to 10 threads from the thread pool (because remember, <code class=\"fm-code-in-text\">Task.Run<\/code> uses the thread pool), possibly creating new threads if there weren\u2019t enough threads already in the thread pool and then immediately putting all those threads in a blocked state where they would be doing nothing except waiting for the hard drive. Let\u2019s see what would happen if we wrote the exact same thing using asynchronous operations only.<a id=\"calibre_link-638\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><\/p>\n<p class=\"fm-code-listing-caption\">Listing 5.5 Reading 10 files asynchronously and processing the data<\/p>\n<pre class=\"programlisting\">public void Process10Files()\n{\n   var tasks = new Task[10];\n   for(int i=0;i&lt;10;++i)\n   {\n      var icopy = i;\n      tasks[i] = Task.Run(async ()=&gt;\n      { \n         await File.ReadAllBytesAsync($\"{icopy}.txt\");\n         Console.WriteLine(\"Doing something with the file's content\");\n      });\n   }\n   Task.WaitAll(tasks);\n}<\/pre>\n<p class=\"copyrightbody\">The code looks exactly the same, except we switched from <code class=\"fm-code-in-text\">File.ReadAllBytes<\/code> to <code class=\"fm-code-in-text\">File.ReadAllBytesAsync<\/code> and added the <code class=\"fm-code-in-text\">async<\/code> and <code class=\"fm-code-in-text\">await<\/code> keywords; however, what happens at runtime is very different. Instead of using 10 threads for the whole time, this will pick up a thread from the thread pool, use it to start the read operation, and then free the thread and use the callback mechanism we talked about in chapter 3. That means the program will use a small number of threads to start the read operations (maybe even one; it depends on the current load on the computer and the state of the thread pool), and then use no threads at all while waiting. Only after the data arrives will it start using 10 threads (that is, only when there is work for them to do).<a id=\"calibre_link-639\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-640\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-246\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><\/p>\n<p class=\"copyrightbody\">In fact, this is even better because as we are reading all the files from the same hard drive, we are likely to get the files\u2019 contents one after the other and not all at once (because there\u2019s just one hard drive with one data connection to the motherboard), and each task will only pick up a thread after its data is available. That means it\u2019s likely we\u2019ll never actually use 10 threads simultaneously (but we can\u2019t tell in advance because multithreaded programming is inherently unpredictable).<\/p>\n<p class=\"copyrightbody\">There was one small lie two paragraphs ago: I said we don\u2019t use any threads while waiting for the files, but we are actually using one thread&mdash;the thread that called <code class=\"fm-code-in-text\">Process10Files<\/code> and is waiting for all the processing to complete. We can fix this; if we just make <code class=\"fm-code-in-text\">Process10Files<\/code> itself <code class=\"fm-code-in-text\">async<\/code>, we will get the following.<\/p>\n<p class=\"fm-code-listing-caption\">Listing 5.6 Making the caller <code class=\"fm-code-in-text1\">async<\/code> too<\/p>\n<pre class=\"programlisting\">public async Task Process10Files()                   <span class=\"fm-combinumeral\">\u2776<\/span>\n{\n   var tasks = new Task[10];\n   for(int i=0;i&lt;10;++i)\n   {\n      var icopy = i;\n      tasks[i] = Task.Run(async ()=&gt;\n      { \n         await File.ReadAllBytesAsync($\"{icopy}.txt\");\n         Console.WriteLine(\"Doing something with the file's content\");\n      });\n   }\n   await Task.WhenAll(tasks);                        <span class=\"fm-combinumeral\">\u2777<\/span>\n}<\/pre>\n<p class=\"copyrightbody\"><span class=\"fm-combinumeral\">\u2776<\/span> Makes the metho<\/p>\n<p class=\"copyrightbody\"><span class=\"fm-combinumeral\">\u2777<\/span> Changes WaitAll to WhenAll<\/p>\n<p class=\"copyrightbody\">This will free the thread that called <code class=\"fm-code-in-text\">Process10Files<\/code> itself and will truly use no threads at all until we finish reading some files.<\/p>\n<p class=\"copyrightbody\">If we free up all the threads while waiting for the data to arrive, when the data finally arrives, we need to continue running, but we can\u2019t because we freed up the thread. So where does our code run after the <code class=\"fm-code-in-text\">await<\/code> call?<a id=\"calibre_link-641\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-642\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><\/p>\n<h2 class=\"fm-head\" id=\"calibre_link-52\">5.2 Where does code run after await?<\/h2>\n<p class=\"copyrightbody\">If you remember from chapter 2, I said that using the <code class=\"fm-code-in-text\">await<\/code> keyword is equivalent to calling <code class=\"fm-code-in-text\">Task.ContinueWith<\/code>, so the code<a id=\"calibre_link-643\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-165\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-644\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><\/p>\n<pre class=\"programlisting\">var buffer = await File.ReadAllBytesAsync(\"somefile.bin\");\nConsole.WriteLine(buffer[0]);<\/pre>\n<p class=\"copyrightbody\">is translated by the compiler to<\/p>\n<pre class=\"programlisting\">File.ReadAllBytesAsync(\"somefile.bin\").ContinueWith(task=&gt;\n{\n   var buffer = task.Result;\n   Console.WriteLine(buffer[0]);\n});<\/pre>\n<p class=\"copyrightbody\">I also mentioned that this is a simplification and that <code class=\"fm-code-in-text\">await<\/code> is a bit more complicated. Now it\u2019s time to see exactly what <code class=\"fm-code-in-text\">await<\/code> does differently.<\/p>\n<p class=\"copyrightbody\"><code class=\"fm-code-in-text\">ContinueWith<\/code> runs the callback in the thread pool, just like <code class=\"fm-code-in-text\">Task.Run<\/code>. Technically, <code class=\"fm-code-in-text\">ContinueWith<\/code> has a version that accepts parameters specifying how to run the callback passed to it, but I won\u2019t go into that because <code class=\"fm-code-in-text\">await<\/code> takes care of it for us, and <code class=\"fm-code-in-text\">ContinueWith<\/code> is very rarely used directly in application code.<\/p>\n<p class=\"copyrightbody\"><code class=\"fm-code-in-text\">await<\/code> tries to run the code after it in a thread of the same type, so in most cases, you don\u2019t have to think about the possibility of a thread change. If <code class=\"fm-code-in-text\">await<\/code> can\u2019t use a thread of the same type, it will use the thread pool instead. The specific rules are<\/p>\n<ul class=\"calibre9\">\n<li class=\"fm-list-bullet\">\n<p class=\"list\">If you are using <code class=\"fm-code-in-text\">await<\/code> on the UI thread of a WinForms, WPF, or UWP app, the code after the <code class=\"fm-code-in-text\">await<\/code> will run on the same thread.<\/p>\n<\/li>\n<li class=\"fm-list-bullet\">\n<p class=\"list\">If you are using <code class=\"fm-code-in-text\">await<\/code> while processing a request in an ASP.NET Classic application (.NET framework 4.8 and earlier), the code after the <code class=\"fm-code-in-text\">await<\/code> will run on the same thread.<\/p>\n<\/li>\n<li class=\"fm-list-bullet\">\n<p class=\"list\">If your code or a framework you are using changes the current thread\u2019s <code class=\"fm-code-in-text\">SynchronizationContext<\/code> or <code class=\"fm-code-in-text\">TaskFactory<\/code> (we\u2019ll talk about them later in the book), then <code class=\"fm-code-in-text\">await<\/code> will use those. This is how the frameworks in the previous bullet points control the behavior of <code class=\"fm-code-in-text\">await<\/code>; except for UI frameworks, this is extremely rare.<\/p>\n<\/li>\n<li class=\"fm-list-bullet\">\n<p class=\"list\">In all other cases, the code after <code class=\"fm-code-in-text\">await<\/code> will run on the thread pool. Here are some common examples:<\/p>\n<ul class=\"calibre19\">\n<li class=\"fm-list-bullet\">\n<p class=\"list\">If the code calling <code class=\"fm-code-in-text\">await<\/code> is running in the thread pool, the code after the <code class=\"fm-code-in-text\">await<\/code> will also run in the thread pool. However, it might run on a different thread.<\/p>\n<\/li>\n<li class=\"fm-list-bullet\">\n<p class=\"list\">This also applies to code processing a request in an ASP.NET Core application (.NET Core or .NET 5.0 and later) because ASP.NET Core uses the thread pool for all processing.<\/p>\n<\/li>\n<li class=\"fm-list-bullet\">\n<p class=\"list\">If you use <code class=\"fm-code-in-text\">await<\/code> in the main thread of a non-UI app, the code after the <code class=\"fm-code-in-text\">await<\/code> will also run in the thread pool and not in the main thread. The system will keep the main thread (and the entire application) alive until the <code class=\"fm-code-in-text\">Task<\/code> you are awaiting completes.<\/p>\n<\/li>\n<li class=\"fm-list-bullet\">\n<p class=\"list\">If you use <code class=\"fm-code-in-text\">await<\/code> in a thread you created with the <code class=\"fm-code-in-text\">Thread<\/code> class, inside the method you passed to the <code class=\"fm-code-in-text\">Thread<\/code> constructor, the thread will terminate, and the code after the <code class=\"fm-code-in-text\">await<\/code> will run on the thread pool.<\/p>\n<\/li>\n<\/ul>\n<\/li>\n<\/ul>\n<p class=\"copyrightbody\"><a id=\"calibre_link-645\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a>Those rules only apply if <code class=\"fm-code-in-text\">await<\/code> has to actually wait. If the operation you are awaiting has already completed by the time <code class=\"fm-code-in-text\">await<\/code> runs, in almost all cases, the code will just continue normally without switching threads. The most common situation in which this happens is if you are awaiting a method that doesn\u2019t do anything asynchronous. For example, the following method calls a remote server to retrieve a result, and it uses a very simple cache to avoid repeating those costly network calls if it already got the result.<\/p>\n<p class=\"fm-code-listing-caption\">Listing 5.7 Getting a value from a server with caching; not thread safe<\/p>\n<pre class=\"programlisting\">\/\/ This method is not thread safe, keep reading for the correct version\nprivate Dictionary&lt;string,string&gt; _cache = new();\n  \npublic async Task&lt;string&gt; GetResult(string query)\n{\n   if(_cache.TryGetValue(query, out var cacheResult)\n          return cacheResult;                               <span class=\"fm-combinumeral\">\u2776<\/span>\n   var http = new HttpClient();\n   var result = await http.GetStringAsync(                  <span class=\"fm-combinumeral\">\u2777<\/span>\n      \"https:\/\/example.com?\"+query);                        <span class=\"fm-combinumeral\">\u2777<\/span>\n   _cache[query] = result;                                  <span class=\"fm-combinumeral\">\u2778<\/span>\n   return result;\n}<\/pre>\n<p class=\"copyrightbody\"><span class=\"fm-combinumeral\">\u2776<\/span> If the result is in the cache, return it.<\/p>\n<p class=\"copyrightbody\"><span class=\"fm-combinumeral\">\u2777<\/span> Calls server to get the result<\/p>\n<p class=\"copyrightbody\"><span class=\"fm-combinumeral\">\u2778<\/span> Saves the result in the cache<\/p>\n<p class=\"copyrightbody\">This method first checks whether the query string is in the cache; if the value is already there, it returns it without doing asynchronous work. If not, the code performs an asynchronous HTTP call to get the result from the server. After the code gets the result from the server, it stores it in the cache.<\/p>\n<p class=\"copyrightbody\">The first time you call this method for a given query, it will return a <code class=\"fm-code-in-text\">Task<\/code> that needs awaiting, but on subsequent calls for the same query, it will return a <code class=\"fm-code-in-text\">Task<\/code> that has already completed because no asynchronous operation has happened. To demonstrate this, let\u2019s write some code that calls this method from a thread created using the <code class=\"fm-code-in-text\">Thread<\/code> class.<\/p>\n<p class=\"fm-code-listing-caption\">Listing 5.8 Calling <code class=\"fm-code-in-text1\">GetResult<\/code> from a thread created by the <code class=\"fm-code-in-text1\">Thread<\/code> class<\/p>\n<pre class=\"programlisting\">var thread = new Thread(()=&gt;\n{\n    var result = await GetResult(\"my query\");\n    DoSomething(result);                                 <span class=\"fm-combinumeral\">\u2776<\/span>\n});\nthread.Name = \"Query thread\";\nthread.Start();<\/pre>\n<p class=\"copyrightbody\"><span class=\"fm-combinumeral\">\u2776<\/span> On which thread will this run?<\/p>\n<p class=\"copyrightbody\">We create a thread that calls the <code class=\"fm-code-in-text\">GetResult<\/code> method from listing 5.7 and then does something with the result. One of the reasons for using the <code class=\"fm-code-in-text\">Thread<\/code> class is the ability to change the thread properties. In this case, I changed the thread name. The thread name is just a string attached to the thread. We can view it in the threads window in Visual Studio to quickly identify the thread and understand its purpose. It has no effect on how the thread runs.<\/p>\n<p class=\"copyrightbody\">If this code happens to be the first time, we call <code class=\"fm-code-in-text\">GetResult(\"my query\")<\/code>. The thread will terminate because, if you remember from chapter 3, <code class=\"fm-code-in-text\">await<\/code> registers code to run later and then returns control to the caller like a <code class=\"fm-code-in-text\">return<\/code> statement, and later, when <code class=\"fm-code-in-text\">DoSomething<\/code> runs, it will run on the thread pool and not in our named thread. In contrast, if the result for \u201cmy query\u201d is already in the cache, the code will continue in our named thread as if the <code class=\"fm-code-in-text\">await<\/code> wasn\u2019t there.<\/p>\n<p class=\"copyrightbody\">Now let\u2019s see how to make the <code class=\"fm-code-in-text\">GetResult<\/code> method from listing 5.7 thread safe.<a id=\"calibre_link-646\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-647\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><\/p>\n<h2 class=\"fm-head\" id=\"calibre_link-53\">5.3 Locks and async\/await<\/h2>\n<p class=\"copyrightbody\"><a id=\"calibre_link-155\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a>The problem with the <code class=\"fm-code-in-text\">GetResult<\/code> from listing 5.7 is that it will most likely run in a multithread environment (by virtue of having an <code class=\"fm-code-in-text\">await<\/code> statement), but it is not thread safe. It is not safe to access a <code class=\"fm-code-in-text\">Dictionary&lt;TKey,TValue&gt;<\/code> (either to modify it or to read from it) while it is being modified by another thread. The code in listing 5.7 modifies the dictionary without protecting it from concurrent access. Fortunately, we learned about the <code class=\"fm-code-in-text\">lock<\/code> statement in the previous chapter. Unfortunately, if we just add a lock around the entire method body, it won\u2019t compile.<a id=\"calibre_link-648\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-649\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><\/p>\n<p class=\"fm-code-listing-caption\">Listing 5.9 Getting a value from a server with caching protected by a lock<\/p>\n<pre class=\"programlisting\">private Dictionary&lt;string,string&gt; _cache = new();\nprivate object _cacheLock = new();\npublic async Task&lt;string&gt; GetResult(string query)\n{\n   lock(_cacheLock)\n   {\n       if(_cache.TryGetValue(query, out var cacheResult)\n          return cacheResult;\n       var http = new HttpClient();\n       var result = \n         await http.GetStringAsync(                       <span class=\"fm-combinumeral\">\u2776<\/span>\n         \"https:\/\/example.com?\"+query);                   <span class=\"fm-combinumeral\">\u2776<\/span><a id=\"calibre_link-650\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a>\n      _cache[query] = result;\n   }\n   return result;\n}<a id=\"calibre_link-651\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-652\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><\/pre>\n<p class=\"copyrightbody\"><span class=\"fm-combinumeral\">\u2776<\/span> Compiler error<\/p>\n<p class=\"copyrightbody\">This doesn\u2019t compile because we are not allowed to use <code class=\"fm-code-in-text\">await<\/code> inside the code block of the <code class=\"fm-code-in-text\">lock<\/code> statement. There are two reasons for this&mdash;one conceptual and one practical:<\/p>\n<ul class=\"calibre9\">\n<li class=\"fm-list-bullet\">\n<p class=\"list\">The conceptual problem is that calling <code class=\"fm-code-in-text\">await<\/code> frees up the thread and potentially runs other code, so we don\u2019t even know what code will run. This is a problem because, as we talked about in the previous chapter, running code you don\u2019t control while holding a lock can cause deadlocks.<\/p>\n<\/li>\n<li class=\"fm-list-bullet\">\n<p class=\"list\">The practical problem is that the code after the <code class=\"fm-code-in-text\">await<\/code> can run on a different thread, and the system used internally by the <code class=\"fm-code-in-text\">lock<\/code> statement only works if you release the lock from the same thread that locked it.<\/p>\n<\/li>\n<\/ul>\n<p class=\"copyrightbody\">How can we solve the problem? It\u2019s easy. Rearrange the code so that the <code class=\"fm-code-in-text\">await<\/code> is outside the lock. We don\u2019t need to hold the lock while doing the HTTP call. We just need to protect the cache access before and after the call.<a id=\"calibre_link-653\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><\/p>\n<p class=\"fm-code-listing-caption\">Listing 5.10 Releasing the lock while awaiting<\/p>\n<pre class=\"programlisting\">private Dictionary&lt;string,string&gt; _cache = new();\nprivate object _cacheLock = new();\npublic async Task&lt;string&gt; GetResult(string query)\n{\n   lock(_cacheLock)                                         <span class=\"fm-combinumeral\">\u2776<\/span>\n   {\n       if(_cache.TryGetValue(query, out var cacheResult)\n          return cacheResult;\n   }\n   var http = new HttpClient();\n   var result = await http.GetStringAsync(                  <span class=\"fm-combinumeral\">\u2777<\/span>\n      \"https:\/\/example.com?\"+query);                        <span class=\"fm-combinumeral\">\u2777<\/span>\n   lock(_cacheLock)                                         <span class=\"fm-combinumeral\">\u2778<\/span>\n   {\n      _cache[query] = result;\n   }\n   return result;\n}<\/pre>\n<p class=\"copyrightbody\"><span class=\"fm-combinumeral\">\u2776<\/span> Lock while checking the cache<a id=\"calibre_link-654\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-655\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><\/p>\n<p class=\"copyrightbody\"><span class=\"fm-combinumeral\">\u2777<\/span> The async HTTP call<\/p>\n<p class=\"copyrightbody\"><span class=\"fm-combinumeral\">\u2778<\/span> Lock while updating the cache<\/p>\n<p class=\"copyrightbody\">In this code, we solved our compilation problem by moving the lock to protect only the cache access and not the whole method, but at the cost of releasing the lock in the middle of the method. In the hypothetical method that was completely protected by a lock, trying to run the method twice simultaneously would result in the sequence shown in figure 5.1.<\/p>\n<div class=\"figure\">\n<p class=\"figure1\"><img decoding=\"async\" alt=\"\" class=\"calibre20\" src=\"\/images\/CSConcurrency_Asynchronous\/000008.png\" \/><\/p>\n<p class=\"figure1\">Figure 5.1 Sequence when locking the entire body of the method<a id=\"calibre_link-656\" class=\"pcalibre2 pcalibre calibre21 pcalibre3 pcalibre1\"><\/a><\/p>\n<\/p><\/div>\n<p class=\"copyrightbody\">One of the concurrent calls gets to run first. It tests the cache, does not find a cached result, makes the HTTP call, and updates the cache, all while inside the lock block. The other call will run second after the cache is updated and will return the cached value. But in the version of the method that actually compiles, we get the sequence as shown in figure 5.2.<\/p>\n<div class=\"figure\">\n<p class=\"figure1\"><img decoding=\"async\" alt=\"\" class=\"calibre22\" src=\"\/images\/CSConcurrency_Asynchronous\/000009.png\" \/><\/p>\n<p class=\"figure1\">Figure 5.2 Sequences when locking only the parts that touch the dictionary<\/p>\n<\/p><\/div>\n<p class=\"copyrightbody\">One of the concurrent calls gets to run first, tests the cache, and does not find a cached result inside the first lock block. It will then release the lock. At this point, the other call will get to run and also test the cache, also not finding a cached result because the first HTTP call hasn\u2019t finished yet. At some point, the first HTTP call will complete, and the first thread will update the cache. A bit later, the second HTTP call will complete, and the second thread will overwrite the value in the cache (that is why we use the operator <code class=\"fm-code-in-text\">[]<\/code> and not <code class=\"fm-code-in-text\">Add<\/code> to update the cache&mdash;<code class=\"fm-code-in-text\">Add<\/code> would have thrown an exception).<\/p>\n<p class=\"copyrightbody\">This is a simple form of caching that works very well for any long process (both asynchronous and non-asynchronous) if that process always returns the same value for the same inputs, we are willing to accept the potential performance hit of running the long process multiple times before the first run completes, and the cache is populated. If we are not willing to run the long process multiple times, this way of writing the cache won\u2019t work. <a id=\"calibre_link-657\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-658\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><\/p>\n<h2 class=\"fm-head\" id=\"calibre_link-54\">5.4 UI threads<\/h2>\n<p class=\"copyrightbody\">The rules for which thread runs the code after the await have a special case for the UI thread of native apps. Let\u2019s see why. To demonstrate the problem this solves, let\u2019s write an event handler for a WinForms button click that does some long calculation and updates the UI with the result (don\u2019t worry, you don\u2019t need to know WinForms to understand the code).<a id=\"calibre_link-659\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-156\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-660\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><\/p>\n<p class=\"fm-code-listing-caption\">Listing 5.11 Long calculation that freezes the UI<\/p>\n<pre class=\"programlisting\">private void MyButtonClick(object sender, EventArgs ea)\n{\n    int result = 0;\n    result = LongCalculation();                         <span class=\"fm-combinumeral\">\u2776<\/span>\n    MyLabel.Text = result.ToString();\n}<\/pre>\n<p class=\"copyrightbody\"><span class=\"fm-combinumeral\">\u2776<\/span> Freezes the UI<\/p>\n<p class=\"copyrightbody\">In response to a button click, this code calls <code class=\"fm-code-in-text\">LongCalculation<\/code> and then displays its result in a label control. However, we have a problem: the thread will be busy while running <code class=\"fm-code-in-text\">LongCalculation<\/code>, so the application\u2019s UI will be frozen until the calculation is done. But we can fix it with multithreading.<a id=\"calibre_link-661\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><\/p>\n<p class=\"fm-code-listing-caption\">Listing 5.12 Calculation that doesn\u2019t freeze the UI but throws an exception<\/p>\n<pre class=\"programlisting\">private void MyButtonClick(object sender, EventArgs ea)\n{\n    Task.Run(()=&gt;\n    {<a id=\"calibre_link-662\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-663\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a>\n       int result = 0;\n       result = LongCalculation();\n       MyLabel.Text = result.ToString();                <span class=\"fm-combinumeral\">\u2776<\/span>\n    }\n}<\/pre>\n<p class=\"copyrightbody\"><span class=\"fm-combinumeral\">\u2776<\/span> Exception<\/p>\n<p class=\"copyrightbody\">We just used <code class=\"fm-code-in-text\">Task.Run<\/code> to move all the calculations to a background thread so the UI thread will be free to handle UI events, and the UI will not freeze. We solved the previous problem, but we created another one. Now when we try to display the result, we are doing it from the wrong thread, and this will throw an exception and crash the program instead of showing the result. We need a way to return to the UI thread after the background process completes. Luckily, <code class=\"fm-code-in-text\">Task.Run<\/code> returns a <code class=\"fm-code-in-text\">Task<\/code> we can use. Specifically, we can use it to know when the result is ready.<a id=\"calibre_link-664\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><\/p>\n<p class=\"fm-code-listing-caption\">Listing 5.13 Running in the background f<a id=\"calibre_link-665\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a>rom the UI code correctly<\/p>\n<pre class=\"programlisting\">private async void MyButtonClick(object sender, EventArgs ea)\n{\n    int result = 0;\n    await Task.Run(()=&gt;\n    {\n       result = LongCalculation();                      <span class=\"fm-combinumeral\">\u2776<\/span>\n    });\n    MyLabel.Text = result.ToString();                   <span class=\"fm-combinumeral\">\u2777<\/span>\n}<\/pre>\n<p class=\"copyrightbody\"><span class=\"fm-combinumeral\">\u2776<\/span> Runs in background; UI not frozen<\/p>\n<p class=\"copyrightbody\"><span class=\"fm-combinumeral\">\u2777<\/span> Back in the UI thread<\/p>\n<p class=\"copyrightbody\">Here we used <code class=\"fm-code-in-text\">Task.Run<\/code> to run the long calculation in the background and <code class=\"fm-code-in-text\">await<\/code> to free up the UI thread until the calculation is complete. Because we called <code class=\"fm-code-in-text\">await<\/code> in the UI thread, when the calculation is complete, our code runs in the UI thread again and so can safely set the text of the label.<a id=\"calibre_link-299\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-666\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><\/p>\n<p class=\"copyrightbody\">Now you can see why <code class=\"fm-code-in-text\">await Task.Run<\/code> is valuable when used to run a background process from the UI thread, unlike almost every other case where it is just wasteful (see the previous chapter).<\/p>\n<h2 class=\"fm-head\" id=\"calibre_link-667\">Summary<\/h2>\n<ul class=\"calibre9\">\n<li class=\"fm-list-bullet\">\n<p class=\"list\">The tools for using asynchronous operations are also good for using multithreaded operations.<\/p>\n<\/li>\n<li class=\"fm-list-bullet\">\n<p class=\"list\">The high-performance code that benefits from multithreading is also likely to benefit from using asynchronous operations.<\/p>\n<\/li>\n<li class=\"fm-list-bullet\">\n<p class=\"list\">In UI apps, when using <code class=\"fm-code-in-text\">await<\/code> in the UI thread, the code after the <code class=\"fm-code-in-text\">await<\/code> will also run in the UI thread.<\/p>\n<\/li>\n<li class=\"fm-list-bullet\">\n<p class=\"list\">In all other cases, the code after <code class=\"fm-code-in-text\">await<\/code> will run in the thread pool (except if someone used <code class=\"fm-code-in-text\">SynchronizationContext<\/code> or <code class=\"fm-code-in-text\">TaskFactory<\/code> to override this behavior).<\/p>\n<\/li>\n<li class=\"fm-list-bullet\">\n<p class=\"list\">If the code calling <code class=\"fm-code-in-text\">await<\/code> is running in the thread pool, the code after the <code class=\"fm-code-in-text\">await<\/code> might run in a different thread in the thread pool.<\/p>\n<\/li>\n<li class=\"fm-list-bullet\">\n<p class=\"list\">You can\u2019t use <code class=\"fm-code-in-text\">await<\/code> inside the code block of a <code class=\"fm-code-in-text\">lock<\/code> statement. The best solution is to rearrange your code and move the <code class=\"fm-code-in-text\">await<\/code> outside of the <code class=\"fm-code-in-text\">lock<\/code> block.<\/p>\n<\/li>\n<\/ul>\n<\/div>\n<\/div>\n<\/div>\n<div class=\"calibre1\" id=\"calibre_link-55\">\n<div id=\"calibre_link-668\" class=\"calibre2\">\n<div id=\"calibre_link-669\" class=\"calibre3\">\n<h1 class=\"copyrighta\" id=\"calibre_link-670\">6 <a id=\"calibre_link-671\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-672\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-673\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-674\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a>When to use async\/await<\/h1>\n<p class=\"copyrightbody\"><a id=\"calibre_link-150\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a>This chapter covers<a id=\"calibre_link-675\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><\/p>\n<ul class=\"calibre9\">\n<li class=\"co-summary-bullet\">The importance of <code class=\"fm-code-in-text\">async\/await<\/code><\/li>\n<li class=\"co-summary-bullet\">The disadvantages of <code class=\"fm-code-in-text\">async\/await<\/code><\/li>\n<li class=\"co-summary-bullet\">Deciding when to use <code class=\"fm-code-in-text\">async\/await<\/code> and when to avoid it<\/li>\n<\/ul>\n<p class=\"copyrightbody\">You probably won\u2019t find it surprising that I, the author of a book about multithreading and asynchronous programming, think that they are important, useful, and something that every software developer should know. However, it\u2019s important to acknowledge that they are not suitable for every situation, and if used inappropriately, they will make your software more complicated and create some bugs that are really difficult to find.<\/p>\n<p class=\"copyrightbody\">This chapter talks about the performance gains of multithreading and asynchronous programming, as well as how asynchronous programming can backfire sometimes and make our life miserable. For the rest of this chapter, I\u2019m going to talk about the concept of asynchronous programming and the C# feature of <code class=\"fm-code-in-text\">async<\/code>\/<code class=\"fm-code-in-text\">await<\/code> as if they were interchangeable&mdash;while they are different, <code class=\"fm-code-in-text\">async<\/code>\/<code class=\"fm-code-in-text\">await<\/code> is by far the easiest way to do asynchronous programming in C#. If you want to use asynchronous programming in C#, you should use <code class=\"fm-code-in-text\">async<\/code>\/<code class=\"fm-code-in-text\">await<\/code>, and conversely, if you don\u2019t use asynchronous programming, you will find <code class=\"fm-code-in-text\">async<\/code>\/<code class=\"fm-code-in-text\">await<\/code> mostly useless.<\/p>\n<p class=\"copyrightbody\">First, let\u2019s quickly go over the scenarios where <code class=\"fm-code-in-text\">async<\/code>\/<code class=\"fm-code-in-text\">await<\/code> truly shines.<\/p>\n<h2 class=\"fm-head\" id=\"calibre_link-56\">6.1 Asynchronous benefits on servers<\/h2>\n<p class=\"copyrightbody\">No one builds non-asynchronous single-threaded servers. Such a server would only be able to handle one client at a time, and the maximum load would be one, or maybe the number of connections we configure this server to have in a pending state before our software starts handling them, depending on how you measure load.<a id=\"calibre_link-177\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-676\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-677\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><\/p>\n<p class=\"copyrightbody\">Single-threaded asynchronous servers are quite common, but almost exclusively in languages that don\u2019t support multithreading, such as node.js and Python. Well-written asynchronous servers can be quite efficient, especially if they are mostly IO bound and do very little processing (for example, serving static files or making database queries). But if you have to do any nontrivial processing, it is advantageous to be able to use that expensive multicore CPU inside the server.<\/p>\n<p class=\"copyrightbody\">To demonstrate the performance advantage of adding asynchronous techniques to a multithreaded server, we will build two nearly identical servers, a classic one-thread-per-request server you will find in network programming tutorials and an asynchronous server. Those will be simple servers serving a static file. They will wait for a network connection, and when a client connects, they will read a file from disk and send it to the client.<\/p>\n<p class=\"copyrightbody\">But before we can test our servers, we need a load-testing client. We\u2019ll make our client asynchronous too because it\u2019s more efficient (as we\u2019ll see from running the tests later in this chapter), and we want to minimize the effect of the client on performance so we can better measure the performance of the servers. Also, the client is a nice example of an asynchronous program.<\/p>\n<p class=\"copyrightbody\">In this program, we start by getting the number of connections from the command line, as this will let us easily run tests with different loads. We will then call <code class=\"fm-code-in-text\">RunTest<\/code>, which actually connects to the server. We will measure how long it takes until all instances of <code class=\"fm-code-in-text\">RunTest<\/code> complete using the <code class=\"fm-code-in-text\">System.Diagnostics.Stopwatch<\/code> class. We will also count the number of times we failed to connect because that will give us a clue about the maximum number of connections the server can handle.<a id=\"calibre_link-678\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-679\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><\/p>\n<p class=\"fm-code-listing-caption\">Listing 6.1 Asynchronous load-testing client<\/p>\n<pre class=\"programlisting\">using System.Diagnostics;\nusing System.Net;\nusing System.Net.Sockets;\n \nint count = int.Parse(args[0]);\nConsole.WriteLine($\"Running with {count} connections\");\n \nvar tasks = new Task[count];\nint failCount = 0;\nvar faileCountLock = new object();\n \nStopwatch sw = Stopwatch.StartNew();                           <span class=\"fm-combinumeral\">\u2776<\/span>\n \nfor (int i = 0; i &lt; count; ++i)\n{\n    tasks[i] = RunTest(i);                                     <span class=\"fm-combinumeral\">\u2777<\/span>\n}\nTask.WaitAll(tasks);                                           <span class=\"fm-combinumeral\">\u2778<\/span>\nsw.Stop();                                                     <span class=\"fm-combinumeral\">\u2779<\/span>\n \nlock(faileCountLock)\n   if (failCount &gt; 0) Console.WriteLine($\"{failCount} failures\");\nConsole.WriteLine($\"time: {sw.ElapsedMilliseconds}ms\");\n \nTask RunTest(int currentTask)\n{\n    return Task.Run(()=&gt;                                       <span class=\"fm-combinumeral\">\u277a<\/span>\n    {\n       var rng = new Random(currentTask);\n       await Task.Delay(rng.Next(2*count));\n       using var clientSocket = \n            new Socket(SocketType.Stream, ProtocolType.Tcp);\n       try\n       {\n           await clientSocket.ConnectAsync(                    <span class=\"fm-combinumeral\">\u277b<\/span>\n                new IPEndP<a id=\"calibre_link-680\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a>oint(IPAddress.Loopback, 7777)); \n           var buffer = new byte[1024 * 1024];\n           while (clientSocket.Connected)\n           {\n               int read = await clientSocket.ReceiveAsync(\n                     buffer, SocketFlags.None);                <span class=\"fm-combinumeral\">\u277c<\/span>\n               if (read == 0) break;\n           }\n       }\n       catch \n       {\n           lock (faileCountLock)\n               ++failCount;                                    <span class=\"fm-combinumeral\">\u277d<\/span>\n       }\n    });\n}<\/pre>\n<p class=\"copyrightbody\"><span class=\"fm-combinumeral\">\u2776<\/span> Starts stopwatch<\/p>\n<p class=\"copyrightbody\"><span class=\"fm-combinumeral\">\u2777<\/span> Runs individual test<\/p>\n<p class=\"copyrightbody\"><span class=\"fm-combinumeral\">\u2778<\/span> Waits for all tests to complete<\/p>\n<p class=\"copyrightbody\"><span class=\"fm-combinumeral\">\u2779<\/span> Stops stopwatch<\/p>\n<p class=\"copyrightbody\"><span class=\"fm-combinumeral\">\u277a<\/span> Runs tests in parallel<\/p>\n<p class=\"copyrightbody\"><span class=\"fm-combinumeral\">\u277b<\/span> Connects to server<\/p>\n<p class=\"copyrightbody\"><span class=\"fm-combinumeral\">\u277c<\/span> Reads data<\/p>\n<p class=\"copyrightbody\"><span class=\"fm-combinumeral\">\u277d<\/span> Counts failures<\/p>\n<p class=\"copyrightbody\"><a id=\"calibre_link-681\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a>Note that in the loop, when we called the <code class=\"fm-code-in-text\">RunTest<\/code> method that actually connects to the server, we did not await it because we want all instances to run in parallel. If you remember from chapter 3, calling an <code class=\"fm-code-in-text\">async<\/code> method does not run it in the background&mdash;the method runs normally until the first <code class=\"fm-code-in-text\">await<\/code>. <a id=\"calibre_link-682\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-683\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><\/p>\n<p class=\"copyrightbody\">Inside the <code class=\"fm-code-in-text\">RunTest<\/code> method, we made sure everything ran in the background using <code class=\"fm-code-in-text\">Task.Run<\/code>. Because <code class=\"fm-code-in-text\">RunTest<\/code> only called <code class=\"fm-code-in-text\">Task.Run<\/code>, we can just return the <code class=\"fm-code-in-text\">Task<\/code> we got from <code class=\"fm-code-in-text\">Task.Run<\/code> instead of making <code class=\"fm-code-in-text\">RunTest<\/code> <code class=\"fm-code-in-text\">async<\/code> and using <code class=\"fm-code-in-text\">await<\/code>. This improves efficiency because the compiler doesn\u2019t have to do the <code class=\"fm-code-in-text\">async<\/code> transformation and doesn\u2019t have to create and manage a <code class=\"fm-code-in-text\">Task<\/code> for <code class=\"fm-code-in-text\">RunTest<\/code> that would only mirror the <code class=\"fm-code-in-text\">Task<\/code> returned from <code class=\"fm-code-in-text\">Task.Run<\/code>.<a id=\"calibre_link-684\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><\/p>\n<p class=\"copyrightbody\">Inside the test code, we add a small random delay before connecting, because in real-world scenarios, we don\u2019t have all clients trying to connect at exactly the same time, and then we connect to the server and read all the information the server sends. We use sockets because this is the lowest overhead network access technology we have access to.<\/p>\n<div class=\"fm-sidebar-block\">\n<p class=\"fm-sidebar-title\">Socket communication<\/p>\n<p class=\"copyrightbody\">We used socket communication in the load testing client and server. Because this isn\u2019t a book about networking, I won\u2019t go into details, but here\u2019s a very short explanation of the networking calls we used.<\/p>\n<p class=\"copyrightbody\">On the server, we first must use <code class=\"fm-code-in-text\">Bind<\/code> to take control of a network port, and then we call <code class=\"fm-code-in-text\">Listen<\/code> to signal we are waiting for connections from clients. <code class=\"fm-code-in-text\">Accept<\/code> will actually wait for the next connection. When a client connects to the server, <code class=\"fm-code-in-text\">Accept<\/code> will return a new socket representing the new connection. <code class=\"fm-code-in-text\">AcceptAsync<\/code> is the asynchronous version of <code class=\"fm-code-in-text\">Accept<\/code> that, instead of waiting, returns a <code class=\"fm-code-in-text\">Task&lt;Socket&gt;<\/code> that will complete when a client connects.<a id=\"calibre_link-685\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-686\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-687\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-688\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-143\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><\/p>\n<p class=\"copyrightbody\">On the client, we then call <code class=\"fm-code-in-text\">ConnectAsync<\/code> to connect to the server. We use <code class=\"fm-code-in-text\">IPAddress.Loopback<\/code> as the server address, that is, a special address that always contacts the current computer. It is better known as <code class=\"fm-code-in-text\">localhost<\/code> in most networking tools. <a id=\"calibre_link-689\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><\/p>\n<p class=\"copyrightbody\"><code class=\"fm-code-in-text\">Send<\/code> sends data, and it returns after the data is handed over to the network stack inside the sending computer (not after the data is sent and not after the data is received by the other side; you can\u2019t know when those happen). <code class=\"fm-code-in-text\">Send<\/code> returns the number of bytes that were actually accepted by the network stack on a modern computer, which will almost always be the entire buffer you are trying to send. <code class=\"fm-code-in-text\">SendAsync<\/code> is the asynchronous version. It returns immediately and returns a <code class=\"fm-code-in-text\">Task&lt;int&gt;<\/code> that will complete when <code class=\"fm-code-in-text\">Send<\/code> would have returned.<a id=\"calibre_link-690\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-691\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><\/p>\n<p class=\"copyrightbody\"><code class=\"fm-code-in-text\">ReceiveAsync<\/code> reads data into an array we give it and returns a <code class=\"fm-code-in-text\">Task&lt;int&gt;<\/code> with the number of bytes received. If that <code class=\"fm-code-in-text\">Task<\/code>\u2019s result is 0, it means no more data is available, and we assume the server closed the connection.<a id=\"calibre_link-692\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><\/p>\n<p class=\"copyrightbody\">And finally, <code class=\"fm-code-in-text\">Shutdown<\/code> shuts down the connection gracefully, including sending a message to the other side notifying it that the connection is now closed. It also clears all the resources held by the connection.<\/p>\n<\/p><\/div>\n<p class=\"copyrightbody\">That was all the code for the test client. Now we need a server. Our first server will be the classic textbook one-thread-per-request server.<\/p>\n<p class=\"fm-code-listing-caption\">Listing 6.2 One-thread-per-request server<\/p>\n<pre class=\"programlisting\">using System.Net;\nusing System.Net.Sockets;\nvar listenSocket = new Socket(SocketType.Stream, ProtocolType.Tcp);\nlistenSocket.Bind(new IPEndPoint(IPAddress.Any, 7777));\nlistenSocket.Listen(50);\n \nwhile (true)\n{\n    var connection = listenSocket.Accept();\n    var thread = new Thread(() =&gt;                           <span class=\"fm-combinumeral\">\u2776<\/span>\n    {\n        using var file = new FileStream(@\"somefile.bin\", \n           FileMode.Open, FileAccess.Read);\n        var buffer = new byte[1024 * 1024];\n        while (true)\n        {\n            int read = file.Read(buffer, 0, buffer.Length);\n            if ((read) != 0)\n            {\n                connection.Send(                            <span class=\"fm-combinumeral\">\u2777<\/span>\n                  new ArraySegment&lt;byte&gt;(buffer, 0, read),\n                  SocketFlags.None);\n            }\n            else\n            {\n                connection.Shutdown(SocketShutdown.Both);\n                connection.Dispose();\n                return;\n            }\n        }\n    });\n    thread.Start();                                         <span class=\"fm-combinumeral\">\u2778<\/span>\n}<\/pre>\n<p class=\"copyrightbody\"><span class=\"fm-combinumeral\">\u2776<\/span> Handles connection in a new thread<\/p>\n<p class=\"copyrightbody\"><span class=\"fm-combinumeral\">\u2777<\/span> Sends file content to client<\/p>\n<p class=\"copyrightbody\"><span class=\"fm-combinumeral\">\u2778<\/span> Don\u2019t forget to start the thread.<\/p>\n<p class=\"copyrightbody\">That is our classic multithreaded non-asynchronous server. Now it\u2019s time to test it.<\/p>\n<p class=\"copyrightbody\"><a id=\"calibre_link-693\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a>I\u2019ve run the server and then the client with 50 connections. The test completed successfully in just under 8 seconds. I looked at the number of threads that the server spun up, and the server used 56 threads. Of those, 50 threads are the threads we created to handle the requests. Apart from this, there\u2019s also the main thread and five more background threads created by the .NET runtime.<\/p>\n<p class=\"copyrightbody\">I repeated the test with 100 connections. The test also completed successfully, this time in about 16 seconds. Looking at the threads of the server process, I\u2019ve seen 106 threads: 100 worker threads instead of the 50 in the previous test, and the same number of overhead threads.<\/p>\n<p class=\"copyrightbody\">After that success, I doubled the number of connections to 200. This time, the test failed with 61 of the connections not being able to complete receiving the file (the time the test took to complete is irrelevant because it didn\u2019t do all the work). The failure is caused by the program being too slow to get to new connections because it is too busy handling the earlier connections. This will overwhelm the pending connection queue and make the network stack refuse to accept any more connections.<\/p>\n<p class=\"copyrightbody\">Now that we\u2019ve seen the limits of the first server, let\u2019s write an asynchronous one. To keep everything as fair as possible, we will only change all the blocking and thread-management calls to their asynchronous version.<\/p>\n<p class=\"fm-code-listing-caption\">Listing 6.3 Asynchronous server<\/p>\n<pre class=\"programlisting\">using System.Net;\nusing System.Net.Sockets;\n \nvar listenSocket = new Socket(SocketType.Stream, ProtocolType.Tcp);\nlistenSocket.Bind(new IPEndPoint(IPAddress.Any, 7777));\nlistenSocket.Listen(100);\n \nwhile(true)\n{\n    var connection = await listenSocket.AcceptAsync();      <span class=\"fm-combinumeral\">\u2776<\/span>\n    Task.Run(async () =&gt;                                    <span class=\"fm-combinumeral\">\u2777<\/span>\n    {\n        using var file = new FileStream(\"somefile.bin\", \n              FileMode.Open, FileAccess.Read);\n        var buffer = new byte[1024*1024];\n        while (true)\n        {\n            int read = await file.ReadAsync(buffer, \n                 0, buffer.Length));                        <span class=\"fm-combinumeral\">\u2778<\/span>\n            if (read != 0)\n            {\n               await connection.SendAsync(\n                  new ArraySegment&lt;byte&gt;(buffer, 0, read),\n                  SocketFlags.None);                        <span class=\"fm-combinumeral\">\u2779<\/span>\n            }\n            else\n            {\n                connection.Shutdown(SocketShutdown.Both);\n                connection.Dispose();\n                return;\n            }\n        }\n    });\n}<\/pre>\n<p class=\"copyrightbody\"><span class=\"fm-combinumeral\">\u2776<\/span> AcceptAsync instead of Accept<\/p>\n<p class=\"copyrightbody\"><span class=\"fm-combinumeral\">\u2777<\/span> Task.Run instead of new Thread<\/p>\n<p class=\"copyrightbody\"><span class=\"fm-combinumeral\">\u2778<\/span> File.ReadAsync instead of Read<\/p>\n<p class=\"copyrightbody\"><span class=\"fm-combinumeral\">\u2779<\/span> SendAsync instead of Send<\/p>\n<p class=\"copyrightbody\">This code is identical to that in listing 6.2, except we changed <code class=\"fm-code-in-text\">Accept<\/code> to <code class=\"fm-code-in-text\">AcceptAsync<\/code>, <code class=\"fm-code-in-text\">Send<\/code> to <code class=\"fm-code-in-text\">SendAsync<\/code>, <code class=\"fm-code-in-text\">new Thread<\/code> to <code class=\"fm-code-in-text\">Task.Run<\/code>, and of course, we\u2019ve added the <code class=\"fm-code-in-text\">async<\/code> and <code class=\"fm-code-in-text\">await<\/code> keywords where needed.<a id=\"calibre_link-694\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-695\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-144\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><\/p>\n<p class=\"copyrightbody\">The difference between servers in run time is that <code class=\"fm-code-in-text\">AcceptAsync<\/code>, <code class=\"fm-code-in-text\">SendAsync<\/code>, and <code class=\"fm-code-in-text\">ReadAsync<\/code> will all release the thread instead of blocking it. This means we need just a small number of threads to handle the same number of connections in parallel. Instead of creating a new thread for each connection, we can use the thread pool (that we use with <code class=\"fm-code-in-text\">Task.Run<\/code>).<a id=\"calibre_link-696\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-697\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-698\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><\/p>\n<p class=\"copyrightbody\">Now we can finally compare the performance of the asynchronous and non-asynchronous versions (see table 6.1). Like with the first server, I\u2019ve first run the test with 50 connections. The test completed successfully in just under 8 seconds&mdash;the same as the non-asynchronous version. However, when looking at the number of threads, this version used only 27 threads instead of the 56 used by the non-asynchronous version (those are 20 thread pool threads doing all the work, the main thread, and six threads created by the framework or operating system&mdash;one more overhead thread compared to the non-asynchronous version).<\/p>\n<p class=\"copyrightbody\">After the first successful test, I doubled the number of connections to 100, and the test completed successfully in about 16 seconds&mdash;again the same as the non-asynchronous version. Looking at the threads, we see only 27 threads&mdash;the same number of threads as in the 50-connection run (compared to 106 for the non-asynchronous version).<\/p>\n<p class=\"copyrightbody\">I doubled the number of connections again to 200 (if you remember, at this point, the non-asynchronous version started failing), but the asynchronous version completed successfully again. Looking at the threads, we can again see only 27 threads.<\/p>\n<p class=\"copyrightbody\">I\u2019ll spare you all the boring details of the rest of the tests. On the poor laptop I\u2019m writing this on, the non-asynchronous version managed to handle around 130 connections, while the asynchronous version got to just above 300.<a id=\"calibre_link-152\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><\/p>\n<p class=\"copyrightbody\">Table 6.1 Differences between non-asynchronous and asynchronous connection handling<\/p>\n<table border=\"1\" class=\"contenttable-1-table\" id=\"calibre_link-699\" width=\"100%\">\n<colgroup class=\"contenttable-0-colgroup\">\n<col class=\"contenttable-0-col\" span=\"1\" width=\"14.29%\"><\/col>\n<col class=\"contenttable-0-col\" span=\"1\" width=\"14.29%\"><\/col>\n<col class=\"contenttable-0-col\" span=\"1\" width=\"14.29%\"><\/col>\n<col class=\"contenttable-0-col\" span=\"1\" width=\"14.29%\"><\/col>\n<col class=\"contenttable-0-col\" span=\"1\" width=\"14.29%\"><\/col>\n<col class=\"contenttable-0-col\" span=\"1\" width=\"14.29%\"><\/col>\n<col class=\"contenttable-0-col\" span=\"1\" width=\"14.29%\"><\/col>\n<\/colgroup>\n<thead class=\"contenttable-1-thead\">\n<tr class=\"contenttable-c-tr\">\n<th class=\"contenttable-1-th\" rowspan=\"2\">\n<p class=\"copyrightfiguresb\">Number of connections<\/p>\n<\/th>\n<th class=\"contenttable-1-th\" colspan=\"3\">\n<p class=\"copyrightfiguresb\">Non-asynchronous<\/p>\n<\/th>\n<th class=\"contenttable-1-th\" colspan=\"3\">\n<p class=\"copyrightfiguresb\">Asynchronous<\/p>\n<\/th>\n<\/tr>\n<tr class=\"contenttable-c-tr\">\n<th class=\"contenttable-1-th\">\n<p class=\"copyrightfiguresb\">Failures<\/p>\n<\/th>\n<th class=\"contenttable-1-th\">\n<p class=\"copyrightfiguresb\">Time<\/p>\n<\/th>\n<th class=\"contenttable-1-th\">\n<p class=\"copyrightfiguresb\">No. of threads<\/p>\n<\/th>\n<th class=\"contenttable-1-th\">\n<p class=\"copyrightfiguresb\">Failures<\/p>\n<\/th>\n<th class=\"contenttable-1-th\">\n<p class=\"copyrightfiguresb\">Time<\/p>\n<\/th>\n<th class=\"contenttable-1-th\">\n<p class=\"copyrightfiguresb\">No. of threads<\/p>\n<\/th>\n<\/tr>\n<\/thead>\n<tbody class=\"contenttable-1-thead1\">\n<tr class=\"contenttable-c-tr\">\n<td class=\"contenttable-1-td\">\n<p class=\"copyrightfiguresb\">50<\/p>\n<\/td>\n<td class=\"contenttable-1-td\">\n<p class=\"copyrightfiguresb\">0<\/p>\n<\/td>\n<td class=\"contenttable-1-td\">\n<p class=\"copyrightfiguresb\">8389 ms<\/p>\n<\/td>\n<td class=\"contenttable-1-td\">\n<p class=\"copyrightfiguresb\">56<\/p>\n<\/td>\n<td class=\"contenttable-1-td\">\n<p class=\"copyrightfiguresb\">0<\/p>\n<\/td>\n<td class=\"contenttable-1-td\">\n<p class=\"copyrightfiguresb\">8534 ms<\/p>\n<\/td>\n<td class=\"contenttable-1-td\">\n<p class=\"copyrightfiguresb\">27<\/p>\n<\/td>\n<\/tr>\n<tr class=\"contenttable-c-tr1\">\n<td class=\"contenttable-1-td\">\n<p class=\"copyrightfiguresb\">100<\/p>\n<\/td>\n<td class=\"contenttable-1-td\">\n<p class=\"copyrightfiguresb\">0<\/p>\n<\/td>\n<td class=\"contenttable-1-td\">\n<p class=\"copyrightfiguresb\">16538 ms<\/p>\n<\/td>\n<td class=\"contenttable-1-td\">\n<p class=\"copyrightfiguresb\">106<\/p>\n<\/td>\n<td class=\"contenttable-1-td\">\n<p class=\"copyrightfiguresb\">0<\/p>\n<\/td>\n<td class=\"contenttable-1-td\">\n<p class=\"copyrightfiguresb\">16310 ms<\/p>\n<\/td>\n<td class=\"contenttable-1-td\">\n<p class=\"copyrightfiguresb\">27<\/p>\n<\/td>\n<\/tr>\n<tr class=\"contenttable-c-tr\">\n<td class=\"contenttable-1-td\">\n<p class=\"copyrightfiguresb\">200<\/p>\n<\/td>\n<td class=\"contenttable-1-td\">\n<p class=\"copyrightfiguresb\">61<\/p>\n<\/td>\n<td class=\"contenttable-1-td\">\n<p class=\"copyrightfiguresb\">N\/R<\/p>\n<\/td>\n<td class=\"contenttable-1-td\">\n<p class=\"copyrightfiguresb\">N\/R<\/p>\n<\/td>\n<td class=\"contenttable-1-td\">\n<p class=\"copyrightfiguresb\">0<\/p>\n<\/td>\n<td class=\"contenttable-1-td\">\n<p class=\"copyrightfiguresb\">32132 ms<\/p>\n<\/td>\n<td class=\"contenttable-1-td\">\n<p class=\"copyrightfiguresb\">27<\/p>\n<\/td>\n<\/tr>\n<tr class=\"contenttable-c-tr1\">\n<td class=\"contenttable-1-td\">\n<p class=\"copyrightfiguresb\">300<\/p>\n<\/td>\n<td class=\"contenttable-1-td\">\n<p class=\"copyrightfiguresb\">168<\/p>\n<\/td>\n<td class=\"contenttable-1-td\">\n<p class=\"copyrightfiguresb\">N\/R<\/p>\n<\/td>\n<td class=\"contenttable-1-td\">\n<p class=\"copyrightfiguresb\">N\/R<\/p>\n<\/td>\n<td class=\"contenttable-1-td\">\n<p class=\"copyrightfiguresb\">0<\/p>\n<\/td>\n<td class=\"contenttable-1-td\">\n<p class=\"copyrightfiguresb\">48229 ms<\/p>\n<\/td>\n<td class=\"contenttable-1-td\">\n<p class=\"copyrightfiguresb\">27<\/p>\n<\/td>\n<\/tr>\n<tr class=\"contenttable-c-tr\">\n<td class=\"contenttable-1-td\">\n<p class=\"copyrightfiguresb\">400<\/p>\n<\/td>\n<td class=\"contenttable-1-td\">\n<p class=\"copyrightfiguresb\">265<\/p>\n<\/td>\n<td class=\"contenttable-1-td\">\n<p class=\"copyrightfiguresb\">N\/R<\/p>\n<\/td>\n<td class=\"contenttable-1-td\">\n<p class=\"copyrightfiguresb\">N\/R<\/p>\n<\/td>\n<td class=\"contenttable-1-td\">\n<p class=\"copyrightfiguresb\">72<\/p>\n<\/td>\n<td class=\"contenttable-1-td\">\n<p class=\"copyrightfiguresb\">N\/R<\/p>\n<\/td>\n<td class=\"contenttable-1-td\">\n<p class=\"copyrightfiguresb\">N\/R<\/p>\n<\/td>\n<\/tr>\n<\/tbody>\n<\/table>\n<p class=\"copyrightbody\">Those numbers might not look impressive, but it\u2019s unlikely that a real-world server will have to handle this number of connections in such a short time (an average of a connection every 2 ms) while also running Word and Visual Studio. In addition, it\u2019s important to note those numbers are very \u201cnoisy\u201d; the exact number of connections will vary depending on your hardware, details of your application, what is running at the time, usage patterns, .NET version, operating system version, and more. But you should see that the asynchronous version consistently uses fewer resources and can handle greater loads. Basically, what we see here is that the asynchronous server could easily handle a double load of the non-asynchronous version while using a fraction of the resources.<\/p>\n<p class=\"copyrightbody\">These days, I expect most C# development to be done on the server, but there are also native and desktop applications.<a id=\"calibre_link-700\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-701\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><\/p>\n<h2 class=\"fm-head\" id=\"calibre_link-57\">6.2 Asynchronous benefits on native client applications<\/h2>\n<p class=\"copyrightbody\">Asynchronous programming is also very useful in desktop applications. While desktop applications typically don\u2019t do tens of thousands of things simultaneously (due to the hardware limits of the person in front of the computer), they do need to keep the thread managing the UI available at all times so the UI does not become frozen.<a id=\"calibre_link-702\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><\/p>\n<p class=\"copyrightbody\">For example, if we have a long calculation that is making our UI nonresponsive, the code making the UI nonresponsive is likely to look like this:<\/p>\n<pre class=\"programlisting\">public void button1_Click(object sender, EventArgs args)\n{\n    LongCalculation();\n    UpdateUIWithCalculationResults();\n}<\/pre>\n<p class=\"copyrightbody\">We need to move <code class=\"fm-code-in-text\">LongCalculation<\/code> to a background thread, but we must keep <code class=\"fm-code-in-text\">UpdateUiWithCalculationResults<\/code> in the UI thread. Thus, we need to do something like<\/p>\n<pre class=\"programlisting\">public void button1_Click(object sender, EventArgs args)\n{\n    Task.Run(()=&gt;\n    {\n       LongCalculation();\n       BeginInvoke(()=&gt;\n       {\n          UpdateUIWithCalculationResults();\n       });\n    });\n}<\/pre>\n<p class=\"copyrightbody\">We used <code class=\"fm-code-in-text\">Task.Run<\/code> to run code on a background thread and then <code class=\"fm-code-in-text\">BeginInvoke<\/code> to run code back on the UI thread. With <code class=\"fm-code-in-text\">async<\/code>\/<code class=\"fm-code-in-text\">await<\/code>, we can rely on <code class=\"fm-code-in-text\">await<\/code> to get us back to the correct thread, and then we only need to write<\/p>\n<pre class=\"programlisting\">public async void button1_Click(object sender, EventArgs args)\n{\n    await Task.Run(()=&gt;\n    {\n       LongCalculation();\n    }); \n    UpdateUIWithCalculationResults();\n}<\/pre>\n<p class=\"copyrightbody\"><a id=\"calibre_link-153\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a>Those three advantages of <code class=\"fm-code-in-text\">async<\/code>\/<code class=\"fm-code-in-text\">wait<\/code> (that asynchronous code can handle higher loads, that it uses less resources even at lower loads, and that it makes it easy to use multithreading in conjunction with code that has to run on a specific thread) are pretty significant and can easily outweigh all the downsides. But the downsides are there, and you should learn about them.<\/p>\n<h2 class=\"fm-head\" id=\"calibre_link-58\">6.3 The downside of async\/await<\/h2>\n<p class=\"copyrightbody\">Up until now, we talked extensively about the benefits of asynchronous programming and why <code class=\"fm-code-in-text\">async<\/code>\/<code class=\"fm-code-in-text\">await<\/code> makes it easy. But, like just about everything, asynchronous programming also has some significant downsides.<a id=\"calibre_link-703\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><\/p>\n<h3 class=\"fm-head\" id=\"calibre_link-59\">6.3.1 Asynchronous programming is contagious<\/h3>\n<p class=\"copyrightbody\">Any code that calls asynchronous code must be asynchronous itself. If you are calling asynchronous code, you must use <code class=\"fm-code-in-text\">await<\/code> or callbacks to get the results. This is often referred to as \u201casynchronous all the way down.\u201d<a id=\"calibre_link-704\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><\/p>\n<p class=\"copyrightbody\">To illustrate this, we\u2019ll start with a program that takes a picture using the camera attached to the computer. The following code snippet is representative of what you need to do to use a camera using Windows\u2019 UWP API. To simplify the example, I removed all the parameters and the code that searches for a camera, but the structure of the code is correct:<\/p>\n<pre class=\"programlisting\">public void TakeSinglePicture()\n{\n   cameraApi.AquireCamera();\n   cameraApi.TakePicture();\n   cameraApi.ReleaseCamera();\n} <\/pre>\n<p class=\"copyrightbody\">The code first acquires the camera, then uses it to take a picture, and finally frees the camera and any associated resources. Now let\u2019s say that in the newest version of our imaginary camera, API made the <code class=\"fm-code-in-text\">TakePicture<\/code> method asynchronous. If we just switch to the new asynchronous version, we get<a id=\"calibre_link-705\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-706\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><\/p>\n<pre class=\"programlisting\">public void TakeSinglePicture()\n{\n   cameraApi.AquireCamera();\n   cameraApi.TakePictureAsync();\n   cameraApi.ReleaseCamera();                           <span class=\"fm-combinumeral\">\u2776<\/span>\n} <\/pre>\n<p class=\"copyrightbody\"><span class=\"fm-combinumeral\">\u2776<\/span> Error: Releases camera before TakePictureAsync is complete<\/p>\n<p class=\"copyrightbody\">However, this is a logic error: taking the picture is asynchronous, so it will complete in the background, but in this example, we don\u2019t wait for it to complete, so we release the camera while it\u2019s still taking the picture. What we need to do is to somehow wait for the <code class=\"fm-code-in-text\">TakePictureAsync<\/code> to complete before continuing. Luckily for us, <code class=\"fm-code-in-text\">async<\/code>\/<code class=\"fm-code-in-text\">await<\/code> makes it easy, but it does require changing the <code class=\"fm-code-in-text\">TakeSinglePicture<\/code> method to be <code class=\"fm-code-in-text\">async<\/code> too:<a id=\"calibre_link-707\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><\/p>\n<pre class=\"programlisting\">public async Task TakeSinglePicture()                   <span class=\"fm-combinumeral\">\u2776<\/span>\n{\n   cameraApi.AquireCamera();\n   await cameraApi.TakePictureAsync();\n   cameraApi.ReleaseCamera();\n} <\/pre>\n<p class=\"copyrightbody\"><span class=\"fm-combinumeral\">\u2776<\/span> Changes from void to async Task<\/p>\n<p class=\"copyrightbody\">It looks like it was an easy fix, but now we need to do the same to the code that calls <code class=\"fm-code-in-text\">TakeSinglePicture<\/code>, and the code that calls that, and the code that calls that, all the way back to the entry point of our code.<\/p>\n<p class=\"copyrightbody\">You may think that we can use <code class=\"fm-code-in-text\">Task.Wait()<\/code> and <code class=\"fm-code-in-text\">Task.Result<\/code> to bypass the problem by turning the asynchronous code into blocking code, but unless the asynchronous code was specifically designed to support this use case, this might cause weird bugs and deadlocks. Some APIs (like the UWP camera API this example is inspired by) will outright fail and throw an exception. And even if it does work, by turning the asynchronous call into a blocking call, we are eliminating any benefits of having an asynchronous method to begin with.<\/p>\n<h3 class=\"fm-head\" id=\"calibre_link-60\">6.3.2 Asynchronous programming has more edge cases<\/h3>\n<p class=\"copyrightbody\">Another problem is that by making your code asynchronous, you add new edge cases and failure modes that just don\u2019t exist in nonasynchronous single-threaded code. Let\u2019s take some straightforward WinForms code. We have a program that manages sources that provide values, and this specific code chooses a random source and displays the source name and the provided value (for extra realism, this code also uses the WinForms editor\u2019s autogenerated names):<a id=\"calibre_link-708\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-709\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><\/p>\n<pre class=\"programlisting\">private void button1_Click(object sender, EventArgs args)\n{\n   var source = GetRandomSource();\n   label1.Text = source.Name;\n   label2.Text = source.GetValue();\n}<\/pre>\n<p class=\"copyrightbody\">This code is pretty straightforward, and except for failures in the source itself, there\u2019s basically nothing that can go wrong. But if <code class=\"fm-code-in-text\">GetValue<\/code> takes a long time to run, it will make the UI unresponsive. We can solve this problem by making <code class=\"fm-code-in-text\">GetValue<\/code> and this method <code class=\"fm-code-in-text\">async<\/code>. The changes to this method are minimal, and our UI will no longer become unresponsive:<\/p>\n<pre class=\"programlisting\">private async void button1_Click(object sender, EventArgs args)\n{\n   var source = GetRandomSource();\n   label1.Text = source.Name;\n   label2.Text = await source.GetValue();\n}<\/pre>\n<p class=\"copyrightbody\">This may look like an easy fix, but we introduced a bug. Now that the UI is not frozen while <code class=\"fm-code-in-text\">GetValue<\/code> is running, the user can click the button again, and if we are unlucky with timing, it\u2019s easy to encounter a situation where the code displays that the source value is from the first click, while the source name is from the second, showing the user incorrect information. To fix the problem, we need to at least disable the specific button while the code is running:<\/p>\n<pre class=\"programlisting\">private async void button1_Click(object sender, EventArgs args)\n{\n   button1.Enabled=false;\n   var source = GetRandomSource();\n   label1.Text = source.Name;\n   label2.Text = await source.GetValue();\n   button1.Enabled=true;\n}<\/pre>\n<p class=\"copyrightbody\">Sometimes we might even have to disable all the UI controls in the application, depending on the details of the app and the dependencies between different UI elements.<\/p>\n<h3 class=\"fm-head\" id=\"calibre_link-61\">6.3.3 Multithreading has even more edge cases<\/h3>\n<p class=\"copyrightbody\">The reason that the previous demo is using WinForms is that WinForms makes it easy to write code that is asynchronous and not multithreaded. But nowadays, we mostly don\u2019t write desktop applications, and that innocent-looking <code class=\"fm-code-in-text\">await<\/code> you added to the code might have made your code multithreaded without even knowing it.<a id=\"calibre_link-710\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-154\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-711\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><\/p>\n<p class=\"copyrightbody\">Multithreading has many pitfalls, so many that there\u2019s an entire chapter about it later in the book.<\/p>\n<h3 class=\"fm-head\" id=\"calibre_link-62\">6.3.4 async\/await is expensive<\/h3>\n<p class=\"copyrightbody\"><code class=\"fm-code-in-text\">async<\/code>\/<code class=\"fm-code-in-text\">await<\/code> is expensive compared to single-threaded code. It adds a lot of compiler-generated code and mechanisms required to make the code asynchronous. It\u2019s important to remember that this is compared to single-threaded code, and in most cases, asynchronous code is more efficient than non-asynchronous multithreading, even with all the overhead.<a id=\"calibre_link-712\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><\/p>\n<p class=\"copyrightbody\">For example, let\u2019s take this complete but useless C# program:<\/p>\n<pre class=\"programlisting\">Thread.Sleep(1000);<\/pre>\n<p class=\"copyrightbody\">What is the actual code that was generated for this program? To answer this question, we\u2019ll use IlSpy&mdash;a free program that can take a .NET-compiled program and reverse-engineer it back to source code form. Because IlSpy looks at the compiled code, it sees all the generated code we talked about in the previous chapters.<\/p>\n<p class=\"copyrightbody\">When we decompile our program, we get eight lines of code. One line is our original line of code, and seven lines wrap our code in a <code class=\"fm-code-in-text\">Main<\/code> method and a class (because while the C# compiler lets you just write code, the runtime only supports code inside classes and methods), and that\u2019s it. If we take the equivalent asynchronous program<a id=\"calibre_link-713\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><\/p>\n<pre class=\"programlisting\">await Task.Delay(1000);<\/pre>\n<p class=\"copyrightbody\">we get a whopping 63 lines of code. The compiler did what we talked about in chapter 3: it turned this line into a class implementing a state machine with two states (before and after the <code class=\"fm-code-in-text\">await<\/code>) with all the associated code to manage it.<\/p>\n<p class=\"copyrightbody\">So after discussing all those advantages and drawbacks, when should we use <code class=\"fm-code-in-text\">async<\/code>\/<code class=\"fm-code-in-text\">await<\/code>, and when should we avoid it?<a id=\"calibre_link-714\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><\/p>\n<h2 class=\"fm-head\" id=\"calibre_link-63\">6.4 When to use async\/await<\/h2>\n<p class=\"copyrightbody\">Here are some simple guidelines that can help you decide when to use <code class=\"fm-code-in-text\">async<\/code>\/<code class=\"fm-code-in-text\">await<\/code> and when to opt for non-asynchronous blocking operations:<a id=\"calibre_link-715\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><\/p>\n<ul class=\"calibre9\">\n<li class=\"fm-list-bullet\">\n<p class=\"list\">If your code needs to manage a large number of connections simultaneously, use <code class=\"fm-code-in-text\">async<\/code>\/<code class=\"fm-code-in-text\">await<\/code> whenever you can.<\/p>\n<\/li>\n<li class=\"fm-list-bullet\">\n<p class=\"list\">If you are using an <code class=\"fm-code-in-text\">async<\/code>-only API, use <code class=\"fm-code-in-text\">async<\/code>\/<code class=\"fm-code-in-text\">await<\/code> whenever you use that API.<\/p>\n<\/li>\n<li class=\"fm-list-bullet\">\n<p class=\"list\">If you are writing a native UI application, and you have a problem with the UI freezing, use <code class=\"fm-code-in-text\">async<\/code>\/<code class=\"fm-code-in-text\">await<\/code> in the specific long-running code that makes the UI freeze.<\/p>\n<\/li>\n<li class=\"fm-list-bullet\">\n<p class=\"list\">If your code creates a thread per request\/item, and a significant part of the run time is I\/O (for example, network or file access), consider using <code class=\"fm-code-in-text\">async<\/code>\/<code class=\"fm-code-in-text\">await<\/code>.<\/p>\n<\/li>\n<li class=\"fm-list-bullet\">\n<p class=\"list\">If you add code to a codebase that already uses <code class=\"fm-code-in-text\">async<\/code>\/<code class=\"fm-code-in-text\">await<\/code> extensively, use <code class=\"fm-code-in-text\">async<\/code>\/<code class=\"fm-code-in-text\">await<\/code> where it makes sense to you.<\/p>\n<\/li>\n<li class=\"fm-list-bullet\">\n<p class=\"list\">If you add code to a codebase that does not use <code class=\"fm-code-in-text\">async<\/code>\/<code class=\"fm-code-in-text\">await<\/code>, avoid <code class=\"fm-code-in-text\">async<\/code>\/<code class=\"fm-code-in-text\">await<\/code> in the code as much as possible. If you decide to use <code class=\"fm-code-in-text\">async<\/code>\/<code class=\"fm-code-in-text\">await<\/code> in the new code, consider refactoring at least the code that calls the new code to also use <code class=\"fm-code-in-text\">async<\/code>\/<code class=\"fm-code-in-text\">await<\/code>.<\/p>\n<\/li>\n<li class=\"fm-list-bullet\">\n<p class=\"list\">If you write code that only does one thing simultaneously, don\u2019t use <code class=\"fm-code-in-text\">async<\/code>\/<code class=\"fm-code-in-text\">await<\/code>.<\/p>\n<\/li>\n<li class=\"fm-list-bullet\">\n<p class=\"list\">And in all other cases, absolutely and without a doubt, consider the trade-offs and make your own judgement.<\/p>\n<\/li>\n<\/ul>\n<p class=\"copyrightbody\"><a id=\"calibre_link-716\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a>The list is sorted by importance, from the most important consideration to the least important one. If your project fits the conditions of more than one of the listed guidelines, give more weight to the earlier entry in the list. But in any such case, or if the best fit is that annoying last bullet, you really do need to weigh the trade-offs and decide for yourself. I wish I could give you straightforward rules that cover every possibility, but the truth is that software design is complicated, and there is no alternative to making difficult choices based on the specific details of your specific project&mdash;after all, if software development was that easy, you wouldn\u2019t have to read books about it.<\/p>\n<h2 class=\"fm-head\" id=\"calibre_link-717\">Summary<\/h2>\n<ul class=\"calibre9\">\n<li class=\"fm-list-bullet\">\n<p class=\"list\">Asynchronous code can handle a much higher load than non-asynchronous code, while using significantly fewer resources.<\/p>\n<\/li>\n<li class=\"fm-list-bullet\">\n<p class=\"list\">In cases where it\u2019s important to run code on a specific thread (like in native UI applications), <code class=\"fm-code-in-text\">async<\/code>\/<code class=\"fm-code-in-text\">await<\/code> makes it easy to use multithreading and asynchronous calls.<\/p>\n<\/li>\n<li class=\"fm-list-bullet\">\n<p class=\"list\">However, asynchronous code also has some disadvantages:<\/p>\n<ul class=\"calibre19\">\n<li class=\"fm-list-bullet\">\n<p class=\"list\">Code that calls asynchronous methods must be made asynchronous itself.<\/p>\n<\/li>\n<li class=\"fm-list-bullet\">\n<p class=\"list\">Asynchronous code has more failure modes than non-asynchronous single threaded code.<\/p>\n<\/li>\n<li class=\"fm-list-bullet\">\n<p class=\"list\">Multithreaded code has more failure modes than single-threaded code.<\/p>\n<\/li>\n<li class=\"fm-list-bullet\">\n<p class=\"list\">Asynchronous techniques require more code than non-asynchronous code (but it\u2019s still faster and more efficient than non-asynchronous multithreaded code).<\/p>\n<\/li>\n<\/ul>\n<\/li>\n<li class=\"fm-list-bullet\">\n<p class=\"list\">You should consider the trade-offs when you choose whether to use <code class=\"fm-code-in-text\">async<\/code>\/<code class=\"fm-code-in-text\">await<\/code>.<\/p>\n<\/li>\n<\/ul>\n<\/div>\n<\/div>\n<\/div>\n<div class=\"calibre1\" id=\"calibre_link-64\">\n<div id=\"calibre_link-718\" class=\"calibre2\">\n<div id=\"calibre_link-719\" class=\"calibre3\">\n<h1 class=\"copyrighta\" id=\"calibre_link-720\">7 <a id=\"calibre_link-721\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-722\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-723\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-724\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a>Classic multithreading pitfalls and how to avoid them<\/h1>\n<p class=\"copyrightbody\"><a id=\"calibre_link-278\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a>This chapter covers<a id=\"calibre_link-725\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><\/p>\n<ul class=\"calibre9\">\n<li class=\"co-summary-bullet\">Classic multithreading pitfalls: partial updates, deadlocks, race conditions, synchronization, and starvation<\/li>\n<li class=\"co-summary-bullet\">Memory access reordering and the C# memory model<\/li>\n<li class=\"co-summary-bullet\">Following simple rules to avoid the classic multithreading pitfalls<\/li>\n<\/ul>\n<p class=\"copyrightbody\">When transitioning from single-thread to multithreaded programming, it\u2019s important to recognize that multithreading introduces certain types of bugs that don\u2019t occur in single-threaded applications. Fortunately, by understanding these common bug categories, we can avoid them. This chapter contains straightforward guidelines you can follow to significantly reduce the likelihood of encountering such problems.<\/p>\n<p class=\"copyrightbody\">We\u2019ll start by examining the most fundamental multithreading side effect. In a single-threaded environment, each piece of code must complete its task before the next one can begin. However, when two pieces of code run simultaneously, one can access the data the other is still processing, leading to potential problems with incomplete work.<\/p>\n<h2 class=\"fm-head\" id=\"calibre_link-65\">7.1 Partial updates<\/h2>\n<p class=\"copyrightbody\">Partial updates happen when one thread updates some data, and then, in the middle of that update, another thread reads the data and sees a mix of the old and new values.<a id=\"calibre_link-726\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-727\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-236\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><\/p>\n<p class=\"copyrightbody\">Sometimes, this problem is obvious, such as in<\/p>\n<pre class=\"programlisting\">x = 5;\ny = 7;<\/pre>\n<p class=\"copyrightbody\">The first line sets <code class=\"fm-code-in-text\">x<\/code>, and the second line sets <code class=\"fm-code-in-text\">y<\/code>. There is a short time between those lines when <code class=\"fm-code-in-text\">x<\/code> has already been set to 5, but <code class=\"fm-code-in-text\">y<\/code> is still not 7. However, often, the problem is not so obvious. For example, the following method has only one assignment and still has a potential partial updates problem:<\/p>\n<pre class=\"programlisting\">void SetGuid(Guid src)\n{\n     _myGuid = src;\n}<\/pre>\n<p class=\"copyrightbody\">In this case, <code class=\"fm-code-in-text\">Guid<\/code> is a <code class=\"fm-code-in-text\">struct<\/code>, and while C# lets us copy a <code class=\"fm-code-in-text\">struct<\/code> with a single assignment operator, internally, the compiler will generate code to copy the members of the <code class=\"fm-code-in-text\">struct<\/code> one by one, thereby making this equivalent to the first code snippet.<a id=\"calibre_link-728\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><\/p>\n<p class=\"copyrightbody\">But things can get worse. In the following code, we assign a <code class=\"fm-code-in-text\">decimal<\/code> variable. <code class=\"fm-code-in-text\">decimal<\/code> is a basic type in .NET and not a <code class=\"fm-code-in-text\">struct<\/code>. So how can this go wrong?<a id=\"calibre_link-729\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><\/p>\n<pre class=\"programlisting\">void SetPrice(decimal newPrice)\n{\n     _price = newPrice;\n}<\/pre>\n<p class=\"copyrightbody\">The problem here is that <code class=\"fm-code-in-text\">decimal<\/code> is 128 bits long, and in 64-bit CPUs, memory access is done in 64-bit&ndash;long blocks. So assigning a decimal variable is split into two distinct memory operations, basically making it exactly as problematic as the other two examples.<\/p>\n<p class=\"copyrightbody\">However, <code class=\"fm-code-in-text\">decimal<\/code> is kind of a weird basic type. It is a basic type in .NET, but it is not natively supported in any CPU architecture I know of, so let\u2019s talk about a basic type: <code class=\"fm-code-in-text\">long<\/code>. The <code class=\"fm-code-in-text\">long<\/code> type is a 64-bit integer and is the most natively supported type in 64-bit CPUs. We even said that memory access is done in 64-bit blocks, so assigning a single long value should be safe, right?<a id=\"calibre_link-730\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><\/p>\n<pre class=\"programlisting\">void SetIndex(long newIndex)\n{\n     _index = newIndex;\n}<\/pre>\n<p class=\"copyrightbody\">This assignment will most likely be atomic in 64-bit systems, but .NET still supports 32 bits, and if your code runs on a 32-bit computer (or a 32-bit operating system on a 64-bit CPU, or a 32-bit process running in a 64-bit OS&mdash;you get the point), then memory access is done in 32-bit blocks, and we\u2019re facing the exact same problem.<\/p>\n<p class=\"copyrightbody\">The solution to all those problems is using a locking mechanism of some sort, and the easiest locking mechanism in C# is the <code class=\"fm-code-in-text\">lock<\/code> statement. For example, in the following listing, we use <code class=\"fm-code-in-text\">lock<\/code> statements in every access to a member variable (both reads and writes), so we are completely safe from partial updates.<a id=\"calibre_link-731\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-268\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><\/p>\n<p class=\"fm-code-listing-caption\">Listing 7.1 Using the <code class=\"fm-code-in-text1\">lock<\/code> statement<\/p>\n<pre class=\"programlisting\">private int _x;\nprivate int _y;\nprivate object _lock = new object();\n \npublic void SetXY(int newX, int newY)\n{\n     lock(_lock)                                      <span class=\"fm-combinumeral\">\u2776<\/span>\n     {\n          _x = newX;\n          _y = newY;\n     }\n} \n \npublic (int x, int y) GetXY()\n{\n     lock(_lock)                                      <span class=\"fm-combinumeral\">\u2777<\/span>\n     {\n          return (_x,_y);\n     }\n}<\/pre>\n<p class=\"copyrightbody\"><span class=\"fm-combinumeral\">\u2776<\/span> lock statement around writes<\/p>\n<p class=\"copyrightbody\"><span class=\"fm-combinumeral\">\u2777<\/span> Another lock statement around reads<\/p>\n<p class=\"copyrightbody\"><code class=\"fm-code-in-text\">lock<\/code> statements prevent more than one thread from running code that is inside the lock\u2019s code block simultaneously. If a thread reaches the lock statement, and another thread is already running code in the code block of a <code class=\"fm-code-in-text\">lock<\/code> statement, the first thread will stop and wait until the other thread exits the block.<a id=\"calibre_link-732\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><\/p>\n<p class=\"copyrightbody\">The <code class=\"fm-code-in-text\">lock<\/code> statement accepts a parameter that lets us have different locks for different variables. When reaching the <code class=\"fm-code-in-text\">lock<\/code> statement, a thread will only wait if there is another thread inside a <code class=\"fm-code-in-text\">lock<\/code> statement with the same parameter. In the following listing, we have two values named A and B. If you call both <code class=\"fm-code-in-text\">GetA<\/code> and <code class=\"fm-code-in-text\">GetB<\/code> at the same time from different threads, one of them will run immediately, and the other will wait until the first one exits the <code class=\"fm-code-in-text\">lock<\/code> code block.<a id=\"calibre_link-733\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><\/p>\n<p class=\"fm-code-listing-caption\">Listing 7.2 Single lock for two variables<\/p>\n<pre class=\"programlisting\">private object _lock = new object();\nprivate int _a;\nprivate int _b;\n \npublic int GetA()\n{\n   lock(_lock)\n   {\n      return _a;\n   }\n}\n \npublic int GetB()\n{\n   lock(_lock)\n   {\n      return _b;\n   }\n}<\/pre>\n<p class=\"copyrightbody\">However, in the following example, because <code class=\"fm-code-in-text\">GetA<\/code> uses <code class=\"fm-code-in-text\">_lockA<\/code> and <code class=\"fm-code-in-text\">GetB<\/code> uses <code class=\"fm-code-in-text\">_lockB<\/code>, they can run simultaneously and will only wait if called at the same time as another piece of code that uses the <code class=\"fm-code-in-text\">lock<\/code> statement with <code class=\"fm-code-in-text\">_lockA<\/code> or <code class=\"fm-code-in-text\">_lockB<\/code>, respectively.<a id=\"calibre_link-734\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-269\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><\/p>\n<p class=\"fm-code-listing-caption\">Listing 7.3 Two locks for two variables<\/p>\n<pre class=\"programlisting\">private object _lockA = new object();\nprivate object _lockB = new object();\nprivate int _a;\nprivate int _b;\n \npublic int GetA()\n{\n   lock(_lockA)\n   {\n      return _a;\n   }\n}\n \npublic int GetB()\n{\n   lock(_lockB)\n   {\n      return _b;\n   }\n}<\/pre>\n<p class=\"copyrightbody\">It is best practice to use a private member of type <code class=\"fm-code-in-text\">object<\/code> (in .NET 9 and later, you can also use an object of type <code class=\"fm-code-in-text\">Lock<\/code>) that is only used for the <code class=\"fm-code-in-text\">lock<\/code> statement and not exposed anywhere outside your class. The reason for not exposing it outside your class is that you don\u2019t want to risk external code using the <code class=\"fm-code-in-text\">lock<\/code> statement with the same object because it can mess up your locking strategy and cause deadlocks (as we will see later in this chapter). The reason for using an object of type <code class=\"fm-code-in-text\">object<\/code> is that any other class that actually does something might use <code class=\"fm-code-in-text\">lock(this)<\/code> (this is common in older code from before using a private <code class=\"fm-code-in-text\">object<\/code> became a best practice), thereby messing with your locking strategy and causing a deadlock.<a id=\"calibre_link-735\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-736\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-737\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><\/p>\n<p class=\"copyrightbody\">You may think that you can prevent partial updates by being careful about the order of assignments, but this doesn\u2019t work due to memory access reordering.<a id=\"calibre_link-738\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-739\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><\/p>\n<h2 class=\"fm-head\" id=\"calibre_link-66\">7.2 Memory access reordering<\/h2>\n<p class=\"copyrightbody\">In modern hardware architectures, accessing memory is painstakingly slow relative to processing data inside the CPU, and different memory access patterns can have a significant effect on performance. To help with better utilization of the hardware, the compiler will change the order of operations in your code to reduce the number of memory access operations and make memory access faster.<a id=\"calibre_link-740\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-741\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-270\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><\/p>\n<p class=\"copyrightbody\">The computer I\u2019m using right now for writing this book has 2.666Mhz DDR4 memory. This type of memory has a latency of about 14.5 nanoseconds (that is, 0.0000000145 seconds), but the computer has 12 virtual cores running at 2.66Ghz, which means each clock cycle takes just 0.37 nanoseconds (to put this in perspective, by the time light travels from the screen to your eye, each CPU core has already finished around seven operations). A simple division tells us that each CPU core can perform roughly 40 operations in the time it takes to retrieve one value from memory, or considering the number of cores, the CPU can do up to 480 operations in the time it takes to get just one value from memory (the real world is, of course, more complicated, and the amount of work the CPU can do in a clock cycle can vary based on what exactly your code does; this is the maximum value). To put this in human terms, if the CPU could do one operation per second, then loading a single value from memory would take 8 minutes.<\/p>\n<p class=\"copyrightbody\">Let\u2019s see a simple example of how the compiler can improve performance by moving and eliminating memory access. Let\u2019s take a simple loop that increments a variable 100 times:<\/p>\n<pre class=\"programlisting\">int counter=0;\nfor(int i;i&lt;100;++i)\n{\n     ++counter;\n}<\/pre>\n<p class=\"copyrightbody\">Now let\u2019s translate this C# code into pseudo-machine code. In machine code, each statement or expression is divided into instructions. Instructions that do calculations can work only on internal variables inside the CPU itself. Those variables are called <i class=\"fm-italics\">registers<\/i>, and there are a limited number of them. Loading a value from memory into a register or storing the value of a register in memory are separate instructions. To keep the results short and readable, we\u2019re not going to translate the loop itself:<\/p>\n<pre class=\"programlisting\">Set register to 0 (fast)\nStore register to memory location \"counter\"(slow)\nfor(int i;i&lt;100;++i)\n{\n     Load from memory location \"counter\" into register (slow)\n     Increment value of register (fast)\n     Store register to memory location \"counter\"(slow)\n}<\/pre>\n<p class=\"copyrightbody\">When this pseudo-code runs, it will execute 101 fast and 201 slow operations (ignoring the overhead of the <code class=\"fm-code-in-text\">for<\/code> loop itself). Now let\u2019s move the memory access outside the loop:<\/p>\n<pre class=\"programlisting\">Set register to 0 (fast)\nStore register to memory location \"counter\" (slow)\nLoad from memory location \"counter\" into register (slow)\nfor(int i;i&lt;100;++i)\n{\n     Increment value of register (fast)\n}\nStore register to memory location \"counter\" (slow)<\/pre>\n<p class=\"copyrightbody\">This new pseudo-code will generate the exact same result but with only 4 slow operations compared to 201 in the direct translation. But we can do even better. At the beginning, we are storing a variable and then immediately loading it. We can skip those two operations and get<\/p>\n<pre class=\"programlisting\">Set register to 0 (fast)\nfor(int i;i&lt;100;++i)\n{\n     Increment value of register (fast)\n}\nStore register to memory location \"counter\" (slow)<\/pre>\n<p class=\"copyrightbody\">And we\u2019re at 101 fast operations and only 1 slow operation, down from 101 fast and 201 slow operations in the direct translation. If we say that each fast operation takes 1 time unit and each slow operation takes 10 units, the direct translation would run in 2,111 time units, and the optimized version would only need 121 time units to do the same work, which is a 20-fold improvement!<\/p>\n<p class=\"copyrightbody\"><a id=\"calibre_link-229\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a>The general rule is that the compiler is allowed to make any changes that do not alter the observed results of the code <i class=\"fm-italics\">in a single-threaded environment<\/i>; in our example, the only result is the value of the <code class=\"fm-code-in-text\">counter<\/code> variable at the end of the loop. In a single-threaded environment, all our transformations did not change any observable results because there is no other thread that can observe the value of <code class=\"fm-code-in-text\">counter<\/code> in the middle of our code. In a multithreading environment, the situation is different. In the original code, another thread could have seen <code class=\"fm-code-in-text\">counter<\/code> gradually increasing, while in the optimized version, <code class=\"fm-code-in-text\">counter<\/code> jumps directly to the final value.<a id=\"calibre_link-742\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><\/p>\n<p class=\"copyrightbody\">Now let\u2019s take the same logic and apply it to another piece of code. We will try to prevent two threads from running the same block of code by using a flag that we set before starting and resetting after we finish. Before entering the code, we will check the value of this flag and stop if the flag is set:<\/p>\n<pre class=\"programlisting\">if(_doingSomething) return;\n_doingSomething = true;\n\/\/ do something\n_doingSomething = false;<\/pre>\n<p class=\"copyrightbody\">But when we exit this code, the _<code class=\"fm-code-in-text\">doingSomething<\/code> flag will always be <code class=\"fm-code-in-text\">false<\/code>, which means that in a single-threaded environment, no one can ever observe the flag as <code class=\"fm-code-in-text\">true<\/code>, so this code is equivalent to<a id=\"calibre_link-743\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><\/p>\n<pre class=\"programlisting\">if(_doingSomething) return;\n\/\/ do something\n_doingSomething = false;<\/pre>\n<p class=\"copyrightbody\">The compiler is free to move or remove the code that sets the flag, thereby completely eliminating our homemade thread synchronization. And we can see that optimizing the code by making alterations that don\u2019t change the results of the code in a single-threaded environment might lead to results that are obviously nonsensical in a multithreaded environment.<\/p>\n<p class=\"copyrightbody\">Things are even worse than that because access to the computer\u2019s memory is so slow. CPUs have smaller and faster (but still slower than the CPU\u2019s processing) blocks of memory built into the CPU. This is called <i class=\"fm-italics\">cache memory<\/i>. The CPU tries to load data from the main memory into the cache before it is needed (in the background, while doing other things), so when the instruction to load a value from memory is executed, the value is already in the cache. Different cores may have their own cache memories.<\/p>\n<p class=\"copyrightbody\">All this together means code like<\/p>\n<pre class=\"programlisting\">public void Init()\n{\n    _value = 7;\n    _initialized = true;\n}<\/pre>\n<p class=\"copyrightbody\">does not guarantee that if <code class=\"fm-code-in-text\">_initialized<\/code> is <code class=\"fm-code-in-text\">true<\/code>, <code class=\"fm-code-in-text\">_value<\/code> is set. The compiler is allowed to swap the order of those assignments, and even if it doesn\u2019t, your code might see an outdated uninitialized version of _<code class=\"fm-code-in-text\">value<\/code> simply because it was already in the cache.<\/p>\n<p class=\"copyrightbody\">If you read just the first paragraph of the C# <code class=\"fm-code-in-text\">volatile<\/code> keyword, you may get the (wrong) impression that it can solve this problem. However, the C# <code class=\"fm-code-in-text\">volatile<\/code> semantics are so complicated that it doesn\u2019t guarantee access to the latest value and might cause even more problems. Basically, don\u2019t use <code class=\"fm-code-in-text\">volatile<\/code>&mdash;it doesn\u2019t do what you think it does.<a id=\"calibre_link-744\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-304\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><\/p>\n<p class=\"copyrightbody\">Obviously, it\u2019s impossible to write correct multithreaded code when any memory access can be moved or eliminated. That\u2019s why we have tools to limit the way the system moves memory access. There are operations that tell the system, \u201cDon\u2019t move reads earlier than this.\u201d This is called <i class=\"fm-italics\">acquire semantics<\/i>, and all the operations that acquire a lock have this property. There are operations that tell the system \u201cDon\u2019t move writes later than this point.\u201d This is called <i class=\"fm-italics\">release semantics<\/i>, and all the operations that release a lock have this property. Figure 7.1 shows how acquire and release semantics affect the system\u2019s ability to move memory operations.<\/p>\n<div class=\"figure\">\n<p class=\"figure1\"><img decoding=\"async\" alt=\"\" class=\"calibre23\" src=\"\/images\/CSConcurrency_Asynchronous\/000010.png\" \/><\/p>\n<p class=\"figure1\">Figure 7.1 Acquire and release semantics<\/p>\n<\/p><\/div>\n<p class=\"copyrightbody\">There are also operations that prevent the compiler from moving both reads and writes across them in any direction. Those are called <i class=\"fm-italics\">memory barriers<\/i>. The set of rules of exactly how the compiler and CPU are allowed to move memory access, in addition to what operations have to acquire or release, or memory barrier semantics, is called the <i class=\"fm-italics\">memory model<\/i>.<\/p>\n<p class=\"copyrightbody\">The important fact about memory reordering and the C# memory model is that if you always use locks when accessing any data that is shared between threads, everything just works. Acquiring a lock has acquire semantics and will give you the most up-to-date values from memory. Releasing a lock has release semantics that will write all changes back to memory, so they are available for the next thread that enters the lock. This also brings us to the first rule for simple multithreading: always use a lock when accessing shared data.<\/p>\n<p class=\"copyrightbody\">And now that we know we absolutely must use locks, we can talk about the most common problem with locks&mdash;deadlocks.<a id=\"calibre_link-745\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-233\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-746\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><\/p>\n<h2 class=\"fm-head\" id=\"calibre_link-67\">7.3 Deadlocks<\/h2>\n<p class=\"copyrightbody\">A deadlock, as we mentioned back in chapter 4, is a situation where a thread is stuck waiting for a resource that will never become available because of something that the same thread did. In the classic deadlock, one thread is holding resource A while waiting for resource B at the same time that another thread is holding resource B while waiting for resource A. At this point, both threads are stuck, each waiting for the other one to complete. And that will never happen because the other one is also stuck, as illustrated in figure 7.2.<a id=\"calibre_link-747\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-748\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><\/p>\n<div class=\"figure\">\n<p class=\"figure1\"><img decoding=\"async\" alt=\"\" class=\"calibre24\" src=\"\/images\/CSConcurrency_Asynchronous\/000011.png\" \/><\/p>\n<p class=\"figure1\">Figure 7.2 Simple deadlock between two threads<\/p>\n<\/p><\/div>\n<p class=\"copyrightbody\">While this is the classic and most common deadlock, deadlocks can be and often are more complicated. There can be any number of threads in a ring (thread 1 holding A waiting for B, thread 2 holding B waiting for C, and thread 3 holding C waiting for A) or even a single thread waiting for itself, which can happen when a thread is holding a resource while trying to acquire that same resource again.<\/p>\n<p class=\"copyrightbody\">Some types of resources, like the <code class=\"fm-code-in-text\">lock<\/code> statement or the <code class=\"fm-code-in-text\">Mutex<\/code> class, will let the same thread acquire them more than once (and you must release them the same number of times as you acquired them). Those are called <i class=\"fm-italics\">recursive locks<\/i>. Other resources, like the <code class=\"fm-code-in-text\">Semaphore<\/code> class or files in exclusive access mode, will consider each attempt to acquire them&mdash;even by the same thread&mdash;as a separate attempt and will block (causing a deadlock) or fail, depending on the actual resource.<a id=\"calibre_link-284\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-749\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-750\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><\/p>\n<p class=\"copyrightbody\">Sometimes you can see the problem by just reading the code. For example, in the following code, there are two methods, and one acquires locks in the reverse order of the other one.<\/p>\n<p class=\"fm-code-listing-caption\">Listing 7.4 Code with a simple deadlock bug<\/p>\n<pre class=\"programlisting\">public int Multiply()\n{ \n    lock(_leftOperandLock)                             <span class=\"fm-combinumeral\">\u2776<\/span>\n    {\n          lock(_rightOperandLock)\n          {\n              return _leftOperand * _rightOperand;\n          }\n     }\n}\npublic int Add()\n{ \n    lock(_rightOperandLock)                            <span class=\"fm-combinumeral\">\u2777<\/span>\n    {\n          lock(_leftOperandLock)\n          {\n              return _leftOperand * _rightOperand;\n          }\n     }\n}<\/pre>\n<p class=\"copyrightbody\"><span class=\"fm-combinumeral\">\u2776<\/span> lock left then right<\/p>\n<p class=\"copyrightbody\"><span class=\"fm-combinumeral\">\u2777<\/span> lock right then left<\/p>\n<p class=\"copyrightbody\">In this example, the person who wrote the <code class=\"fm-code-in-text\">Multiply<\/code> method locked the left operand first because you read math from left to right, and the person who wrote the <code class=\"fm-code-in-text\">Add<\/code> method locked the right operand first because they are right-handed. In each of the methods, the order does not matter, but if you run the two methods simultaneously and get unlucky with your timing, you get a deadlock.<a id=\"calibre_link-751\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-752\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-753\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><\/p>\n<p class=\"copyrightbody\">This brings us to the second rule for easy multithreading: always acquire the locks in the same order. The order itself doesn\u2019t matter. You can painstakingly analyze the code to deduce the optimal order, or you can always lock in alphabetical order&mdash;it doesn\u2019t matter. The point is to always lock in the same order. This is called <i class=\"fm-italics\">lock hierarchy.<\/i><\/p>\n<p class=\"copyrightbody\">The following listing fixes the bug in the previous listing by defining a lock hierarchy&mdash;locks are acquired in math-reading order, so <code class=\"fm-code-in-text\">_leftOperandLock<\/code> is always acquired before <code class=\"fm-code-in-text\">_rightOperandLock<\/code>.<\/p>\n<p class=\"fm-code-listing-caption\">Listing 7.5 Solving the deadlock with lock hierarchy<\/p>\n<pre class=\"programlisting\">public int Multiply()\n{ \n    lock(_leftOperandLock)                            <span class=\"fm-combinumeral\">\u2776<\/span>\n    {\n          lock(_rightOperandLock)\n          {\n              return _leftOperand * _rightOperand;\n          }\n     }\n}\npublic int Add()\n{ \n    lock(_leftOperandLock)                            <span class=\"fm-combinumeral\">\u2777<\/span>\n    {\n          lock(_leftOperandLock)\n          {\n              return _leftOperand * _rightOperand;\n          }\n     }\n}<\/pre>\n<p class=\"copyrightbody\"><span class=\"fm-combinumeral\">\u2776<\/span> lock left and then right<\/p>\n<p class=\"copyrightbody\"><span class=\"fm-combinumeral\">\u2777<\/span> Also lock left and then right<\/p>\n<p class=\"copyrightbody\">It\u2019s important to always keep the same lock order, even if we think we have a good reason to change it. For example, let\u2019s add a <code class=\"fm-code-in-text\">Divide<\/code> method, and because division by zero is not allowed in math, this method will check that the right operand is not zero before dividing the numbers (if the second number is zero, it will invoke the <code class=\"fm-code-in-text\">DivideByZero<\/code> event). We might be tempted to lock and check the right operand before locking the left operand because if the right operand is zero, we don\u2019t need to access the left operand at all.<a id=\"calibre_link-754\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-755\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-756\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><\/p>\n<p class=\"fm-code-listing-caption\">Listing 7.6 Causing a deadlock by trying to avoid unnecessary locking<\/p>\n<pre class=\"programlisting\">public int Divide()\n{\n   lock(_rightOperandLock)                             <span class=\"fm-combinumeral\">\u2776<\/span>\n   {\n      if(_rightOperand==0)\n      {\n          DivideByZeroEvent?.Invoke(this,EventArgs.Empty);\n          return 0\n      }\n      lock(_leftOperandLock)                           <span class=\"fm-combinumeral\">\u2777<\/span>\n      {\n          return _leftOperand\/_rightOperand; \n      }\n   }\n}<\/pre>\n<p class=\"copyrightbody\"><span class=\"fm-combinumeral\">\u2776<\/span> Locks right operand first (bug)<\/p>\n<p class=\"copyrightbody\"><span class=\"fm-combinumeral\">\u2777<\/span> Only locks left operand if needed<\/p>\n<p class=\"copyrightbody\">In this code, while trying to avoid unnecessary locking, we broke the lock order by locking the right operand before the left operand, thereby introducing a potential deadlock. We must always keep the lock ordering, as in the following listing.<\/p>\n<p class=\"fm-code-listing-caption\">Listing 7.7 Correct lock order but with unnecessary locking<\/p>\n<pre class=\"programlisting\">public int Divide()\n{\n   lock(_leftOperandLock)                             <span class=\"fm-combinumeral\">\u2776<\/span>\n   {\n      lock(_rightOperandLock)\n      {\n          if(_rightOperand==0)\n          {\n              DivideByZeroEvent?.Invoke(this,EventArgs.Empty);\n              return 0\n          }\n          return _leftOperand\/_rightOperand; \n      }\n   }\n}<\/pre>\n<p class=\"copyrightbody\"><span class=\"fm-combinumeral\">\u2776<\/span> Locks left operand first, even if we don\u2019t need it<\/p>\n<p class=\"copyrightbody\">In this listing, we kept the lock ordering, but if the right operand is zero, we acquire the left operand lock without using it. This is bad because we could delay another operation that needs the left operand. If we do not want to hold a lock we don\u2019t need (like in listing 7.7) and also do not want to risk getting into a deadlock (listing 7.6), then whenever we need to acquire a lock out of order, we have to release and reacquire locks as needed to keep the order intact&mdash;and deal with the possibility that things have changed because we released the lock. The correct way to write the previous listing while avoiding unnecessary locking is as follows.<\/p>\n<p class=\"fm-code-listing-caption\">Listing 7.8 Correct lock order without unnecessary locking<\/p>\n<pre class=\"programlisting\">public int Divide()\n{\n   lock(_rightOperandLock)                                     <span class=\"fm-combinumeral\">\u2776<\/span>\n   {\n      if(_rightOperand==0)\n      {\n          DivideByZeroEvent?.Invoke(this,EventArgs.Empty);\n          return 0                                             <span class=\"fm-combinumeral\">\u2777<\/span>\n      }\n   }                                                           <span class=\"fm-combinumeral\">\u2778<\/span>\n   lock(_leftOperandLock)                                      <span class=\"fm-combinumeral\">\u2778<\/span>\n   {                                                           <span class=\"fm-combinumeral\">\u2778<\/span>\n      lock(_rightOperandLock)                                  <span class=\"fm-combinumeral\">\u2778<\/span>\n      {\n          if(_rightOperand==0)                                 <span class=\"fm-combinumeral\">\u2779<\/span>\n          {                                                    <span class=\"fm-combinumeral\">\u2779<\/span>\n              DivideByZeroEvent?.Invoke(this,EventArgs.Empty); <span class=\"fm-combinumeral\">\u2779<\/span>\n              return 0                                         <span class=\"fm-combinumeral\">\u2779<\/span>\n          }                                                    <span class=\"fm-combinumeral\">\u2779<\/span>\n          return _leftOperand\/_rightOperand; \n      }\n   }\n}<\/pre>\n<p class=\"copyrightbody\"><span class=\"fm-combinumeral\">\u2776<\/span> Locks only the right operand<\/p>\n<p class=\"copyrightbody\"><span class=\"fm-combinumeral\">\u2777<\/span> If the right operand is zero, the method ends here.<\/p>\n<p class=\"copyrightbody\"><span class=\"fm-combinumeral\">\u2778<\/span> Releases lock and reacquires in the correct order<\/p>\n<p class=\"copyrightbody\"><span class=\"fm-combinumeral\">\u2779<\/span> Rechecks condition because it could have changed while the lock was released<\/p>\n<p class=\"copyrightbody\"><a id=\"calibre_link-757\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a>In this code, we acquired the right operand lock and handled the case where the right operand is zero. We then released the lock to acquire both locks in the correct order. Next, we had to handle the case where the right operand is zero again because it could have changed in that tiny period between when we released the right operand lock and when we acquired it again. And only then could we finally do the calculation and return the result.<\/p>\n<p class=\"copyrightbody\">But those were the easy cases. Sometimes, the deadlock is more difficult to find. The previous two listings, the ones with the correct locking order, still have a potential deadlock bug. Let\u2019s take a look at this code again (we\u2019ll use the shorter and simpler code from listing 7.7).<\/p>\n<p class=\"fm-code-listing-caption\">Listing 7.9 Correct lock ordering but still a potential deadlock<\/p>\n<pre class=\"programlisting\">public int Divide()\n{\n   lock(_leftOperandLock)\n   {\n      lock(_rightOperandLock)\n      {\n          if(_rightOperand==0)\n          {\n              DivideByZero?.Invoke(this,EventArgs.Empty);\n              return 0\n          }\n          return _leftOperand\/_rightOperand; \n      }\n   }\n}<\/pre>\n<p class=\"copyrightbody\">This code acquires both locks in the correct order, and then, if the second operand is zero, it invokes the <code class=\"fm-code-in-text\">DivideByZero<\/code> event; otherwise, it divides the first operand by the second and returns the result. The problem is in the call to the <code class=\"fm-code-in-text\">DivideByZero<\/code> event handler. The code in that event is outside our control. It could be written by someone from a different organization and could do different things in different applications. This code could, for example, have locks of its own.<a id=\"calibre_link-758\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-759\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-760\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><\/p>\n<p class=\"fm-code-listing-caption\">Listing 7.10 Code that triggers the deadlock bug in listing 7.9<\/p>\n<pre class=\"programlisting\">public void SomeMethod()\n{\n    lock(_outputLock)\n    {\n        Console.WriteLine(_numbers.Add());\n    }\n} \n \nPrivate void Numbers_DivideByZeroEvent(object sender, EventArgs ea)\n{\n    lock(_outputLock)\n    {\n        Console.WriteLine(\"Divide by zero\");\n    }\n}<\/pre>\n<p class=\"copyrightbody\">This code acquires a lock to call the <code class=\"fm-code-in-text\">Add<\/code> method from listing 7.5 and acquires the same lock if it is called by the <code class=\"fm-code-in-text\">Divide<\/code> method from listing 7.9. By itself, this code looks correct, just like our <code class=\"fm-code-in-text\">Divide<\/code> method that also by itself looks correct. <a id=\"calibre_link-761\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-762\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><\/p>\n<p class=\"copyrightbody\">But if one thread calls <code class=\"fm-code-in-text\">SomeMethod<\/code> while another thread tries to use <code class=\"fm-code-in-text\">Divide<\/code> to divide by zero, we might get a deadlock. The first thread acquires a lock on <code class=\"fm-code-in-text\">_outputLock<\/code> (in <code class=\"fm-code-in-text\">SomeMethod<\/code>) first and then tries to acquire <code class=\"fm-code-in-text\">_leftOperandLock<\/code> and <code class=\"fm-code-in-text\">_rightOperandLock<\/code> (inside <code class=\"fm-code-in-text\">Add<\/code>), while the second thread acquires <code class=\"fm-code-in-text\">_leftOperandLock<\/code> and <code class=\"fm-code-in-text\">_rightOperandLock<\/code> (inside <code class=\"fm-code-in-text\">Divide<\/code>) and then tries to acquire <code class=\"fm-code-in-text\">_outputLock<\/code> (in <code class=\"fm-code-in-text\">Numbers_DivideByZeroEvent<\/code>).<\/p>\n<p class=\"copyrightbody\">The first thread is holding <code class=\"fm-code-in-text\">_outputLock<\/code> while waiting for <code class=\"fm-code-in-text\">_leftOperandLock<\/code> and <code class=\"fm-code-in-text\">_rightOperandLock<\/code>, while the second thread is holding <code class=\"fm-code-in-text\">_leftOperandLock<\/code> and <code class=\"fm-code-in-text\">_rightOperandLock<\/code> while waiting for <code class=\"fm-code-in-text\">_outputLock.<\/code> This is the exact same problem we\u2019ve seen before, only now it\u2019s spread out over multiple files and is more difficult to debug.<\/p>\n<p class=\"copyrightbody\">This brings us to the third rule: never call code that is not under your control while holding a lock. When you need to call any code that is not under your control, you must call it after releasing the locks. For example, the current way to write the code from listing 7.9 is as follows.<\/p>\n<p class=\"fm-code-listing-caption\">Listing 7.11 Solving the event deadlock bug<\/p>\n<pre class=\"programlisting\">public int Divide()\n{\n   lock(_leftOperandLock)\n   {\n      lock(_rightOperandLock)\n      {\n          if(_rightOperand!=0)                          <span class=\"fm-combinumeral\">\u2776<\/span>\n          {\n              return _leftOperand\/_rightOperand;        <span class=\"fm-combinumeral\">\u2777<\/span>\n          }\n      }\n   }\n   DivideByZero?.Invoke(this,EventArgs.Empty);          <span class=\"fm-combinumeral\">\u2778<\/span>\n   return 0\n}<\/pre>\n<p class=\"copyrightbody\"><span class=\"fm-combinumeral\">\u2776<\/span> Reverses the condition<\/p>\n<p class=\"copyrightbody\"><span class=\"fm-combinumeral\">\u2777<\/span> If the right operand is not zero, the method ends here.<\/p>\n<p class=\"copyrightbody\"><span class=\"fm-combinumeral\">\u2778<\/span> Calls the event outside the lock<\/p>\n<p class=\"copyrightbody\">With this version, instead of checking whether the right operand is zero and invoking the event, we check whether the right operand is not zero and perform the calculation. This means that if we get to the code at the end of the method, after we release all the locks, the operand is zero, and at this point, it\u2019s safe to invoke events.<\/p>\n<p class=\"copyrightbody\"><a id=\"calibre_link-234\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a>You might think we can solve the problem by never holding more than one lock at the same time, but that can lead to race conditions.<a id=\"calibre_link-763\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-764\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><\/p>\n<h2 class=\"fm-head\" id=\"calibre_link-68\">7.4 Race conditions<\/h2>\n<p class=\"copyrightbody\">A <i class=\"fm-italics\">race condition<\/i> is a situation where the result of the code is dependent on uncontrollable timing events. For example, let\u2019s say someone \u201cfixed\u201d the <code class=\"fm-code-in-text\">Add<\/code> method from earlier to only hold one lock at a time, and that same developer also added a <code class=\"fm-code-in-text\">SetOperands<\/code> method to set the two operands using the same locking strategy.<a id=\"calibre_link-765\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-766\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-767\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-768\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><\/p>\n<p class=\"fm-code-listing-caption\">Listing 7.12 Holding just one lock at a time<\/p>\n<pre class=\"programlisting\">public int Add()\n{ \n    int leftCopy,rightCopy;\n    lock(_leftOperandLock)\n    {\n        leftCopy = _leftOperand;\n    }\n    lock(_rightOperandLock)\n    { \n       rightCopy = _rightOperand;\n    }\n    return rightCopy + leftCopy;   \n}\n \npublic int SetOperands(int left, int right)\n{ \n    lock(_leftOperandLock)\n    {\n        _leftOperand = left;\n    }\n    lock(_rightOperandLock)\n    { \n       _rightOperand = right;\n    }\n}<\/pre>\n<p class=\"copyrightbody\">In the <code class=\"fm-code-in-text\">Add<\/code> method, this code acquires a lock for both operands one at a time, copies the value to a local variable, and then immediately releases the lock. Likewise, in the <code class=\"fm-code-in-text\">SetOperands<\/code> method, the code acquires one lock, sets the values, and then releases the lock before repeating this for the second operand. Because the code never tries to acquire a lock while holding another, it is completely deadlock proof. However, together, those two methods present a new problem. If those two methods are called at exactly the same time, we can\u2019t be sure in what order the four lock statements will execute. If we are lucky, the two blocks from the same thread will execute together&mdash;let\u2019s call those situations the \u201cgood options\u201d (figure 7.3).<a id=\"calibre_link-769\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-770\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-771\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><\/p>\n<div class=\"figure\">\n<p class=\"figure1\"><img decoding=\"async\" alt=\"\" class=\"calibre25\" src=\"\/images\/CSConcurrency_Asynchronous\/000012.png\" \/><\/p>\n<p class=\"figure1\">Figure 7.3 Locking operations ordering with correct results<\/p>\n<\/p><\/div>\n<p class=\"copyrightbody\">In option 1, we get the correct result; we set the new values and then immediately use them. In option 2, we get an outdated result, but it\u2019s only outdated by less than a millisecond, so I\u2019m going to call this a correct result too. Usually, it is okay to produce a result that is just a little bit outdated (the acceptable value of \u201ca little bit\u201d varies greatly between projects), and it\u2019s exceptionally difficult to guarantee that the results are never outdated because of physics. If you look out the window and see that there is light outside, it only tells you that the sun existed 8 minutes ago (it takes the light from the sun about 8 minutes to get to the earth). It\u2019s possible (but, very fortunately for us, extremely unlikely) that during the last 8 minutes, the sun exploded, and we just don\u2019t know it yet.<\/p>\n<p class=\"copyrightbody\"><a id=\"calibre_link-772\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a>Because we can get different results based on tiny thread scheduling differences, this is already a race condition. But it gets worse because the operation from the two threads can interleave in any way. It\u2019s also possible the two operations from one thread will run between the operations from the other thread. Then we get the situation shown in figure 7.4.<\/p>\n<div class=\"figure\">\n<p class=\"figure1\"><img decoding=\"async\" alt=\"\" class=\"calibre26\" src=\"\/images\/CSConcurrency_Asynchronous\/000013.png\" \/><\/p>\n<p class=\"figure1\">Figure 7.4 Locking operations ordering with incorrect results<\/p>\n<\/p><\/div>\n<p class=\"copyrightbody\">In those two options, we clearly get incorrect results. What happened is that because we used separate short locks, we managed to get the results of a partial update despite using locks. This is due to the unfortunate fact that composing several thread-safe operations together does not necessarily result in a thread-safe operation&mdash;each of the two locks is individually thread safe, but two locks in succession are likely to introduce race conditions.<\/p>\n<p class=\"copyrightbody\">And this brings us to the fourth rule: you must hold locks for the entire operation. In case you are now screaming, \u201cNo, you must hold locks only for the absolute minimal duration!\u201d you are right and should keep reading because holding a lock for too long is likely to cause synchronization.<a id=\"calibre_link-773\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-774\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><\/p>\n<h2 class=\"fm-head\" id=\"calibre_link-69\">7.5 Synchronization<\/h2>\n<p class=\"copyrightbody\">Synchronization is the situation when operations happen sequentially and not in parallel. To demonstrate, let\u2019s revisit listing 4.11 for a quick recap of our adventure in chapter 4. We wrote a program that counts from 0 to 10 million. To count faster, we created two threads, each counting to five million. But then we didn\u2019t get the correct result because of the partial update problem that we talked about in chapter 4 and in more detail at the beginning of this chapter. After we fixed the problem by adding locks, we got the following.<a id=\"calibre_link-775\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-279\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-776\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><\/p>\n<p class=\"fm-code-listing-caption\">Listing 7. 13 Multithreaded counting to 10 million<\/p>\n<pre class=\"programlisting\">public void GetCorrectValue() \n{\n   int theValue = 0;\n   object theLock = new Object();\n \n   var threads = new Thread[2];\n   for(int i=0;i&lt;2;++i)\n   {\n      threads[i] = new Thread(()=&gt;\n      {\n         for(int j=0;j&lt;5000000;++j)\n         {\n            lock(theLock)\n            {\n               ++theValue;\n            }\n         }\n      });\n      threads[i].Start();\n   }\n \n   foreach(var current in threads) \n   { \n      current.Join();\n   }\n   Console.WriteLine(theValue);\n}<\/pre>\n<p class=\"copyrightbody\">This code creates two threads, and each increments a value five million times. To avoid the partial updates problem we talked about at the beginning of this chapter, the code uses a lock while incrementing the value. But there is still a problem with this code. We use two threads so we can increase performance, but because of the locks around the actual incrementing operations, the incrementing itself happens sequentially and not in parallel. Figure 7.5 is a diagram showing how the code runs.<\/p>\n<div class=\"figure\">\n<p class=\"figure1\"><img decoding=\"async\" alt=\"\" class=\"calibre27\" src=\"\/images\/CSConcurrency_Asynchronous\/000014.png\" \/><\/p>\n<p class=\"figure1\">Figure 7.5 Not getting performance gains from multithreading due to synchronization<\/p>\n<\/p><\/div>\n<p class=\"copyrightbody\">The first bar shows what would happen if we just built this code as a single-threaded program: we would have a single thread that starts, counts to 10 million, and then exits. The second two bars look like what we wanted to happen: two threads each doing half the work&mdash;finishing the same work in about half the time. The last two columns are what actually happened: we did divide the work between two threads, but whenever one of the threads is doing useful work, the other has to wait, resulting in no real parallelism and slower speed than the single-threaded case (because of thread synchronization overhead).<\/p>\n<p class=\"copyrightbody\"><a id=\"calibre_link-777\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a>This brings us to the fifth rule for easy multithreading: to avoid synchronization, we need to hold locks for the shortest time possible, preferably just for the time it takes to access the shared resource, and not for the duration of the entire operation. You may think that this rule conflicts with the previous one, that \u201chold locks for the minimum duration, and not for an entire operation\u201d somehow contradicts \u201chold locks for the entire operation.\u201d And if that is what you think, you are absolutely right. If our locks are too short, we risk race conditions, and if our locks are too long, we get synchronization.<\/p>\n<p class=\"copyrightbody\">We should try to aim for the happy middle ground where the locks are long enough to prevent race conditions but short enough to avoid synchronization. But this happy middle ground doesn\u2019t always exist. There are situations where reducing the lock\u2019s duration to anything that doesn\u2019t cause synchronization will cause race conditions. In those cases, you should remember that synchronization may hurt performance, but race conditions will produce incorrect and unexpected results. So prefer synchronization to race conditions.<\/p>\n<p class=\"copyrightbody\">Synchronization is bad if we intend to do things in parallel and synchronize them unintentionally, but it is actually desirable in some other cases. For example, in banking, it\u2019s generally frowned upon if money is transferred twice just because two wire transfer instructions arrived simultaneously. To avoid this situation, the international banking system (which is a highly decentralized digital distributed system run by thousands of different independent organizations around the world) synchronizes access to your bank account. Whenever you look at your bank account or credit card transaction history, you will see a sequence of transactions where each transaction ends before the next one begins.<\/p>\n<p class=\"copyrightbody\">Even if two credit card transactions started at the exact same time at two shops in different countries, and each shop used a different payment processor and a different bank (much more parallel than different threads in the same computer can ever be), the system will still synchronize them into an ordered sequence and act like one of them started after the other completed.<\/p>\n<p class=\"copyrightbody\">When you want to synchronize operations, you can use locks like in the counting example we\u2019ve just seen, or you can use one of the other more advanced strategies we will discuss in the next chapter. In cases when synchronization is not desired, when parallel operations become sequential unintentionally and reduce the performance of the system, two or more threads need exclusive access to the same shared resource (usually a lock) to do their work, so the threads alternate between themselves. Each thread acquires the resource, does a little bit of work, and releases it. However, sometimes the one thread might hold that resource for a very long time, preventing another thread from working at all. This is called starvation.<a id=\"calibre_link-778\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-779\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><\/p>\n<h2 class=\"fm-head\" id=\"calibre_link-70\">7.6 Starvation<\/h2>\n<p class=\"copyrightbody\"><i class=\"fm-italics\">Starvation<\/i> is the situation when one thread or a group of threads monopolizes access to some resource, never letting another thread or group of threads do any work. For example, the following program will create two threads, with each thread acquiring a lock and writing a character in the console (the first thread is a minus sign and the second thread is an x) in an infinite loop.<a id=\"calibre_link-780\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-781\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-280\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><\/p>\n<p class=\"fm-code-listing-caption\">Listing 7.14 Starvation due to locking<\/p>\n<pre class=\"programlisting\">using System.Diagnostics;\n \nvar theLock = new object();\nvar thread1 = new Thread(() =&gt;\n{\n   lock(theLock)\n   {\n      while (true)\n      {\n       Console.Write(\"-\");\n        }\n    }\n});\nthread1.Start();\n \nvar thread2 = new Thread(() =&gt;\n{\n    while (true)\n    {\n        lock (theLock)\n        {\n            Console.Write(\"x\");\n        }\n    }\n});\nthread2.Start();<\/pre>\n<p class=\"copyrightbody\">The first thread acquires the lock before entering the loop and releases it after the loop (because it\u2019s an infinite loop, that means never), while the second thread acquires and releases the lock for each character written to the console. If we run this program, we will see it writes only minus signs because the first thread holds the lock for the duration of the program, and the second thread never gets a chance to acquire the lock.<\/p>\n<p class=\"copyrightbody\">This brings us back to the fifth rule: hold locks for the shortest duration possible. When we talked about this rule before, we said that holding a lock for too long can lead to synchronization. Now we see that in extreme cases, we get starvation when we hold a lock for way too long.<\/p>\n<p class=\"copyrightbody\">Starvation is also often caused by some threads monopolizing other resources&mdash;often the CPU. If you have high-priority threads that do not block, they might prevent lower-priority threads from running. For example, this program creates two threads: the first thread writes minus signs to the console in an infinite loop, and the second write x characters. I\u2019ve bumped the second thread\u2019s priority to <code class=\"fm-code-in-text\">AboveNormal<\/code> and made the whole program use just the first CPU core (because otherwise, we\u2019d have to create enough threads to saturate all cores and risk making your computer unresponsive when you run this program). This is called <i class=\"fm-italics\">processor affinity<\/i>.<a id=\"calibre_link-782\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><\/p>\n<p class=\"fm-code-listing-caption\">Listing 7.15 Starvation due to thread priority<\/p>\n<pre class=\"programlisting\">using System.Diagnostics;\n \nProcess.GetCurrentProcess().ProcessorAffinity = new IntPtr(1);  <span class=\"fm-combinumeral\">\u2776<\/span>\n \nvar thread1 = new Thread(() =&gt;\n{\n   while (true)\n   {\n      Console.Write(\"-\");\n   }\n});\nthread1.Start();\n \nvar thread2 = new Thread(() =&gt;\n{\n   while (true)\n   {\n      Console.Write(\"x\");\n   }\n});\nthread2.Priority = ThreadPriority.AboveNormal;                  <span class=\"fm-combinumeral\">\u2777<\/span>\nthread2.Start();<\/pre>\n<p class=\"copyrightbody\"><span class=\"fm-combinumeral\">\u2776<\/span> Runs only on the first CPU core<\/p>\n<p class=\"copyrightbody\"><span class=\"fm-combinumeral\">\u2777<\/span> Increases thread priority<\/p>\n<p class=\"copyrightbody\">If we run this program on Windows, we will get a screen full of x characters with a single minus thrown in every once in a while. This happens because of an anti-starvation mechanism Microsoft added to the Windows thread scheduler. On Linux, we will see roughly the same number of x characters and minuses because by default, Linux does not allow changing the thread priority.<\/p>\n<p class=\"copyrightbody\">Running this program on those two operating systems shows the two sides of the problem with changing the threads\u2019 or processes\u2019 priority and affinity:<\/p>\n<ul class=\"calibre9\">\n<li class=\"fm-list-bullet\">\n<p class=\"list\">The Windows example showed us that even a tiny bump in a single thread\u2019s priority can significantly limit the processing power that other threads can use.<\/p>\n<\/li>\n<li class=\"fm-list-bullet\">\n<p class=\"list\">The Linux example showed us that priority and affinity sometimes don\u2019t work like we expect them to.<\/p>\n<\/li>\n<\/ul>\n<p class=\"copyrightbody\">And this gives us the final rule for easy multithreading: don\u2019t change priority or processor affinity.<\/p>\n<p class=\"copyrightbody\">Now that we have covered the most common multithreading mistakes and know how to avoid them, it\u2019s time to talk about different strategies for writing multithreaded code.<a id=\"calibre_link-783\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-784\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-281\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><\/p>\n<h2 class=\"fm-head\" id=\"calibre_link-785\">Summary<\/h2>\n<ul class=\"calibre9\">\n<li class=\"fm-list-bullet\">\n<p class=\"list\">The compiler and CPU may reorder or even eliminate memory access operation (as long as the result of your code doesn\u2019t change in a single-threaded environment). You can\u2019t count on other threads seeing the state that is consistent with the code you wrote unless you use locks. So always use a lock when accessing shared data.<\/p>\n<\/li>\n<li class=\"fm-list-bullet\">\n<p class=\"list\">Always acquire the locks in the same order; that is called <i class=\"fm-italics\">lock hierarchy<\/i>.<\/p>\n<\/li>\n<li class=\"fm-list-bullet\">\n<p class=\"list\">Never call code that is not under your control while holding a lock.<\/p>\n<\/li>\n<li class=\"fm-list-bullet\">\n<p class=\"list\">Composing several thread-safe operations together rarely results in a thread-safe operation.<\/p>\n<\/li>\n<li class=\"fm-list-bullet\">\n<p class=\"list\">Hold locks for entire operations.<\/p>\n<\/li>\n<li class=\"fm-list-bullet\">\n<p class=\"list\">Hold locks for the shortest possible duration.<\/p>\n<\/li>\n<li class=\"fm-list-bullet\">\n<p class=\"list\">The last two bullet points contradict each other. If you hold locks for too long, you might get synchronization. If your locks are not long enough, you get race conditions. Try to find something in the middle. If you can\u2019t do it, opt for longer locks because race conditions are typically worse than synchronization.<\/p>\n<\/li>\n<li class=\"fm-list-bullet\">\n<p class=\"list\">Synchronization is sometimes desirable. There are operations you want to perform sequentially, even when most of the system can work in parallel.<\/p>\n<\/li>\n<li class=\"fm-list-bullet\">\n<p class=\"list\">Don\u2019t change the thread\u2019s and processes\u2019 priority or processor affinity.<\/p>\n<\/li>\n<\/ul>\n<\/div>\n<\/div>\n<\/div>\n<div class=\"calibre1\" id=\"calibre_link-71\">\n<div id=\"calibre_link-786\" class=\"calibre2\">\n<div id=\"calibre_link-787\" class=\"calibre3\">\n<h1 class=\"copyrighta\" id=\"calibre_link-788\">Part 2. Advanced uses of async\/await and multithreading<\/h1>\n<p class=\"copyrightbody\"><span class=\"fm-part-initial-cap\">N<\/span>ow that you know all about <code class=\"fm-code-in-text\">async<\/code>\/<code class=\"fm-code-in-text\">await<\/code> and multithreading, it\u2019s time to dive deeper and understand that there\u2019s much more to multithreading and asynchronous programming than the <code class=\"fm-code-in-text\">await<\/code> keyword and <code class=\"fm-code-in-text\">Task.Run<\/code>.<\/p>\n<p class=\"copyrightbody\">Part 2 discusses different ways to process data in the background (chapter 8) and then explains how to cancel background processing (chapter 9). Next, you will learn how to build complex asynchronous components (chapter 10) and how to customize <code class=\"fm-code-in-text\">async<\/code>\/<code class=\"fm-code-in-text\">await<\/code>\u2019s threading behavior (chapter 11). We\u2019ll have a short discussion about the complexity of exceptions in asynchronous programming (chapter 12) and talk about thread-safe collections (chapter 13). In the final chapter, we\u2019ll talk about how to write our own asynchronous collection-like components (chapter 14).<\/p>\n<p class=\"copyrightbody\">By the end of part 2 (and the book), you should have everything you need to understand and develop multithreaded applications. You will know how all the parts work and how to combine them.<\/p>\n<\/div>\n<\/div>\n<\/div>\n<div class=\"calibre1\" id=\"calibre_link-72\">\n<div id=\"calibre_link-789\" class=\"calibre2\">\n<div id=\"calibre_link-790\" class=\"calibre3\">\n<h1 class=\"copyrighta\" id=\"calibre_link-791\">8 <a id=\"calibre_link-792\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-793\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-794\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-795\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a>Processing a sequence of items in the background<\/h1>\n<p class=\"copyrightbody\"><a id=\"calibre_link-197\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a>This chapter covers<a id=\"calibre_link-796\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><\/p>\n<ul class=\"calibre9\">\n<li class=\"co-summary-bullet\">Processing items in parallel<\/li>\n<li class=\"co-summary-bullet\">Performance characteristics of different ways to run code in parallel<\/li>\n<li class=\"co-summary-bullet\">Processing items sequentially in the background<\/li>\n<li class=\"co-summary-bullet\">Background processing of important jobs<\/li>\n<\/ul>\n<p class=\"copyrightbody\">There are three primary reasons for using multithreading in everyday applications. The first, and the most common, is when an application server needs to manage requests from multiple clients simultaneously. Typically, this is handled by the framework we use, such as ASP.NET, and it is beyond our control. The other two reasons for using multithreading are to finish processing sooner by performing parts of the processing in parallel and to push some tasks to be run later in the background. Both of these can significantly improve your program performance (or, at least, responsiveness and perceived performance). Let\u2019s begin by discussing the first reason: completing our processing faster.<\/p>\n<h2 class=\"fm-head\" id=\"calibre_link-73\">8.1 Processing items in parallel<\/h2>\n<p class=\"copyrightbody\">To demonstrate parallel processing, we will write the world\u2019s simplest mail merge software. Mail merge is a process that takes a mail template and creates an individual customized message for each recipient by replacing tokens in the template with information about the recipient.<a id=\"calibre_link-797\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-798\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-799\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-198\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><\/p>\n<p class=\"fm-code-listing-caption\">Listing 8.1 World\u2019s simplest mail merge<\/p>\n<pre class=\"programlisting\">void MailMerge(\n   string from,\n   string subject,\n   string text, \n   (string email,string name)[] recipients)\n{\n   var sender = new SmtpClient(\"smtp.example.com\");\n   foreach(var current in recipients)                          <span class=\"fm-combinumeral\">\u2776<\/span>\n   {\n      try\n      {\n         var message = new MailMessage();\n         message.From = new MailAddress(from);\n         message.Subject = subject;\n         message.To.Add(new MailAddress(current.email));\n         message.Body = text.Replace(\"{name}\", current.name);  <span class=\"fm-combinumeral\">\u2777<\/span>\n         sender.Send(message);                                 <span class=\"fm-combinumeral\">\u2778<\/span>\n      }\n      catch\n      {\n         LogFailure(current.email);\n      }\n   }\n}<\/pre>\n<p class=\"copyrightbody\"><span class=\"fm-combinumeral\">\u2776<\/span> Loops over all recipients<\/p>\n<p class=\"copyrightbody\"><span class=\"fm-combinumeral\">\u2777<\/span> Replaces token with value<\/p>\n<p class=\"copyrightbody\"><span class=\"fm-combinumeral\">\u2778<\/span> Sends message<\/p>\n<p class=\"copyrightbody\">This method accepts the sender\u2019s e-mail address, the mail subject line, the e-mail template text, and a list of recipients\u2019 names and addresses. It then replaces the token <code class=\"fm-code-in-text\">{name}<\/code> for each recipient with the recipient\u2019s name and sends the message. If there\u2019s an error, we just log it and continue (in real code, sending an e-mail can fail for many reasons, many of them being transient, so we\u2019ll usually have some retry logic).<\/p>\n<p class=\"copyrightbody\">Note that, due to constant abuse by spammers, e-mail service providers are very strict about enforcing their terms of use. If you need to send e-mail from your program, make sure you comply with your provider\u2019s terms and consider using a transactional e-mail&ndash;sending service instead of your regular e-mail service provider. I highly recommend you never write code that sends e-mail in a loop unless you\u2019ve cleared it with your e-mail service provider.<\/p>\n<p class=\"copyrightbody\">If we use this method in a web application, we will quickly run into an issue: sending an e-mail is slow and can take up to several seconds per message. The typical timeout for a web request is 30 seconds. That means we will start timing out and not returning the results to the user at somewhere between 10 and 40 messages, and this is a really small number of messages for anything that requires automated mail merge.<\/p>\n<h3 class=\"fm-head\" id=\"calibre_link-74\">8.1.1 Processing items in parallel with the Thread class<\/h3>\n<p class=\"copyrightbody\">We don\u2019t have time to wait for all the messages to be sent sequentially, so the obvious solution is to just send all the messages in parallel. That way, we only have to wait for as long as it takes to send the longest message. To parallelize this, we can use any of the options we talked about in chapter 4, for example, the <code class=\"fm-code-in-text\">Thread<\/code> class. <a id=\"calibre_link-800\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-801\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-802\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-263\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-803\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><\/p>\n<p class=\"fm-code-listing-caption\">Listing 8.2 Mail merge with a thread per message<\/p>\n<pre class=\"programlisting\"> void MailMerge(\n   string from,\n   string subject,\n   string text, \n   (string email,string name)[] recipients)\n{\n   var processingThreads = new Thread[recipients.Length];\n   for(int i=0;i&lt; recipients.Length;++i)\n   {\n      processingThreads[i] = new Thread(()=&gt;                 <span class=\"fm-combinumeral\">\u2776<\/span>\n      {\n         try\n         {\n            var sender = new SmtpClient(\"smtp.example.com\");\n            var message = new MailMessage();\n            message.From = new MailAddress(from);\n            message.Subject = subject;\n            message.To.Add(new MailAddress(recipients[i].email));\n            message.Body = text.Replace(\"{name}\", recipients[i].name);\n            sender.Send(message);\n         }\n         catch\n         {\n            LogFailure(current.email);\n         }\n      });\n      processingThreads[i].Start();\n   }\n   foreach(var current in processingThreads)                 <span class=\"fm-combinumeral\">\u2777<\/span>\n   { \n      current.Join();\n    }\n}<\/pre>\n<p class=\"copyrightbody\"><span class=\"fm-combinumeral\">\u2776<\/span> Sends each message in its own thread<\/p>\n<p class=\"copyrightbody\"><span class=\"fm-combinumeral\">\u2777<\/span> Waits for all threads to complete<\/p>\n<p class=\"copyrightbody\">In this code, we create a thread for every message we want to send, run all those threads in parallel, and then wait for all those threads to finish.<\/p>\n<p class=\"copyrightbody\">This can work just fine, but it does have a few weaknesses&mdash;most obviously, there is no limit to the number of threads this code can create. For example, if we have 10 simultaneous users, and each sends 100 messages (and those are not big numbers), this code is going to create 1,000 threads, and we don\u2019t know how that will affect our program\u2019s performance. But we can write a small program to estimate that effect.<\/p>\n<p class=\"fm-code-listing-caption\">Listing 8.3 Thread-per-message performance benchmark<\/p>\n<pre class=\"programlisting\">for (int j = 0; j &lt; 5; ++j)\n{\n   var sw = Stopwatch.StartNew();\n \n   var threads = new Thread[1000];\n   for (int i = 0; i &lt; 1000; i++)\n   {\n      threads[i] = new Thread(() =&gt; Thread.Sleep(1000));\n      threads[i].Start();\n   }\n   foreach (var current in threads) \n      current.Join();\n   sw.Stop();\n   Console.WriteLine(sw.ElapsedMilliseconds);\n}<\/pre>\n<p class=\"copyrightbody\">This program creates 1,000 threads, where each thread just sleeps for 1 second. We repeat this five times just to make sure we didn\u2019t get an incorrect number because of something that isn\u2019t related to our code running simultaneously.<\/p>\n<p class=\"copyrightbody\">When running in release configuration and without a debugger, my laptop outputs between 1.1 and 1.2 seconds for each iteration. This shows us that with a modern computer, the overhead of 1,000 threads is acceptable for our program.<\/p>\n<p class=\"copyrightbody\">If we increase the number of threads to 10,000, the output will be just over 2 seconds, and if we go to 100,000 threads, it will be between 15 and 20 seconds, and that is in a program that does nothing. In a real server, things are likely to be worse because the server needs to actually do useful work and not just play around with threads, so please don\u2019t create a huge number of threads and assume the overhead will be negligible.<\/p>\n<p class=\"copyrightbody\">Note that if you run the program under a debugger, you will get significantly worst results because the debugger monitors thread creation and destruction. When I ran the program under a debugger, it took 14 seconds instead of just 1.2&mdash;be careful with your performance tests!<a id=\"calibre_link-804\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-805\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-806\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-264\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-807\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><\/p>\n<h3 class=\"fm-head\" id=\"calibre_link-75\">8.1.2 Processing items in parallel with the thread pool<\/h3>\n<p class=\"copyrightbody\">Creating an arbitrarily large number of threads inside our server process seems bad. Fortunately for us, the thread pool was designed exactly for this situation. Let\u2019s move our message processing to the thread pool. We could use <code class=\"fm-code-in-text\">ThreadPool.QueueUserWorkItem<\/code> to run our code in the thread pool, but then we will have to write our own mechanism for detecting when all the threads finish sending the message. Writing this code isn\u2019t that difficult, but it\u2019s even easier to not write it, and Microsoft has been nice enough to include this feature in <code class=\"fm-code-in-text\">Task.Run<\/code>.<a id=\"calibre_link-808\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-809\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-810\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-811\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><\/p>\n<p class=\"fm-code-listing-caption\">Listing 8.4 Mail merge with each message processed in the thread pool<\/p>\n<pre class=\"programlisting\">void MailMerge(\n   string from,\n   string subject,\n   string text, \n   (string email,string name)[] recipients)\n{\n   var processingTasks = new Task[recipients.Length];\n   for(int i=0;i&lt; recipients.Length;++i)\n   {\n      processingTasks[i] = Task.Run(()=&gt;                 <span class=\"fm-combinumeral\">\u2776<\/span>\n      {\n         try\n         {\n            var sender = new SmtpClient(\"smtp.example.com\");\n            var message = new MailMessage();\n            message.From = new MailAddress(from);\n            message.Subject = subject;\n            message.To.Add(new MailAddress(recipients[i].email));\n            message.Body = text.Replace(\"{name}\", recipients[i].name);\n            sender.Send(message);\n         }\n         catch\n         {\n            LogFailure(current.email);\n         }\n      });\n   }\n   Task.WaitAll(processingTasks);                        <span class=\"fm-combinumeral\">\u2777<\/span>\n}<\/pre>\n<p class=\"copyrightbody\"><span class=\"fm-combinumeral\">\u2776<\/span> Uses Task.Run to run in the thread pool<\/p>\n<p class=\"copyrightbody\"><span class=\"fm-combinumeral\">\u2777<\/span> Waits for all threads to finish<\/p>\n<p class=\"copyrightbody\">This is almost the same code as that in listing 8.2. We just replaced <code class=\"fm-code-in-text\">new<\/code> <code class=\"fm-code-in-text\">Thread<\/code> with <code class=\"fm-code-in-text\">Task.Run<\/code>, removed the call to <code class=\"fm-code-in-text\">Thread.Start<\/code>, and changed the <code class=\"fm-code-in-text\">Join<\/code> loop at the end to a single call to <code class=\"fm-code-in-text\">Task.WaitAll<\/code>.<\/p>\n<p class=\"copyrightbody\"><a id=\"calibre_link-812\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a>This will solve the problem of potentially creating a huge number of threads. The thread pool will limit the number of threads to a sane number the system can handle, and there\u2019s no longer any thread creation and destruction overhead. However, we do introduce the possibility of oversaturating the thread pool. If we try to send the same 1,000 messages from the previous example, we will tie up the thread pool until all those messages are sent, and in the meantime, anything else that uses the thread pool (like ASP.NET, for example) will have to wait. That means our server might stop processing web requests if we try to send too many messages.<\/p>\n<p class=\"copyrightbody\">Let\u2019s modify our performance test program and see how switching to the thread pool improves our performance.<\/p>\n<p class=\"fm-code-listing-caption\">Listing 8.5 Thread pool performance benchmark<\/p>\n<pre class=\"programlisting\">for (int j = 0; j &lt; 5; ++j)\n{\n   var sw = Stopwatch.StartNew();\n \n   var tasks = new Task[1000];\n   for (int i = 0; i &lt; 1000; i++)\n   {\n      tasks[i] = Task.Run(() =&gt; Thread.Sleep(1000));\n   }\n   Task.WaitAll(tasks);\n   sw.Stop();\n   Console.WriteLine(sw.ElapsedMilliseconds);\n}<\/pre>\n<p class=\"copyrightbody\">Here we just took our code from listing 8.3 and made the same changes to switch from dedicated threads to the thread pool.<\/p>\n<p class=\"copyrightbody\">When I ran this performance test, I got 69 seconds for the first iteration, 37 for the second, 27 for the third, 23 for the fourth, and 20 seconds for the fifth and final iteration. What does this tell us? First, obviously, we completely overwhelmed the thread pool, and this version took 60 times longer to run compared to the previous one. But there\u2019s something weird in the results: each iteration is faster than the previous one. The reason for this is that the thread pool is always automatically optimizing the number of threads, and it will continue to become faster with every iteration. This means that while this is unacceptably slow for a program that does something that rarely requires a lot of threads, in a system that continuously uses a large number of threads, this will run very well.<\/p>\n<p class=\"copyrightbody\">If we are writing a program that we know will require a large number of thread pool threads, we can just tell the system about it and not wait for the automatic optimizations. If we tell the thread pool, we will require 1,000 worker threads by using the following two lines of code:<\/p>\n<pre class=\"programlisting\">ThreadPool.GetMinThreads(out _, out var completionPortThreads);\nThreadPool.SetMinThreads(1000, completionPortThreads);<\/pre>\n<p class=\"copyrightbody\">The first iteration will be just as fast as using the <code class=\"fm-code-in-text\">Thread<\/code> class, and subsequent iterations will be faster, averaging 1,025 milliseconds on my computer.<a id=\"calibre_link-813\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-814\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-815\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-261\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-816\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><\/p>\n<h3 class=\"fm-head\" id=\"calibre_link-76\">8.1.3 Asynchronously processing items in parallel<\/h3>\n<p class=\"copyrightbody\">In the previous example, we overwhelmed the thread pool because we added too many long-running work items, and there were not enough available threads to process them. In our case, the threads are long running because we used blocking operations. If those work items were doing calculations, the thread pool wouldn\u2019t have been slower than any other options because we would have been limited by the number of CPU cores. But our program is spending most of its time just waiting for the server and doing nothing. All those thread pool threads are just blocked and doing nothing. We already said that this is the exact situation where asynchronous techniques shine, so let\u2019s make our mail merge asynchronous.<a id=\"calibre_link-817\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-818\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-819\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><\/p>\n<p class=\"fm-code-listing-caption\">Listing 8.6 Asynchronous mail merge using <code class=\"fm-code-in-text1\">Task.Run<\/code><\/p>\n<pre class=\"programlisting\">void MailMerge(\n   string from,\n   string subject,\n   string text, \n   (string email,string name)[] recipients)\n{\n   var processingTasks = new Task[recipients.Length];\n   for(int i=0;i&lt; recipients.Length;++i)\n   {\n      processingTasks[i] = Task.Run(<b class=\"fm-bold\">async<\/b> ()=&gt;               <span class=\"fm-combinumeral\">\u2776<\/span>\n      {\n         try\n         {\n            var sender = new SmtpClient(\"smtp.example.com\");\n            var message = new MailMessage();\n            message.From = new MailAddress(from);\n            message.Subject = subject;\n            message.To.Add(new MailAddress(recipients[i].email));\n            message.Body = text.Replace(\"{name}\", recipients[i].name);\n            <b class=\"fm-bold\">await<\/b> sender.SendMail<b class=\"fm-bold\">Async<\/b>(message);             <span class=\"fm-combinumeral\">\u2777<\/span>\n         }\n         catch\n         {\n            LogFailure(current.email);\n         }\n      });\n   }\n   Task.WaitAll(processingTasks);\n}<\/pre>\n<p class=\"copyrightbody\"><span class=\"fm-combinumeral\">\u2776<\/span> Added async<\/p>\n<p class=\"copyrightbody\"><span class=\"fm-combinumeral\">\u2777<\/span> Added await<\/p>\n<p class=\"copyrightbody\">We only had to make two tiny changes to the code from listing 6.4. We added the <code class=\"fm-code-in-text\">async<\/code> keyword and switched from using <code class=\"fm-code-in-text\">Send<\/code> to <code class=\"fm-code-in-text\">SendMailAsync<\/code> awaiting the result (the <code class=\"fm-code-in-text\">async<\/code> version of <code class=\"fm-code-in-text\">Send<\/code> is called <code class=\"fm-code-in-text\">SendMailAsync<\/code> and not <code class=\"fm-code-in-text\">SendAsync<\/code> because that name was already taken by an older method that predates <code class=\"fm-code-in-text\">async<\/code>\/<code class=\"fm-code-in-text\">await<\/code>).<\/p>\n<p class=\"copyrightbody\">And, of course, we are also going to update our performance test to be asynchronous. This only requires changing <code class=\"fm-code-in-text\">()=&gt;Thread.Sleep(1000)<\/code> to <code class=\"fm-code-in-text\">async<\/code> <code class=\"fm-code-in-text\">()=&gt;<\/code> <code class=\"fm-code-in-text\">await<\/code> <code class=\"fm-code-in-text\">Task.Delay(1000)<\/code>.<a id=\"calibre_link-820\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><\/p>\n<p class=\"fm-code-listing-caption\">Listing 8.7 Asynchronous performance benchmark<\/p>\n<pre class=\"programlisting\">for (int j = 0; j &lt; 5; ++j)\n{\n   var sw = Stopwatch.StartNew();\n \n   var tasks = new Task[1000];\n   for (int i = 0; i &lt; 1000; i++)\n   {\n      tasks[i] = Task.Run(async () =&gt; await Task.Delay(1000));\n   }\n   Task.WaitAll(tasks);\n   sw.Stop();\n   Console.WriteLine(sw.ElapsedMilliseconds);\n}<\/pre>\n<p class=\"copyrightbody\">How is this going to affect performance? Running this code, I got results between 1,001 and 1,017 <i class=\"fm-italics\">milliseconds<\/i>, which means that here, the thread pool has virtually no overhead. It\u2019s important to remember that in the mail merge program, the code will spend most of its time waiting, but in our performance test, it spends <i class=\"fm-italics\">all<\/i> of its time waiting, so those results do not perfectly translate to the real program (I already said you need to be careful with your performance tests).<\/p>\n<h3 class=\"fm-head\" id=\"calibre_link-77\">8.1.4 The Parallel class<\/h3>\n<p class=\"copyrightbody\">In all the samples so far, we wrote a loop that created threads or added items to the thread pool. We then collected the <code class=\"fm-code-in-text\">Thread<\/code> or <code class=\"fm-code-in-text\">Task<\/code> objects so we could wait until they were all completed. This is tedious and exactly the kind of boilerplate code we don\u2019t like to write. Luckily, the .NET library has the <code class=\"fm-code-in-text\">Parallel<\/code> class that can do all of this for us.<a id=\"calibre_link-821\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-822\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-823\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-262\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-824\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><\/p>\n<p class=\"copyrightbody\">The <code class=\"fm-code-in-text\">Parallel<\/code> class has four static methods:<\/p>\n<ul class=\"calibre9\">\n<li class=\"fm-list-bullet\">\n<p class=\"list\"><code class=\"fm-code-in-text\">Invoke<\/code>&mdash;Takes an array of delegates and executes all of them, potentially in parallel. This method returns after all the delegates finish running.<\/p>\n<\/li>\n<li class=\"fm-list-bullet\">\n<p class=\"list\"><code class=\"fm-code-in-text\">For<\/code>&mdash;Acts like a <code class=\"fm-code-in-text\">for<\/code> loop, but iterations happen in parallel. It will return after all the iterations finish running.<\/p>\n<\/li>\n<li class=\"fm-list-bullet\">\n<p class=\"list\"><code class=\"fm-code-in-text\">ForEach<\/code>&mdash;Acts like a <code class=\"fm-code-in-text\">foreach<\/code> loop, but iterations happen in parallel. It will return after all the iterations finish running.<\/p>\n<\/li>\n<li class=\"fm-list-bullet\">\n<p class=\"list\"><code class=\"fm-code-in-text\">ForEachAsync<\/code>&mdash;Similar to <code class=\"fm-code-in-text\">ForEach<\/code>, but the loop body is an async method. It will return immediately and return a <code class=\"fm-code-in-text\">Task<\/code> that will complete when all the iterations finish running.<\/p>\n<\/li>\n<\/ul>\n<p class=\"copyrightbody\">In this chapter, we talk about <code class=\"fm-code-in-text\">Parallel.ForEach<\/code> and <code class=\"fm-code-in-text\">Parallel.ForEachAsync<\/code> because they are useful for our mail merge example. Internally, <code class=\"fm-code-in-text\">Invoke<\/code> and <code class=\"fm-code-in-text\">For<\/code> use the same code as <code class=\"fm-code-in-text\">ForEach<\/code>. Here is what that code will look like if we use the <code class=\"fm-code-in-text\">Parallel<\/code> class.<\/p>\n<p class=\"fm-code-listing-caption\">Listing 8.8 Mail merge with the <code class=\"fm-code-in-text1\">Parallel<\/code> class<\/p>\n<pre class=\"programlisting\">void MailMerge(\n   string from,\n   string subject,\n   string text, \n   (string email,string name)[] recipients)\n{\n   var processingTasks = new Task[recipients.Length];\n   Parallel.ForEach(recipients, \n      (current,_) =&gt;\n      {\n         try\n         {\n            var sender = new SmtpClient(\"smtp.example.com\");\n            var message = new MailMessage();\n            message.From = new MailAddress(from);\n            message.Subject = subject;\n            message.To.Add(new MailAddress(current.email));\n            message.Body = text.Replace(\"{name}\", current.name);\n            sender.Send(message);\n         }\n         catch\n         {\n            LogFailure(current.email);\n         }\n      }).Wait();\n}<\/pre>\n<p class=\"copyrightbody\">We can see that this code looks closer to the original nonmultithreaded code from listing 8.1. Basically, we swapped <code class=\"fm-code-in-text\">foreach<\/code> for <code class=\"fm-code-in-text\">Parallel.ForEach<\/code>, which made our code run in parallel. The ignored parameter is a cancellation token. We will talk about those in the next chapter.<\/p>\n<p class=\"copyrightbody\">The <code class=\"fm-code-in-text\">Parallel<\/code> class also supports cancellation, setting a scheduler, and controlling the maximum number of items we process simultaneously. Cancellation is easy to implement ourselves, and we will talk about it in the next chapter. Using schedulers is also widely supported, and we will talk about it in chapter 11. Controlling the maximum number of items processed in parallel is not easily available elsewhere and is, surprisingly, the biggest pitfall of using the <code class=\"fm-code-in-text\">Parallel<\/code> class. If we migrate our performance test to use <code class=\"fm-code-in-text\">Parallel.ForEach<\/code>, we get the following.<a id=\"calibre_link-825\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><\/p>\n<p class=\"fm-code-listing-caption\">Listing 8.9 <code class=\"fm-code-in-text1\">Parallel.ForEach<\/code> performance benchmark<\/p>\n<pre class=\"programlisting\">for (int j = 0; j &lt; 5; ++j)\n{\n   var items = Enumerable.Range(0, 1000).ToArray();\n   var sw = Stopwatch.StartNew();\n   Parallel.ForEach(items, \n      (item)=&gt;Thread.Sleep(1000));\n   sw.Stop();\n   Console.WriteLine(sw.ElapsedMilliseconds);\n}<\/pre>\n<p class=\"copyrightbody\">In this version of the performance test, we create an array of numbers from 0 to 999 and use <code class=\"fm-code-in-text\">Parallel.ForEach<\/code> to iterate over them, waiting 1 second for each item. I fully expected this code to have exactly the same performance characteristics as when using <code class=\"fm-code-in-text\">Task.Run<\/code> in listing 8.5 because it\u2019s a different syntax for doing exactly the same thing. But when I ran it, I was surprised. The first iteration took 48 seconds&mdash;faster than the almost 70 seconds we got using <code class=\"fm-code-in-text\">Task.Run<\/code>. However, all subsequent iterations took 31 seconds, which was faster than the first two iterations with <code class=\"fm-code-in-text\">Task.Run<\/code> but slower than the third iteration and later.<\/p>\n<p class=\"copyrightbody\">What happened here is that contrary to what is explicitly written in the documentation, <code class=\"fm-code-in-text\">Parallel.ForEach<\/code> by default limits the number of items processed in parallel, so it didn\u2019t quite overwhelm the thread pool as much as our <code class=\"fm-code-in-text\">Task.Run<\/code> code did. However, because of that, the thread pool self-optimization didn\u2019t create so many threads in response to our unreasonable load, and that is why later iterations are slower with <code class=\"fm-code-in-text\">Parallel.ForEach<\/code>.<\/p>\n<p class=\"copyrightbody\">We can test this theory by setting the max number of items to be processed in parallel to a high number, by replacing the <code class=\"fm-code-in-text\">Parallel.ForEach<\/code> line with<\/p>\n<pre class=\"programlisting\">Parallel.ForEach(items,\n   new ParallelOptions { MaxDegreeOfParallelism = 1000 },\n   (item)=&gt;Thread.Sleep(1000));<\/pre>\n<p class=\"copyrightbody\">If we do that and set <code class=\"fm-code-in-text\">MaxDegreeOfParallelism<\/code> to the length of the list (thereby telling it to process everything simultaneously), we do get the exact same performance characteristics we got with <code class=\"fm-code-in-text\">Task.Run<\/code> in listing 8.5. This is in contradiction to the official documentation that clearly states that the default behavior is to use all threads and that setting <code class=\"fm-code-in-text\">MaxDegreeOfParallelism<\/code> can only reduce but never increase the number of threads used. This means <code class=\"fm-code-in-text\">Parallel.ForEach<\/code> works very well for shorter collections and when the thread pool didn\u2019t have a chance to create a lot of threads already.<\/p>\n<p class=\"copyrightbody\">Note that whenever we find that the observed behavior contradicts the documented behavior, we have a problem. Obviously, we can\u2019t rely on the documented behavior because that\u2019s not how the system actually works. But it\u2019s also risky to rely on the observed behavior because any update can fix the bug and make the system work as documented. We need to either write code that works well with both the documented behavior and the observed behavior or take the risk that we will need to issue as emergency update if this ever gets fixed in the future.<\/p>\n<p class=\"copyrightbody\">In the previous examples that used <code class=\"fm-code-in-text\">Task.Run<\/code>, we got an enormous speed boost when we switched from blocking operations (listings 8.4 and 8.5) to asynchronous operations (listings 8.6 and 8.7). Unfortunately, this doesn\u2019t happen when switching from <code class=\"fm-code-in-text\">Parallel.ForEach<\/code> to its <code class=\"fm-code-in-text\">async<\/code>\/<code class=\"fm-code-in-text\">await<\/code> compatible counterpart <code class=\"fm-code-in-text\">Parallel.ForEachAsync<\/code>. Unlike <code class=\"fm-code-in-text\">Parallel.ForEach<\/code>, the default <code class=\"fm-code-in-text\">MaxDegreeOfParallelism<\/code> is, according to the documentation, the number of cores, and this is logically and theoretically the most efficient number of threads for asynchronous code. However, here is the problem: <code class=\"fm-code-in-text\">Parallel.ForEachAsync<\/code> uses this as the number of items that are processed at the same time and not the number of threads.<a id=\"calibre_link-826\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><\/p>\n<p class=\"copyrightbody\">For example, our code waits asynchronously for 1 second 1,000 times, and my laptop has 12 cores, so <code class=\"fm-code-in-text\">Parallel.ForEachAsync<\/code> will start working on the first 12 items. They will all take exactly 1 second to complete, and it will then start working on the next 12, for a total run time of 84 seconds (because 1,000 divided by 12 rounded up is 84).<\/p>\n<p class=\"copyrightbody\">This behavior is problematic, and unless it\u2019s changed in a future version of .NET, I would recommend avoiding <code class=\"fm-code-in-text\">Parallel.ForEachAsync<\/code> or, if you have to use it, choosing a good value for <code class=\"fm-code-in-text\">MaxDegreeOfParallelism<\/code>.<\/p>\n<p class=\"copyrightbody\">For completeness, here is a version of the code with <code class=\"fm-code-in-text\">Parallel.ForEachAsync<\/code>.<\/p>\n<p class=\"fm-code-listing-caption\">Listing 8.10 Asyncronous mail merge with the <code class=\"fm-code-in-text1\">Parallel<\/code> class<\/p>\n<pre class=\"programlisting\">void MailMerge(\n   string from,\n   string subject,\n   string text, \n   (string email,string name)[] recipients)\n{\n   var processingTasks = new Task[recipients.Length];\n   Parallel.ForEachAsync(recipients,                        <span class=\"fm-combinumeral\">\u2776<\/span>\n      new ParallelOptions { \n         MaxDegreeOfParallelism= recipients.Length          <span class=\"fm-combinumeral\">\u2777<\/span>\n      },\n      async (current,_) =&gt;                                  <span class=\"fm-combinumeral\">\u2778<\/span>\n      {\n         try\n         {\n            var sender = new SmtpClient(\"smtp.example.com\");\n            var message = new MailMessage();\n            message.From = new MailAddress(from);\n            message.Subject = subject;\n            message.To.Add(new MailAddress(current.email));\n            message.Body = text.Replace(\"{name}\", current.name);\n            await sender.SendMailAsync(message);            <span class=\"fm-combinumeral\">\u2779<\/span>\n         }\n         catch\n         {\n            LogFailure(current.email);\n         }\n      }).Wait();                                            <span class=\"fm-combinumeral\">\u277a<\/span>\n}<\/pre>\n<p class=\"copyrightbody\"><span class=\"fm-combinumeral\">\u2776<\/span> Uses Parallel.ForEach<\/p>\n<p class=\"copyrightbody\"><span class=\"fm-combinumeral\">\u2777<\/span> Don\u2019t forget MaxDegreeOfParallelism.<\/p>\n<p class=\"copyrightbody\"><span class=\"fm-combinumeral\">\u2778<\/span> Makes the loop body lambda async<\/p>\n<p class=\"copyrightbody\"><span class=\"fm-combinumeral\">\u2779<\/span> Awaits the async version of Send<\/p>\n<p class=\"copyrightbody\"><span class=\"fm-combinumeral\">\u277a<\/span> At the end, waits until all threads complete<\/p>\n<p class=\"copyrightbody\">In this code, we made the following changes:<\/p>\n<ul class=\"calibre9\">\n<li class=\"fm-list-bullet\">\n<p class=\"list\">We made the loop body lambda <code class=\"fm-code-in-text\">async<\/code>, switched from <code class=\"fm-code-in-text\">Send<\/code> to <code class=\"fm-code-in-text\">SendMailAsync<\/code>, and awaited it (like the changes we made when we converted the <code class=\"fm-code-in-text\">Task.Run<\/code> example to <code class=\"fm-code-in-text\">async<\/code> in listing 8.6).<\/p>\n<\/li>\n<li class=\"fm-list-bullet\">\n<p class=\"list\">We used <code class=\"fm-code-in-text\">Task.Wait()<\/code> on the task returned from <code class=\"fm-code-in-text\">Parallel.ForEachAsync<\/code> to wait until all the processing completes (in listing 8.6, we used <code class=\"fm-code-in-text\">Task.WaitAll<\/code> for the same purpose).<\/p>\n<\/li>\n<li class=\"fm-list-bullet\">\n<p class=\"list\">And finally, we set <code class=\"fm-code-in-text\">MaxDegreeOfParallelism<\/code> to the length of the list. This is probably not the optimal value, but it\u2019s much better than the default.<a id=\"calibre_link-827\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-828\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-829\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-830\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-831\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-832\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-833\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><\/p>\n<\/li>\n<\/ul>\n<h2 class=\"fm-head\" id=\"calibre_link-78\">8.2 Processing items sequentially in the background<\/h2>\n<p class=\"copyrightbody\">In all the preceding examples, we always waited until all the messages were sent, but we didn\u2019t do anything with the result of the sending operation. We could have just moved the sending operation to a background thread and returned a reply to the user immediately without waiting for the result. Basically, if we don\u2019t wait for all the messages to be sent, we don\u2019t care how long it takes to send them.<a id=\"calibre_link-834\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-835\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-199\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><\/p>\n<p class=\"copyrightbody\">If we just move the entire e-mail sending loop to a background thread, we solve all our performance problems. And, as a bonus, we are also nicer to our e-mail service provider because we don\u2019t try to send an unreasonable number of messages simultaneously.<\/p>\n<h3 class=\"fm-head\" id=\"calibre_link-79\">8.2.1 Processing items sequentially in the background with the Thread class<\/h3>\n<p class=\"copyrightbody\">Way back at the beginning of the chapter, when we started running things in parallel in listing 8.2, the first thing we used was the <code class=\"fm-code-in-text\">Thread<\/code> class, so it only seems fitting that the first thing we use here is also the <code class=\"fm-code-in-text\">Thread<\/code> class.<a id=\"calibre_link-836\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-837\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-838\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><\/p>\n<p class=\"fm-code-listing-caption\">Listing 8.11 Moving the entire loop to a background thread<\/p>\n<pre class=\"programlisting\">void MailMerge(\n   string from,\n   string subject,\n   string text, \n   (string email,string name)[] recipients)\n{\n   var processingThread = new Thread(()=&gt;                 <span class=\"fm-combinumeral\">\u2776<\/span>\n   {\n      var sender = new SmtpClient(\"smtp.example.com\");\n      foreach(var current in recipients)\n      {\n         Try                                              <span class=\"fm-combinumeral\">\u2777<\/span>\n         {\n            var message = new MailMessage();\n            message.From = new MailAddress(from);\n            message.Subject = subject;\n            message.To.Add(new MailAddress(current.email));\n            message.Body = text.Replace(\"{name}\", current.name);\n            sender.Send(message);\n         }\n         catch\n         {\n            LogFailure(current.email);\n         }\n      });\n      processingThread.Start();\n   }\n}<\/pre>\n<p class=\"copyrightbody\"><span class=\"fm-combinumeral\">\u2776<\/span> Creates thread here<\/p>\n<p class=\"copyrightbody\"><span class=\"fm-combinumeral\">\u2777<\/span> Instead of here<\/p>\n<p class=\"copyrightbody\"><a id=\"calibre_link-839\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a>This code is very similar to listing 8.2. Basically, the only difference is that we create our thread outside the loop instead of inside. We still don\u2019t have a limit on the number of threads this code can create, but it\u2019s now one per request and not one per message, so the performance implications should really be negligible.<\/p>\n<p class=\"copyrightbody\">It\u2019s important to note that if we try to exit our program normally (which never happens in ASP.NET applications but does happen in the command line and native UI apps), the program will not exit until the thread finishes sending all the messages. This can be an advantage or a disadvantage, depending on the situation. If we want the program to exit without waiting for the thread, we can set the thread\u2019s <code class=\"fm-code-in-text\">IsBackground<\/code> property to <code class=\"fm-code-in-text\">true<\/code>.<\/p>\n<p class=\"copyrightbody\">Spinning up a new thread to run some process in the background is useful in single-user applications, such as native UI apps, because we only need to run work in the background occasionally, and if the app does produce too many threads and overwhelms the CPU, the only person that suffers from the degraded performance is the user who made the app do it. This is not true for servers. In servers (and other multiuser scenarios), we tend to have to manage sustained load and prevent any single user from overwhelming the system. That is why in servers we need to better control the number of threads, and for this, we will usually use the work queue pattern.<\/p>\n<h3 class=\"fm-head\" id=\"calibre_link-80\">8.2.2 The work queue pattern and BlockingCollection<\/h3>\n<p class=\"copyrightbody\">If we no longer care about the time it takes to send the messages, it\u2019s better to just use one thread, or a small, fixed number of threads, that will send everything. This is called the <i class=\"fm-italics\">work queue pattern<\/i> and is implemented by creating a queue where every thread can add items to the queue, and there is a dedicated set of threads that processes all the items. Those threads just have a loop that reads the next item from the queue and handles it. To keep the code simple, we\u2019ll have just one processing thread in our example.<a id=\"calibre_link-840\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-841\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-842\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-843\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-205\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><\/p>\n<p class=\"copyrightbody\">There are a surprisingly large number of tiny details you must get right when building this queue, but Microsoft has been nice enough to do most of the work for us with the <code class=\"fm-code-in-text\">BlockingCollection&lt;T&gt;<\/code> class. <a id=\"calibre_link-844\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><\/p>\n<p class=\"copyrightbody\"><code class=\"fm-code-in-text\">BlockingCollection&lt;T&gt;<\/code> can be used in multiple ways. For example, it can be used as a thread-safe <code class=\"fm-code-in-text\">List&lt;T&gt;<\/code>. But the interesting scenario is when we use <code class=\"fm-code-in-text\">BlockingCollection&lt;T&gt;<\/code> as a work queue. In this case, there are only three methods we care about:<\/p>\n<ul class=\"calibre9\">\n<li class=\"fm-list-bullet\">\n<p class=\"list\"><code class=\"fm-code-in-text\">Add<\/code>&mdash;Unsurprisingly, adds a new item to the end of the queue.<\/p>\n<\/li>\n<li class=\"fm-list-bullet\">\n<p class=\"list\"><code class=\"fm-code-in-text\">CompleteAdding<\/code>&mdash;Indicates that we will not add any more items, and the thread that is processing the items can exit after it finishes with items already in the queue.<\/p>\n<\/li>\n<li class=\"fm-list-bullet\">\n<p class=\"list\"><code class=\"fm-code-in-text\">GetConsumingEnumerable<\/code>&mdash;Returns an object that can be used with a <code class=\"fm-code-in-text\">foreach<\/code> loop to iterate over all the items in the queue. If the queue is empty, <code class=\"fm-code-in-text\">foreach<\/code> will block until another item is added to the queue or <code class=\"fm-code-in-text\">CompleteAdding<\/code> is called. When <code class=\"fm-code-in-text\">CompleteAdding<\/code> is called, the enumerable will indicate that there are no more items, and the <code class=\"fm-code-in-text\">foreach<\/code> loop will exit.<\/p>\n<\/li>\n<\/ul>\n<p class=\"copyrightbody\">Because this is a bit longer than the previous examples, I\u2019ve written it as a class and not as a method. We\u2019ll start with the class definition, a record to store all the information we need to store in the queue and the <code class=\"fm-code-in-text\">BlockingCollection<\/code> queue itself.<\/p>\n<p class=\"fm-code-listing-caption\">Listing 8.12 Work queue with <code class=\"fm-code-in-text1\">BlockingCollection<\/code><\/p>\n<pre class=\"programlisting\">public class MailMerger\n{\n   private record MailInfo(\n      string from,\n      string subject,\n      string text,\n      string email);\n \n   BlockingCollection&lt;MailInfo&gt; _queue = new();<\/pre>\n<p class=\"copyrightbody\">Now we need to create a thread to process the queue (the code to run in that thread is in the <code class=\"fm-code-in-text\">BackgroundThread<\/code>):<\/p>\n<pre class=\"programlisting\">   public void Start()\n   {\n      var thread = new Thread(BackgroundProc);\n      thread.Start();\n   }<\/pre>\n<p class=\"copyrightbody\">We will also add a way to close the background thread, so we should add a method that calls <code class=\"fm-code-in-text\">CompleteAdding<\/code>; that will cause the background thread to exit once everything in the queue is already handled:<\/p>\n<pre class=\"programlisting\">   public void Stop()\n   {\n      _queue.CompleteAdding();\n   }<\/pre>\n<p class=\"copyrightbody\"><a id=\"calibre_link-845\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a>Now we add a method that acts like the <code class=\"fm-code-in-text\">MailMerge<\/code> from the previous code listings. In this example, this method only adds to the queue and doesn\u2019t actually send the mail. We run the mail merge loop here and add the individually prepared messages to the queue. Preparing the messages before inserting them into or after reading them from the queue doesn\u2019t make any difference here, but it is important for persistent queues (we will talk about that in just a few paragraphs):<\/p>\n<pre class=\"programlisting\">   public void MailMerge(\n      string from,\n      string subject,\n      string text,\n      (string email, string name)[] recipients)\n   {\n      foreach(var current in recipients)\n      {\n         _queue.Add(new MailInfo(\n            from, \n            subject, \n            text.Replace(\"{name}\", current.name),\n            current.email));\n      }\n   }<\/pre>\n<p class=\"copyrightbody\">And finally, the part you\u2019ve all been waiting for&mdash;the code that runs in the background thread and sends this message. This method is somewhat anticlimactic. It just uses <code class=\"fm-code-in-text\">foreach<\/code> on the return value of the <code class=\"fm-code-in-text\">BlockingCollections.GetConsumingEnumerable<\/code> and sends the message:<\/p>\n<pre class=\"programlisting\">   private void BackgroundProc()\n   {\n      var sender = new SmtpClient(\"smtp.example.com\");\n      foreach (var current in _queue.GetConsumingEnumerable())\n      {\n         try\n         {\n            var message = new MailMessage();\n            message.From = new MailAddress(current.from);\n            message.Subject = current.subject;\n            message.To.Add(new MailAddress(current.email));\n            message.Body = current.text.Replace(\"{name}\", current.name);\n            sender.Send(message);\n         }\n         catch\n         {\n            LogFailure(current.email);\n         }\n      }\n   }\n \n}<\/pre>\n<p class=\"copyrightbody\">This is a complete work queue implementation of our mail merge feature. We used the <code class=\"fm-code-in-text\">Thread<\/code> class because this is a very long-running thread&mdash;probably it will run for the entire run time of the program&mdash;and using the thread pool will just use up one of the thread pool threads without giving us the benefit of being able to reuse that thread for something else after we finish with it (because we will never finish with it). We saw back in chapter 5 that the <code class=\"fm-code-in-text\">Thread<\/code> class doesn\u2019t work well with asynchronous code, but <code class=\"fm-code-in-text\">BlockingCollection<\/code> is not asynchronous and does not have an asynchronous version that does not block. You will see how we can build one in chapter 10.<\/p>\n<p class=\"copyrightbody\"><code class=\"fm-code-in-text\">BlockingCollection<\/code> is stored only in memory, meaning that if the process crashes or exists in any other way (including if the computer is rebooted or someone pulls the power cord), all unprocessed items that are still in the queue will be lost. This makes it suitable only for \u201cbest effort\u201d work (the system will try to do the work, but it can fail unexpectedly for any reason). If you need a more reliable work queue implementation, you need to use persistent queues.<a id=\"calibre_link-846\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-847\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-848\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-849\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><\/p>\n<h3 class=\"fm-head\" id=\"calibre_link-81\">8.2.3 Processing important items with persistent queues<\/h3>\n<p class=\"copyrightbody\">In all the previous samples, if the process crashes (and in some of them, even if the process exists normally), all the messages that are still pending would be lost. In many cases, this is unacceptable. For those situations, we will use persistent queues (also called durable queues).<a id=\"calibre_link-850\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-851\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-852\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-206\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-853\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><\/p>\n<p class=\"copyrightbody\">Persistent queues are simply queues stored on disk and not in memory, so they are not lost if the program crashes. You can write your own queue by just storing the items in a database table, or you can use a separate queues server. If you are running in a cloud environment, your cloud provider probably has a cheap and easy-to-use queueing service you can use (AWS has SQS, and Azure has storage queues). Another common option is the free RabbitMQ server. However, how exactly to use Azure, AWS, or RabbitMQ is outside the scope of this book.<\/p>\n<p class=\"copyrightbody\">When you use a persistent queue, reading the next item from the queue and removing it can be separate operations. This is important because it lets us select what happens when there\u2019s a failure.<\/p>\n<p class=\"copyrightbody\">The first option is to remove the item from the queue after we finish processing it. In this case, if a stray cat pulls the power cord out of the wall right after we finish processing but before we remove the item, then after the computer restarts, we won\u2019t know that we already processed this item, and we will process it again. This is called \u201cat-least-once delivery.\u201d<\/p>\n<p class=\"copyrightbody\">The second option is to remove the item from the queue before we process it. In this case, if a good dog wags his tail because he is happy to see us and hits the power switch after we remove the item from the queue but before we process it, then after the computer restarts, the item will not be in the queue and will never be processed. This is called \u201cat-most-once delivery.\u201d<\/p>\n<p class=\"copyrightbody\">What we really want is to guarantee each item will be processed once and only once. This is called \u201cexactly once delivery\u201d and, unfortunately, is usually impossible. For example, in our mail merge program, even if our queue supports exactly one delivery, if we lose connection to the mail server after we finished sending the message but before we got the confirmation from the server, we have no way of knowing whether the message was sent. And that brings us back to the same situation where we must either risk sending the message twice or risk not sending it at all.<\/p>\n<p class=\"copyrightbody\">In almost all cases, losing data is worse than processing it twice, and we will opt for at least one delivery. But if we opt for at least one delivery, and there is a message in the queue that causes our program to crash, we will be stuck in an infinite loop where the program starts, reads the first item from the queue, crashes while trying to process it, restarts, and repeats the whole process. That is why it\u2019s important to have something that monitors the processing code for failure (this can be as simple as a try-catch block around the processing code), and if processing fails repeatedly for the same message, removes this message from the queue.<\/p>\n<p class=\"copyrightbody\">Messages that always cause code to crash are called <i class=\"fm-italics\">poison messages<\/i>, and the best practice is to save them somewhere (often in another persistent queue) so we can inspect the message and find the bug that caused the crash. Queues that store those messages, as well as messages that weren\u2019t processed for other reasons, are often referred to as <i class=\"fm-italics\">dead letter queues<\/i>.<\/p>\n<p class=\"copyrightbody\">It\u2019s also important to think about failures when we design the items that we store in the queue. This is why the last example in listing 8.12 prepared the messages before adding them to the queue. That way, a failure to process an item will only affect one message and not all the messages in our mail merge operation.<a id=\"calibre_link-200\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-854\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-855\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-856\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-857\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-858\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-859\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><\/p>\n<h2 class=\"fm-head\" id=\"calibre_link-860\">Summary<\/h2>\n<ul class=\"calibre9\">\n<li class=\"fm-list-bullet\">\n<p class=\"list\">If you have work items that are processed individually, you can make the processing finish faster by processing the items in parallel.<\/p>\n<\/li>\n<li class=\"fm-list-bullet\">\n<p class=\"list\">You can use the <code class=\"fm-code-in-text\">Thread<\/code> class for parallel processing. This works well but can be resource intensive.<\/p>\n<\/li>\n<li class=\"fm-list-bullet\">\n<p class=\"list\">You can use the thread pool using <code class=\"fm-code-in-text\">ThreadPool.QueueUserWorkItem<\/code> or <code class=\"fm-code-in-text\">Task.Run<\/code>. The thread pool is efficient and self-tuning. But it can take a while to get to peak performance if you throw a lot of work at it all at once. This can be mitigated by changing the thread pool settings if you know in advance the number of threads you will need.<\/p>\n<\/li>\n<li class=\"fm-list-bullet\">\n<p class=\"list\">The thread pool is especially efficient with asynchronous code.<\/p>\n<\/li>\n<li class=\"fm-list-bullet\">\n<p class=\"list\">The <code class=\"fm-code-in-text\">Parallel<\/code> class is a simpler syntax to use the thread pool, but if you use it on a large collection, you should use a performance test to get a good value for <code class=\"fm-code-in-text\">MaxDegreeOfParallelism<\/code>.<\/p>\n<\/li>\n<li class=\"fm-list-bullet\">\n<p class=\"list\">If you don\u2019t care how much time it takes to finish the operation but just want to free the current thread, you can process work items sequentially in the background.<\/p>\n<\/li>\n<li class=\"fm-list-bullet\">\n<p class=\"list\">You can use the <code class=\"fm-code-in-text\">Thread<\/code> class or the thread pool. Both options will work.<\/p>\n<\/li>\n<li class=\"fm-list-bullet\">\n<p class=\"list\">However, a better option is to use the work queue pattern, probably with the <code class=\"fm-code-in-text\">BlockingCollection<\/code> class.<\/p>\n<\/li>\n<li class=\"fm-list-bullet\">\n<p class=\"list\">If you don\u2019t want to lose data when the program crashes, you should use a persistent queue. You can implement one yourself using a database or use a dedicated queue solution such as RabbitMQ, AWS SQS, or Azure Storage Queues.<\/p>\n<\/li>\n<li class=\"fm-list-bullet\">\n<p class=\"list\">With persistent queues, you should consider whether you want an \u201cat-least-once delivery\u201d or an \u201cat-most-once delivery\u201d system. You should also handle poison messages.<a id=\"calibre_link-861\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><\/p>\n<\/li>\n<\/ul>\n<\/div>\n<\/div>\n<\/div>\n<div class=\"calibre1\" id=\"calibre_link-82\">\n<div id=\"calibre_link-862\" class=\"calibre2\">\n<div id=\"calibre_link-863\" class=\"calibre3\">\n<h1 class=\"copyrighta\" id=\"calibre_link-864\">9 <a id=\"calibre_link-865\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-866\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-867\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-868\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-869\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a>Canceling background tasks<\/h1>\n<p class=\"copyrightbody\"><a id=\"calibre_link-202\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a>This chapter covers<a id=\"calibre_link-870\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-871\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><\/p>\n<ul class=\"calibre9\">\n<li class=\"co-summary-bullet\">Canceling operations<\/li>\n<li class=\"co-summary-bullet\">The <code class=\"fm-code-in-text\">CancellationToken<\/code> and <code class=\"fm-code-in-text\">Cancellation-TokenSource<\/code> classes<\/li>\n<li class=\"co-summary-bullet\">Implementing timeouts<\/li>\n<li class=\"co-summary-bullet\">Combining cancellation sources<\/li>\n<\/ul>\n<p class=\"copyrightbody\">In the previous chapter, we talked about how to run stuff in the background. In this chapter, we are going to talk about how to make it stop. The .NET library provides a standard mechanism for signaling that a background operation should end, which is called <code class=\"fm-code-in-text\">CancellationToken<\/code>. The <code class=\"fm-code-in-text\">CancellationToken<\/code> class is used consistently for (almost) all cancelable operations in the .NET library itself and in most third-party libraries.<a id=\"calibre_link-872\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><\/p>\n<h2 class=\"fm-head\" id=\"calibre_link-83\">9.1 Introducing CancellationToken<\/h2>\n<p class=\"copyrightbody\">For this chapter, we need an example of a long-running operation we can cancel. So let\u2019s write a short program that will count for the longest time possible&mdash;forever.<a id=\"calibre_link-873\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><\/p>\n<p class=\"fm-code-listing-caption\">Listing 9.1 Running a background thread forever<\/p>\n<pre class=\"programlisting\">var thread = new<a id=\"calibre_link-874\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a> Thread(BackgroundProc);\nthread.Start();\nConsole.ReadKey();\n \nvoid BackgroundProc()\n{\n   int i=0;\n   while(true)\n   {\n      Console.WriteLine(i++);\n   }\n}<\/pre>\n<p class=\"copyrightbody\">This program starts a thread that counts forever. It then waits for the user to press any key, and when the user finally does so, nothing happens. The program won\u2019t end until the second thread stops, and because we didn\u2019t write any mechanism that will make it stop, this program will continue forever, or more correctly, until you use some external means to terminate the entire process (you can use Task Manager, the <code class=\"fm-code-in-text\">taskkill<\/code> command, debugger, hitting Ctrl-C, rebooting the entire machine, etc.)<a id=\"calibre_link-142\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-875\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><\/p>\n<p class=\"copyrightbody\">The easiest way to make the program terminate is to mark the thread as a background thread. A process terminates when the last thread <i class=\"fm-italics\">that is not marked as a background thread<\/i> terminates, so we can make the program exit when the user hits a key by simply adding this line before the call to <code class=\"fm-code-in-text\">Thread.Start<\/code>:<\/p>\n<pre class=\"programlisting\">thread.IsBackground = true;<\/pre>\n<p class=\"copyrightbody\">While this can solve the problem in some cases, it has two major drawbacks:<\/p>\n<ul class=\"calibre9\">\n<li class=\"fm-list-bullet\">\n<p class=\"list\">You can only use this technique to cancel an operation when you completely exit your program.<\/p>\n<\/li>\n<li class=\"fm-list-bullet\">\n<p class=\"list\">This will stop the background thread in the middle of whatever it was doing without giving it a chance to complete an operation or save its state (however, it will not leave your program in an unstable state because the program is no longer running).<\/p>\n<\/li>\n<\/ul>\n<p class=\"copyrightbody\">The first problem alone already makes this unsuitable for most scenarios. When we look for a way to stop a thread without closing the entire program, we can see that the <code class=\"fm-code-in-text\">Thread<\/code> class has a method named <code class=\"fm-code-in-text\">Abort<\/code> that seems promising. However, that method still suffers from the second problem. It\u2019s actually worse than the previous example because terminating a thread in the middle of whatever it was doing can leave the entire program in an inconsistent state if that process, for instance, was allocating memory and updating the memory manager internal data structures. <a id=\"calibre_link-876\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-877\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><\/p>\n<p class=\"copyrightbody\">This makes <code class=\"fm-code-in-text\">Abort<\/code> too dangerous to use, so dangerous that Microsoft made it not work anymore in .NET Core and .NET 5 and later (it now just throws a <code class=\"fm-code-in-text\">PlatformNotSupportedException<\/code> on all platforms).<a id=\"calibre_link-878\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><\/p>\n<p class=\"copyrightbody\">So with no built-in way to stop a thread, we have no choice but to code something ourselves. Let\u2019s start with the simplest possible option, just a flag that tells us when to stop the thread.<a id=\"calibre_link-271\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><\/p>\n<p class=\"fm-code-listing-caption\">Listing 9.2 Using a flag to cancel a background thread<\/p>\n<pre class=\"programlisting\">var thread = new Thread(BackgroundProc);\nbool isCancellationRequested = false;                  <span class=\"fm-combinumeral\">\u2776<\/span>\nthread.Start();\nConsole.ReadKey();\nisCancellationRequested = true;                        <span class=\"fm-combinumeral\">\u2777<\/span>\n \nvoid BackgroundProc()\n{\n   int i=0;\n   while(true)\n   {\n      if(isCancellationRequested) return;              <span class=\"fm-combinumeral\">\u2778<\/span>\n      Console.WriteLine(i++);\n   }\n}<\/pre>\n<p class=\"copyrightbody\"><span class=\"fm-combinumeral\">\u2776<\/span> Flags variable<\/p>\n<p class=\"copyrightbody\"><span class=\"fm-combinumeral\">\u2777<\/span> Sets flag to exit<\/p>\n<p class=\"copyrightbody\"><span class=\"fm-combinumeral\">\u2778<\/span> If a flag is set, exit.<\/p>\n<p class=\"copyrightbody\">This option works in the current version of .NET and on current hardware, but it isn\u2019t guaranteed to work. As we talked about in chapter 7, high-end CPUs can have per-core cache, and when the main thread sets the flag, it actually updates its own core\u2019s cached version. Likewise, when the background thread checks the flag, it might be reading from a different core\u2019s cached version. On your development machine, you\u2019ll typically have a smaller number of cores and a lot of programs running (such as your development environment and a web browser), so the CPU cores need to switch threads and processes often, and this problem will never surface. But if you then run your software on a high-end server with many CPU cores and a smaller number of processes, the cancellation might be delayed because setting the flag won\u2019t propagate to the background thread until both cores flush their cache.<\/p>\n<p class=\"copyrightbody\">In addition, as also discussed chapter 7, the compiler is allowed to rewrite your code to make it run faster as long as it does not change the result of the code <i class=\"fm-italics\">in a single-threaded environment<\/i>. And in a single-threaded environment, the flag can\u2019t change during the loop, so it\u2019s safe to remove the check. This problem is especially difficult to debug because it tends to happen only in release builds (debug builds are usually not optimized) and can appear only in some environments; thus, the code can run perfectly fine on your development machine and fail on the production server. It can even run on the server today but start failing when something on the server is upgraded in the future.<a id=\"calibre_link-879\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><\/p>\n<p class=\"copyrightbody\">The solution, as we\u2019ve also seen in chapter 7, is to use locks when accessing the flag. There are better and faster ways to protect access to a single <code class=\"fm-code-in-text\">bool<\/code> variable, but I\u2019m going to use the <code class=\"fm-code-in-text\">lock<\/code> statement for simplicity. Don\u2019t worry. We will change it to something better in the next code listing.<a id=\"calibre_link-880\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><\/p>\n<p class=\"fm-code-listing-caption\">Listing 9.3 Using locks to protect the cancellation flag<\/p>\n<pre class=\"programlisting\">var thread = new Thread(BackgroundProc);\nvar cancelLock = new object();\nbool isCancellationRequested = false;\nthread.Start();\nConsole.ReadKey();\nlock(cancelLock)                                      <span class=\"fm-combinumeral\">\u2776<\/span>\n{\n   isCancellationRequested = true;\n}\n \nvoid BackgroundProc()\n{\n   int i=0;\n   while(true)\n   {\n      lock(cancelLock)                                <span class=\"fm-combinumeral\">\u2777<\/span>\n      {\n         if(isCancellationRequested) return;\n      }\n      Console.WriteLine(i++);\n   }\n}<\/pre>\n<p class=\"copyrightbody\"><span class=\"fm-combinumeral\">\u2776<\/span> Locks when setting the flag<\/p>\n<p class=\"copyrightbody\"><span class=\"fm-combinumeral\">\u2777<\/span> Locks when checking the flag<\/p>\n<p class=\"copyrightbody\">We just took the previous example and wrapped all access to the flag with <code class=\"fm-code-in-text\">lock<\/code> statements. Now we have a thread-safe, future-proof way to cancel the background thread. But we created a maintainability problem. It\u2019s just a matter of time until some future team member forgets to add a lock and introduces a bug that only happens in production under load. This is bad, but fortunately for us, object-oriented programming already solved this problem more than 50 years ago (object-oriented programming was first formalized in 1967): just write a class that encapsulates the flag and controls all access to it.<a id=\"calibre_link-881\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><\/p>\n<p class=\"fm-code-listing-caption\">Listing 9.4 Wrapping the cancel flag in a class<\/p>\n<pre class=\"programlisting\">public class CancelFlag\n{\n   private bool _isCancellationRequested;\n   private object _lock = new();\n \n   public void Cancel()\n   {\n      lock(_lock)\n      {\n          _isCancellationRequested = true;\n      }\n   }\n \n   public bool IsCancellationRequested\n   {\n      get\n      {\n         lock(_lock)\n         {\n            return _isCancellationRequested;\n         }\n      }\n   }\n}<\/pre>\n<p class=\"copyrightbody\">This class is about as simple as it can get: there\u2019s a <code class=\"fm-code-in-text\">Cancel<\/code> method that lets you set the cancel flag and an <code class=\"fm-code-in-text\">IsCancellationRequested<\/code> property that lets you check the value of the cancel flag. Inside each of those, access to the flag is protected by locks.<a id=\"calibre_link-882\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-883\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-214\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><\/p>\n<p class=\"copyrightbody\">Now we just need to change our program to use the <code class=\"fm-code-in-text\">CancelFlag<\/code> class:<\/p>\n<pre class=\"programlisting\">var thread = new Thread(BackgroundProc);\nvar shouldCancel = new CancelFlag();                        <span class=\"fm-combinumeral\">\u2776<\/span>\nthread.Start();\nConsole.ReadKey();\nshouldCancel.Cancel();                                      <span class=\"fm-combinumeral\">\u2777<\/span>\n \nvoid BackgroundProc()\n{\n   int i=0;\n   while(true)\n   {\n      if(shouldCancel. IsCancellationRequested) return;     <span class=\"fm-combinumeral\">\u2778<\/span>\n      Console.WriteLine(i++);\n   }\n}<\/pre>\n<p class=\"copyrightbody\"><span class=\"fm-combinumeral\">\u2776<\/span> Creates cancel flag<\/p>\n<p class=\"copyrightbody\"><span class=\"fm-combinumeral\">\u2777<\/span> Sets cancel flag<\/p>\n<p class=\"copyrightbody\"><span class=\"fm-combinumeral\">\u2778<\/span> Checks cancel flag<\/p>\n<p class=\"copyrightbody\">We have now created a thread-safe, future-proof, and maintainable way to cancel the background thread. But&mdash;and you know there has to be a but because we\u2019re not even close to the end of the chapter&mdash;the <code class=\"fm-code-in-text\">CancelFlag<\/code> API has a weak point. It\u2019s easy to abuse the <code class=\"fm-code-in-text\">CancelFlag<\/code> and use it in a way that will have unexpected effects on other parts of the program. For example, if we add another background thread that sometimes needs to cancel itself, it might look something like this:<\/p>\n<pre class=\"programlisting\">void SomeOtherBackgroundProcesses()\n{\n   int i=0;\n   while(true)\n   {\n      if(shouldCancel. IsCancellationRequested) return;\n      Console.WriteLine(i++);\n      if(i==7) shouldCancel.Cancel();                    <span class=\"fm-combinumeral\">\u2776<\/span>\n   }\n}<\/pre>\n<p class=\"copyrightbody\"><span class=\"fm-combinumeral\">\u2776<\/span> Uses the cancel flag to cancel itself<\/p>\n<p class=\"copyrightbody\">This is a method similar to <code class=\"fm-code-in-text\">BackgroundProc<\/code> from the previous example that has an additional exit condition, and the developer noticed there is already a way to stop the thread (our cancel flag), so they used it. This works for this method, but it also has the side effect of canceling the other background thread simply because both threads are using the same flag, which is probably not what we want. We can fix this shortcoming by splitting our <code class=\"fm-code-in-text\">CancelFlag<\/code> into two classes: one lets us set the cancel flag, while the other can only check it. We then get an API that looks like<a id=\"calibre_link-201\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-884\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><\/p>\n<pre class=\"programlisting\">class CancelFlag\n{\n      public bool IsCancellationRequested {get;}\n}\nclass CancelFlagSource\n{\n      public void Cancel();\n      public CancelFlag Flag {get;}\n}<\/pre>\n<p class=\"copyrightbody\">We separated the interface into two classes: the <code class=\"fm-code-in-text\">CancelFlagSource<\/code> creates and controls the <code class=\"fm-code-in-text\">CancelFlag<\/code>, and the <code class=\"fm-code-in-text\">CancelFlag<\/code> is only used for checking if cancellation was requested. Code that may cancel the operation uses <code class=\"fm-code-in-text\">CancelFlagSource<\/code>, while code that can be canceled only gets the <code class=\"fm-code-in-text\">CancelFlag<\/code>. If we change the program to use our new cancel flag interface, we get the following.<a id=\"calibre_link-885\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><\/p>\n<p class=\"fm-code-listing-caption\">Listing 9.5 Using <code class=\"fm-code-in-text1\">CancelFlag<\/code> and <code class=\"fm-code-in-text1\">CancelFlagSource<\/code><\/p>\n<pre class=\"programlisting\">var thread = new Thread(BackgroundProc);\nvar cancelFlagSource = new CancellationFlagSource();      <span class=\"fm-combinumeral\">\u2776<\/span>\nvar shouldCancel = cancelFlagSource.Flag;                 <span class=\"fm-combinumeral\">\u2777<\/span>\nthread.Start();\nConsole.ReadKey();\ncancelFlagSource.Cancel();                                <span class=\"fm-combinumeral\">\u2778<\/span>\n \nvoid BackgroundProc()\n{\n   int i=0;\n   while(true)\n   {\n      if(shouldCancel. IsCancellationRequested) return;   <span class=\"fm-combinumeral\">\u2779<\/span>\n      Console.WriteLine(i++);\n   }\n}<\/pre>\n<p class=\"copyrightbody\"><span class=\"fm-combinumeral\">\u2776<\/span> Creates flag source<\/p>\n<p class=\"copyrightbody\"><span class=\"fm-combinumeral\">\u2777<\/span> Gets flag for background thread<\/p>\n<p class=\"copyrightbody\"><span class=\"fm-combinumeral\">\u2778<\/span> Sets flag<\/p>\n<p class=\"copyrightbody\"><span class=\"fm-combinumeral\">\u2779<\/span> Checks whether flag was set<\/p>\n<p class=\"copyrightbody\">There is one important thing missing in this example: we didn\u2019t implement the <code class=\"fm-code-in-text\">CancelFlagSource<\/code> and <code class=\"fm-code-in-text\">CancelFlag<\/code> classes. But that\u2019s okay because Microsoft has done all the work and implemented the <code class=\"fm-code-in-text\">CancellationToken<\/code> and <code class=\"fm-code-in-text\">CancellationTokenSource<\/code> classes that do everything we talked about and more. Here\u2019s how our program looks when we use <code class=\"fm-code-in-text\">CancellationToken<\/code>.<a id=\"calibre_link-886\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-887\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-888\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-889\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><\/p>\n<p class=\"fm-code-listing-caption\">Listing 9.6 Using <code class=\"fm-code-in-text1\">CancellationToken<\/code><\/p>\n<pre class=\"programlisting\">var thread = new Thread(BackgroundProc);\nvar cancelTokenSource = new CancellationTokenSource();     <span class=\"fm-combinumeral\">\u2776<\/span>\nvar shouldCancel = cancelTokenSource.Token;                <span class=\"fm-combinumeral\">\u2777<\/span>\nthread.Start();\nConsole.ReadKey();\ncancelTokenSource.Cancel();                                <span class=\"fm-combinumeral\">\u2778<\/span>\n \nvoid BackgroundProc()\n{\n   int i=0;\n   while(true)\n   {\n      if(shouldCancel. IsCancellationRequested) return;    <span class=\"fm-combinumeral\">\u2779<\/span>\n      Console.WriteLine(i++);\n   }\n}<\/pre>\n<p class=\"copyrightbody\"><span class=\"fm-combinumeral\">\u2776<\/span> Creates CancellationTokenSource<\/p>\n<p class=\"copyrightbody\"><span class=\"fm-combinumeral\">\u2777<\/span> Gets token for background thread<\/p>\n<p class=\"copyrightbody\"><span class=\"fm-combinumeral\">\u2778<\/span> Cancels token<\/p>\n<p class=\"copyrightbody\"><span class=\"fm-combinumeral\">\u2779<\/span> Checks whether token was canceled<\/p>\n<p class=\"copyrightbody\">This is exactly the same code as in listing 9.5. I just replaced <code class=\"fm-code-in-text\">CancelFlag<\/code> with <code class=\"fm-code-in-text\">CancellationToken<\/code>.<\/p>\n<p class=\"copyrightbody\">It\u2019s important to remember that at its core, <code class=\"fm-code-in-text\">CancellationToken<\/code> is just a <code class=\"fm-code-in-text\">bool<\/code> variable (wrapped in a thread-safe, future-proof, abuse-resistant class); there\u2019s nothing magic about it, and it doesn\u2019t know by itself how to cancel anything. If our previous program did something time consuming in the loop instead of <code class=\"fm-code-in-text\">Console.WriteLine<\/code> (for example, a calculation that takes 1 full minute), the thread cancellation will be delayed until that long calculation completes.<a id=\"calibre_link-890\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-891\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><\/p>\n<p class=\"fm-code-listing-caption\">Listing 9.7 Delayed cancellation with a long operation<\/p>\n<pre class=\"programlisting\">var thread = new Thread(BackgroundProc);\nvar cancelTokenSource = new CancellationTokenSource();\nvar shouldCancel = cancelTokenSource.Token;\nthread.Start();\nConsole.ReadKey();\ncancelTokenSource.Cancel();\n \nvoid BackgroundProc()\n{\n   int i=0;\n   while(true)\n   {\n      if(shouldCancel.IsCancellationRequested) return;\n      ACalculationThatTakesOneMinute();\n      Console.WriteLine(i++);\n   }\n}\n \nvoid ACalculationThatTakesOneMinute()\n{\n   var result = 0;\n   var start = DateTime.UtcNow;\n   while((DateTime.UtcNow - start).TotalMinutes &lt; 1)        <span class=\"fm-combinumeral\">\u2776<\/span>\n   {\n       result++;                                            <span class=\"fm-combinumeral\">\u2777<\/span>\n   }\n}<\/pre>\n<p class=\"copyrightbody\"><span class=\"fm-combinumeral\">\u2776<\/span> For 1 full minute<\/p>\n<p class=\"copyrightbody\"><span class=\"fm-combinumeral\">\u2777<\/span> Calculates stuff<\/p>\n<p class=\"copyrightbody\">In this code, the background thread main loop, which does the cancellation checking, calls another long-running method. That means that we wait until this method returns before the next cancellation check, and because the time between cancellation checks is 1 minute in this example, it would take between 0 and 1 minute (or 30 seconds on average) from the time we cancel the background thread until it finally terminates.<\/p>\n<p class=\"copyrightbody\">If you do anything time-consuming inside the loop, you either have to accept that canceling may take a while or change the long-running code to check the <code class=\"fm-code-in-text\">CancellationToken<\/code> periodically. For example, we can modify our previous example to check for cancellation inside <code class=\"fm-code-in-text\">ACalculationThatTakesOneMinute<\/code>.<a id=\"calibre_link-213\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><\/p>\n<p class=\"fm-code-listing-caption\">Listing 9.8 Using <code class=\"fm-code-in-text1\">CancellationToken<\/code> with a long operation<\/p>\n<pre class=\"programlisting\">var thread = new Thread(BackgroundProc);\nvar cancelTokenSource = new CancellationTokenSource();\nvar shouldCancel = cancelTokenSource.Token;\nthread.Start();\nConsole.ReadKey();\ncancelTokenSource.Cancel();\n \nvoid BackgroundProc()\n{\n   int i=0;\n   while(true)\n   {\n      if(!ACalculationThatTakesOneMinute(cancelTokenSource.Token))\n          return;\n      Console.WriteLine(i++);\n   }\n}\n \nbool ACalculationThatTakesOneMinute(CancellationToken shouldCancel)\n{\n   var start = DateTime.UtcNow;\n   var result = 0;\n   while((DateTime.UtcNow - start).TotalMinutes &lt; 1)\n   {\n      if(shouldCancel.IsCancellationRequested)          <span class=\"fm-combinumeral\">\u2776<\/span>\n         return false;\n      result++;\n   }\n   return true;\n}<\/pre>\n<p class=\"copyrightbody\"><span class=\"fm-combinumeral\">\u2776<\/span> Inner cancellation check<\/p>\n<p class=\"copyrightbody\">In this code, we moved the cancellation check into the <code class=\"fm-code-in-text\">ACalculationThatTakesOneMinute<\/code> method and changed it to return <code class=\"fm-code-in-text\">bool<\/code> where <code class=\"fm-code-in-text\">true<\/code> means the method has completed successfully, and <code class=\"fm-code-in-text\">false<\/code> means it has been canceled. This is required because most of the time in a real program, it\u2019s useful to know whether the calculation has completed, and we can use the result or not. <a id=\"calibre_link-892\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-893\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-894\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><\/p>\n<h2 class=\"fm-head\" id=\"calibre_link-84\">9.2 Canceling using an exception<\/h2>\n<p class=\"copyrightbody\">In our previous examples, we moved the cancellation check into the <code class=\"fm-code-in-text\">ACalculationThatTakesOneMinute<\/code> method. This means calling the method changed from the nice and straightforward<a id=\"calibre_link-895\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-896\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-897\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-207\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><\/p>\n<pre class=\"programlisting\">ACalculationThatTakesOneMinute();<\/pre>\n<p class=\"copyrightbody\">to the more convoluted<\/p>\n<pre class=\"programlisting\">if(!ACalculationThatTakesOneMinute()) return;<\/pre>\n<p class=\"copyrightbody\">This doesn\u2019t only clutter our code with <code class=\"fm-code-in-text\">if<\/code>s, but it also creates a maintenance risk because someone in the future might change the code and forget to add the <code class=\"fm-code-in-text\">if<\/code>. It also uses up the method return value, so if our method needs to return a value, we must use tuples or <code class=\"fm-code-in-text\">out<\/code> parameters.<\/p>\n<p class=\"copyrightbody\">We can solve all those problems by using an exception. We can solve those problems if we replace our cancellation check that returns <code class=\"fm-code-in-text\">false<\/code> on cancellation from<\/p>\n<pre class=\"programlisting\">      if(shouldCancel.IsCancellationRequested)\n         return false;<\/pre>\n<p class=\"copyrightbody\">with a very similar code that throws an exception<\/p>\n<pre class=\"programlisting\">      if(shouldCancel.IsCancellationRequested)\n         throw new OperationCanceledException();<\/pre>\n<p class=\"copyrightbody\">This is so common that Microsoft has provided a method that does just that, and the cancellation check becomes just<\/p>\n<pre class=\"programlisting\">      shouldCancel.ThrowIfCancellationRequested();<\/pre>\n<p class=\"copyrightbody\">In all the examples so far, the background operations we wanted to cancel were some kind of calculations, a piece of code that is doing some work, and we can embed the cancellation check inside that work. But what if we want to cancel an operation that we can\u2019t insert cancellation checks into?<\/p>\n<h2 class=\"fm-head\" id=\"calibre_link-85\">9.3 Getting a callback when the caller cancels our operation<\/h2>\n<p class=\"copyrightbody\">Let\u2019s say we have a library that has its own cancellation system not based on <code class=\"fm-code-in-text\">CancellationToken<\/code>. For example, it can have an interface that looks like<a id=\"calibre_link-898\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-899\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><\/p>\n<pre class=\"programlisting\">class MyCalculation\n{\n   void Start();\n   void Cancel();\n   event Action Complete;\n}<\/pre>\n<p class=\"copyrightbody\">With this interface, in normal operation, we call <code class=\"fm-code-in-text\">Start<\/code> and wait for the <code class=\"fm-code-in-text\">Complete<\/code> event. If we want to cancel an ongoing operation, we call the <code class=\"fm-code-in-text\">Cancel<\/code> method. We sometimes find interfaces like those in code that calls remote servers, code that uses some non-.NET libraries, or more rarely, in third-party libraries written by someone who just for whatever reason doesn\u2019t like <code class=\"fm-code-in-text\">CancellationToken<\/code>.<a id=\"calibre_link-900\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-901\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><\/p>\n<p class=\"copyrightbody\">We can add another background thread that just repeatedly checks the status of <code class=\"fm-code-in-text\">CancellationToken<\/code> and calls <code class=\"fm-code-in-text\">MyCalculation.Cancel<\/code> when <code class=\"fm-code-in-text\">IsCancellationRequested<\/code> becomes <code class=\"fm-code-in-text\">true<\/code>, but this is obviously wasteful. That is why <code class=\"fm-code-in-text\">CancellationToken<\/code> can call a callback when it is canceled. That way, using the example <code class=\"fm-code-in-text\">MyCalculation<\/code> class is easy:<\/p>\n<pre class=\"programlisting\">void RunMyCalculation(CancellationToken cancel)\n{\n   var calc = new MyCaclulation();\n   cancel.Register(()=&gt;calc.Cancel());                 <span class=\"fm-combinumeral\">\u2776<\/span>\n   calc.Complete += CalcComplete();\n   calc.Start();\n}<\/pre>\n<p class=\"copyrightbody\"><span class=\"fm-combinumeral\">\u2776<\/span> Registers a callback<\/p>\n<p class=\"copyrightbody\">The <code class=\"fm-code-in-text\">CancellationToken.Register<\/code> method is used to register the callback we want the <code class=\"fm-code-in-text\">CancellationToken<\/code> to call when it is canceled. Calling <code class=\"fm-code-in-text\">Register<\/code> multiple times will cause all callbacks to run when the <code class=\"fm-code-in-text\">CancellationToken<\/code> is canceled. Calling <code class=\"fm-code-in-text\">Register<\/code> when the <code class=\"fm-code-in-text\">CancellationToken<\/code> is already canceled will run the callback immediately. <code class=\"fm-code-in-text\">Register<\/code> returns an object that can be used to unregister the callback.<a id=\"calibre_link-902\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><\/p>\n<p class=\"copyrightbody\">Note that the callback you pass to <code class=\"fm-code-in-text\">Register<\/code> will run in the thread calling <code class=\"fm-code-in-text\">Cancel<\/code> and not in the background thread you are trying to cancel. Make sure everything you do in the callback is thread safe and avoid doing things that can interfere with the calling thread.<\/p>\n<h2 class=\"fm-head\" id=\"calibre_link-86\">9.4 Implementing timeouts<\/h2>\n<p class=\"copyrightbody\">A very common scenario for cancellation is the timeout, where we want to cancel an operation if it hasn\u2019t completed in a certain time. For example, if we tried to open a network connection, and we didn\u2019t get a reply, we can\u2019t tell if we didn\u2019t get an answer because the network packet hasn\u2019t reached us yet or because the computer we are trying to connect to doesn\u2019t exist. So we wait for a certain time, and if we don\u2019t get a reply by then, we assume that the reply will never arrive and cancel the operation.<a id=\"calibre_link-903\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-904\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-208\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><\/p>\n<p class=\"copyrightbody\">It would have been easy to write code that starts a timer and calls the <code class=\"fm-code-in-text\">CancellationTokenSource.Cancel<\/code> when the timer elapses, but because this is such a common scenario, <code class=\"fm-code-in-text\">CancellationTokenSource<\/code> already has this feature built in with the <code class=\"fm-code-in-text\">CancelAfter<\/code> method. The <code class=\"fm-code-in-text\">CancelAfter<\/code> method has two overrides, one that accepts the number of milliseconds to wait<\/p>\n<pre class=\"programlisting\">var cancelSource = new CancellationTokenSource();\ncancelSource.CancelAfter(30000);<\/pre>\n<p class=\"copyrightbody\">and the nicer, more modern override that accepts a <code class=\"fm-code-in-text\">TimeSpan<\/code>:<\/p>\n<pre class=\"programlisting\">var cancelSource = new CancellationTokenSource();\ncancelSource.CancelAfter(TimeSpan.FromSeconds(30));<\/pre>\n<p class=\"copyrightbody\">Both of those code snippets create a <code class=\"fm-code-in-text\">CancellationToken<\/code> (accessible as <code class=\"fm-code-in-text\">cancelSource .Token<\/code>) that will cancel automatically after 30 seconds.<\/p>\n<p class=\"copyrightbody\">Calling <code class=\"fm-code-in-text\">CancelAfter<\/code> when the <code class=\"fm-code-in-text\">CancellationToken<\/code> is already canceled does nothing. Calling <code class=\"fm-code-in-text\">CancelAfter<\/code> a second time, before the <code class=\"fm-code-in-text\">CancellationToken<\/code> is canceled, will reset the timer. Calling <code class=\"fm-code-in-text\">CancelAfter(-1)<\/code> before the <code class=\"fm-code-in-text\">CancellationToken<\/code> is canceled will cancel the timeout.<\/p>\n<h2 class=\"fm-head\" id=\"calibre_link-87\">9.5 Combining cancellation methods<\/h2>\n<p class=\"copyrightbody\">Sometimes you want to be able to cancel an operation for two completely different reasons. For example, let\u2019s say you have code that can be canceled by the user, and you want to add a timeout. For this example, we\u2019ll write code that performs an HTTP GET request to a server and returns the result as a string.<a id=\"calibre_link-905\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-209\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><\/p>\n<p class=\"fm-code-listing-caption\">Listing 9.9 HTTP call that can be canceled by the user<\/p>\n<pre class=\"programlisting\">public async Task&lt;string&gt;\n    GetTextFromServer(CancellationToken canceledByUser)\n{\n   using(var http = new HttpClient())\n   {\n       return await http.GetStringAsync(\"http:\/\/example.com\", \n            canceledByUser);\n   } \n}<\/pre>\n<p class=\"copyrightbody\">This method accepts a <code class=\"fm-code-in-text\">CancellationToken<\/code> called <code class=\"fm-code-in-text\">canceledByUser<\/code>, unsurprisingly indicating that the operation was canceled by the user. We now want to add a timeout, but we can\u2019t because we need a <code class=\"fm-code-in-text\">CancellationTokenSource<\/code>, and we only have a <code class=\"fm-code-in-text\">CancellationToken<\/code>.<\/p>\n<p class=\"copyrightbody\">The <code class=\"fm-code-in-text\">CancellationTokenSource.CreateLinkedTokenSource<\/code> static method can create a <code class=\"fm-code-in-text\">CancellationTokenSource<\/code> from one or more <code class=\"fm-code-in-text\">CancellationToken<\/code> objects. We can then use the new <code class=\"fm-code-in-text\">CancellationTokenSource<\/code> to create a <code class=\"fm-code-in-text\">CancellationToken<\/code> we control and add the timeout to it.<a id=\"calibre_link-906\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><\/p>\n<p class=\"fm-code-listing-caption\">Listing 9.10 HTTP call that can be canceled by the user or a timeout<\/p>\n<pre class=\"programlisting\">public async Task&lt;string&gt;\n   GetTextFromServer(CancellationToken canceledByUser)\n{\n   var combined = CancellationTokenSource.CreateLinkedTokenSource( <span class=\"fm-combinumeral\">\u2776<\/span>\n      canceledByUser);  \n   combined.CancelAfter(TimeSpan.FromSeconds(10));                 <span class=\"fm-combinumeral\">\u2777<\/span>\n   using(var http = new HttpClient())\n   {\n       return await http.GetStringAsync(\"http:\/\/example.com\", \n            combined.Token);                                       <span class=\"fm-combinumeral\">\u2778<\/span>\n   } \n}<\/pre>\n<p class=\"copyrightbody\"><span class=\"fm-combinumeral\">\u2776<\/span> Creates a CancellationTokenSource we control<\/p>\n<p class=\"copyrightbody\"><span class=\"fm-combinumeral\">\u2777<\/span> Adds timeout<\/p>\n<p class=\"copyrightbody\"><span class=\"fm-combinumeral\">\u2778<\/span> Uses new token<\/p>\n<p class=\"copyrightbody\">You can pass any number of <code class=\"fm-code-in-text\">CancellationToken<\/code> objects to <code class=\"fm-code-in-text\">CreateLinkedTokenSource<\/code>; the token controlled by the new <code class=\"fm-code-in-text\">CancellationTokenSource<\/code> will be canceled automatically if any of them are canceled. You can then use the new <code class=\"fm-code-in-text\">CancellationTokenSource<\/code> to add a timeout or manually cancel its token. Anything you do with the new <code class=\"fm-code-in-text\">CancellationTokenSource<\/code> will not affect the tokens used to create it.<\/p>\n<h2 class=\"fm-head\" id=\"calibre_link-88\">9.6 Special cancellation tokens<\/h2>\n<p class=\"copyrightbody\">We spent this entire chapter talking about how to use a <code class=\"fm-code-in-text\">CancellationToken<\/code> to cancel an operation; however, sometimes, while you don\u2019t need to be able to cancel an operation, the API you are using still requires a <code class=\"fm-code-in-text\">CancellationToken<\/code>. In those cases, you can just pass <code class=\"fm-code-in-text\">CancellationToken.None<\/code>. This will give you a <code class=\"fm-code-in-text\">CancellationToken<\/code> that can never be canceled. Creating a <code class=\"fm-code-in-text\">CancellationToken<\/code> with <code class=\"fm-code-in-text\">new CancellationToken(false)<\/code> will give you the same results but is less readable.<a id=\"calibre_link-907\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-908\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-909\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-910\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-203\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><\/p>\n<p class=\"copyrightbody\">In contrast, <code class=\"fm-code-in-text\">new CancellationToken(true)<\/code> will create a <code class=\"fm-code-in-text\">CancellationToken<\/code> that is already canceled. This doesn\u2019t make much sense in normal code but can be useful in unit tests.<\/p>\n<h2 class=\"fm-head\" id=\"calibre_link-911\">Summary<\/h2>\n<ul class=\"calibre9\">\n<li class=\"fm-list-bullet\">\n<p class=\"list\"><code class=\"fm-code-in-text\">CancellationToken<\/code> is the standard way to cancel operations in .NET.<\/p>\n<\/li>\n<li class=\"fm-list-bullet\">\n<p class=\"list\">The <code class=\"fm-code-in-text\">CancellationTokenSource<\/code> class is used to create and control <code class=\"fm-code-in-text\">CancellationToken<\/code> objects.<\/p>\n<\/li>\n<li class=\"fm-list-bullet\">\n<p class=\"list\"><code class=\"fm-code-in-text\">CancellationTokenSource.Cancel<\/code> is used to cancel an operation, and <code class=\"fm-code-in-text\">CancellationToken.IsCancellationRequired<\/code> is used to check whether it has been canceled.<\/p>\n<\/li>\n<li class=\"fm-list-bullet\">\n<p class=\"list\"><code class=\"fm-code-in-text\">CancellationToken<\/code> is just a flag. It doesn\u2019t know how to cancel anything by itself.<\/p>\n<\/li>\n<li class=\"fm-list-bullet\">\n<p class=\"list\">You can use <code class=\"fm-code-in-text\">CancellationToken.Register<\/code> to run a callback when it canceled.<\/p>\n<\/li>\n<li class=\"fm-list-bullet\">\n<p class=\"list\">You can use <code class=\"fm-code-in-text\">CancellationTokenSource.CancelAfter<\/code> to implement timeouts.<\/p>\n<\/li>\n<li class=\"fm-list-bullet\">\n<p class=\"list\"><code class=\"fm-code-in-text\">CancellationTokenSource.CreateLinkedTokenSource<\/code> lets you create a <code class=\"fm-code-in-text\">CancellationTokenSource<\/code> you control from one or more existing <code class=\"fm-code-in-text\">CancellationToken<\/code> objects.<\/p>\n<\/li>\n<li class=\"fm-list-bullet\">\n<p class=\"list\">When you need to pass a <code class=\"fm-code-in-text\">CancellationToken<\/code> that you never want to cancel, you can use <code class=\"fm-code-in-text\">CancellationToken.None.<\/code><\/p>\n<\/li>\n<\/ul>\n<\/div>\n<\/div>\n<\/div>\n<div class=\"calibre1\" id=\"calibre_link-89\">\n<div id=\"calibre_link-912\" class=\"calibre2\">\n<div id=\"calibre_link-913\" class=\"calibre3\">\n<h1 class=\"copyrighta\" id=\"calibre_link-914\">10 Await your own events<a id=\"calibre_link-915\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-916\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-917\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-918\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-919\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-920\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><\/h1>\n<p class=\"copyrightbody\"><a id=\"calibre_link-238\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a>This chapter covers<a id=\"calibre_link-921\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><\/p>\n<ul class=\"calibre9\">\n<li class=\"co-summary-bullet\">Creating <code class=\"fm-code-in-text\">Task<\/code> objects that you can control<\/li>\n<li class=\"co-summary-bullet\"><code class=\"fm-code-in-text\">TaskCompletionSource<\/code> and <code class=\"fm-code-in-text\">TaskCompletionSource&lt;T&gt;<\/code><\/li>\n<li class=\"co-summary-bullet\">Completing a <code class=\"fm-code-in-text\">Task<\/code> successfully and with an error, and canceling a <code class=\"fm-code-in-text\">Task<\/code><\/li>\n<li class=\"co-summary-bullet\">Adapting old and nonstandard asynchronous APIs to use tasks<\/li>\n<li class=\"co-summary-bullet\">Using <code class=\"fm-code-in-text\">TaskCompletionSource<\/code> to implement asynchronous initialization<\/li>\n<li class=\"co-summary-bullet\">Using <code class=\"fm-code-in-text\">TaskCompletionSource<\/code> to implement asynchronous data structures<\/li>\n<\/ul>\n<p class=\"copyrightbody\">Until now, we\u2019ve talked about using <code class=\"fm-code-in-text\">async<\/code>\/<code class=\"fm-code-in-text\">await<\/code> to consume asynchronous APIs. In this chapter, we\u2019ll talk about writing your own asynchronous APIs. Common reasons for<a id=\"calibre_link-922\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a> doing so include adapting a non-<code class=\"fm-code-in-text\">Task<\/code>&ndash;based asynchronous API so that it can be used with <code class=\"fm-code-in-text\">await<\/code>, using <code class=\"fm-code-in-text\">await<\/code> to asynchronously wait for events that happen in your application, or creating an <code class=\"fm-code-in-text\">async<\/code>\/<code class=\"fm-code-in-text\">await<\/code>-compatible thread-safe data structure, just to give a few examples. (Spoiler: We will write code for those examples later in this chapter.)<\/p>\n<p class=\"copyrightbody\">Way back in chapter 3, to understand how the <code class=\"fm-code-in-text\">async<\/code> and <code class=\"fm-code-in-text\">await<\/code> keywords work, we took a method that used <code class=\"fm-code-in-text\">async<\/code>\/<code class=\"fm-code-in-text\">await<\/code> and transformed it into an equivalent method that produces exactly the same asynchronous operation but doesn\u2019t use <code class=\"fm-code-in-text\">async<\/code> and <code class=\"fm-code-in-text\">await<\/code>. Back then, we didn\u2019t know how to create <code class=\"fm-code-in-text\">Task<\/code> objects, but we did know that <code class=\"fm-code-in-text\">await<\/code> can be implemented by a callback (specifically, <code class=\"fm-code-in-text\">Task.ContinueWith<\/code>). So instead of a <code class=\"fm-code-in-text\">Task<\/code>, we used callbacks to report the operation results. To make this change, we modified the method signature from<a id=\"calibre_link-923\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-924\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><\/p>\n<pre class=\"programlisting\">Task&lt;int&gt; GetBitmapWidth(string path) <\/pre>\n<p class=\"copyrightbody\">to<\/p>\n<pre class=\"programlisting\">void GetBitmapWidth(string path, \n    Action&lt;int&gt; setResult, \n    Action&lt;Exception&gt; setException)<\/pre>\n<p class=\"copyrightbody\"><code class=\"fm-code-in-text\">ContinueWith<\/code>, the .NET built in callback mechanism, uses a single callback that must check the <code class=\"fm-code-in-text\">Task<\/code> for information regarding the success and failure of the asynchronous operation. However, we choose to use separate <code class=\"fm-code-in-text\">setResult<\/code> and <code class=\"fm-code-in-text\">setException<\/code> callbacks for the success and failure cases because it\u2019s simpler. As a byproduct, by successfully simulating a <code class=\"fm-code-in-text\">Task<\/code> with those two calls, we showed that those <code class=\"fm-code-in-text\">setResult<\/code> and <code class=\"fm-code-in-text\">setException<\/code> calls are (if we have a way to connect them to a <code class=\"fm-code-in-text\">Task<\/code>) sufficient to control it.<a id=\"calibre_link-925\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-926\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><\/p>\n<p class=\"copyrightbody\">Surprise! The .NET library has a class named <code class=\"fm-code-in-text\">TaskCompletionSource&lt;T&gt;<\/code>. It can create <code class=\"fm-code-in-text\">Task&lt;T&gt;<\/code> objects and has methods named <code class=\"fm-code-in-text\">SetResult<\/code> and <code class=\"fm-code-in-text\">SetException<\/code>. Let\u2019s see how you can use it.<a id=\"calibre_link-927\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-162\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-928\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><\/p>\n<h2 class=\"fm-head\" id=\"calibre_link-90\">10.1 Introducing TaskCompletionSource<\/h2>\n<p class=\"copyrightbody\">The .NET library has the <code class=\"fm-code-in-text\">TaskCompletionSource<\/code> class to create and control <code class=\"fm-code-in-text\">Task<\/code> objects and the <code class=\"fm-code-in-text\">TaskCompletionSource&lt;T&gt;<\/code> class to create and control <code class=\"fm-code-in-text\">Task&lt;T&gt;<\/code> objects. <code class=\"fm-code-in-text\">TaskCompletionSource<\/code> and <code class=\"fm-code-in-text\">TaskCompletionSource&lt;T&gt;<\/code> are exactly the same, except that for <code class=\"fm-code-in-text\">TaskCompletionSource<\/code> (without the <code class=\"fm-code-in-text\">&lt;T&gt;<\/code>), the <code class=\"fm-code-in-text\">SetResult<\/code> and <code class=\"fm-code-in-text\">TrySetResult<\/code> methods do not accept any parameter and just complete the <code class=\"fm-code-in-text\">Task<\/code> without setting a result (because unlike <code class=\"fm-code-in-text\">Task&lt;T&gt;<\/code>, <code class=\"fm-code-in-text\">Task<\/code> does not have a <code class=\"fm-code-in-text\">Result<\/code> property). For the rest of this chapter, I\u2019m going to write <code class=\"fm-code-in-text\">TaskCompletionSource<\/code> instead of <code class=\"fm-code-in-text\">TaskCompletionSource<\/code> or <code class=\"fm-code-in-text\">TaskCompletionSource&lt;T&gt;<\/code>, but everything I write applies to both.<a id=\"calibre_link-929\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-930\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-931\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-932\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-933\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-934\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-935\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><\/p>\n<p class=\"copyrightbody\"><code class=\"fm-code-in-text\">TaskCompletionSource<\/code> has a property named <code class=\"fm-code-in-text\">Task<\/code> that lets us get the <code class=\"fm-code-in-text\">Task<\/code> created by it. Each <code class=\"fm-code-in-text\">TaskCompletionSource<\/code> controls one <code class=\"fm-code-in-text\">Task<\/code>, and reading the <code class=\"fm-code-in-text\">Task<\/code> property multiple times will return the same <code class=\"fm-code-in-text\">Task<\/code> object.<\/p>\n<p class=\"copyrightbody\">Initially, the <code class=\"fm-code-in-text\">Task<\/code> status is <code class=\"fm-code-in-text\">WaitingForActivation<\/code>, and the <code class=\"fm-code-in-text\">Task<\/code>\u2019s <code class=\"fm-code-in-text\">IsCompleted<\/code>, <code class=\"fm-code-in-text\">IsCompletedSuccessfully<\/code>, <code class=\"fm-code-in-text\">IsCanceled<\/code>, and <code class=\"fm-code-in-text\">IsFaulted<\/code> properties are all <code class=\"fm-code-in-text\">false<\/code>. Using <code class=\"fm-code-in-text\">await<\/code> on the new <code class=\"fm-code-in-text\">Task<\/code> will asynchronously wait, and calling <code class=\"fm-code-in-text\">Wait<\/code> or reading the <code class=\"fm-code-in-text\">Result<\/code> property will block until you use the <code class=\"fm-code-in-text\">TaskCompletionSource<\/code> to complete the <code class=\"fm-code-in-text\">Task<\/code>.<a id=\"calibre_link-936\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-937\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-938\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-939\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-940\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><\/p>\n<p class=\"copyrightbody\">To demonstrate the various ways we can complete the <code class=\"fm-code-in-text\">Task<\/code>, we\u2019ll use the following example code.<a id=\"calibre_link-204\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><\/p>\n<p class=\"fm-code-listing-caption\">Listing 10.1 A template for <code class=\"fm-code-in-text1\">TaskCompletionSource<\/code> demo<\/p>\n<pre class=\"programlisting\">public class TaskCompletionSourceDemo\n{\n   private Task&lt;int&gt; BackgroundWork()                    <span class=\"fm-combinumeral\">\u2776<\/span>\n   {\n      var tcs = new TaskCompletionSource&lt;int&gt;();\n      Task.Run(()=&gt;                                      <span class=\"fm-combinumeral\">\u2777<\/span>\n      {\n                                                         <span class=\"fm-combinumeral\">\u2778<\/span>\n      });\n      return tcs.Task;                                   <span class=\"fm-combinumeral\">\u2779<\/span>\n   } \n \n   public async Task RunDemo()\n   {\n       var result = await BackgroundWork();              <span class=\"fm-combinumeral\">\u277a<\/span>\n       Console.WriteLine(result); \n   }\n}<\/pre>\n<p class=\"copyrightbody\"><span class=\"fm-combinumeral\">\u2776<\/span> No async keyword<\/p>\n<p class=\"copyrightbody\"><span class=\"fm-combinumeral\">\u2777<\/span> Runs in another thread<\/p>\n<p class=\"copyrightbody\"><span class=\"fm-combinumeral\">\u2778<\/span> Task completion should happen here.<\/p>\n<p class=\"copyrightbody\"><span class=\"fm-combinumeral\">\u2779<\/span> Returns Task&lt;int&gt;, not int<\/p>\n<p class=\"copyrightbody\"><span class=\"fm-combinumeral\">\u277a<\/span> Waits for Task to complet<\/p>\n<p class=\"copyrightbody\">Note that the <code class=\"fm-code-in-text\">BackgroundWork<\/code> method is not marked as <code class=\"fm-code-in-text\">async<\/code>. Because of this, the compiler doesn\u2019t transform it, we can\u2019t use <code class=\"fm-code-in-text\">await<\/code> inside of it, and the compiler doesn\u2019t wrap the result in a <code class=\"fm-code-in-text\">Task<\/code>, which means we are responsible for creating and returning the <code class=\"fm-code-in-text\">Task&lt;int&gt;<\/code> ourselves. The <code class=\"fm-code-in-text\">RunDemo<\/code> method (that is marked as <code class=\"fm-code-in-text\">async<\/code>) just uses <code class=\"fm-code-in-text\">await<\/code> to get the result produced by the <code class=\"fm-code-in-text\">BackgroundWork<\/code> method. <a id=\"calibre_link-941\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-942\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><\/p>\n<p class=\"copyrightbody\"><code class=\"fm-code-in-text\">TaskCompletionSource<\/code> has three sets of methods we can use to complete the <code class=\"fm-code-in-text\">Task<\/code>:<\/p>\n<p class=\"copyrightbody\">&nbsp;&nbsp; 1.&nbsp; <code class=\"fm-code-in-text\">SetResult<\/code> and <code class=\"fm-code-in-text\">TrySetResult<\/code> will complete the <code class=\"fm-code-in-text\">Task<\/code>, change its state to <code class=\"fm-code-in-text\">RanToCompletion<\/code>, and in case of a <code class=\"fm-code-in-text\">Task&lt;T&gt;<\/code>, store the result value in the <code class=\"fm-code-in-text\">Task&lt;T&gt;<\/code> object (accessible with <code class=\"fm-code-in-text\">Task.Result<\/code> or <code class=\"fm-code-in-text\">await<\/code>). After calling <code class=\"fm-code-in-text\">SetResult<\/code> or <code class=\"fm-code-in-text\">TrySetResult<\/code>, both <code class=\"fm-code-in-text\">IsCompleted<\/code> and <code class=\"fm-code-in-text\">IsCompletedSuccessfully<\/code> will be <code class=\"fm-code-in-text\">true<\/code>.<a id=\"calibre_link-943\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-944\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><\/p>\n<p class=\"fm-code-listing-captione\">Listing 10.2 <code class=\"fm-code-in-text\">TaskCompletionSource.TrySetResult<\/code> demo<\/p>\n<pre class=\"programlisting\">public class TaskCompletionSourceDemo\n{\n   private Task&lt;int&gt; BackgroundWork()\n   {\n      var tcs = new TaskCompletionSource&lt;int&gt;();\n      Task.Run(()=&gt;\n      {\n          tcs.TrySetResult(7)                            <span class=\"fm-combinumeral\">\u2776<\/span>\n      });\n      return tcs.Task;\n   } \n \n   public async Task RunDemo()\n   {\n       var result = await BackgroundWork();              <span class=\"fm-combinumeral\">\u2777<\/span>\n       Console.WriteLine(result);                        <span class=\"fm-combinumeral\">\u2778<\/span>\n   }\n}<\/pre>\n<p class=\"copyrightbody\"><span class=\"fm-combinumeral\">\u2776<\/span> Completes Task successfully<\/p>\n<p class=\"copyrightbody\"><span class=\"fm-combinumeral\">\u2777<\/span> Continues running<\/p>\n<p class=\"copyrightbody\"><span class=\"fm-combinumeral\">\u2778<\/span> Prints 7<\/p>\n<p class=\"copyrightbody\">This example shows how to complete a <code class=\"fm-code-in-text\">Task<\/code> successfully. Calling <code class=\"fm-code-in-text\">TrySetResult<\/code> (or <code class=\"fm-code-in-text\">SetResult<\/code>) causes the <code class=\"fm-code-in-text\">await<\/code> to continue running.<\/p>\n<p class=\"copyrightbody\">&nbsp;&nbsp; 2.&nbsp; <code class=\"fm-code-in-text\">SetException<\/code> and <code class=\"fm-code-in-text\">TrySetException<\/code> will complete the <code class=\"fm-code-in-text\">Task<\/code>, change its state to <code class=\"fm-code-in-text\">Faulted<\/code>, and store the exception or list of exceptions in the <code class=\"fm-code-in-text\">Task<\/code>. The exception or list of exceptions will be wrapped in an <code class=\"fm-code-in-text\">AggregateException<\/code> object and stored in the <code class=\"fm-code-in-text\">Task.Exception<\/code> property. Using <code class=\"fm-code-in-text\">await<\/code> on the task, reading the <code class=\"fm-code-in-text\">Result<\/code> property, or calling <code class=\"fm-code-in-text\">Wait()<\/code> will cause the <code class=\"fm-code-in-text\">AggregateException<\/code> to be thrown. After calling <code class=\"fm-code-in-text\">SetException<\/code> or <code class=\"fm-code-in-text\">TrySetException<\/code>, <code class=\"fm-code-in-text\">IsCompleted<\/code> and <code class=\"fm-code-in-text\">IsFaulted<\/code> will be <code class=\"fm-code-in-text\">true<\/code>.<a id=\"calibre_link-945\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-946\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-947\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-292\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-948\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><\/p>\n<p class=\"fm-code-listing-captione\">Listing 10.3 <code class=\"fm-code-in-text\">TaskCompletionSource.TrySetException<\/code> demo<\/p>\n<pre class=\"programlisting\">public class TaskCompletionSourceDemo\n{\n   private Task&lt;int&gt; BackgroundWork()\n   {\n      var tcs = new TaskCompletionSource&lt;int&gt;();\n      Task.Run(()=&gt;\n      {\n          tcs.TrySetException(new Exception(\"oops\"))      <span class=\"fm-combinumeral\">\u2776<\/span>\n      });\n      return tcs.Task;\n   } \n \n   public async Task RunDemo()\n   {\n       var result = await BackgroundWork();               <span class=\"fm-combinumeral\">\u2777<\/span>\n       Console.WriteLine(result);\n   }\n}<\/pre>\n<p class=\"copyrightbody\"><span class=\"fm-combinumeral\">\u2776<\/span> Completes Task with error<\/p>\n<p class=\"copyrightbody\"><span class=\"fm-combinumeral\">\u2777<\/span> Throws AggregateException<\/p>\n<p class=\"copyrightbody\">In this example, we used <code class=\"fm-code-in-text\">TrySetException<\/code> to complete the <code class=\"fm-code-in-text\">Task<\/code> and change it to a faulted state. The <code class=\"fm-code-in-text\">await<\/code> operator will throw the exception.<a id=\"calibre_link-949\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><\/p>\n<p class=\"copyrightbody\">&nbsp;&nbsp; 3.&nbsp; <code class=\"fm-code-in-text\">SetCanceled<\/code> and <code class=\"fm-code-in-text\">TrySetCanceled<\/code> will complete the <code class=\"fm-code-in-text\">Task<\/code>, change its state to <code class=\"fm-code-in-text\">Canceled<\/code>, and optionally, store a cancellation token in the <code class=\"fm-code-in-text\">Task<\/code>. Using <code class=\"fm-code-in-text\">await<\/code> on the task, reading the <code class=\"fm-code-in-text\">Result<\/code> property, or calling <code class=\"fm-code-in-text\">Wait()<\/code>will throw a <code class=\"fm-code-in-text\">TaskCanceledException<\/code>. If you pass a cancellation token to <code class=\"fm-code-in-text\">TrySetCanceled<\/code>, it will be available in the <code class=\"fm-code-in-text\">TaskCanceledException.CancellationToken<\/code> property. After calling <code class=\"fm-code-in-text\">SetCanceled<\/code> or <code class=\"fm-code-in-text\">TrySetCanceled<\/code>, the <code class=\"fm-code-in-text\">IsCompleted<\/code> and <code class=\"fm-code-in-text\">IsCanceled<\/code> properties will be <code class=\"fm-code-in-text\">true<\/code>. Note that although <code class=\"fm-code-in-text\">await<\/code> will throw an exception, the <code class=\"fm-code-in-text\">Task<\/code>\u2019s <code class=\"fm-code-in-text\">IsFaulted<\/code> property will be <code class=\"fm-code-in-text\">false<\/code>, and the <code class=\"fm-code-in-text\">Exception<\/code> property will be <code class=\"fm-code-in-text\">null.<\/code><code class=\"fm-code-in-text\"><a class=\"pcalibre2 pcalibre pcalibre3 pcalibre1 calibre8\" id=\"calibre_link-950\"><\/a><a class=\"pcalibre2 pcalibre pcalibre3 pcalibre1 calibre8\" id=\"calibre_link-951\"><\/a><a class=\"pcalibre2 pcalibre pcalibre3 pcalibre1 calibre8\" id=\"calibre_link-952\"><\/a><\/code><\/p>\n<p class=\"fm-code-listing-captione\">Listing 10.4 <code class=\"fm-code-in-text\">TaskCompletionSource.TrySetCanceled<\/code> demo<\/p>\n<pre class=\"programlisting\">public class TaskCompletionSourceDemo\n{\n   private Task&lt;int&gt; BackgroundWork()\n   {\n      var tcs = new TaskCompletionSource&lt;int&gt;();\n      Task.Run(()=&gt;\n      {\n          tcs.TrySetCanceled()                            <span class=\"fm-combinumeral\">\u2776<\/span>\n      });\n      return tcs.Task;\n   } \n \n   public async Task RunDemo()\n   {\n       var result = await BackgroundWork();               <span class=\"fm-combinumeral\">\u2777<\/span>\n       Console.WriteLine(result);\n   }\n}<\/pre>\n<p class=\"copyrightbody\"><span class=\"fm-combinumeral\">\u2776<\/span> Completes Task by canceling it<\/p>\n<p class=\"copyrightbody\"><span class=\"fm-combinumeral\">\u2777<\/span> Throws TaskCanceledException<\/p>\n<p class=\"copyrightbody\"><a id=\"calibre_link-239\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a>In this example, we used <code class=\"fm-code-in-text\">TrySetCanceled<\/code> to cancel the <code class=\"fm-code-in-text\">Task<\/code>, and <code class=\"fm-code-in-text\">await<\/code> will throw a <code class=\"fm-code-in-text\">TaskCanceledException<\/code> exception. There is no way to use <code class=\"fm-code-in-text\">TaskCompletionSource<\/code> to set the <code class=\"fm-code-in-text\">Task<\/code>\u2019s status to any of the other options (<code class=\"fm-code-in-text\">WaitingToRun<\/code>, <code class=\"fm-code-in-text\">Running<\/code>, or <code class=\"fm-code-in-text\">WaitingForChildrenToComplete<\/code>).<a id=\"calibre_link-953\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><\/p>\n<p class=\"copyrightbody\">The difference between the two variations of each method is that the older <code class=\"fm-code-in-text\">SetXXX<\/code> will throw an exception if the <code class=\"fm-code-in-text\">Task<\/code> is already complete, while the newer <code class=\"fm-code-in-text\">TrySetXXX<\/code> will not (if the <code class=\"fm-code-in-text\">Task<\/code> is already complete, the <code class=\"fm-code-in-text\">Task<\/code> will not change, and any parameters passed to the method will be ignored). The <code class=\"fm-code-in-text\">TrySetXXX<\/code> variation was added because the older methods can create a race condition in any situation where you might try to complete a task from two different threads (for example, one thread doing the work and another handling cancellation). It is best practice to use the newer <code class=\"fm-code-in-text\">Try<\/code> versions of all the methods unless you specifically rely on them to throw an exception if the <code class=\"fm-code-in-text\">Task<\/code> is already complete. The <code class=\"fm-code-in-text\">Try<\/code> variant will return <code class=\"fm-code-in-text\">true<\/code> if it completes the <code class=\"fm-code-in-text\">Task<\/code> or <code class=\"fm-code-in-text\">false<\/code> if the <code class=\"fm-code-in-text\">Task<\/code> was already completed.<a id=\"calibre_link-954\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-955\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><\/p>\n<p class=\"copyrightbody\">For example, in the following code snippet, simulating a situation when a different thread cancels the <code class=\"fm-code-in-text\">Task<\/code> right before a calculation is complete, the call to <code class=\"fm-code-in-text\">SetResult<\/code> will throw an exception:<\/p>\n<pre class=\"programlisting\">var tcs = new TaskCompletionSource&lt;int&gt;();\ntcs.SetCanceled();                                     <span class=\"fm-combinumeral\">\u2776<\/span>\ntcs.SetResult(7);                                      <span class=\"fm-combinumeral\">\u2777<\/span><\/pre>\n<p class=\"copyrightbody\"><span class=\"fm-combinumeral\">\u2776<\/span> Cancels the task<\/p>\n<p class=\"copyrightbody\"><span class=\"fm-combinumeral\">\u2777<\/span> Throws an exception<\/p>\n<p class=\"copyrightbody\">While in this code snippet, the call to <code class=\"fm-code-in-text\">TrySetResult<\/code> will be ignored without an exception (you can still know <code class=\"fm-code-in-text\">TrySetResult<\/code> failed because it will return <code class=\"fm-code-in-text\">false<\/code>):<a id=\"calibre_link-956\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-957\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-958\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><\/p>\n<pre class=\"programlisting\">var tcs = new TaskCompletionSource&lt;int&gt;();\ntcs.TrySetCanceled();                                  <span class=\"fm-combinumeral\">\u2776<\/span>\ntcs.TrySetResult(7);                                   <span class=\"fm-combinumeral\">\u2777<\/span><\/pre>\n<p class=\"copyrightbody\"><span class=\"fm-combinumeral\">\u2776<\/span> Cancels the task<\/p>\n<p class=\"copyrightbody\"><span class=\"fm-combinumeral\">\u2777<\/span> Ignored, returns false<\/p>\n<h2 class=\"fm-head\" id=\"calibre_link-91\">10.2 Choosing where continuations run<\/h2>\n<p class=\"copyrightbody\">The code that runs after the asynchronous operation (the code after the <code class=\"fm-code-in-text\">await<\/code> or the callback passed to <code class=\"fm-code-in-text\">ContinueWith<\/code>) is called a continuation. Calling any of the <code class=\"fm-code-in-text\">TaskCompletionSource<\/code>\u2019s methods that complete the <code class=\"fm-code-in-text\">Task<\/code> will cause the continuation to run (obviously, that\u2019s the whole point), and <code class=\"fm-code-in-text\">TaskCompletionSource<\/code> lets us decide whether the continuation can run immediately in the thread that called the <code class=\"fm-code-in-text\">TaskCompletionSource<\/code> method.<a id=\"calibre_link-959\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-960\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-178\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><\/p>\n<p class=\"copyrightbody\">If we allow the continuation to run immediately, it can run before <code class=\"fm-code-in-text\">TrySetResult<\/code> (or any of the other methods) return. This means that <code class=\"fm-code-in-text\">TrySetResult<\/code> can take an arbitrarily long time to run and that our code is in a state that can run arbitrary code that isn\u2019t under our control safely. For example, the following code has a potential deadlock bug:<\/p>\n<pre class=\"programlisting\">lock(_valueLock)\n{\n     _taskSource.TrySetResult(_value);\n}<\/pre>\n<p class=\"copyrightbody\">In this code, we want to use a value protected by a lock as the result of a task, so we acquire the lock and call <code class=\"fm-code-in-text\">TrySetResult<\/code> with the value. This might cause code that is not under our control (the <code class=\"fm-code-in-text\">Task<\/code> continuation) to run while we are holding the lock, and if this code waits for something else that needs the same lock in another thread, we will have a deadlock.<\/p>\n<p class=\"copyrightbody\">One solution to this problem is to move the <code class=\"fm-code-in-text\">TrySetResult<\/code> call outside of the <code class=\"fm-code-in-text\">lock<\/code> block:<\/p>\n<pre class=\"programlisting\">int copyOfValue;\nlock(_valueLock)\n{\n   copyOfValue = _value;\n}\n_taskSource.TrySetResult(copyOfValue);<\/pre>\n<p class=\"copyrightbody\">We can\u2019t use the _<code class=\"fm-code-in-text\">value<\/code> variables outside of the <code class=\"fm-code-in-text\">lock<\/code> block, but we can copy it to a local variable and pass the copy to <code class=\"fm-code-in-text\">TrySetResult<\/code> outside the lock. This might still run code outside our control before <code class=\"fm-code-in-text\">TrySetResult<\/code> returns, so we can\u2019t know how much time <code class=\"fm-code-in-text\">TrySetResult<\/code> will take, but there is no longer a risk of a deadlock.<\/p>\n<p class=\"copyrightbody\">Another option is to make <code class=\"fm-code-in-text\">TaskCompletionSource<\/code> run the code in another thread. We do this by using the <code class=\"fm-code-in-text\">TaskCompletionSource<\/code> constructor that accepts a <code class=\"fm-code-in-text\">TaskCreationOptions<\/code> parameter and passes the <code class=\"fm-code-in-text\">TaskCreationOptions<\/code>. <code class=\"fm-code-in-text\">RunContinuationsAsynchronously<\/code> value:<\/p>\n<pre class=\"programlisting\">_taskSource = new TaskCompletionSource&lt;int&gt;(\n   TaskCreationOptions. RunContinuationsAsynchronously);<\/pre>\n<p class=\"copyrightbody\">We need to decide whether we want <code class=\"fm-code-in-text\">TaskCompletionSource<\/code> to run the continuation code in another thread at the <code class=\"fm-code-in-text\">TaskCompletionSource<\/code> construction time. We can\u2019t choose some <code class=\"fm-code-in-text\">TrySetResult<\/code> to run the continuation in a background thread while others don\u2019t. For example, we can\u2019t make <code class=\"fm-code-in-text\">TaskCompletionSource<\/code> use another thread only when we are holding a lock.<\/p>\n<p class=\"copyrightbody\">I used <code class=\"fm-code-in-text\">TrySetResult<\/code> in this example, but everything here also applies to all the other methods that complete the <code class=\"fm-code-in-text\">Task<\/code> (<code class=\"fm-code-in-text\">SetResult<\/code>, <code class=\"fm-code-in-text\">SetException<\/code>, <code class=\"fm-code-in-text\">TrySetExcetion<\/code>, <code class=\"fm-code-in-text\">SetCanceled<\/code>, and <code class=\"fm-code-in-text\">TrySetCanceld<\/code>).<\/p>\n<h2 class=\"fm-head\" id=\"calibre_link-92\">10.3 Example: Waiting for initialization<\/h2>\n<p class=\"copyrightbody\">Let\u2019s start with a simple example: we\u2019ll write a class that requires a lengthy initialization process and performs this initialization in the background. Whenever you call a method of this class, if the initialization hasn\u2019t completed yet, that method will await until the initialization is complete.<a id=\"calibre_link-240\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-961\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-962\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><\/p>\n<p class=\"fm-code-listing-caption\">Listing 10.5 Class with background initialization<\/p>\n<pre class=\"programlisting\">public class RequiresInit\n{\n   private Task&lt;int&gt; _value;\n \n   public RequiresInit ()\n   {\n      var tcs = new TaskCompletionSource&lt;int&gt;();\n      _value = tcs.Task;                              <span class=\"fm-combinumeral\">\u2776<\/span>\n      Task.Run(()=&gt;\n      {\n          try\n          {\n             Thread.Sleep(1000);                      <span class=\"fm-combinumeral\">\u2777<\/span>\n             tcs.TrySetResult(7);                     <span class=\"fm-combinumeral\">\u2778<\/span>\n          }\n          catch(Exception ex)\n          {\n             tcs.TrySetException(ex);\n          }\n      });\n   }\n   public async Task&lt;int&gt; Add1()\n   {\n      var actualValue = await _value;                 <span class=\"fm-combinumeral\">\u2779<\/span>\n      return actualValue+1;\n   }\n}<\/pre>\n<p class=\"copyrightbody\"><span class=\"fm-combinumeral\">\u2776<\/span> Assigns the Task before leaving constructor<\/p>\n<p class=\"copyrightbody\"><span class=\"fm-combinumeral\">\u2777<\/span> Simulates long calculation<\/p>\n<p class=\"copyrightbody\"><span class=\"fm-combinumeral\">\u2778<\/span> Sets the Task\u2019s result<\/p>\n<p class=\"copyrightbody\"><span class=\"fm-combinumeral\">\u2779<\/span> Waits for result if needed<\/p>\n<p class=\"copyrightbody\">In this example, we wrote the <code class=\"fm-code-in-text\">RequiresInit<\/code> class. This class has a lengthy initialization process and doesn\u2019t want to (or maybe can\u2019t) let the entire initialization process run in the constructor. So inside the constructor, we just kick off that initialization process in a background thread using <code class=\"fm-code-in-text\">Task.Run<\/code> and return immediately. To access the result of the initialization process, we create a <code class=\"fm-code-in-text\">Task&lt;int&gt;<\/code> using <code class=\"fm-code-in-text\">TaskCompletionSource&lt;int&gt;<\/code> and assign it to the <code class=\"fm-code-in-text\">value<\/code> field.<a id=\"calibre_link-963\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-964\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-965\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-966\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><\/p>\n<p class=\"copyrightbody\">Obviously, the result of this lengthy initialization is probably a complex object, but for the sake of simplicity, it\u2019s an <code class=\"fm-code-in-text\">int<\/code> in this example. Also, the initialization is just a call to <code class=\"fm-code-in-text\">Thread.Sleep<\/code>, and the result of the initialization is always the number 7.<\/p>\n<p class=\"copyrightbody\">In the background thread, after calculating the result, we use <code class=\"fm-code-in-text\">TrySetResult<\/code> to complete the task and assign the calculation result to it. In case of an exception during the calculation, we use <code class=\"fm-code-in-text\">TrySetException<\/code> to propagate the exception into the task.<a id=\"calibre_link-967\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-968\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><\/p>\n<p class=\"copyrightbody\">Later, when we want to use the initialization result, we read it using <code class=\"fm-code-in-text\">await<\/code> <code class=\"fm-code-in-text\">_value<\/code>, and if the calculation has already completed, this will return the value immediately. If the calculation hasn\u2019t completed yet, this will asynchronously wait until the result becomes available. Finally, if the calculation has failed, this will throw an exception telling us why.<\/p>\n<p class=\"copyrightbody\">Using a task like this combines getting the result, handling the signal that the result is available, and reporting initialization errors (if any) into a single operation. This not only saves us from typing but also makes the code more maintainable because future developers can\u2019t forget to wait for the value to become available or forget to check for errors.<\/p>\n<h2 class=\"fm-head\" id=\"calibre_link-93\">10.4 Example: Adapting old APIs<\/h2>\n<p class=\"copyrightbody\">Probably the most straightforward use of <code class=\"fm-code-in-text\">TaskCompletionSource<\/code> is adapting asynchronous APIs that are incompatible with <code class=\"fm-code-in-text\">await<\/code>. Fortunately, this is becoming quite rare because almost all the asynchronous operations in the .NET library and common third-party components have been adapted to use <code class=\"fm-code-in-text\">Task<\/code> objects and are already compatible with <code class=\"fm-code-in-text\">await<\/code>. Today, libraries that don\u2019t support <code class=\"fm-code-in-text\">async<\/code>\/<code class=\"fm-code-in-text\">await<\/code> are mostly either wrappers for non-.NET code or written by authors who really hate <code class=\"fm-code-in-text\">async<\/code>\/<code class=\"fm-code-in-text\">await<\/code>.<a id=\"calibre_link-969\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-970\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-971\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-190\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><\/p>\n<p class=\"copyrightbody\">To demonstrate this, we\u2019ll use a pattern that was pretty common before <code class=\"fm-code-in-text\">async<\/code>\/<code class=\"fm-code-in-text\">await<\/code>, an interface that lets you start an operation and get notified when it completes:<\/p>\n<pre class=\"programlisting\">public interface IAsyncOperation\n{\n    void StartCalculation();\n    event Action&lt;int&gt; CalculationComplete;\n}<\/pre>\n<p class=\"copyrightbody\">Adapting this using <code class=\"fm-code-in-text\">TaskCompletionSource<\/code> is rather simple, as shown in the following listing.<\/p>\n<p class=\"fm-code-listing-caption\">Listing 10.6 Adapting non-standard asynchronous APIs<\/p>\n<pre class=\"programlisting\">public Task&lt;int&gt; CallAsyncOperation()\n{\n   var tcs = new TaskCompletionSource&lt;int&gt;();\n   _asyncOperation.CalculationComplete += \n      result =&gt; tcs.TrySetResult(result);\n   _asyncOperation.StartCalculation();\n   return tcs.Task;\n}<\/pre>\n<p class=\"copyrightbody\">We just created a <code class=\"fm-code-in-text\">TaskCompletionSource<\/code>, subscribed to the asynchronous operation\u2019s nonstandard completion notification, and called <code class=\"fm-code-in-text\">TrySetResult<\/code> when the asynchronous operation is completed.<\/p>\n<h2 class=\"fm-head\" id=\"calibre_link-94\">10.5 Old-style asynchronous operations (BeginXXX, EndXXX)<\/h2>\n<p class=\"copyrightbody\">The standard pattern for asynchronous operations in .NET before tasks and <code class=\"fm-code-in-text\">async<\/code>\/<code class=\"fm-code-in-text\">await<\/code> was a pair of methods, one with the <code class=\"fm-code-in-text\">Begin<\/code> prefix that returns an <code class=\"fm-code-in-text\">IAsyncResult<\/code> object and one with the <code class=\"fm-code-in-text\">End<\/code> prefix. All those methods in the .NET library and most third-party libraries already have a task-based alternative, so it\u2019s quite rare to have to deal with those. I\u2019m only talking about this so you\u2019ll know what all of those <code class=\"fm-code-in-text\">BeginXXX<\/code> and <code class=\"fm-code-in-text\">EndXXX<\/code> methods are and what to do if you find yourself using an old library that wasn\u2019t adapted to using the <code class=\"fm-code-in-text\">Task<\/code> class.<a id=\"calibre_link-972\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-973\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-974\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-975\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-976\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-977\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-172\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-978\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><\/p>\n<p class=\"copyrightbody\">Before <code class=\"fm-code-in-text\">async<\/code>\/<code class=\"fm-code-in-text\">await<\/code>, writing asynchronous code was difficult. The asynchronous methods were a rarely used option for only those who really needed them, so the asynchronous version was based on the non-asynchronous API version. The asynchronous version was always composed of two methods:<\/p>\n<ul class=\"calibre9\">\n<li class=\"fm-list-bullet\">\n<p class=\"list\">The method with the <code class=\"fm-code-in-text\">Begin<\/code> prefix accepts all the parameters of the non-async version and two additional parameters (called callback and state). This method starts the asynchronous operation. The <code class=\"fm-code-in-text\">IAsyncResult<\/code> object returned by the <code class=\"fm-code-in-text\">Begin<\/code> method represents the asynchronous operation and, like <code class=\"fm-code-in-text\">Task<\/code> in the newer APIs, can be used to detect when the operation completes.<a id=\"calibre_link-979\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><\/p>\n<\/li>\n<li class=\"fm-list-bullet\">\n<p class=\"list\">The method with the <code class=\"fm-code-in-text\">End<\/code> prefix takes the <code class=\"fm-code-in-text\">IAsyncResult<\/code> object, cleans up any resources used by the asynchronous operation, and returns the result of the operation.<a id=\"calibre_link-980\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><\/p>\n<\/li>\n<\/ul>\n<p class=\"copyrightbody\">To demonstrate adapting this, we\u2019ll take an old-style asynchronous operation and adapt it to the new <code class=\"fm-code-in-text\">Task<\/code>-based style. For this example, we will use the <code class=\"fm-code-in-text\">Stream.Read<\/code> method:<a id=\"calibre_link-981\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><\/p>\n<pre class=\"programlisting\">int Read (byte[] buffer, int offset, int count);<\/pre>\n<p class=\"copyrightbody\">And the old-style async version is composed of two methods&mdash;<code class=\"fm-code-in-text\">Stream.BeginRead<\/code> and <code class=\"fm-code-in-text\">Stream.EndRead<\/code>:<a id=\"calibre_link-982\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-983\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><\/p>\n<pre class=\"programlisting\">IAsyncResult BeginRead(\n   byte[] buffer, int offset, int count, \n   AsyncCallback? callback, object? state);\nint EndRead (IAsyncResult asyncResult);<\/pre>\n<p class=\"copyrightbody\">As you can guess, we can use the <code class=\"fm-code-in-text\">callback<\/code> parameter and <code class=\"fm-code-in-text\">TaskCompletionSource<\/code> just like we used in the previous example, but there\u2019s an easier way. The .NET library contains the <code class=\"fm-code-in-text\">Task.Factory.FromAsync<\/code> method that creates a <code class=\"fm-code-in-text\">Task<\/code> from this method pair. Here is how it is used:<a id=\"calibre_link-984\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-985\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-986\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><\/p>\n<pre class=\"programlisting\">public Task&lt;int&gt; MyReadAsync(\n   Stream stream, byte[] buffer, int offset, int length)\n{\n   return Task.Factory.FromAsync(\n      (callback,state)=&gt;stream.BeginRead(\n      buffer,0,buffer.Length,callback,state), stream.EndRead, null);\n}<\/pre>\n<p class=\"copyrightbody\">The <code class=\"fm-code-in-text\">Task.Factory.FromAsync<\/code> method takes three parameters:<a id=\"calibre_link-987\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><\/p>\n<ul class=\"calibre9\">\n<li class=\"fm-list-bullet\">\n<p class=\"list\"><i class=\"fm-italics\">A lambda that calls the<\/i> <code class=\"fm-code-in-text\">BeginXXX<\/code> <i class=\"fm-italics\">method<\/i>&mdash;If the <code class=\"fm-code-in-text\">BeginXXX<\/code> method doesn\u2019t need any parameters other than callback and state, you can pass it without wrapping it in a lambda.<a id=\"calibre_link-988\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><\/p>\n<\/li>\n<li class=\"fm-list-bullet\">\n<p class=\"list\"><i class=\"fm-italics\">The<\/i> <code class=\"fm-code-in-text\">EndXXX<\/code> <i class=\"fm-italics\">method<\/i>&mdash;If this method has <code class=\"fm-code-in-text\">out<\/code> parameters, you need to wrap it in a lambda and extract the values of those parameters.<a id=\"calibre_link-989\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><\/p>\n<\/li>\n<li class=\"fm-list-bullet\">\n<p class=\"list\"><i class=\"fm-italics\">The<\/i> <code class=\"fm-code-in-text\">state<\/code> <i class=\"fm-italics\">parameter<\/i>&mdash;It isn\u2019t required if you are using lambda, and it can always be <code class=\"fm-code-in-text\">null<\/code>.<a id=\"calibre_link-990\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><\/p>\n<\/li>\n<\/ul>\n<p class=\"copyrightbody\">Because most APIs (including <code class=\"fm-code-in-text\">Stream.Read<\/code>) already have a <code class=\"fm-code-in-text\">Task<\/code>-based version, and newer APIs only have <code class=\"fm-code-in-text\">Task<\/code>-based asynchronous versions without the <code class=\"fm-code-in-text\">BeginXXX<\/code> and <code class=\"fm-code-in-text\">EndXXX<\/code> methods, having to use this is quite rare. So we will not go into any more detail about it.<\/p>\n<h2 class=\"fm-head\" id=\"calibre_link-95\">10.6 Example: Asynchronous data structures<\/h2>\n<p class=\"copyrightbody\">In this example, we\u2019ll write an asynchronous queue. Our asynchronous queue, just like a normal queue, is a FIFO (first-in, first-out) collection with two operations: enqueue and dequeue. The enqueue operation adds an item to the queue, and the dequeue operation returns the first item in the queue if the queue isn\u2019t empty. What makes our <code class=\"fm-code-in-text\">AsyncQueue<\/code> special is that if there are no items in the queue, the dequeue operation will return a <code class=\"fm-code-in-text\">Task<\/code> that will complete when a new item is later added to the queue. That way, <code class=\"fm-code-in-text\">await asyncQueue.Dequeue()<\/code> will return immediately with the next value if it\u2019s already in the queue or, if the queue is empty, asynchronously wait until the next value becomes available. <a id=\"calibre_link-991\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-992\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-993\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-175\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-994\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><\/p>\n<p class=\"copyrightbody\">Our queue class is mostly two queues, one of data waiting to be processed and one of processors waiting for data. At least one of those queues must be empty at all times, because otherwise, we have missed an opportunity to match a data item with a processor.<\/p>\n<p class=\"fm-code-listing-caption\">Listing 10.7 <code class=\"fm-code-in-text1\">AsyncQueue<\/code><\/p>\n<pre class=\"programlisting\">public class AsyncQueue&lt;T&gt;\n{\n \n   private Queue&lt;TaskCompletionSource&lt;T&gt;&gt; \n      _processorsWaitingForData = new();\n   private Queue&lt;T&gt; _dataWaitingForProcessors  = new();\n   private object _lock = new object();<\/pre>\n<p class=\"copyrightbody\">When a processor becomes available, it calls <code class=\"fm-code-in-text\">Dequeue<\/code>. If a data item is waiting, we deliver it to the processor immediately via a completed <code class=\"fm-code-in-text\">Task<\/code> created with <code class=\"fm-code-in-text\">Task.FromResult<\/code>. If no data is available, we create a new <code class=\"fm-code-in-text\">TaskCompletionSource<\/code> and return its <code class=\"fm-code-in-text\">Task<\/code>, and we enqueue this <code class=\"fm-code-in-text\">TaskCompletionSource<\/code> in the <code class=\"fm-code-in-text\">processorsWaitingForData<\/code> queue:<a id=\"calibre_link-995\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><\/p>\n<pre class=\"programlisting\">   public Task&lt;T&gt; Dequeue(CancellationToken cancellationToken)\n   {\n      lock (_lock)\n      {\n         if (_dataWaitingForProcessors.Count &gt; 0)\n         {\n            return Task.FromResult(_dataWaitingForProcessors.Dequeue());\n         }\n         var tcs = new TaskCompletionSource&lt;T&gt;(\n            TaskCreationOptions.RunContinuationsAsynchronously);\n         _processorsWaitingForData.Enqueue(tcs);<\/pre>\n<p class=\"copyrightbody\">Because whoever uses our class is likely to expect <code class=\"fm-code-in-text\">Enqueue<\/code> and <code class=\"fm-code-in-text\">Dequque<\/code> operations to be fast, we create the <code class=\"fm-code-in-text\">TaskCompletionSource<\/code> objects with the <code class=\"fm-code-in-text\">TaskCreationOptions.RunContinuationsAsynchronously<\/code> flag. This means the code that processes the data will run in another thread and not inside our <code class=\"fm-code-in-text\">Enqueue<\/code> and <code class=\"fm-code-in-text\">Dequeue<\/code> methods. It also allows us to call <code class=\"fm-code-in-text\">TrySetResult<\/code> and <code class=\"fm-code-in-text\">TryCancel<\/code> while holding a lock. <a id=\"calibre_link-996\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-997\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-211\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><\/p>\n<p class=\"copyrightbody\">We also let the processor pass a <code class=\"fm-code-in-text\">CancellationToken<\/code> because we need a way for a processor to indicate it is no longer available. If this cancellation token becomes canceled, we cancel the processor\u2019s <code class=\"fm-code-in-text\">Task<\/code> but leave the <code class=\"fm-code-in-text\">TaskCompletionSource<\/code> in the queue because it\u2019s simpler that way.<a id=\"calibre_link-998\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><\/p>\n<p class=\"copyrightbody\">As an optimization, we only register if the <code class=\"fm-code-in-text\">CancellationToken<\/code> can be canceled. An example of a <code class=\"fm-code-in-text\">CancellationToken<\/code> that can\u2019t be canceled is the dummy token returned by the <code class=\"fm-code-in-text\">CancellationToken.None<\/code> property:<a id=\"calibre_link-999\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><\/p>\n<pre class=\"programlisting\">         if (cancellationToken.CanBeCanceled)\n         {\n            cancellationToken.Register(() =&gt;\n            {\n               tcs.TrySetCanceled(cancellationToken);\n            });\n         }\n         return tcs.Task;\n      }\n   }<\/pre>\n<p class=\"copyrightbody\">When data is added to the queue by calling <code class=\"fm-code-in-text\">Enqueue<\/code>, we try to deliver it to the first available processor, dequeue the first <code class=\"fm-code-in-text\">TaskCompletionSource<\/code> from <code class=\"fm-code-in-text\">_processorsWaitingForData<\/code> queue, and call <code class=\"fm-code-in-text\">TrySetResult<\/code>. If <code class=\"fm-code-in-text\">TrySetResult<\/code> returns <code class=\"fm-code-in-text\">true<\/code>, we successfully completed the <code class=\"fm-code-in-text\">Task<\/code> and sent the data item to the processor, so we can return.<\/p>\n<p class=\"copyrightbody\">If <code class=\"fm-code-in-text\">TrySetResult<\/code> returns <code class=\"fm-code-in-text\">false<\/code>, it means the <code class=\"fm-code-in-text\">Task<\/code> has already completed, that is, it was canceled because the <code class=\"fm-code-in-text\">TaskCompletionSource<\/code> is fully under our control, and the cancellation code is the only code we wrote that completes a task without first removing its <code class=\"fm-code-in-text\">TaskCompletionSource<\/code> from the queue. In this case, we just move to the next processor.<\/p>\n<p class=\"copyrightbody\">As an optimization, we only handle the cancellation case if the <code class=\"fm-code-in-text\">CancellationToken<\/code> can be canceled (for example, the <code class=\"fm-code-in-text\">CancellationToken.None<\/code> property returns a dummy token that is never canceled):<a id=\"calibre_link-1000\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><\/p>\n<pre class=\"programlisting\">   public void Enqueue(T value)\n   {\n      lock (_lock)\n      {\n          while (_processorsWaitingForData.Count &gt; 0)\n          {\n             var nextDequqer = _processorsWaitingForData.Dequeue();\n             if(nextDequqer.TrySetResult(value))\n             {\n                return;\n             }\n          }<\/pre>\n<p class=\"copyrightbody\">If the processor queue was empty or all the entries in the queue were canceled, we enqueue the data in the _<code class=\"fm-code-in-text\">dataWaitingForProcessors<\/code> queue, where it will wait until someone calls <code class=\"fm-code-in-text\">Dequeue<\/code>:<a id=\"calibre_link-1001\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-1002\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-1003\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-176\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><\/p>\n<pre class=\"programlisting\">          _dataWaitingForProcessors .Enqueue(value);\n      }\n   }\n \n}<\/pre>\n<h2 class=\"fm-head\" id=\"calibre_link-1004\">Summary<\/h2>\n<ul class=\"calibre9\">\n<li class=\"fm-list-bullet\">\n<p class=\"list\">You can use <code class=\"fm-code-in-text\">TaskCompletionSource<\/code> to create <code class=\"fm-code-in-text\">Task<\/code> objects and <code class=\"fm-code-in-text\">TaskCompletionSource&lt;T&gt;<\/code> to create <code class=\"fm-code-in-text\">Task&lt;T&gt;<\/code> objects.<\/p>\n<\/li>\n<li class=\"fm-list-bullet\">\n<p class=\"list\"><code class=\"fm-code-in-text\">TaskCompletionSource&lt;T&gt;.TrySetResult<\/code> is used to complete a <code class=\"fm-code-in-text\">Task&lt;T&gt;<\/code> successfully and set the <code class=\"fm-code-in-text\">Task<\/code>\u2019s <code class=\"fm-code-in-text\">Result<\/code> property.<\/p>\n<\/li>\n<li class=\"fm-list-bullet\">\n<p class=\"list\"><code class=\"fm-code-in-text\">TaskCompletionSource.TrySetResult<\/code> is used to complete a <code class=\"fm-code-in-text\">Task<\/code> successfully. It doesn\u2019t set the result because unlike <code class=\"fm-code-in-text\">Task&lt;T&gt;<\/code>, <code class=\"fm-code-in-text\">Task<\/code> doesn\u2019t have a result.<\/p>\n<\/li>\n<li class=\"fm-list-bullet\">\n<p class=\"list\"><code class=\"fm-code-in-text\">TaskCompletionSource&lt;T&gt;.TrySetException<\/code> and <code class=\"fm-code-in-text\">TaskCompletionSource<\/code><code class=\"fm-code-in-text\">.TrySetException<\/code> are used to complete the <code class=\"fm-code-in-text\">Task<\/code>, change its status to <code class=\"fm-code-in-text\">faulted<\/code>, and store one or more exceptions in the <code class=\"fm-code-in-text\">Task&lt;T&gt;<\/code> or <code class=\"fm-code-in-text\">Task<\/code>.<\/p>\n<\/li>\n<li class=\"fm-list-bullet\">\n<p class=\"list\"><code class=\"fm-code-in-text\">TaskCompletionSource&lt;T&gt;.TrySetCanceled<\/code> and <code class=\"fm-code-in-text\">TaskCompletionSource.TrySetCanceled<\/code> are used to complete the <code class=\"fm-code-in-text\">Task<\/code> and change its state to <code class=\"fm-code-in-text\">Canceled<\/code>.<\/p>\n<\/li>\n<li class=\"fm-list-bullet\">\n<p class=\"list\">While using <code class=\"fm-code-in-text\">await<\/code>, calling <code class=\"fm-code-in-text\">Wait<\/code> or reading the <code class=\"fm-code-in-text\">Result<\/code> property of a canceled <code class=\"fm-code-in-text\">Task<\/code> will throw a <code class=\"fm-code-in-text\">TaskCanceledException<\/code>. The <code class=\"fm-code-in-text\">Task<\/code>\u2019s <code class=\"fm-code-in-text\">Exception<\/code> property will be <code class=\"fm-code-in-text\">null<\/code>. You can use the <code class=\"fm-code-in-text\">Task<\/code>\u2019s <code class=\"fm-code-in-text\">Status<\/code> or <code class=\"fm-code-in-text\">IsCanceled<\/code> properties to check whether a <code class=\"fm-code-in-text\">Task<\/code> is canceled.<\/p>\n<\/li>\n<li class=\"fm-list-bullet\">\n<p class=\"list\">All the <code class=\"fm-code-in-text\">TrySetXXX<\/code> methods mentioned previously will return <code class=\"fm-code-in-text\">true<\/code> if they completed the <code class=\"fm-code-in-text\">Task<\/code> or <code class=\"fm-code-in-text\">false<\/code> if the <code class=\"fm-code-in-text\">Task<\/code> is already completed.<\/p>\n<\/li>\n<li class=\"fm-list-bullet\">\n<p class=\"list\">There\u2019s also a <code class=\"fm-code-in-text\">SetXXX<\/code> variant that throws an exception if the <code class=\"fm-code-in-text\">Task<\/code> is already completed. It\u2019s best practice to use the <code class=\"fm-code-in-text\">TrySetXXX<\/code> variant because the older <code class=\"fm-code-in-text\">SetXXX<\/code> might cause a race condition in some multithreading scenarios.<\/p>\n<\/li>\n<li class=\"fm-list-bullet\">\n<p class=\"list\">By default, continuations (code after the <code class=\"fm-code-in-text\">await<\/code> or in <code class=\"fm-code-in-text\">ContinueWith<\/code> callbacks) can run immediately inside the <code class=\"fm-code-in-text\">TrySetXXX<\/code> or <code class=\"fm-code-in-text\">SetXXX<\/code> call, which makes it unsafe to call them while holding a lock. To make it run in another thread (and so make it safe to call them while holding a lock), pass the <code class=\"fm-code-in-text\">TaskCreationOptions.RunContinuationsAsynchronously<\/code> flag to the <code class=\"fm-code-in-text\">TaskCompletionSource<\/code> constructor.<\/p>\n<\/li>\n<li class=\"fm-list-bullet\">\n<p class=\"list\">If you need to use an old-style asynchronous operation (<code class=\"fm-code-in-text\">BeginXXX<\/code>, <code class=\"fm-code-in-text\">EndXXX<\/code>) with tasks, use the <code class=\"fm-code-in-text\">Task.Factory.FromAsync<\/code> method.<a id=\"calibre_link-1005\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><\/p>\n<\/li>\n<\/ul>\n<\/div>\n<\/div>\n<\/div>\n<div class=\"calibre1\" id=\"calibre_link-96\">\n<div id=\"calibre_link-1006\" class=\"calibre2\">\n<div id=\"calibre_link-1007\" class=\"calibre3\">\n<h1 class=\"copyrighta\" id=\"calibre_link-1008\">11 Controlling on which thread your asynchronous code runs<a id=\"calibre_link-1009\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-1010\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-1011\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-1012\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-1013\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-1014\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><\/h1>\n<p class=\"copyrightbody\"><a id=\"calibre_link-181\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a>This chapter covers<a id=\"calibre_link-1015\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-1016\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><\/p>\n<ul class=\"calibre9\">\n<li class=\"co-summary-bullet\">The <code class=\"fm-code-in-text\">await<\/code> threading behavior<\/li>\n<li class=\"co-summary-bullet\">Understanding <code class=\"fm-code-in-text\">SynchronizationContext<\/code><\/li>\n<li class=\"co-summary-bullet\">When to use <code class=\"fm-code-in-text\">ConfigureAwait<\/code><\/li>\n<li class=\"co-summary-bullet\">Using <code class=\"fm-code-in-text\">Task.Yield<\/code><\/li>\n<li class=\"co-summary-bullet\">The basics of <code class=\"fm-code-in-text\">TaskScheduler<\/code><\/li>\n<\/ul>\n<p class=\"copyrightbody\">Most of the time, you don\u2019t care on which thread your code runs. If you calculate something, your calculation will produce the exact same result regardless of the thread or CPU core it runs on. But some operations do work differently, depending on the thread that runs them, the most common being<\/p>\n<ul class=\"calibre9\">\n<li class=\"fm-list-bullet\">\n<p class=\"list\"><i class=\"fm-italics\">GUI<\/i>&mdash;In WinForms and in WPF, all UI elements can only be accessed by the same thread that created them. Typically, all UI elements are created and accessed by just one thread (called the <i class=\"fm-italics\">UI thread<\/i>), and it is usually the process\u2019 main thread.<\/p>\n<\/li>\n<li class=\"fm-list-bullet\">\n<p class=\"list\"><i class=\"fm-italics\">ASP.NET classic<\/i>&mdash;In ASP.NET classic, which is an older version used in .NET Framework 4.8 and earlier, the <code class=\"fm-code-in-text\">HttpContext.Current<\/code> property will only return the correct value if called from the right thread. (For anyone who doesn\u2019t have experience with ASP.NET classic, access to <code class=\"fm-code-in-text\">HttpContext.Current<\/code> is required in many common scenarios.)<a id=\"calibre_link-1017\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><\/p>\n<\/li>\n<li class=\"fm-list-bullet\">\n<p class=\"list\"><i class=\"fm-italics\">COM<\/i>&mdash;The rules about threads and COM components are complex, and we won\u2019t cover them in this book. But accessing a COM component from the wrong thread might fail or incur a significant performance penalty, depending on the circumstances.<\/p>\n<\/li>\n<li class=\"fm-list-bullet\">\n<p class=\"list\"><i class=\"fm-italics\">Blocking operations<\/i>&mdash;Blocking operations can lock up the thread for a potentially long time. Blocking different threads can have different effects on the system; for example, blocking the UI thread will cause the UI to freeze, blocking a lot of thread pool threads can prevent the servers from accepting connections and continuing asynchronous operations, and so forth.<\/p>\n<\/li>\n<li class=\"fm-list-bullet\">\n<p class=\"list\"><i class=\"fm-italics\">Potentially any other piece of third-party code<\/i>&mdash;Any code you use can have restrictions regarding its use. Newer .NET code tends to be compatible with <code class=\"fm-code-in-text\">async<\/code>\/<code class=\"fm-code-in-text\">await<\/code> and agnostic about which thread runs it. But older code and native code can have stricter rules about threads.<\/p>\n<\/li>\n<\/ul>\n<p class=\"copyrightbody\">In previous chapters, we talked about code after an <code class=\"fm-code-in-text\">await<\/code> and the callbacks passed to <code class=\"fm-code-in-text\">ContinueWith<\/code> as interchangeable. However, everything in this chapter applies only to <code class=\"fm-code-in-text\">await<\/code>. Back in chapter 3, we implemented <code class=\"fm-code-in-text\">await<\/code> using <code class=\"fm-code-in-text\">ContinueWith<\/code>, and I said the code generated by the compiler is more complicated. This is what I meant: all the complexity in this chapter is implemented by code generated by the compiler for the <code class=\"fm-code-in-text\">await<\/code> operator.<\/p>\n<h2 class=\"fm-head\" id=\"calibre_link-97\">11.1 await-threading behavior<\/h2>\n<p class=\"copyrightbody\">Basically, the rules for where the code after <code class=\"fm-code-in-text\">await<\/code> runs are<a id=\"calibre_link-1018\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-1019\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-194\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><\/p>\n<ul class=\"calibre9\">\n<li class=\"fm-list-bullet\">\n<p class=\"list\">In UI apps (WinForms and WPF), if you are using <code class=\"fm-code-in-text\">await<\/code> in a UI thread and don\u2019t use <code class=\"fm-code-in-text\">ConfigureAwait<\/code> (we will talk about it later in this chapter), the code after the <code class=\"fm-code-in-text\">await<\/code> will run in the same thread.<\/p>\n<\/li>\n<li class=\"fm-list-bullet\">\n<p class=\"list\">In ASP.NET classic (not ASP.NET Core), if you are using <code class=\"fm-code-in-text\">await<\/code> in a thread that is processing a web request, and you don\u2019t use <code class=\"fm-code-in-text\">ConfigureAwait<\/code>, the code after the <code class=\"fm-code-in-text\">await<\/code> will run in the same thread.<\/p>\n<\/li>\n<li class=\"fm-list-bullet\">\n<p class=\"list\">In all other cases, the code after the <code class=\"fm-code-in-text\">await<\/code> will run in the thread pool.<\/p>\n<\/li>\n<\/ul>\n<p class=\"copyrightbody\">This list is short, simple, and easy to remember, and it reveals the motivation behind this feature&mdash;supporting UI apps and the older ASP.NET. While this is the default behavior for everything included out of the box in .NET (at least up to version 9), this behavior can be modified. Later in this chapter, we will see how this is implemented and how you (and third-party code) can change this behavior.<\/p>\n<h3 class=\"fm-head\" id=\"calibre_link-98\">11.1.1 await in UI threads<\/h3>\n<p class=\"copyrightbody\">It\u2019s common in UI apps to read values from the user, do something with them, and display the result. For example, the following methods, which are called when the user clicks a button, read the text the user has entered into a text box, pass it to the async <code class=\"fm-code-in-text\">DoSomething<\/code> method, and display the result on screen in a label.<a id=\"calibre_link-1020\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-1021\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-1022\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-1023\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><\/p>\n<p class=\"fm-code-listing-caption\">Listing 11.1 <code class=\"fm-code-in-text1\">await<\/code> in a UI event handler<\/p>\n<pre class=\"programlisting\">private async void button1_Click(object sender, EventArgs ea)\n{\n   label1.Text = await DoSomething(textBox1.Text);\n}<\/pre>\n<p class=\"copyrightbody\">This method will be called by the UI framework on the thread that created the button. In almost all cases, this will be the thread that created all the UI (and so it will be the only thread that can access the UI). Reading <code class=\"fm-code-in-text\">textBox1.Text<\/code> is done before the <code class=\"fm-code-in-text\">await<\/code>, and it runs on the UI thread. Writing <code class=\"fm-code-in-text\">label1.Text<\/code> comes after the <code class=\"fm-code-in-text\">await<\/code>, and it will fail if not run on the UI thread.<\/p>\n<p class=\"copyrightbody\"><a id=\"calibre_link-196\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a>If the code running after the <code class=\"fm-code-in-text\">await<\/code> did not run on the UI thread, this would break one of the most useful properties of <code class=\"fm-code-in-text\">await<\/code>&mdash;that asynchronous code using <code class=\"fm-code-in-text\">await<\/code> is written just like non-asynchronous code. If we use what we learned in chapter 3 about converting this method from an <code class=\"fm-code-in-text\">async<\/code> method that uses <code class=\"fm-code-in-text\">await<\/code> to a non-async method that uses <code class=\"fm-code-in-text\">ContinueWith,<\/code> we will get the following listing.<\/p>\n<p class=\"fm-code-listing-caption\">Listing 11.2 UI access failure with <code class=\"fm-code-in-text1\">ContinueWith<\/code><\/p>\n<pre class=\"programlisting\">private void button1_Click(object sender, EventArgs ea)\n{\n   var result = DoSomething(textBox1.Text).ContinueWith(t=&gt;  <span class=\"fm-combinumeral\">\u2776<\/span>\n   {\n      label1.Text = t.Result;                                <span class=\"fm-combinumeral\">\u2777<\/span>\n   }\n}<\/pre>\n<p class=\"copyrightbody\"><span class=\"fm-combinumeral\">\u2776<\/span> Changes await to ContinueWith<\/p>\n<p class=\"copyrightbody\"><span class=\"fm-combinumeral\">\u2777<\/span> Exception<\/p>\n<p class=\"copyrightbody\">We just took the part after the <code class=\"fm-code-in-text\">await<\/code> and moved it into a lambda that we passed to <code class=\"fm-code-in-text\">ContinueWith<\/code>, but this doesn\u2019t work. If you run it, you will get an exception because <code class=\"fm-code-in-text\">ContinueWith<\/code> always runs the callback on the thread pool (and not the UI thread). So we need to make the part that sets the label text run in the UI thread explicitly. Both WinForms and WPF provide this feature. In WinForms, this is done with <code class=\"fm-code-in-text\">Control.BeginInvoke<\/code>, and in WPF, with <code class=\"fm-code-in-text\">Dispatcher.BeginInvoke<\/code>.<\/p>\n<p class=\"fm-code-listing-caption\">Listing 11.3 UI access with <code class=\"fm-code-in-text1\">ContinueWith<\/code><\/p>\n<pre class=\"programlisting\">private void button1_Click(object sender, EventArgs ea)\n{\n   var result = DoSomething(textBox1.Text).ContinueWith(t=&gt;\n   {\n      label1.BeginInvoke((Action)(()=&gt;                       <span class=\"fm-combinumeral\">\u2776<\/span>\n      { \n          label1.Text = t.Result));\n      });\n   }\n}<\/pre>\n<p class=\"copyrightbody\"><span class=\"fm-combinumeral\">\u2776<\/span> Switches to UI thread<\/p>\n<p class=\"copyrightbody\">In this listing, we used <code class=\"fm-code-in-text\">ContinueWith<\/code>, like in listing 11.2, but this time, we also used <code class=\"fm-code-in-text\">Control.BeginInvoke<\/code> to ask WinForms to run the code that writes to <code class=\"fm-code-in-text\">label1.Text<\/code> in the UI thread. Now the UI is only accessed from the UI thread, and everything works.<\/p>\n<p class=\"copyrightbody\">Listings 11.1 and 11.3 do exactly the same thing, and you can see from the difference between them that the threading behavior of <code class=\"fm-code-in-text\">await<\/code> saves us quite a bit of complexity and messing with threads.<\/p>\n<h3 class=\"fm-head\" id=\"calibre_link-99\">11.1.2 await in non-UI threads<\/h3>\n<p class=\"copyrightbody\">Now that we have covered the UI case and we\u2019ve seen why returning to the same thread after an <code class=\"fm-code-in-text\">await<\/code> is so important in UI threads, let\u2019s see why <code class=\"fm-code-in-text\">await<\/code> doesn\u2019t return to the same thread when it is used in non-UI threads. To demonstrate this, we\u2019ll write a program that creates a thread and does something asynchronous in that thread.<a id=\"calibre_link-1024\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-1025\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-195\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><\/p>\n<p class=\"fm-code-listing-caption\">Listing 11.4 <code class=\"fm-code-in-text1\">async<\/code> operation is a thread created by the <code class=\"fm-code-in-text1\">Thread<\/code> class<\/p>\n<pre class=\"programlisting\">var thread = new Thread(async ()=&gt;\n   {\n      Console.WriteLine($\"Thread {Thread.CurrentThread.ManagedThreadId}\");\n      await Task.Delay(500);\n      Console.WriteLine($\"Thread {Thread. CurrentThread.ManagedThreadId}\");\n   });\nthread.Start();\nThread.Sleep(1000);<\/pre>\n<p class=\"copyrightbody\">This program creates a thread that asynchronously waits for half a second. It also writes the thread ID to the console both before and after waiting. The main thread starts the thread we created and then waits for a second because the program will terminate when the code in the main thread ends, and we want to keep the program alive until the second thread does its thing.<\/p>\n<p class=\"copyrightbody\">If we run this code, we\u2019ll see that the thread ID before and after the <code class=\"fm-code-in-text\">await<\/code> is different. But why didn\u2019t <code class=\"fm-code-in-text\">await<\/code> get us back to the original thread like with UI threads?<\/p>\n<p class=\"copyrightbody\">If you remember from chapter 3, <code class=\"fm-code-in-text\">await<\/code> sets up the asynchronous operation and then returns, in this case, from the main method of the thread (the method we passed to the <code class=\"fm-code-in-text\">Thread<\/code> constructor). This will make the thread terminate (successfully; for all it knows, the code we ran in the thread finished doing whatever we needed it to do). After waiting for half a second, when it\u2019s time to run the code after the <code class=\"fm-code-in-text\">await<\/code>, the original thread that called <code class=\"fm-code-in-text\">await<\/code> no longer exists.<a id=\"calibre_link-1026\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><\/p>\n<p class=\"copyrightbody\">But what happens if we manage to call <code class=\"fm-code-in-text\">await<\/code> in a way that doesn\u2019t terminate the thread?<\/p>\n<p class=\"fm-code-listing-caption\">Listing 11.5 <code class=\"fm-code-in-text1\">async<\/code> operation without terminating the thread<\/p>\n<pre class=\"programlisting\">var thread = new Thread(()=&gt;\n{\n   DoSomethingAsync();\n   int i=0;\n   while(true) Console.Write(++i);\n});\nthread.IsBackground = true;\nthread.Start();\nThread.Sleep(1000);\n  \nasync Task DoSomethingAsync()\n{\n   Console.WriteLine($\"Thread {Thread.CurrentThread.ManagedThreadId}\");\n   await Task.Delay(500);\n   Console.WriteLine($\"Thread {Thread. CurrentThread.ManagedThreadId}\");\n}<\/pre>\n<p class=\"copyrightbody\">In this listing, we changed the code so the <code class=\"fm-code-in-text\">await<\/code> happens in a method that is called from the thread\u2019s main code. In the thread\u2019s main method, we ignore the <code class=\"fm-code-in-text\">Task<\/code> returned by this method and do not <code class=\"fm-code-in-text\">await<\/code> it. Because we don\u2019t use <code class=\"fm-code-in-text\">await<\/code>, the compiler <code class=\"fm-code-in-text\">await<\/code> support does not kick in, and it does not introduce a <code class=\"fm-code-in-text\">return<\/code>. That way, the thread\u2019s main method doesn\u2019t return, and the thread does not terminate. After calling the async method, the thread starts counting forever just so it has something to do, and we can see it\u2019s working. We also marked this thread as a background thread, so the app will exit after the main thread exits (after one second) and will not keep running forever.<\/p>\n<p class=\"copyrightbody\">If we run this code, we will see that the code before and after the <code class=\"fm-code-in-text\">await<\/code> ran on different threads (as expected). We can also see that the thread we created is busy counting. Even if the system wanted to run the code after the <code class=\"fm-code-in-text\">await<\/code> in the same thread, it has no way of doing so. The thread is running our code, and we didn\u2019t implement any way for the system to ask us to run the code after the <code class=\"fm-code-in-text\">await<\/code> (like WinForms\u2019s <code class=\"fm-code-in-text\">Control.BeginInvoke<\/code> that we used in listing 11.3).<a id=\"calibre_link-1027\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-179\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-1028\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><\/p>\n<h2 class=\"fm-head\" id=\"calibre_link-100\">11.2 Synchronization contexts<\/h2>\n<p class=\"copyrightbody\">The UI thread behavior isn\u2019t magic or some special case in the compiler available just for UI frameworks written by Microsoft. This behavior is implemented using a .NET feature called <code class=\"fm-code-in-text\">Synchronizati<a class=\"pcalibre2 pcalibre pcalibre3 pcalibre1 calibre8\" id=\"calibre_link-1029\"><\/a>onContext<\/code>. <a id=\"calibre_link-1030\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-1031\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-1032\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><\/p>\n<p class=\"copyrightbody\">A <code class=\"fm-code-in-text\">SynchronizationContext<\/code> is a generic way of running code in another thread. Let\u2019s say that you are writing code that spins up a background thread to calculate something and then uses a callback to report the result back to its caller. By default, the callback will run in the background thread you created, which is inconvenient if used in a native UI app because trying to access the UI from that thread will cause an exception.<\/p>\n<p class=\"copyrightbody\">If you know this code will always be used in, for example, a WinForms app, you could use the <code class=\"fm-code-in-text\">Control.BeginInvoke<\/code> method like we did in listing 11.3. However, this has the obvious limitation that it only works in WinForms. For WPF, you\u2019ll need to use <code class=\"fm-code-in-text\">Dispatcher<\/code>, and other frameworks will have other mechanisms.<a id=\"calibre_link-1033\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><\/p>\n<p class=\"copyrightbody\">If you want your code to work in any situation, you can\u2019t use <code class=\"fm-code-in-text\">Control.BeginInvoke<\/code> directly. You could create an abstract class that represents running stuff in another thread and require whoever uses your code to implement it. The class may look like this:<\/p>\n<pre class=\"programlisting\">public abstract class RunInOtherThread\n{\n   public abstract void Run(Action codeToRun);\n}<\/pre>\n<p class=\"copyrightbody\">Anyone writing a WPF app will implement the <code class=\"fm-code-in-text\">Run<\/code> method using <code class=\"fm-code-in-text\">Dispatcher.BeginInvoke<\/code>, anyone writing a WinForms app will implement it using <code class=\"fm-code-in-text\">Control.BeginInvoke<\/code>, and so on for any framework that has threading limitations. That way, you can both run your callbacks in the most convenient thread for your user and not take a dependency on any UI framework. As a bonus, this will also work with future frameworks you don\u2019t even know about.<a id=\"calibre_link-293\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-1034\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><\/p>\n<p class=\"copyrightbody\"><code class=\"fm-code-in-text\">SynchronizationContext<\/code> is the .NET built-in implementation of our <code class=\"fm-code-in-text\">RunInOtherThread<\/code> class. It has two ways of running code in the target thread: <code class=\"fm-code-in-text\">Send<\/code>, which will wait until the other threads finish running our code, and <code class=\"fm-code-in-text\">Post<\/code> which doesn\u2019t wait. <code class=\"fm-code-in-text\">await<\/code> only uses <code class=\"fm-code-in-text\">Post<\/code>.<a id=\"calibre_link-1035\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><\/p>\n<p class=\"copyrightbody\">But we never passed a <code class=\"fm-code-in-text\">SynchronizationContext<\/code> to <code class=\"fm-code-in-text\">await<\/code>, so how does it know how to use the correct one? For this, a <code class=\"fm-code-in-text\">SynchronizationContext<\/code> can be associated with a thread by calling <code class=\"fm-code-in-text\">SynchronizationContext.SetSynchronizationContext<\/code>. After that call, any code running in this thread can read <code class=\"fm-code-in-text\">SynchronizationContext.Current<\/code> to retrieve it. WinForms, WPF, and ASP.NET classic all implement a class derived from <code class=\"fm-code-in-text\">SynchronizationContext<\/code> and associate it with the UI or request handling threads so that any generic code that needs to return to the correct thread (such as <code class=\"fm-code-in-text\">await<\/code>) can use it.<\/p>\n<p class=\"copyrightbody\">Let\u2019s write a <code class=\"fm-code-in-text\">SynchronizationContext<\/code>-derived class that runs the code after the <code class=\"fm-code-in-text\">await<\/code> in the same thread. We\u2019ll use <code class=\"fm-code-in-text\">BlockingCollection<\/code> and the work queue pattern we talked about back in chapter 8.<\/p>\n<p class=\"fm-code-listing-caption\">Listing 11.6 Custom <code class=\"fm-code-in-text1\">SynchronizationContext<\/code> for <code class=\"fm-code-in-text1\">async<\/code>\/<code class=\"fm-code-in-text1\">await<\/code><\/p>\n<pre class=\"programlisting\">using System.Collections.Concurrent;\n \npublic class SingleThreadSyncContext : SynchronizationContext\n{<\/pre>\n<p class=\"copyrightbody\">We begin with a <code class=\"fm-code-in-text\">Run<\/code> method that will start our work queue. Because we want to run everything in the current thread, the <code class=\"fm-code-in-text\">Run<\/code> method will not return until we are finished. The <code class=\"fm-code-in-text\">Run<\/code> method will accept as a parameter a method to run because without it, no one will be able to use our <code class=\"fm-code-in-text\">SynchronizationContext<\/code> (only code that we run after the <code class=\"fm-code-in-text\">SetSynchronizationContext<\/code> call will have access to the <code class=\"fm-code-in-text\">SynchronizationContext<\/code>, so if we need to run code, that will kick off the operation there):<a id=\"calibre_link-1036\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><\/p>\n<pre class=\"programlisting\">   public static void Run(Func&lt;Task&gt; startup)\n   {\n      var prev = SynchronizationContext.Current;\n      try\n      {\n         var ctxt = new SingleThreadSyncContext();\n         SynchronizationContext.SetSynchronizationContext(ctxt); <span class=\"fm-combinumeral\">\u2776<\/span>\n         ctxt.Loop(startup);                                     <span class=\"fm-combinumeral\">\u2777<\/span>\n      }\n      finally\n      {\n         SynchronizationContext.SetSynchronizationContext(prev); <span class=\"fm-combinumeral\">\u2778<\/span>\n      }\n   }<\/pre>\n<p class=\"copyrightbody\"><span class=\"fm-combinumeral\">\u2776<\/span> Associates SynchronizationContext with thread<\/p>\n<p class=\"copyrightbody\"><span class=\"fm-combinumeral\">\u2777<\/span> Runs work queue<\/p>\n<p class=\"copyrightbody\"><span class=\"fm-combinumeral\">\u2778<\/span> Restores original SynchronizationContext<\/p>\n<p class=\"copyrightbody\"><a id=\"calibre_link-285\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a>Now we\u2019ll implement the work queue part. Just like we did in chapter 8, we create a queue of delegates representing the work to be done. Using <code class=\"fm-code-in-text\">foreach<\/code> with <code class=\"fm-code-in-text\">GetConsumingEnumerable<\/code>, we get the next item in the queue or wait if the item isn\u2019t available yet, and then we invoke the delegate we get from the queue:<\/p>\n<pre class=\"programlisting\">   private BlockingCollection&lt;(SendOrPostCallback call,object? state)&gt; \n      _queue = new();\n \n   private void Loop(Func&lt;Task&gt; startup)\n   {\n      startup().ContinueWith(t =&gt; _queue.CompleteAdding());      <span class=\"fm-combinumeral\">\u2776<\/span>\n      foreach(var next in _queue.GetConsumingEnumerable())       <span class=\"fm-combinumeral\">\u2777<\/span>\n      {                                                          <span class=\"fm-combinumeral\">\u2777<\/span>\n         next.call(next.state);                                  <span class=\"fm-combinumeral\">\u2777<\/span>\n      }                                                          <span class=\"fm-combinumeral\">\u2777<\/span>\n   }<\/pre>\n<p class=\"copyrightbody\"><span class=\"fm-combinumeral\">\u2776<\/span> Stops work when the first method completes<\/p>\n<p class=\"copyrightbody\"><span class=\"fm-combinumeral\">\u2777<\/span> Work queue loop<\/p>\n<p class=\"copyrightbody\">The last part is the <code class=\"fm-code-in-text\">Post<\/code> method that will add work to the queue. When an asynchronous operation ends, <code class=\"fm-code-in-text\">await<\/code> will call it to run the code after the <code class=\"fm-code-in-text\">await<\/code> (via a <code class=\"fm-code-in-text\">TaskScheduler<\/code>; we\u2019ll talk about those later in this chapter):<a id=\"calibre_link-1037\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><\/p>\n<pre class=\"programlisting\">   public override void Post(SendOrPostCallback d, object? state)\n   {\n      _queue.Add((d, state));\n   }<\/pre>\n<p class=\"copyrightbody\">What\u2019s left are all the parts of <code class=\"fm-code-in-text\">SynchronizationContext<\/code> that are not used by <code class=\"fm-code-in-text\">await<\/code>. We will just throw <code class=\"fm-code-in-text\">NotImplementedException<\/code> exceptions for all of those:<\/p>\n<pre class=\"programlisting\">   public override void Send(SendOrPostCallback d, object? state)\n   {\n      \/\/ not needed for async\/await\n      throw new NotImplementedException();\n   }\n \n   public override SynchronizationContext CreateCopy()\n   {\n      \/\/ not needed for async\/await\n      throw new NotImplementedException();\n   }\n \n   public override int Wait(IntPtr[] waitHandles, \n      bool waitAll, int millisecondsTimeout)\n   {\n      \/\/ not needed for async\/await\n      throw new NotImplementedException();\n   }\n}<\/pre>\n<p class=\"copyrightbody\">Now we just need to test our custom <code class=\"fm-code-in-text\">SynchronizationContext<\/code>. First, we\u2019ll run a simple <code class=\"fm-code-in-text\">async<\/code> operation without it.<a id=\"calibre_link-1038\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><\/p>\n<p class=\"fm-code-listing-caption\">Listing 11.7 Simple <code class=\"fm-code-in-text1\">async<\/code> operation without <code class=\"fm-code-in-text1\">SingleThreadSyncContext<\/code><\/p>\n<pre class=\"programlisting\">Console.WriteLine($\"before await {Thread.CurrentThread.ManagedThreadId}\");\nawait Task.Delay(500);\nConsole.WriteLine($\"before await {Thread.CurrentThread.ManagedThreadId}\");<\/pre>\n<p class=\"copyrightbody\">This code just prints the current thread ID, uses <code class=\"fm-code-in-text\">await<\/code>, and then prints the current thread ID again. If we run this, we\u2019ll see that the code after the <code class=\"fm-code-in-text\">await<\/code> runs in a different thread than the code before the <code class=\"fm-code-in-text\">await<\/code>, just like we expected.<\/p>\n<p class=\"copyrightbody\">And now let\u2019s run the same code with our <code class=\"fm-code-in-text\">SingleThreadSyncContext<\/code>.<\/p>\n<p class=\"fm-code-listing-caption\">Listing 11.8 Simple <code class=\"fm-code-in-text1\">async<\/code> operation with <code class=\"fm-code-in-text1\">SingleThreadSyncContext<\/code><\/p>\n<pre class=\"programlisting\">SingleThreadSyncContext.Run(async ()=&gt;\n{\n   Console.WriteLine($\"before {Thread.CurrentThread.ManagedThreadId }\");\n   await Task.Delay(500);\n   Console.WriteLine($\"after {Thread.CurrentThread.ManagedThreadId }\");\n});<\/pre>\n<p class=\"copyrightbody\">We took the exact code from listing 11.7 and put it into a lambda passed to <code class=\"fm-code-in-text\">SingleThreadSyncContext.Run<\/code>. When we run this code, we\u2019ll see that the thread ID doesn\u2019t change, and the code before and after the <code class=\"fm-code-in-text\">await<\/code> runs in the same thread (specifically, the thread that called <code class=\"fm-code-in-text\">SingleThreadSyncContext.Run<\/code>).<\/p>\n<p class=\"copyrightbody\">WinForms and WPF both install their own <code class=\"fm-code-in-text\">SynchronizationContext<\/code> in the UI thread, and as we\u2019ve seen in our example, any third-party code can also use its own <code class=\"fm-code-in-text\">SynchronizationContext<\/code> by calling <code class=\"fm-code-in-text\">SetSynchronizationContext<\/code>. But if no one called <code class=\"fm-code-in-text\">SetSynchronizationContext<\/code> in the current thread&mdash;which is almost always the case in non-UI apps (such as console apps and ASP.NET Core apps), as well as in non-UI threads in UI apps&mdash;then <code class=\"fm-code-in-text\">SynchronizationContext.Current<\/code> will be <code class=\"fm-code-in-text\">null<\/code>, and like we\u2019ve seen in listing 11.7, the code after an <code class=\"fm-code-in-text\">await<\/code> will run in the thread pool.<a id=\"calibre_link-1039\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-1040\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-1041\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-180\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><\/p>\n<h2 class=\"fm-head\" id=\"calibre_link-101\">11.3 Breaking away&mdash;ConfigureAwait(false)<\/h2>\n<p class=\"copyrightbody\">We\u2019ve talked about why and how <code class=\"fm-code-in-text\">await<\/code> returns to the same thread in UI apps. Now it\u2019s time to talk about how and why to block this behavior.<a id=\"calibre_link-1042\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-1043\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><\/p>\n<p class=\"copyrightbody\">The <code class=\"fm-code-in-text\">ConfigureAwait(false)<\/code> method allows us to prevent <code class=\"fm-code-in-text\">await<\/code> from using the current <code class=\"fm-code-in-text\">SynchronizationContext<\/code>, as well as the current <code class=\"fm-code-in-text\">TaskScheduler<\/code> (that we\u2019ll discuss later in this chapter). First, I want to debunk the common but wrong explanation of <code class=\"fm-code-in-text\">ConfigureAwait<\/code>(<code class=\"fm-code-in-text\">false<\/code>) that \u201cwithout <code class=\"fm-code-in-text\">ConfigureAwait(false)<\/code>, you continue on the same thread, and with <code class=\"fm-code-in-text\">ConfigureAwait(false)<\/code>, you continue on another thread.\u201d First, let\u2019s debunk the first half of this explanation.<a id=\"calibre_link-1044\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><\/p>\n<p class=\"fm-code-listing-caption\">Listing 11.9 Console app without <code class=\"fm-code-in-text1\">ConfigureAwait(false)<\/code><\/p>\n<pre class=\"programlisting\">Console.WriteLine($\"1: {Thread.CurrentThread.ManagedThreadId}\");\nawait Task.Delay(500);\nConsole.WriteLine($\"2: {Thread.CurrentThread.ManagedThreadId}\");<\/pre>\n<p class=\"copyrightbody\">If you run this program as a console application, you will see that we used <code class=\"fm-code-in-text\">await<\/code> without <code class=\"fm-code-in-text\">ConfigureAwait(false)<\/code> and switched threads. The reason is that while <code class=\"fm-code-in-text\">await<\/code> tries to stay in the same <code class=\"fm-code-in-text\">SynchronizationContext<\/code> (not thread), we do not have one set, and so <code class=\"fm-code-in-text\">await<\/code> continues on the thread pool.<\/p>\n<p class=\"copyrightbody\">Now for the second part: Will <code class=\"fm-code-in-text\">ConfigureAwait(false)<\/code> always switch to a different thread?<\/p>\n<p class=\"fm-code-listing-caption\">Listing 11.10 <code class=\"fm-code-in-text1\">ConfigureAwait(false)<\/code> and completed tasks<\/p>\n<pre class=\"programlisting\">Console.WriteLine($\"1: {Thread.CurrentThread.ManagedThreadId}\");\nawait DoSomething().ConfigureAwait(false);\nConsole.WriteLine($\"2: {Thread.CurrentThread.ManagedThreadId}\");\n \nasync Task DoSomething()\n{\n   Console.WriteLine(\"did something\");\n}<\/pre>\n<p class=\"copyrightbody\"><a id=\"calibre_link-1045\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a>If you run this code, you will see that <code class=\"fm-code-in-text\">ConfigureAwait(false)<\/code> didn\u2019t make us switch threads. The reason for this is that <code class=\"fm-code-in-text\">DoSomething<\/code> always returns a completed task, and using <code class=\"fm-code-in-text\">await<\/code> on a completed task always just continues running on the same thread.<\/p>\n<p class=\"copyrightbody\">Why does <code class=\"fm-code-in-text\">DoSomething<\/code> return a completed task? Like we said in chapter 3, a simplified but mostly correct model (except for synchronization contexts) of how the compiler deals with <code class=\"fm-code-in-text\">async<\/code> methods is that each <code class=\"fm-code-in-text\">await<\/code> is replaced with a call to <code class=\"fm-code-in-text\">Task.ContinueWith<\/code>. Because <code class=\"fm-code-in-text\">DoSomething<\/code> does not use <code class=\"fm-code-in-text\">await<\/code>, the compiler has nothing to replace. The method remains exactly the same as it would if it weren\u2019t <code class=\"fm-code-in-text\">async<\/code>, except that it needs to return a <code class=\"fm-code-in-text\">Task<\/code>, so it translates roughly into<a id=\"calibre_link-1046\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><\/p>\n<pre class=\"programlisting\">Task DoSomething()\n{\n   Console.WriteLine(\"did something\");\n   return Task.CompletedTask;\n}  <\/pre>\n<p class=\"copyrightbody\">Remember, marking a method as <code class=\"fm-code-in-text\">async<\/code> does not make it run in the background&mdash;it only turns on the compiler\u2019s support for <code class=\"fm-code-in-text\">await<\/code>.<\/p>\n<p class=\"copyrightbody\">You might think our <code class=\"fm-code-in-text\">DoSomething<\/code> method is a rare edge case or even a bug, but methods that always return an already completed <code class=\"fm-code-in-text\">Task<\/code> are not uncommon. Many libraries have non-asynchronous methods that return a <code class=\"fm-code-in-text\">Task<\/code>, mostly because the author wants to be able to support asynchronous operations in the future without changing the API or because the operation was asynchronous in a previous version.<\/p>\n<p class=\"copyrightbody\">Now let\u2019s see what <code class=\"fm-code-in-text\">ConfigureAwait(false)<\/code> really does. We\u2019ll start with this WinForms code.<\/p>\n<p class=\"fm-code-listing-caption\">Listing 11.11 WinForms event handler with <code class=\"fm-code-in-text1\">ConfigureAwait<\/code><\/p>\n<pre class=\"programlisting\">private async void Button1_Click(object sender, EventArgs ea)\n{\n   Debug.WriteLine($\" before: {Thread.CurrentThread.ManagedThreadId }\");\n   await Task.Delay(500).ConfigureAwait(false);\n   Debug.WriteLine($\" after: {Thread.CurrentThread.ManagedThreadId }\");\n}<\/pre>\n<p class=\"copyrightbody\"><a id=\"calibre_link-1047\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a>This code uses <code class=\"fm-code-in-text\">await<\/code> with <code class=\"fm-code-in-text\">ConfgureAwait(false)<\/code> to wait for half a second and prints the thread ID both before and after the <code class=\"fm-code-in-text\">await<\/code>. We know that without <code class=\"fm-code-in-text\">ConfigureAwait(false)<\/code>, both should print the same thread ID, but if we run this code, we\u2019ll see two different thread IDs, exactly like we\u2019ve seen in listing 11.9. The difference between listings 11.9 and 11.11 is that listing 11.9 is a console app, and as such, it doesn\u2019t have a <code class=\"fm-code-in-text\">SynchronizationContext<\/code>, while listing 11.11 is a WinForms app, and so it has a <code class=\"fm-code-in-text\">SynchronizationContext<\/code>. So what <code class=\"fm-code-in-text\">ConfigureAwait(false)<\/code> does is simply ignore any <code class=\"fm-code-in-text\">SynchronizationContext<\/code> associated with the current thread.<\/p>\n<p class=\"copyrightbody\">If we summarize everything we\u2019ve talked about so far, the rules for where the code after an <code class=\"fm-code-in-text\">await<\/code> runs are the following:<\/p>\n<ul class=\"calibre9\">\n<li class=\"fm-list-bullet\">\n<p class=\"list\">If the task has already completed, the code continues to run in the same thread. <code class=\"fm-code-in-text\">ConfigureAwait(false)<\/code> has no effect in this case.<\/p>\n<\/li>\n<li class=\"fm-list-bullet\">\n<p class=\"list\">If there is a <code class=\"fm-code-in-text\">SynchronizationContext<\/code> set for the current thread, and <code class=\"fm-code-in-text\">ConfigureAwait(false)<\/code> is not used, the code after the await will use the <code class=\"fm-code-in-text\">SynchronizationContext<\/code> to run.<\/p>\n<\/li>\n<li class=\"fm-list-bullet\">\n<p class=\"list\">In all other cases, the code will run using the thread pool.<\/p>\n<\/li>\n<\/ul>\n<p class=\"copyrightbody\">And now I\u2019m going to write something that might seem controversial to readers who have seen <code class=\"fm-code-in-text\">async<\/code>\/<code class=\"fm-code-in-text\">await<\/code> best practices\u2019 lists (but really isn\u2019t): don\u2019t use <code class=\"fm-code-in-text\">ConfigureAwait(false)<\/code> every time you use <code class=\"fm-code-in-text\">await<\/code>.<\/p>\n<p class=\"copyrightbody\">A lot of best practice lists state you should use <code class=\"fm-code-in-text\">ConfigureAwait(false)<\/code> whenever you use <code class=\"fm-code-in-text\">await<\/code>. They say that because misusing <code class=\"fm-code-in-text\">async<\/code>\/<code class=\"fm-code-in-text\">await<\/code> in UI apps and ASP.NET classic apps (not ASP.NET core) can cause deadlocks, and <code class=\"fm-code-in-text\">ConfigureAwait(false)<\/code> will prevent them. However, this is throwing out the baby with the bathwater. The official guidance from Microsoft agrees with me and says you should always use <code class=\"fm-code-in-text\">ConfigureAwait(false)<\/code> in library code and not application code.<\/p>\n<p class=\"copyrightbody\">Quite a few best practice lists adopted the use \u201calways use <code class=\"fm-code-in-text\">ConfigureAwait(false)<\/code>\u201d part but leave out the \u201cin library code\u201d part because it seems like just putting <code class=\"fm-code-in-text\">ConfigureAwait(false)<\/code>everywhere will prevent deadlocks without making the developer think about it or debug their code, which sounds nice but doesn\u2019t work so well. I will show the problem with this approach and other solutions for this deadlock. But first, let\u2019s see the problem.<\/p>\n<p class=\"fm-code-listing-caption\">Listing 11.12 <code class=\"fm-code-in-text1\">async<\/code>\/<code class=\"fm-code-in-text1\">await<\/code> deadlock<\/p>\n<pre class=\"programlisting\">private void button1_Click(object sender, EventArgs ea)\n{\n   var task = DoSomething();\n   label1.Text = task.Result;\n}\n \nprivate async Task&lt;string&gt; DoSomething()\n{\n   await Task.Delay(500);\n   return \"done\";\n}<\/pre>\n<p class=\"copyrightbody\"><a id=\"calibre_link-297\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a>This code combines asynchronous calls with blocking calls. The first method, <code class=\"fm-code-in-text\">button1_Click<\/code>, calls <code class=\"fm-code-in-text\">DoSomething<\/code> without using <code class=\"fm-code-in-text\">await<\/code>, and then it reads the <code class=\"fm-code-in-text\">Task.Result<\/code> property&mdash;that makes the thread block because <code class=\"fm-code-in-text\">DoSomething<\/code> hasn\u2019t completed yet. Meanwhile, inside <code class=\"fm-code-in-text\">DoSomething<\/code>, <code class=\"fm-code-in-text\">Task.Delay<\/code> completes, and the next line (<code class=\"fm-code-in-text\">return \"done\"<\/code>) is ready to run. As we\u2019ve seen in this chapter, the code after the <code class=\"fm-code-in-text\">await<\/code> will run on the UI thread, but the UI thread is busy waiting in <code class=\"fm-code-in-text\">Task.Result<\/code>.<a id=\"calibre_link-1048\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><\/p>\n<p class=\"copyrightbody\">So what we have here is that the UI thread is busy waiting for <code class=\"fm-code-in-text\">DoSomething<\/code> to complete, but <code class=\"fm-code-in-text\">DoSomething<\/code> can\u2019t complete until the UI thread frees up&mdash;a classic deadlock. If we just add <code class=\"fm-code-in-text\">ConfigureAwait(false)<\/code> to the <code class=\"fm-code-in-text\">await<\/code>, we get the following.<\/p>\n<p class=\"fm-code-listing-caption\">Listing 11.13 Deadlock prevented by using <code class=\"fm-code-in-text1\">ConfigureAwait(false)<\/code><\/p>\n<pre class=\"programlisting\">private void button1_Click(object sender, EventArgs ea)\n{\n   var task = DoSomething();\n   label1.Text = task.Result;\n}\n \nprivate async Task&lt;string&gt; DoSomething()\n{\n   await Task.Delay(500).ConfigureAwait(false);            <span class=\"fm-combinumeral\">\u2776<\/span>\n   return \"done\";\n}<\/pre>\n<p class=\"copyrightbody\"><span class=\"fm-combinumeral\">\u2776<\/span> Added ConfigureAwait<\/p>\n<p class=\"copyrightbody\">Now, in <code class=\"fm-code-in-text\">button1_Click<\/code>, the UI thread blocks waiting for <code class=\"fm-code-in-text\">DoSomething<\/code> to complete just like in listing 11.12. But this time, after <code class=\"fm-code-in-text\">Task.Delay<\/code> completes, <code class=\"fm-code-in-text\">DoSomething<\/code> continues to run on the thread pool and not the UI thread. This means <code class=\"fm-code-in-text\">DoSomething<\/code> will complete in the background, <code class=\"fm-code-in-text\">Task.Result<\/code> will stop blocking and return the result, and everything will just work.<\/p>\n<p class=\"copyrightbody\">So if just dropping <code class=\"fm-code-in-text\">ConfigureAwait(false)<\/code> mechanically everywhere prevents deadlocks, why am I so against it? First, in this case, there\u2019s an easier fix: if we don\u2019t mix asynchronous and blocking operations and just stick to using <code class=\"fm-code-in-text\">await<\/code>, we don\u2019t have that problem.<\/p>\n<p class=\"fm-code-listing-caption\">Listing 11.14 Deadlock prevented by using <code class=\"fm-code-in-text1\">await<\/code><\/p>\n<pre class=\"programlisting\">private async void button1_Click(object sender, EventArgs ea)\n{\n   var result = await DoSomething();                      <span class=\"fm-combinumeral\">\u2776<\/span>\n   label1.Text = result;\n}\n \nprivate async Task&lt;string&gt; DoSomething()\n{\n   await Task.Delay(500);\n   return \"done\";\n}<\/pre>\n<p class=\"copyrightbody\"><span class=\"fm-combinumeral\">\u2776<\/span> Changed to await<\/p>\n<p class=\"copyrightbody\"><a id=\"calibre_link-256\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a>We solved this problem by using <code class=\"fm-code-in-text\">await<\/code> instead of reading <code class=\"fm-code-in-text\">Task.Result<\/code>. Now <code class=\"fm-code-in-text\">button1_Click<\/code> does not block the thread until <code class=\"fm-code-in-text\">DoSomething<\/code> completes, and we have no deadlock. Note that using <code class=\"fm-code-in-text\">await<\/code> isn\u2019t always possible, and we did change the way the program operates in case there\u2019s an exception in <code class=\"fm-code-in-text\">DoSomething<\/code>. We\u2019ll cover those problems in a bit, but first, let\u2019s see what happens if we introduce <code class=\"fm-code-in-text\">ConfigureAwait<\/code> to this version of the code.<\/p>\n<p class=\"fm-code-listing-caption\">Listing 11.15 WinForms code with <code class=\"fm-code-in-text1\">ConfigureAwait(false)<\/code> everywhere<\/p>\n<pre class=\"programlisting\">private async void button1_Click(object sender, EventArgs ea)\n{\n   var result = await DoSomething().ConfigureAwait(false);   <span class=\"fm-combinumeral\">\u2776<\/span>\n   label1.Text = result;                                     <span class=\"fm-combinumeral\">\u2777<\/span>\n}\n \nprivate async Task&lt;string&gt; DoSomething()\n{\n   await Task.Delay(500).ConfigureAwait(false);\n   return \"done\";\n}<\/pre>\n<p class=\"copyrightbody\"><span class=\"fm-combinumeral\">\u2776<\/span> Adds ConfigureAwait<\/p>\n<p class=\"copyrightbody\"><span class=\"fm-combinumeral\">\u2777<\/span> Exception<\/p>\n<p class=\"copyrightbody\">In this listing, we added <code class=\"fm-code-in-text\">ConfigureAwait(false)<\/code> to the first <code class=\"fm-code-in-text\">await<\/code>. This means the code after the <code class=\"fm-code-in-text\">await<\/code> will run in the thread pool instead of taking up the UI thread, but this code modifies the UI (now from the wrong thread), and we get an <code class=\"fm-code-in-text\">InvalidOperationException<\/code> exception.<a id=\"calibre_link-1049\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><\/p>\n<p class=\"copyrightbody\">To make this code work with <code class=\"fm-code-in-text\">ConfigureAwait(false)<\/code>, we need to use <code class=\"fm-code-in-text\">Control.BeginInvoke<\/code>, like we did in listing 11.3 where we didn\u2019t use <code class=\"fm-code-in-text\">await<\/code> at all.<\/p>\n<p class=\"fm-code-listing-caption\">Listing 11.16 WinForms code that works with <code class=\"fm-code-in-text1\">ConfigureAwait(false)<\/code> everywhere<\/p>\n<pre class=\"programlisting\">private async void button1_Click(object sender, EventArgs ea)\n{\n   var result = await DoSomething().ConfigureAwait(false);   <span class=\"fm-combinumeral\">\u2776<\/span>\n   label1.BeginInvoke((Action)(()=&gt;                          <span class=\"fm-combinumeral\">\u2777<\/span>\n      {\n          label1.Text = result));\n      });\n \n}\n \nprivate async Task&lt;string&gt; DoSomething()\n{\n   await Task.Delay(500).ConfigureAwait(false);\n   return \"done\";\n}<\/pre>\n<p class=\"copyrightbody\"><span class=\"fm-combinumeral\">\u2776<\/span> ConfigureAwait<\/p>\n<p class=\"copyrightbody\"><span class=\"fm-combinumeral\">\u2777<\/span> Sets label text on UI thread<\/p>\n<p class=\"copyrightbody\"><a id=\"calibre_link-1050\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a>In this listing, because the code after the <code class=\"fm-code-in-text\">await<\/code> no longer runs in the UI thread (due to our usage of <code class=\"fm-code-in-text\">ConfigureAwait(false)<\/code>), we had to use other means to run the code that updates the UI on the UI thread, and this looks very much like code that doesn\u2019t use <code class=\"fm-code-in-text\">await<\/code> at all, which shows us that <code class=\"fm-code-in-text\">ConfigureAwait(false)<\/code> outright negates the benefits of <code class=\"fm-code-in-text\">await<\/code>.<\/p>\n<p class=\"copyrightbody\">But <code class=\"fm-code-in-text\">ConfigureAwait<\/code> isn\u2019t totally evil. If we only use <code class=\"fm-code-in-text\">ConfigureAwait(false)<\/code> on the <code class=\"fm-code-in-text\">await<\/code> inside <code class=\"fm-code-in-text\">DoSomething<\/code>, everything still works.<\/p>\n<p class=\"fm-code-listing-caption\">Listing 11.17 WinForms code with <code class=\"fm-code-in-text1\">ConfigureAwait(false)<\/code> only in non-UI methods<\/p>\n<pre class=\"programlisting\">private async void button1_Click(object sender, EventArgs ea)\n{\n   var result = await DoSomething();                        <span class=\"fm-combinumeral\">\u2776<\/span>\n   label1.Text = result;                                    <span class=\"fm-combinumeral\">\u2777<\/span>\n}\n \nprivate async Task&lt;string&gt; DoSomething()\n{\n   await Task.Delay(500).ConfigureAwait(false);\n   return \"done\";\n}<\/pre>\n<p class=\"copyrightbody\"><span class=\"fm-combinumeral\">\u2776<\/span> No ConfigureAwait&mdash;return to UI context<\/p>\n<p class=\"copyrightbody\"><span class=\"fm-combinumeral\">\u2777<\/span> No exception<\/p>\n<p class=\"copyrightbody\">Here, inside <code class=\"fm-code-in-text\">DoSomething<\/code>, we break out of the UI context, and the return line will run on the thread pool. But the <code class=\"fm-code-in-text\">await<\/code> in <code class=\"fm-code-in-text\">button1_Click<\/code> (that does not use <code class=\"fm-code-in-text\">ConfigureAwait(false)<\/code>) will return us to the UI thread, and the line that modifies the label will work.<\/p>\n<p class=\"copyrightbody\">Also note that the <code class=\"fm-code-in-text\">DoSomething<\/code> method in this listing is exactly the same as the one in listing 11.12, so <code class=\"fm-code-in-text\">ConfigureAwait(false)<\/code> can be beneficial if you don\u2019t know if your caller is asynchronous, like in listing 11.16, or blocking, like in listing 11.13, as would commonly happen if you were writing a library. Note that <code class=\"fm-code-in-text\">ConfigureAwait(false)<\/code> works here because <code class=\"fm-code-in-text\">DoSomething<\/code> doesn\u2019t access the UI itself and thus doesn\u2019t care in what context the code after the <code class=\"fm-code-in-text\">await<\/code> runs.<\/p>\n<p class=\"copyrightbody\">Remember that even in libraries, you often do care about the context (and thread) in which your code runs. An obvious example is a library designed to be used specifically in a UI application. A less obvious example is a library that uses callbacks to call the application that uses it. Even if the library doesn\u2019t care in which thread it runs, the code inside the application\u2019s callback might.<\/p>\n<p class=\"copyrightbody\">Before we wrap up our discussion of <code class=\"fm-code-in-text\">ConfigureAwait(false)<\/code>, I\u2019ll mention how we can solve our deadlock without using <code class=\"fm-code-in-text\">ConfigureAwait<\/code>. This deadlock, in its general form&mdash;UI waiting for something that is waiting for UI&mdash;has existed ever since we started making UI applications; it predates <code class=\"fm-code-in-text\">async<\/code>\/<code class=\"fm-code-in-text\">await<\/code>, it predates .NET and C#, it even predates asynchronous IO in the Windows operating system. And so, unsurprisingly, there is a standard solution for this problem already built into WinForms (and WPF and all other UI frameworks I know about). This solution is to let the UI handle events (or <i class=\"fm-italics\">pump messages<\/i>, in Windows API terminology) while we are waiting for the background task to complete. In WinForms, we do this by calling the <code class=\"fm-code-in-text\">Application.DoEvents<\/code> method.<a id=\"calibre_link-148\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-1051\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><\/p>\n<p class=\"fm-code-listing-caption\">Listing 11.18 Prevent the deadlock with <code class=\"fm-code-in-text1\">DoEvents<\/code><\/p>\n<pre class=\"programlisting\">private void button1_Click(object sender, EventArgs ea)\n{\n   var task = DoSomething();\n   while(!task.IsCompleted)                                  <span class=\"fm-combinumeral\">\u2776<\/span>\n     Application.DoEvents();                                 <span class=\"fm-combinumeral\">\u2776<\/span>\n   label1.Text = task.Result;\n}\n \nprivate async Task&lt;string&gt; DoSomething()\n{\n   await Task.Delay(500)\n   return \"done\";\n}<\/pre>\n<p class=\"copyrightbody\"><span class=\"fm-combinumeral\">\u2776<\/span> Processes events while waiting<\/p>\n<p class=\"copyrightbody\">This works exactly like we expected our original code in listing 11.11 would work. It doesn\u2019t deadlock, the <code class=\"fm-code-in-text\">button1_Click<\/code> method isn\u2019t asynchronous, and as an added benefit, the UI doesn\u2019t freeze until <code class=\"fm-code-in-text\">DoSomething<\/code> completes.<a id=\"calibre_link-1052\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><\/p>\n<div class=\"fm-sidebar-block\">\n<p class=\"fm-sidebar-title\">A note about DoEvents<\/p>\n<p class=\"copyrightbody\">Note that the <code class=\"fm-code-in-text\">DoEvents<\/code> loop will take 100% CPU (of one core) while waiting. It does not affect your app (specifically your app\u2019s UI thread) because this loop will run any UI events as soon as possible, but it does take resources that could be used by another app and prevent the CPU core from switching to idle power saving mode. As such, it is not recommended to use <code class=\"fm-code-in-text\">DoEvents<\/code>; yet, it is better than having a deadlock. It\u2019s mostly okay to use a <code class=\"fm-code-in-text\">DoEvents<\/code> here because we know we are only waiting for half a second, and the effect on the system will be minimal, but we need to consider this every time we write <code class=\"fm-code-in-text\">DoEvents<\/code> loops.<a id=\"calibre_link-1053\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><\/p>\n<\/p><\/div>\n<p class=\"copyrightbody\">To summarize, my suggested rules for using <code class=\"fm-code-in-text\">ConfigureAwait(false)<\/code> are<\/p>\n<ul class=\"calibre9\">\n<li class=\"fm-list-bullet\">\n<p class=\"list\">If you are writing application code, avoid using <code class=\"fm-code-in-text\">ConfigureAwait(false)<\/code>; the default behavior is there for a reason.<\/p>\n<\/li>\n<li class=\"fm-list-bullet\">\n<p class=\"list\">If your code is only designed to run in environments that don\u2019t use <code class=\"fm-code-in-text\">SynchronizationContext<\/code> (for example, Console apps and ASP.NET core), don\u2019t use <code class=\"fm-code-in-text\">ConfigureAwait(false)<\/code>.<\/p>\n<\/li>\n<li class=\"fm-list-bullet\">\n<p class=\"list\">If you are writing library code, and you don\u2019t care in which context your code runs, use <code class=\"fm-code-in-text\">ConfigureAwait(false)<\/code> on every <code class=\"fm-code-in-text\">await<\/code>.<\/p>\n<\/li>\n<li class=\"fm-list-bullet\">\n<p class=\"list\">If you want to leave the current context, use <code class=\"fm-code-in-text\">Task.Run<\/code> and not <code class=\"fm-code-in-text\">ConfigureAwait(false)<\/code>, because <code class=\"fm-code-in-text\">ConfigureAwait(false)<\/code> does nothing if the <code class=\"fm-code-in-text\">Task<\/code> is already completed.<\/p>\n<\/li>\n<\/ul>\n<p class=\"copyrightbody\">There are some unit-testing frameworks that will not work unless you always use <code class=\"fm-code-in-text\">ConfigureAwait(false)<\/code>. I personally think this is a bug in the unit-testing framework, and I will let you decide if it\u2019s better to change the threading behavior of the app to compensate for a technical bug in your unit-test framework or to use a different unit&ndash;test framework.<\/p>\n<p class=\"copyrightbody\">After all this talk about <code class=\"fm-code-in-text\">ConfigureAwait(false)<\/code>, you may be curious about <code class=\"fm-code-in-text\">ConfigureAwait(true)<\/code>. <code class=\"fm-code-in-text\">ConfigureAwait(true)<\/code> is the default behavior and has no effect on your code whatsoever (except for silencing static code analyzers that complain about not using <code class=\"fm-code-in-text\">ConfigureAwait(false)<\/code>).<a id=\"calibre_link-1054\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-182\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-1055\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><\/p>\n<h2 class=\"fm-head\" id=\"calibre_link-102\">11.4 More ConfigureAwait options<\/h2>\n<p class=\"copyrightbody\">.NET 8 added a new version of <code class=\"fm-code-in-text\">ConfigureAwait<\/code> with new and exciting options that further complicate things. Those options are implemented as an overload of <code class=\"fm-code-in-text\">ConfigureAwait<\/code> that accepts a <code class=\"fm-code-in-text\">ConfigureAwaitOptions<\/code> parameter. Unfortunately, while useful in specialized cases, all those options have hidden complexities, and I recommend not using them in normal application code.<a id=\"calibre_link-1056\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-1057\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><\/p>\n<p class=\"copyrightbody\">Just in case you encounter them in code you have to debug, these are the options, each with its biggest pitfall identified:<\/p>\n<ul class=\"calibre9\">\n<li class=\"fm-list-bullet\">\n<p class=\"list\"><code class=\"fm-code-in-text\">None<\/code>&mdash;Calling <code class=\"fm-code-in-text\">ConfigureAwait(ConfigureAwaitOptions.None)<\/code> is equivalent to <code class=\"fm-code-in-text\">ConfigureAwait(false)<\/code>, that is, it changes the behavior of <code class=\"fm-code-in-text\">await<\/code> and makes it run continuations on the thread pool. I recommend using the old <code class=\"fm-code-in-text\">Configure<\/code><code class=\"fm-code-in-text\">Await(false)<\/code> and not the new <code class=\"fm-code-in-text\">ConfigureAwait(ConfigureAwaitOptions.None)<\/code>. The new version is somehow even worse at actually saying what it does (considering the meaning of \u201cnone\u201d in the English language, I would expect <code class=\"fm-code-in-text\">None<\/code> to do nothing, but it changes the behavior), and the old one is at least more concise.<\/p>\n<\/li>\n<li class=\"fm-list-bullet\">\n<p class=\"list\"><code class=\"fm-code-in-text\">ContinueOnCapturedContext<\/code>&mdash;This value keeps the default <code class=\"fm-code-in-text\">await<\/code> behavior; using it by itself does nothing. It is required because the <code class=\"fm-code-in-text\">ConfigureAwaitOptions<\/code> options are flags, which means this can be combined together, and with <code class=\"fm-code-in-text\">None<\/code> being the default. All the other options also include the <code class=\"fm-code-in-text\">ConfigureAwait(false)<\/code> behavior unless you combine them with<a id=\"calibre_link-1058\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a> the <code class=\"fm-code-in-text\">ContinueOnCapturedContext<\/code> option.<\/p>\n<\/li>\n<li class=\"fm-list-bullet\">\n<p class=\"list\"><code class=\"fm-code-in-text\">ForceYielding<\/code>&mdash;This option makes <code class=\"fm-code-in-text\">await<\/code> always return and schedule the continuation to run later, even if it doesn\u2019t have to because the <code class=\"fm-code-in-text\">Task<\/code> has already completed. This does not make the code you are calling run in the background&mdash;it just switches to the thread pool after the <code class=\"fm-code-in-text\">await<\/code>. Using this option is equivalent to writing <code class=\"fm-code-in-text\">await Task.Yield().ConfigureAwait(false);<\/code> in the next line.<\/p>\n<\/li>\n<li class=\"fm-list-bullet\">\n<p class=\"list\"><code class=\"fm-code-in-text\">SuppressThrowing<\/code>&mdash;This option makes <code class=\"fm-code-in-text\">await<\/code> ignore <i class=\"fm-italics\">some<\/i> errors. It is meant for situations where you don\u2019t care if the operation you run succeeds or fails. However, it will only ignore errors that occur after the first <code class=\"fm-code-in-text\">await<\/code> inside the method you are calling, so it doesn\u2019t guarantee that no exception will be thrown. Also, it will throw an exception at run time if you try to use it with a <code class=\"fm-code-in-text\">Task&lt;T&gt;.<\/code><\/p>\n<\/li>\n<\/ul>\n<p class=\"copyrightbody\">In conclusion, out of the four new options, <code class=\"fm-code-in-text\">None<\/code> and <code class=\"fm-code-in-text\">ContinueOnCapturedContext<\/code> are already more concisely supported with the old <code class=\"fm-code-in-text\">ConfigureAwait<\/code>. <code class=\"fm-code-in-text\">ForceYielding<\/code> is not very useful, and <code class=\"fm-code-in-text\">SuppressThrowing<\/code> doesn\u2019t do what its name implies. Also, just to add another pitfall, the new <code class=\"fm-code-in-text\">ConfigureAwait<\/code> is not supported on <code class=\"fm-code-in-text\">ValueTask<\/code> and <code class=\"fm-code-in-text\">ValueTask&lt;T&gt;<\/code>, so I recommend sticking with the older <a id=\"calibre_link-167\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><code class=\"fm-code-in-text\">ConfigureAwait(bool).<\/code><\/p>\n<h2 class=\"fm-head\" id=\"calibre_link-103\">11.5 Letting other code run: Task.Yield<\/h2>\n<p class=\"copyrightbody\">Internally, both events generated by Windows (mouse moves, keyboard clicks, and so forth) and work queued by <code class=\"fm-code-in-text\">Control.BeginInvoke<\/code> and the <code class=\"fm-code-in-text\">SynchronizationContext<\/code> are stored in a queue called the input queue (because its primary function is to deliver input from the UI to the app).<a id=\"calibre_link-1059\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-1060\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><\/p>\n<p class=\"copyrightbody\">We\u2019ve seen in listing 11.18 that in WinForms, we can use <code class=\"fm-code-in-text\">Application.DoEvents<\/code> to let the framework handle events and remain responsive. <code class=\"fm-code-in-text\">DoEvents<\/code> simply reads all pending entries in the input queue, returning only when all the events are handled.<\/p>\n<p class=\"copyrightbody\">The generic <code class=\"fm-code-in-text\">async<\/code>\/<code class=\"fm-code-in-text\">await<\/code> compatible version of <code class=\"fm-code-in-text\">DoEvents<\/code> is <code class=\"fm-code-in-text\">Task.Yield<\/code>. When you await <code class=\"fm-code-in-text\">Task.Yield()<\/code> in a UI thread, the code after the <code class=\"fm-code-in-text\">await<\/code> is added to the end of the input queue and runs after all the other events that are already pending. The following listing shows what happens if we build a WinForms app that counts forever.<\/p>\n<p class=\"fm-code-listing-caption\">Listing 11.19 Trying to count forever and freezing the app<\/p>\n<pre class=\"programlisting\">private void button1_Click(object sender, EventArgs ea)\n{\n   int i=0;\n   while(true)\n   {\n      label1.Text = (++i).ToString();\n   }\n}<\/pre>\n<p class=\"copyrightbody\">With this method, when the user clicks a button, the program will loop forever, counting and setting the number into a label\u2019s <code class=\"fm-code-in-text\">Text<\/code> property. If you run this code, the program will just freeze. The UI thread will be busy counting and will not handle input queue events such as mouse clicks. Also, you will not see the content of the label change because the UI thread will not handle requests to redraw the label. We can use the same strategy that worked so well in listing 11.18 and fix this with <code class=\"fm-code-in-text\">DoEvents.<\/code><code class=\"fm-code-in-text\"><a class=\"pcalibre2 pcalibre pcalibre3 pcalibre1 calibre8\" id=\"calibre_link-1061\"><\/a><\/code><\/p>\n<p class=\"fm-code-listing-caption\">Listing 11.20 Counting forever without freezing the app<\/p>\n<pre class=\"programlisting\">private void button1_Click(object sender, EventArgs ea)\n{\n   int i=0;\n   while(true)\n   {\n      label1.Text = (++i).ToString();\n      Application.DoEvents();\n   }\n}<\/pre>\n<p class=\"copyrightbody\">Now at every iteration, the method calls <code class=\"fm-code-in-text\">DoEvents<\/code>. This will handle all the pending events (including the label\u2019s redraw events). The app will remain responsive, and the label with show the changing number. Note that our code will use 100% of a CPU core doing the counting, so unlike listing 11.18, it is not negatively affecting the system by calling <code class=\"fm-code-in-text\">DoEvents<\/code>. We could also go the <code class=\"fm-code-in-text\">async<\/code>\/<code class=\"fm-code-in-text\">await<\/code> route and do this with <code class=\"fm-code-in-text\">Task.Yield.<\/code><\/p>\n<p class=\"fm-code-listing-caption\">Listing 11.21 Counting forever without freezing the app using <code class=\"fm-code-in-text1\">await<\/code><\/p>\n<pre class=\"programlisting\">private async void button1_Click(object sender, EventArgs ea)\n{\n   int i=0;\n   while(true)\n   {\n      label1.Text = (++i).ToString();\n      await Task.Yield();\n   }\n}<\/pre>\n<p class=\"copyrightbody\">In this version, at the end of every iteration, the method will queue itself at the end of the input queue and return. It is a very different technique than <code class=\"fm-code-in-text\">DoEvents<\/code>, but with exactly the same results.<\/p>\n<p class=\"copyrightbody\"><a id=\"calibre_link-166\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a>When deciding where to run the code after it, <code class=\"fm-code-in-text\">await<\/code> <code class=\"fm-code-in-text\">Task.Yield()<\/code> follows the same rules listed in this chapter, so you can use them to figure out in which thread the code will run in your specific situation.<\/p>\n<h2 class=\"fm-head\" id=\"calibre_link-104\">11.6 Task schedulers<\/h2>\n<p class=\"copyrightbody\">In this chapter, I repeatedly wrote that <code class=\"fm-code-in-text\">await<\/code> uses <code class=\"fm-code-in-text\">SynchronizationContext<\/code>. Well, I left something out: <code class=\"fm-code-in-text\">async<\/code>\/<code class=\"fm-code-in-text\">await<\/code> has its own infrastructure for deciding on which thread to run code. This infrastructure is based on the <code class=\"fm-code-in-text\">TaskScheduler<\/code> class. Classes derived from <code class=\"fm-code-in-text\">TaskScheduler<\/code>, like classes derived from <code class=\"fm-code-in-text\">SyncronizationContext<\/code>, know how to take a task created by <code class=\"fm-code-in-text\">await<\/code> and schedule it to run on some thread sometime in the future.<a id=\"calibre_link-1062\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-1063\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-1064\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-1065\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-1066\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><\/p>\n<p class=\"copyrightbody\">The default task scheduler (accessible via the <code class=\"fm-code-in-text\">TaskScheduler.Default<\/code> static property) always queues your code to run on the thread pool. If you call <code class=\"fm-code-in-text\">await<\/code> in a thread with a <code class=\"fm-code-in-text\">SynchronizationContext<\/code>, the compiler will create a scheduler that will use its <code class=\"fm-code-in-text\">Post<\/code> method to schedule the code (the <code class=\"fm-code-in-text\">TaskScheduler.FromCurrentSynchronizationContext<\/code> does this). You can get the current scheduler by reading <code class=\"fm-code-in-text\">TaskScheduler.Current<\/code>.<a id=\"calibre_link-1067\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-1068\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><\/p>\n<p class=\"copyrightbody\">Unlike <code class=\"fm-code-in-text\">SynchronizationContext<\/code>, you can\u2019t set the current <code class=\"fm-code-in-text\">TaskSchuduler<\/code>, but you can set the task scheduler when you call <code class=\"fm-code-in-text\">Task.Run<\/code>, <code class=\"fm-code-in-text\">ContinueWith<\/code>, or any of the other <code class=\"fm-code-in-text\">async<\/code>\/<code class=\"fm-code-in-text\">await<\/code> compatible ways to run code. For example, this code will run a lambda half a second later on the thread pool:<\/p>\n<pre class=\"programlisting\">Task.Delay(500).ContinueWith(t=&gt;Console.WriteLine(\"Hello\"));<\/pre>\n<p class=\"copyrightbody\"><a id=\"calibre_link-286\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a>This code uses <code class=\"fm-code-in-text\">ContinueWith<\/code> to run after the timeout is passed to <code class=\"fm-code-in-text\">Task.Delay<\/code>. Because we didn\u2019t pass the optional <code class=\"fm-code-in-text\">TaskScheduler<\/code> parameter, this will use the default scheduler that will run the code on the thread pool. However, if we are running in a thread with <code class=\"fm-code-in-text\">SynchronizationContext<\/code>, we can create a task scheduler that uses it:<\/p>\n<pre class=\"programlisting\">Task.Delay(500).ContinueWith(t=&gt;Console.WriteLine(\"Hello\"),\n   TaskScheduler.FromCurrentSynchronizationContext());<\/pre>\n<p class=\"copyrightbody\">Here we passed the optional <code class=\"fm-code-in-text\">TaskScheduler<\/code> parameter. Specifically, we passed a scheduler created from the current <code class=\"fm-code-in-text\">SynchronizationContext<\/code>, so the lambda will run on this thread. If there\u2019s no current <code class=\"fm-code-in-text\">SynchronizationContext<\/code>, or the <code class=\"fm-code-in-text\">SynchronizationContext<\/code> can\u2019t be wrapped in a <code class=\"fm-code-in-text\">TaskScheduler<\/code>, <code class=\"fm-code-in-text\">FromCurrentSynchronizationContext<\/code> will throw an exception. In the current version of .NET at the time of this writing (version 8), this only happens if there is no current <code class=\"fm-code-in-text\">SynchronizationContext<\/code> (that is, <code class=\"fm-code-in-text\">SynchronizationContext.Current<\/code> is <code class=\"fm-code-in-text\">null<\/code>).<\/p>\n<p class=\"copyrightbody\">Just like with <code class=\"fm-code-in-text\">SyncronizationContext<\/code>, <code class=\"fm-code-in-text\">ConfigureAwait(false)<\/code> will make await ignore the current <code class=\"fm-code-in-text\">TaskScheduler<\/code> and use the default scheduler instead.<\/p>\n<p class=\"copyrightbody\">This completes the rules for which thread runs the code after an <code class=\"fm-code-in-text\">await<\/code>, in this order:<\/p>\n<ul class=\"calibre9\">\n<li class=\"fm-list-bullet\">\n<p class=\"list\">If the task is already complete, the code continues to run immediately in the same thread. <code class=\"fm-code-in-text\">ConfigureAwait(false)<\/code> has no effect in this case.<\/p>\n<\/li>\n<li class=\"fm-list-bullet\">\n<p class=\"list\">If the current thread has a <code class=\"fm-code-in-text\">SynchronizationContext<\/code> set, and <code class=\"fm-code-in-text\">ConfigureAwait(false)<\/code> is not used, the <code class=\"fm-code-in-text\">SynchronizationContext<\/code> will be used.<\/p>\n<\/li>\n<li class=\"fm-list-bullet\">\n<p class=\"list\">If the current task has a <code class=\"fm-code-in-text\">TaskScheduler<\/code> associated with it, and <code class=\"fm-code-in-text\">ConfigureAwait(false)<\/code> is not used, the <code class=\"fm-code-in-text\">TaskScheduler<\/code> will be used.<\/p>\n<\/li>\n<li class=\"fm-list-bullet\">\n<p class=\"list\">If <code class=\"fm-code-in-text\">ConfigureAwait(false)<\/code> was called, or if the thread has no <code class=\"fm-code-in-text\">SynchronizationContext<\/code> and no <code class=\"fm-code-in-text\">TaskScheduler<\/code>, the default task scheduler will be used, and the code will run in the thread pool.<\/p>\n<\/li>\n<\/ul>\n<h2 class=\"fm-head\" id=\"calibre_link-1069\">Summary<\/h2>\n<ul class=\"calibre9\">\n<li class=\"fm-list-bullet\">\n<p class=\"list\">The simplified rules regarding which thread runs the code after an <code class=\"fm-code-in-text\">await<\/code> are as follows:<\/p>\n<ul class=\"calibre19\">\n<li class=\"fm-list-bullet\">\n<p class=\"list\">In UI apps (WinForms and WPF), if you are using <code class=\"fm-code-in-text\">await<\/code> in a UI thread, and you don\u2019t use <code class=\"fm-code-in-text\">ConfigureAwait(false)<\/code>, the code after the <code class=\"fm-code-in-text\">await<\/code> will run in the same thread.<\/p>\n<\/li>\n<li class=\"fm-list-bullet\">\n<p class=\"list\">In ASP.NET classic (not ASP.NET Core), if you are using <code class=\"fm-code-in-text\">await<\/code> in a thread that is processing a web request, and you don\u2019t use <code class=\"fm-code-in-text\">ConfigureAwait(false)<\/code>, the code after the <code class=\"fm-code-in-text\">await<\/code> will run in the same thread.<\/p>\n<\/li>\n<li class=\"fm-list-bullet\">\n<p class=\"list\">In all other cases, the code after the <code class=\"fm-code-in-text\">await<\/code> will run in the thread pool.<\/p>\n<\/li>\n<\/ul>\n<\/li>\n<li class=\"fm-list-bullet\">\n<p class=\"list\">However, the real rules are<\/p>\n<ul class=\"calibre19\">\n<li class=\"fm-list-bullet\">\n<p class=\"list\">If the task is already complete, and <code class=\"fm-code-in-text\">ConfigureAwait(ConfigureAwaitOptions.ForceYielding)<\/code> was not used, the code continues to run immediately in the same thread, <code class=\"fm-code-in-text\">ConfigureAwait(false)<\/code> has no effect in this case.<\/p>\n<\/li>\n<li class=\"fm-list-bullet\">\n<p class=\"list\">If the current thread has a <code class=\"fm-code-in-text\">SynchronizationContext<\/code> set, and <code class=\"fm-code-in-text\">ConfigureAwait(false)<\/code> is not used, the <code class=\"fm-code-in-text\">SynchronizationContext<\/code> will be used.<\/p>\n<\/li>\n<li class=\"fm-list-bullet\">\n<p class=\"list\">If the current task has a <code class=\"fm-code-in-text\">TaskScheduler<\/code> associated with it, and <code class=\"fm-code-in-text\">ConfigureAwait(false)<\/code> is not used, the <code class=\"fm-code-in-text\">TaskScheduler<\/code> will be used.<\/p>\n<\/li>\n<li class=\"fm-list-bullet\">\n<p class=\"list\">If <code class=\"fm-code-in-text\">ConfigureAwait(false)<\/code> was called, or the thread has no <code class=\"fm-code-in-text\">SynchronizationContext<\/code> and no <code class=\"fm-code-in-text\">TaskScheduler<\/code>, the default task scheduler will be used, and the code will run in the thread pool.<\/p>\n<\/li>\n<\/ul>\n<\/li>\n<li class=\"fm-list-bullet\">\n<p class=\"list\">If you are not using third-party frameworks or writing your own <code class=\"fm-code-in-text\">SynchronizationContext<\/code> or <code class=\"fm-code-in-text\">TaskScheduler<\/code>, those two sets of rules produce the same results.<\/p>\n<\/li>\n<li class=\"fm-list-bullet\">\n<p class=\"list\"><code class=\"fm-code-in-text\">ConfigureAwait(false)<\/code> makes <code class=\"fm-code-in-text\">await<\/code> ignore the current <code class=\"fm-code-in-text\">SynchronizationContext<\/code> or <code class=\"fm-code-in-text\">TaskScheduler.<\/code> This may prevent deadlocks but can make using<a id=\"calibre_link-1070\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-1071\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a> <code class=\"fm-code-in-text\">await<\/code> much less convenient.<\/p>\n<\/li>\n<li class=\"fm-list-bullet\">\n<p class=\"list\">The rules for using <code class=\"fm-code-in-text\">ConfigureAwait(false)<\/code> are as follows:<\/p>\n<ul class=\"calibre19\">\n<li class=\"fm-list-bullet\">\n<p class=\"list\">If you are writing application code, avoid using <code class=\"fm-code-in-text\">ConfigureAwait(false)<\/code>. The default behavior is there for a reason.<\/p>\n<\/li>\n<li class=\"fm-list-bullet\">\n<p class=\"list\">If your code needs to continue running on the same thread, for example, if you change the thread\u2019s settings or you use thread local storage, don\u2019t use <code class=\"fm-code-in-text\">ConfigureAwait(false)<\/code>.<\/p>\n<\/li>\n<li class=\"fm-list-bullet\">\n<p class=\"list\">If your code is only designed to run in environments that don\u2019t use <code class=\"fm-code-in-text\">SynchronizationContext<\/code> (for example, Console apps and ASP.NET core), don\u2019t use <code class=\"fm-code-in-text\">ConfigureAwait(false)<\/code>.<\/p>\n<\/li>\n<li class=\"fm-list-bullet\">\n<p class=\"list\">If you are writing library code, and you don\u2019t care in which context your code runs, use <code class=\"fm-code-in-text\">ConfigureAwait(false)<\/code> on every <code class=\"fm-code-in-text\">await<\/code>.<\/p>\n<\/li>\n<li class=\"fm-list-bullet\">\n<p class=\"list\">If you want to leave the current context, use <code class=\"fm-code-in-text\">Task.Run<\/code> and not <code class=\"fm-code-in-text\">ConfigureAwait(false)<\/code> because <code class=\"fm-code-in-text\">ConfigureAwait(false)<\/code> does nothing if the <code class=\"fm-code-in-text\">Task<\/code> is already completed.<\/p>\n<\/li>\n<\/ul>\n<\/li>\n<\/ul>\n<\/div>\n<\/div>\n<\/div>\n<div class=\"calibre1\" id=\"calibre_link-105\">\n<div id=\"calibre_link-1072\" class=\"calibre2\">\n<div id=\"calibre_link-1073\" class=\"calibre3\">\n<h1 class=\"copyrighta\" id=\"calibre_link-1074\">12 Exceptions and async\/await<a id=\"calibre_link-1075\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-1076\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-1077\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-1078\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-1079\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-1080\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-1081\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><\/h1>\n<p class=\"copyrightbody\"><a id=\"calibre_link-242\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a>This chapter covers<a id=\"calibre_link-1082\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><\/p>\n<ul class=\"calibre9\">\n<li class=\"co-summary-bullet\">How exceptions work with asynchronous code<\/li>\n<li class=\"co-summary-bullet\">How to fix lost exceptions<\/li>\n<li class=\"co-summary-bullet\">Handling exceptions in async void methods<\/li>\n<\/ul>\n<p class=\"copyrightbody\">In this chapter, we are going to talk about exceptions. We\u2019ll discuss how they work in asynchronous code and the differences in how they work in non-asynchronous code. In transitional code, exceptions bubble up the call stack. As we\u2019ve seen in chapters 3, 5, and 11, in asynchronous code, callbacks are constantly registered to be called later, often from other threads; thus, the call stack no longer describes the flow of your code. This knowledge and the knowledge about what <code class=\"fm-code-in-text\">async<\/code>\/<code class=\"fm-code-in-text\">await<\/code> does to mitigate this are important when debugging problems related to exceptions in asynchronous code, that is, when debugging any situation where the asynchronous code fails in a non-straightforward way. We\u2019ll also cover some pitfalls you should be aware of regarding exceptions.<\/p>\n<h2 class=\"fm-head\" id=\"calibre_link-106\">12.1 Exceptions and asynchronous code<\/h2>\n<p class=\"copyrightbody\">Exceptions use the call stack. The call stack is a data structure (specifically a stack) used by the system to implement the concept of methods (or functions or procedures, depending on your programming language). When you call a method, the system pushes the memory address of the next instruction into the call stack, and when you execute a <code class=\"fm-code-in-text\">return<\/code> statement, the system jumps to the address at the top of the stack (this explanation is a gross oversimplification because this book is not about processor architecture). <a id=\"calibre_link-1083\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-1084\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-168\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><\/p>\n<p class=\"copyrightbody\">When an exception is thrown, if it\u2019s inside a <code class=\"fm-code-in-text\">try<\/code> block with an appropriate <code class=\"fm-code-in-text\">catch<\/code> clause, control passes to that <code class=\"fm-code-in-text\">catch<\/code> clause. If the exception is thrown outside of a <code class=\"fm-code-in-text\">try<\/code> block, or that <code class=\"fm-code-in-text\">try<\/code> block has no appropriate <code class=\"fm-code-in-text\">catch<\/code> clause, the exception bubbles up the call stack until it finds an appropriate <code class=\"fm-code-in-text\">catch<\/code> clause. If it gets to the beginning of the call stack without finding a <code class=\"fm-code-in-text\">catch<\/code> clause, the program crashes.<a id=\"calibre_link-1085\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-1086\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><\/p>\n<p class=\"copyrightbody\">This exception bubbling happens in run time and uses the program\u2019s call stack, not the structure of the source code. For example, let\u2019s take a look at some code where the structure of the code doesn\u2019t match the runtime behavior:<\/p>\n<pre class=\"programlisting\">public void MyMethod()\n{\n   try\n   {\n       Win.Click += ()=&gt;\n       {\n          throw new NotImplementedException();\n       };\n   }\n   catch\n   {\n       Console.WriteLine(\"In catch clause\");\n   }\n}<\/pre>\n<p class=\"copyrightbody\">In this code, while the <code class=\"fm-code-in-text\">throw<\/code> statement is located inside the <code class=\"fm-code-in-text\">try<\/code> block from a textual perspective, it doesn\u2019t run as part of this method. The lambda added to the <code class=\"fm-code-in-text\">Click<\/code> event is separated by the compiler into a different method (like we\u2019ve seen in chapter 2). It doesn\u2019t run inside our <code class=\"fm-code-in-text\">try<\/code> block. The only thing that runs inside the <code class=\"fm-code-in-text\">try<\/code> is attaching the <code class=\"fm-code-in-text\">Click<\/code> event. When and if the code in the lambda runs, it will be called by the code that triggers the <code class=\"fm-code-in-text\">Click<\/code> event, and the exception will bubble up into that code and not into our code.<a id=\"calibre_link-1087\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-1088\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><\/p>\n<p class=\"copyrightbody\"><code class=\"fm-code-in-text\">async<\/code> methods have the same problem because, as we\u2019ve seen in chapter 3, <code class=\"fm-code-in-text\">await<\/code> is equivalent to calling <code class=\"fm-code-in-text\">ContinueWith<\/code>. So if we take a simple <code class=\"fm-code-in-text\">async<\/code> method that throws an exception, we get<a id=\"calibre_link-1089\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><\/p>\n<pre class=\"programlisting\">try\n{\n   await File.ReadAllBytesAsync(\"file.bin\");\n   throw new NotImplementedException();\n}\ncatch\n{\n   Console.WriteLine(\"In catch clause\");\n}<\/pre>\n<p class=\"copyrightbody\">This code awaits a call to <code class=\"fm-code-in-text\">ReadAllBytesAsync<\/code> and then always throws an exception. If we translate <code class=\"fm-code-in-text\">await<\/code> to <code class=\"fm-code-in-text\">ContinueWith<\/code>, we get<a id=\"calibre_link-290\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-1090\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><\/p>\n<pre class=\"programlisting\">try\n{\n   File.ReadAllBytes(\"file.bin\").ContinueWith(()=&gt;\n   {\n      throw new NotImplementedException();\n   });\n}\ncatch\n{\n    Console.WriteLine(\"In catch clause\");\n}<\/pre>\n<p class=\"copyrightbody\">And this code has the same problem as the event handler example. The <code class=\"fm-code-in-text\">throw<\/code> line is in the lambda (that is passed to <code class=\"fm-code-in-text\">ContinueWith<\/code>), so it\u2019s not inside the <code class=\"fm-code-in-text\">try<\/code> block. For this reason, the compiler will also duplicate the <code class=\"fm-code-in-text\">try-catch<\/code> to make it look like <code class=\"fm-code-in-text\">await<\/code> works seamlessly with <code class=\"fm-code-in-text\">try-catch<\/code> blocks:<a id=\"calibre_link-1091\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><\/p>\n<pre class=\"programlisting\">try\n{\n   File.ReadAllBytesAsync(\"file.bin\").ContinueWith(()=&gt;\n   {\n      try\n      {\n         throw new NotImplementedException();\n      }\n      catch\n      {\n         Console.WriteLine(\"In catch clause\");\n      }\n   });\n}\ncatch\n{\n    Console.WriteLine(\"In catch clause\");\n}<\/pre>\n<p class=\"copyrightbody\">Here the compiler knows where the <code class=\"fm-code-in-text\">catch<\/code> clause is, so it can do all those transformations to make <code class=\"fm-code-in-text\">try-catch<\/code> work. But what if the <code class=\"fm-code-in-text\">try<\/code> statement is not in our methods but in code that calls us? In this case, you can\u2019t know at compile time which <code class=\"fm-code-in-text\">catch<\/code> clause to use, and the compiler can\u2019t just copy it into the continuation code. Let\u2019s see what happens with a simple <code class=\"fm-code-in-text\">async<\/code> method that can throw an exception:<a id=\"calibre_link-1092\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><\/p>\n<pre class=\"programlisting\">public async Task&lt;int&gt; MyMethod()\n{\n   throw new NotImplementedException();\n} <\/pre>\n<p class=\"copyrightbody\">This is an <code class=\"fm-code-in-text\">async<\/code> method that just throws an exception, and it translates to<\/p>\n<pre class=\"programlisting\">public Task MyMethod()\n{\n   throw new NotImplementedException();\n}<\/pre>\n<p class=\"copyrightbody\">The compiler didn\u2019t do anything! Remember, marking a method as <code class=\"fm-code-in-text\">async<\/code> does not make it asynchronous; it\u2019s just a flag for the compiler to enable all the processing required for supporting <code class=\"fm-code-in-text\">await<\/code>. If you don\u2019t use <code class=\"fm-code-in-text\">await<\/code>, the only thing the compiler does is wrap the return value in a <code class=\"fm-code-in-text\">Task<\/code> object. Note that the compiler didn\u2019t need to change the code to make exceptions behave like in a non-<code class=\"fm-code-in-text\">async<\/code> method; calling this method will throw the exception just like a non-<code class=\"fm-code-in-text\">async<\/code> method, which is what we wanted.<a id=\"calibre_link-296\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-1093\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><\/p>\n<p class=\"copyrightbody\">Now let\u2019s take a look at a method that uses <code class=\"fm-code-in-text\">await<\/code>:<\/p>\n<pre class=\"programlisting\">public async Task&lt;int&gt; MyMethod()\n{\n   await File.ReadAllBytesAsync(\"file.bin\");\n   throw new NotImplementedException();\n} <\/pre>\n<p class=\"copyrightbody\">This is a method that awaits <code class=\"fm-code-in-text\">ReadAllBytesAsync<\/code> and then throws an exception. In this case, to support reporting the error to the calling code, the compiler will add a <code class=\"fm-code-in-text\">try-catch<\/code> that will catch the exception and stash it in the returned task:<\/p>\n<pre class=\"programlisting\">public async Task&lt;int&gt; MyMethod()\n{\n   var result = new TaskCompletionSource&lt;int&gt;();\n   File.ReadAllBytesAsync(\"file.bin\").ContinueWith(t=&gt;\n   {\n      try\n      {\n         throw new NotImplementedException();\n      }\n      catch(Exception ex)\n      {\n         result.TrySetException(new AggregateException(ex));\n      }\n   });\n} <\/pre>\n<p class=\"copyrightbody\">Here, the compiler added a <code class=\"fm-code-in-text\">try<\/code> block inside the continuation (the code that it passed to <code class=\"fm-code-in-text\">ContinueWith)<\/code>. Note that, like in our previous example, the compiler did not add a <code class=\"fm-code-in-text\">try<\/code> block to the part before the first <code class=\"fm-code-in-text\">await<\/code> and the call to <code class=\"fm-code-in-text\">ReadAllBytesAsync<\/code> itself. If an error occurs before the first <code class=\"fm-code-in-text\">await<\/code>, the method will throw a regular exception. Only if the error occurs after the first <code class=\"fm-code-in-text\">await<\/code> will the exception be caught by compiler generated code and stored in the returned <code class=\"fm-code-in-text\">Task<\/code>. This is how most asynchronous code works; an asynchronous method can both throw a regular exception and report an error using the <code class=\"fm-code-in-text\">Task<\/code> object (by setting the <code class=\"fm-code-in-text\">Task<\/code>\u2019s <code class=\"fm-code-in-text\">Status<\/code> property to <code class=\"fm-code-in-text\">Faulted<\/code> and storing the exception in the <code class=\"fm-code-in-text\">Task.Exception<\/code> property). <a id=\"calibre_link-1094\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-1095\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><\/p>\n<p class=\"copyrightbody\">If you use <code class=\"fm-code-in-text\">await<\/code> when you call the method, both situations look the same. But if you are not using <code class=\"fm-code-in-text\">await<\/code> (for example, if you are collecting multiple tasks and using <code class=\"fm-code-in-text\">Task.WhenAny<\/code> or <code class=\"fm-code-in-text\">Task.WhenAll<\/code>), you need to handle both exceptions thrown by the asynchronous methods and exceptions stored in the returned <code class=\"fm-code-in-text\">Task<\/code>. Also, remember that the continuation usually runs after the method returns, so in case of an error, the <code class=\"fm-code-in-text\">Task<\/code> returned by the asynchronous method will be in the <code class=\"fm-code-in-text\">Created<\/code>, <code class=\"fm-code-in-text\">WaitingForActivation<\/code>, or <code class=\"fm-code-in-text\">Running<\/code> state when it\u2019s returned, and it will only change to the <code class=\"fm-code-in-text\">Faulted<\/code> state later.<\/p>\n<p class=\"copyrightbody\">There\u2019s just one difference between using <code class=\"fm-code-in-text\">await<\/code> to rethrow the exception or using the <code class=\"fm-code-in-text\">Task.Exception<\/code> property, and that is how they use the <code class=\"fm-code-in-text\">AggregateException<\/code>.<a id=\"calibre_link-1096\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-1097\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><\/p>\n<h2 class=\"fm-head\" id=\"calibre_link-107\">12.2 await and AggregateException<\/h2>\n<p class=\"copyrightbody\"><a id=\"calibre_link-151\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a>The <code class=\"fm-code-in-text\">Task.Exception<\/code> property always stores an <code class=\"fm-code-in-text\">AggregateException<\/code>. The <code class=\"fm-code-in-text\">AggregateException<\/code> class, as the name suggests, is an exception class that stores multiple other exceptions inside it. <a id=\"calibre_link-1098\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-1099\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-1100\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><\/p>\n<p class=\"copyrightbody\"><code class=\"fm-code-in-text\">Task<\/code> uses <code class=\"fm-code-in-text\">AggreggateException<\/code> because a <code class=\"fm-code-in-text\">Task<\/code> can represent the result of multiple operations running in parallel (for example, multiple asynchronous operations passed to <code class=\"fm-code-in-text\">Task.WhenAll<\/code>). Because more than one of those background operations can fail, we need a way to store multiple exceptions.<\/p>\n<p class=\"copyrightbody\">In practice, this feature is almost never used. In fact, this feature is so rarely used that if you use <code class=\"fm-code-in-text\">await<\/code>, and the <code class=\"fm-code-in-text\">Task<\/code> you are awaiting fails, the await operator will always throw the first exception inside the <code class=\"fm-code-in-text\">AggregateException<\/code> and not the <code class=\"fm-code-in-text\">AggregateException<\/code> itself. If there is more than one exception inside, the <code class=\"fm-code-in-text\">AggregateException<\/code> <code class=\"fm-code-in-text\">await<\/code> will still throw just the first one and ignore the rest. All exceptions except for the first one, along with any information stored inside them, will be lost. Here is code showing how <code class=\"fm-code-in-text\">await<\/code> throws the stored exception:<\/p>\n<pre class=\"programlisting\">var tcs = new TaskCompletionSource();\ntcs.SetException(new NotSupportedException());\nConsole.WriteLine(\"In tasks: \"+tcs.Task.Exception.GetType());  <span class=\"fm-combinumeral\">\u2776<\/span>\ntry\n{\n   await tcs.Task;                                             <span class=\"fm-combinumeral\">\u2777<\/span>\n}\ncatch(Exception ex)\n{\n   Console.WriteLine(\"Thrown: \"+ex.GetType());                 <span class=\"fm-combinumeral\">\u2778<\/span>\n}<\/pre>\n<p class=\"copyrightbody\"><span class=\"fm-combinumeral\">\u2776<\/span> AggregateException<\/p>\n<p class=\"copyrightbody\"><span class=\"fm-combinumeral\">\u2777<\/span> Will throw the inner exception<\/p>\n<p class=\"copyrightbody\"><span class=\"fm-combinumeral\">\u2778<\/span> NotSupportedException<\/p>\n<p class=\"copyrightbody\">This program stores a <code class=\"fm-code-in-text\">NotSupportedException<\/code> in a <code class=\"fm-code-in-text\">Task<\/code> using <code class=\"fm-code-in-text\">TaskCompletionSource<\/code> (we talked about creating your own tasks with <code class=\"fm-code-in-text\">TaskCompletionSource<\/code> back in chapter 10). Then we check to see what exception is stored inside the <code class=\"fm-code-in-text\">Task<\/code> and get an <code class=\"fm-code-in-text\">AggregateException<\/code> wrapping our exception. However, we then use <code class=\"fm-code-in-text\">await<\/code> because the <code class=\"fm-code-in-text\">Task<\/code> in the <code class=\"fm-code-in-text\">Failed<\/code> state <code class=\"fm-code-in-text\">await<\/code> will throw an exception, but it will throw the inner <code class=\"fm-code-in-text\">NotSupportedException<\/code> and not the <code class=\"fm-code-in-text\">AggregateException.<\/code><\/p>\n<h2 class=\"fm-head\" id=\"calibre_link-108\">12.3 The case of the lost exception<\/h2>\n<p class=\"copyrightbody\">We\u2019ve seen that the compiler will generate code to catch exceptions and stash them inside the <code class=\"fm-code-in-text\">Task<\/code>. And <code class=\"fm-code-in-text\">await<\/code> will rethrow that exception. But what happens if, for some reason, we don\u2019t use <code class=\"fm-code-in-text\">await<\/code>?<a id=\"calibre_link-244\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-1101\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><\/p>\n<p class=\"copyrightbody\">The answer is nothing. The compiler-generated code will catch the exception and store it in the <code class=\"fm-code-in-text\">Task<\/code>. And that\u2019s it. If no one reads the exception from the <code class=\"fm-code-in-text\">Task<\/code> (either by using <code class=\"fm-code-in-text\">await<\/code> or by reading the <code class=\"fm-code-in-text\">Task<\/code>\u2019s <code class=\"fm-code-in-text\">Exception<\/code> property), the exception will be ignored.<\/p>\n<p class=\"copyrightbody\">Let\u2019s take a look at another piece of code:<\/p>\n<pre class=\"programlisting\">Public async Task MethodThatThrowsException()\n{\n   await Task.Delay(100);\n   throw new NotImplementedException();\n}\n \nPublic async Task MethodThatCallsOtherMethod()\n{\n    MethodThatTHrowsException();\n}<\/pre>\n<p class=\"copyrightbody\">Here we have two methods. The first method, <code class=\"fm-code-in-text\">MethodThatThrowsException<\/code>, throws an exception after an <code class=\"fm-code-in-text\">await<\/code>, so the compiler will catch the exception and stash it in the returned <code class=\"fm-code-in-text\">Task<\/code>. The second method calls the first, but when I wrote it, I forgot the <code class=\"fm-code-in-text\">await<\/code>, so no one is looking at the retuned <code class=\"fm-code-in-text\">Task<\/code>. The exception was caught in the first method by the compiler-generated code but ignored by the second method because I didn\u2019t use <code class=\"fm-code-in-text\">await<\/code>. And so the runtime thinks we handled the exception (because the compiler generated code caught it), and the code continues to run while ignoring the error.<a id=\"calibre_link-1102\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><\/p>\n<p class=\"copyrightbody\">If the method that throws the exception is in a library, and you have the \u201cjust my code\u201d feature of the debugger enabled, you won\u2019t even see the exception in the debugger. So if some code in your program seems to stop running with no indication of why, there\u2019s a good chance someone forgot an <code class=\"fm-code-in-text\">await<\/code> somewhere.<\/p>\n<h2 class=\"fm-head\" id=\"calibre_link-109\">12.4 Exceptions and async void methods<\/h2>\n<p class=\"copyrightbody\">In <code class=\"fm-code-in-text\">async void<\/code> methods, the method does not return a <code class=\"fm-code-in-text\">Task<\/code> (obviously). Because there is no <code class=\"fm-code-in-text\">Task<\/code> to stash the exception in, the compiler doesn\u2019t know what to do with the exception thrown inside the method, so it will not generate the <code class=\"fm-code-in-text\">try-catch<\/code> block we\u2019ve seen in the previous example. As a result, any exception thrown in the code will bubble up the call stack into the <code class=\"fm-code-in-text\">SynchronizationContext<\/code> that runs the code (we talked about how <code class=\"fm-code-in-text\">SynchronizationContext<\/code> works in chapter 11). This will most likely crash your program. Because of that, it is best practice to handle all exceptions in <code class=\"fm-code-in-text\">async void<\/code> methods yourself and never let an exception bubble out of it.<a id=\"calibre_link-1103\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-1104\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><\/p>\n<h2 class=\"fm-head\" id=\"calibre_link-1105\">Summary<\/h2>\n<ul class=\"calibre9\">\n<li class=\"fm-list-bullet\">\n<p class=\"list\">Exceptions use the call stack to find the correct code to run in case of error, which is a problem for asynchronous code because continuations don\u2019t run in the same call stack as the code that calls the asynchronous method.<a id=\"calibre_link-243\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><\/p>\n<\/li>\n<li class=\"fm-list-bullet\">\n<p class=\"list\">If you use <code class=\"fm-code-in-text\">async<\/code>\/<code class=\"fm-code-in-text\">await<\/code>, the compiler will generate code to make it look like non-<code class=\"fm-code-in-text\">async<\/code> code. It does this by catching exceptions inside <code class=\"fm-code-in-text\">async<\/code> methods and stashing them in the returned <code class=\"fm-code-in-text\">Task<\/code>. <code class=\"fm-code-in-text\">await<\/code> then throws the exception inside the continuation, making it look like it was thrown by the <code class=\"fm-code-in-text\">await<\/code>.<\/p>\n<\/li>\n<li class=\"fm-list-bullet\">\n<p class=\"list\">Every asynchronous method can throw a normal exception or signal a failure using the returned <code class=\"fm-code-in-text\">Task<\/code>. <code class=\"fm-code-in-text\">await<\/code> makes both of those failure modes look the same. If you don\u2019t use <code class=\"fm-code-in-text\">await<\/code>, you need to handle both yourself.<\/p>\n<\/li>\n<li class=\"fm-list-bullet\">\n<p class=\"list\">The exception stored inside the <code class=\"fm-code-in-text\">Task<\/code> is an <code class=\"fm-code-in-text\">AggregateException<\/code>, just in case the <code class=\"fm-code-in-text\">Task<\/code> represents multiple operations. <code class=\"fm-code-in-text\">await<\/code> ignores all but the first exception inside that <code class=\"fm-code-in-text\">AggregateException<\/code>. If you don\u2019t use <code class=\"fm-code-in-text\">await<\/code>, you need to deal with this yourself. In rare cases, the <code class=\"fm-code-in-text\">Task<\/code> does represent multiple operations, and if you care about multiple failures, you can\u2019t use <code class=\"fm-code-in-text\">await<\/code> and need to read the <code class=\"fm-code-in-text\">Task.Exception<\/code> property yourself.<\/p>\n<\/li>\n<li class=\"fm-list-bullet\">\n<p class=\"list\">If you ignore the <code class=\"fm-code-in-text\">Task<\/code> returned by an asynchronous method (by forgetting to use <code class=\"fm-code-in-text\">await<\/code>, for example), and that method throws an exception, the exception will be lost.<\/p>\n<\/li>\n<li class=\"fm-list-bullet\">\n<p class=\"list\">As a corollary, if code fails in a way that should have been an exception, but you can\u2019t see that exception, there\u2019s a good chance you forgot an <code class=\"fm-code-in-text\">await<\/code> somewhere.<\/p>\n<\/li>\n<li class=\"fm-list-bullet\">\n<p class=\"list\">All the exception support provided by <code class=\"fm-code-in-text\">async<\/code>\/<code class=\"fm-code-in-text\">await<\/code> is dependent on the returned <code class=\"fm-code-in-text\">Task<\/code>. <code class=\"fm-code-in-text\">async void<\/code> methods don\u2019t return a <code class=\"fm-code-in-text\">Task<\/code> and so don\u2019t have this support. Never throw an exception from or let an exception bubble out of an <code class=\"fm-code-in-text\">async void<\/code> method.<\/p>\n<\/li>\n<\/ul>\n<\/div>\n<\/div>\n<\/div>\n<div class=\"calibre1\" id=\"calibre_link-110\">\n<div id=\"calibre_link-1106\" class=\"calibre2\">\n<div id=\"calibre_link-1107\" class=\"calibre3\">\n<h1 class=\"copyrighta\" id=\"calibre_link-1108\">13 Thread-safe collections<a id=\"calibre_link-1109\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><\/h1>\n<p class=\"copyrightbody\"><a id=\"calibre_link-301\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a>This chapter covers<a id=\"calibre_link-1110\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><\/p>\n<ul class=\"calibre9\">\n<li class=\"co-summary-bullet\">The problems encountered when using regular collections in a multithreaded program<\/li>\n<li class=\"co-summary-bullet\">Concurrent collections<\/li>\n<li class=\"co-summary-bullet\">The <code class=\"fm-code-in-text\">BlockingCollection<\/code> class<\/li>\n<li class=\"co-summary-bullet\">Asynchronous alternatives to <code class=\"fm-code-in-text\">Blocking-Collection<\/code><\/li>\n<li class=\"co-summary-bullet\">Immutable collections and special considerations when using them<\/li>\n<li class=\"co-summary-bullet\">Frozen collections<\/li>\n<\/ul>\n<p class=\"copyrightbody\">The <code class=\"fm-code-in-text\">System.Collections.Generic<\/code> namespace contains many useful collections; however, we can\u2019t just use them in a multithreaded application because all those collections are not thread safe. In this chapter, we\u2019ll look at the problems with the simplest way of making collections thread safe&mdash;just putting a lock around any access to the collection. We\u2019ll also talk about the thread-safe alternatives provided by the .NET library.<\/p>\n<p class=\"copyrightbody\">Specifically, we\u2019ll examine the concurrent collections added in .NET framework 4, discuss the immutable collections added in .NET Core (which is the basis for .NET 5 and later), and talk about the frozen collections added in .NET 8. You will also learn how to use each type of collection and when it\u2019s appropriate to do so. But first, let\u2019s talk about why you can\u2019t just use the regular collections.<\/p>\n<h2 class=\"fm-head\" id=\"calibre_link-111\">13.1 The problems with using regular collections<\/h2>\n<p class=\"copyrightbody\">The .NET library provides many useful collection classes in the <code class=\"fm-code-in-text\">System.Collections.Generic<\/code> namespace. Those collections support multiple concurrent reads, but they can be corrupted and produce unexpected results if there are multiple concurrent writers or if different threads try to read and write simultaneously. <a id=\"calibre_link-1111\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-215\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-1112\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><\/p>\n<p class=\"copyrightbody\">Also, according to the official documentation, iterating over the collection is intrinsically not thread safe, which means that if you iterate over the collection, either with a loop such as <code class=\"fm-code-in-text\">foreach<\/code> or a Linq expression, you must prevent any writes by other threads to the collection for the entire duration of the loop. To use those collections in a multithreaded program, you must take care of synchronization yourself, typically by using locks, and doing so correctly when using collections is often nontrivial.<\/p>\n<p class=\"copyrightbody\">For example, let\u2019s consider a very common use case. We want to use a <code class=\"fm-code-in-text\">Dictionary&lt;TKey,TValue&gt;<\/code> as a cache. When we need some data item, we first check whether it\u2019s in the cache, and if not, we create and initialize the item, probably by retrieving it from an external service or by precalculating some stuff (the reason we use a cache to begin with is that initializing the item takes a long time). We\u2019ll start with the single threaded code first and add locking later.<a id=\"calibre_link-1113\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><\/p>\n<p class=\"fm-code-listing-caption\">Listing 13.1 Simple, non&ndash;thread-safe cache<\/p>\n<pre class=\"programlisting\">if(!dictionary.TryGetValue(itemId, out var item))\n{\n   item = CreateAndInitializeItem(itemId);\n   dictionary.Add(itemId,item);\n}<\/pre>\n<p class=\"copyrightbody\">This code tries to retrieve an item from the dictionary, and if the item isn\u2019t already there, it calls <code class=\"fm-code-in-text\">CreateAndInitializeItem<\/code> to create and initialize the item. After creating an item, the code calls <code class=\"fm-code-in-text\">Add<\/code> to add the item to the dictionary so it\u2019s available the next time we need it.<a id=\"calibre_link-1114\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><\/p>\n<p class=\"copyrightbody\">This is a perfectly good way to implement a simple in-process cache for single-threaded applications, but this code is very much not thread safe. Calling <code class=\"fm-code-in-text\">TryGetValue<\/code> from multiple threads simultaneously is explicitly allowed, but calling <code class=\"fm-code-in-text\">Add<\/code> concurrently or calling <code class=\"fm-code-in-text\">Add<\/code> and <code class=\"fm-code-in-text\">TryGetValue<\/code> at the same time can produce unexpected results and even corrupt the dictionary. <a id=\"calibre_link-1115\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><\/p>\n<p class=\"copyrightbody\">Let\u2019s make this thread safe. We\u2019ll start with the simplest option&mdash;placing a lock around the entire block.<\/p>\n<p class=\"fm-code-listing-caption\">Listing 13.2 Thread-safe cache with a single lock<\/p>\n<pre class=\"programlisting\">Item item;\nlock(_dictLock)                                     <span class=\"fm-combinumeral\">\u2776<\/span>\n{\n   if(!dictionary.TryGetValue(itemId, out item))\n   {\n      item = CreateAndInitializeItem(itemId);\n      dictionary.Add(itemId,item);\n   }\n}<\/pre>\n<p class=\"copyrightbody\"><span class=\"fm-combinumeral\">\u2776<\/span> Adds a lock<\/p>\n<p class=\"copyrightbody\">This code is the same as listing 13.1, except it uses a lock to prevent multiple threads from running it simultaneously. This does make our code thread safe, but at the cost of locking the entire cache every time we run it. If the item is already in the dictionary, the lock will be short, and everything will be fine. However, if we need to create a new item, the entire cache will remain locked for the entire duration of the initialization, meaning that other threads that are working on completely different items will have to wait every time a new item has to be initialized. To solve this problem, we must release the lock while initializing the item.<\/p>\n<p class=\"fm-code-listing-caption\">Listing 13.3 Non&ndash;thread-safe cache with lock released during initialization<\/p>\n<pre class=\"programlisting\">Item item;\nbool exists;\nlock(_dictLock)                                      <span class=\"fm-combinumeral\">\u2776<\/span>\n{\n   exists = dictionary.TryGetValue(itemId, out item);\n}                                                    <span class=\"fm-combinumeral\">\u2777<\/span>\nif(!exists)\n{\n   item = CreateAndInitializeItem(itemId);\n   lock(_dictLock)                                   <span class=\"fm-combinumeral\">\u2778<\/span>\n   {\n      dictionary.Add(itemId,item);                   <span class=\"fm-combinumeral\">\u2779<\/span>\n   }\n}<\/pre>\n<p class=\"copyrightbody\"><span class=\"fm-combinumeral\">\u2776<\/span> Lock<\/p>\n<p class=\"copyrightbody\"><span class=\"fm-combinumeral\">\u2777<\/span> Unlock<\/p>\n<p class=\"copyrightbody\"><span class=\"fm-combinumeral\">\u2778<\/span> Lock again<\/p>\n<p class=\"copyrightbody\"><span class=\"fm-combinumeral\">\u2779<\/span> Add&mdash;fails if already added by another thread<\/p>\n<p class=\"copyrightbody\"><a id=\"calibre_link-302\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a>This code has two lock blocks, one protecting the <code class=\"fm-code-in-text\">TryGetValue<\/code> call and the other protecting the <code class=\"fm-code-in-text\">Add<\/code> call. Those locks ensure that <code class=\"fm-code-in-text\">Dictionary&lt;T&gt;<\/code> is never called from multiple threads at the same time, which means we will not corrupt the dictionary. Unfortunately, this does not make our code thread safe. This code is actually almost guaranteed to fail if multiple threads need to use the same item that is not already in the cache.<a id=\"calibre_link-1116\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><\/p>\n<p class=\"copyrightbody\">This a common problem, where composing two (or more) thread-safe operations often does not result in thread-safe code. The call to <code class=\"fm-code-in-text\">TryGetValue<\/code> is now thread safe because it is protected by the lock, and the call to <code class=\"fm-code-in-text\">Add<\/code> is thread safe for the same reason. But because we don\u2019t hold a lock for the entire runtime of the code, other threads can change the dictionary between <code class=\"fm-code-in-text\">TryGetValue<\/code> and <code class=\"fm-code-in-text\">Add<\/code>.<\/p>\n<p class=\"copyrightbody\">If two threads run this code simultaneously for the same item, the first thread will execute the <code class=\"fm-code-in-text\">TryGetValue<\/code> and discover that the item isn\u2019t in the dictionary, so it will go on to create and initialize the item. The second thread will then also call <code class=\"fm-code-in-text\">TryGetValue<\/code> (before the initialization is complete, because the reason we use a cache is that the initialization takes a long time). In addition, because the first thread didn\u2019t add the item yet, it will also see that the item is not in the cache and go on to create and initialize another copy of the item.<\/p>\n<p class=\"copyrightbody\">Now we have two different threads busy initializing two different copies of the <code class=\"fm-code-in-text\">Item<\/code> object for the same logical item. One of those threads will finish first and add the item to the cache by calling <code class=\"fm-code-in-text\">Add<\/code>. The other thread will also finish initializing its copy at some point and attempt to add it to the cache by calling <code class=\"fm-code-in-text\">Add<\/code>; however, because the first thread has already added the item, <code class=\"fm-code-in-text\">Add<\/code> will now throw an <code class=\"fm-code-in-text\">ArgumentException<\/code>. Figure 13.1 illustrates the flow of those two threads.<a id=\"calibre_link-259\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-1117\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><\/p>\n<div class=\"figure\">\n<p class=\"figure1\"><img decoding=\"async\" alt=\"\" class=\"calibre28\" src=\"\/images\/CSConcurrency_Asynchronous\/000015.png\" \/><\/p>\n<p class=\"figure1\">Figure 13.1 Concurrent initialization of the same item with two threads. The second thread fails because the first thread already added the item.<\/p>\n<\/p><\/div>\n<p class=\"copyrightbody\">To make this code thread safe, we must avoid calling <code class=\"fm-code-in-text\">Add<\/code> if another thread has already added the item while we were busy initializing it. The easiest option is to replace the call to <code class=\"fm-code-in-text\">Add<\/code> with the <code class=\"fm-code-in-text\">[]<\/code> operator (technically, it\u2019s the <code class=\"fm-code-in-text\">Item[]<\/code> property, but I\u2019m going to call it an operator and not a property because it\u2019s used as an operator). The <code class=\"fm-code-in-text\">[]<\/code> operator adds a new item if the key does not exist and overrides the existing item if it does. This solves our exception problem but also introduces a new subtle bug.<a id=\"calibre_link-1118\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><\/p>\n<p class=\"fm-code-listing-caption\">Listing 13.4 Thread-safe cache with operator <code class=\"fm-code-in-text1\">[]<\/code><\/p>\n<pre class=\"programlisting\">Item item;\nbool exists;\nlock(_dictLock)                                       <span class=\"fm-combinumeral\">\u2776<\/span>\n{\n   exists = dictionary.TryGetValue(itemId, out item);\n}                                                     <span class=\"fm-combinumeral\">\u2777<\/span>\nif(!exists)\n{\n   item = CreateAndInitializeItem(itemId);\n   lock(_dictLock)                                    <span class=\"fm-combinumeral\">\u2778<\/span>\n   {\n      dictionary[itemId] = item;                      <span class=\"fm-combinumeral\">\u2779<\/span>\n   }\n}<\/pre>\n<p class=\"copyrightbody\"><span class=\"fm-combinumeral\">\u2776<\/span> Lock<\/p>\n<p class=\"copyrightbody\"><span class=\"fm-combinumeral\">\u2777<\/span> Unlock<\/p>\n<p class=\"copyrightbody\"><span class=\"fm-combinumeral\">\u2778<\/span> Lock again<\/p>\n<p class=\"copyrightbody\"><span class=\"fm-combinumeral\">\u2779<\/span> Overrides changes if already added by another thread<\/p>\n<p class=\"copyrightbody\">This code just replaces <code class=\"fm-code-in-text\">dictionary.Add(itemId,item)<\/code> with <code class=\"fm-code-in-text\">dictionary[itemId]=item<\/code>, which solves our immediate problem because operator <code class=\"fm-code-in-text\">[]<\/code> will just override the previous value if it exists; however, this might introduce a bug. Now the first thread uses its own copy of the <code class=\"fm-code-in-text\">Item<\/code> object, while the second and subsequent threads use the copy created by the second thread. If the <code class=\"fm-code-in-text\">Item<\/code> object is immutable, and the initialization always returns an equivalent object for the same key, this can be fine; however, if the <code class=\"fm-code-in-text\">Item<\/code> object is modified by the first thread, those changes will be lost.<a id=\"calibre_link-1119\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-260\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><\/p>\n<p class=\"copyrightbody\">To make sure all the threads use the same <code class=\"fm-code-in-text\">Item<\/code> object, we have no choice but to recheck the dictionary after initialization and, if another thread has updated the dictionary first, use the value from the first thread.<\/p>\n<p class=\"fm-code-listing-caption\">Listing 13.5 Thread-safe cache with lock released during initialization<\/p>\n<pre class=\"programlisting\">Item item;\nbool exists;\nlock(_dictLock)                                        <span class=\"fm-combinumeral\">\u2776<\/span>\n{\n   exists = dictionary.TryGetValue(itemId, out item);\n}                                                      <span class=\"fm-combinumeral\">\u2777<\/span>\nif(!exists)\n{\n   item = CreateAndInitializeItem(itemId);\n   lock(_dictLock)                                     <span class=\"fm-combinumeral\">\u2778<\/span>\n   {\n      if(dictionary.TryGetValue(itemId,                <span class=\"fm-combinumeral\">\u2779<\/span>\n         out var itemFromOtherThread))                 <span class=\"fm-combinumeral\">\u2779<\/span>\n      {\n         item = itemFromOtherThread;\n      }\n      else\n      {\n         dictionary.Add(itemId,item);\n      }\n   }\n}<\/pre>\n<p class=\"copyrightbody\"><span class=\"fm-combinumeral\">\u2776<\/span> Lock<\/p>\n<p class=\"copyrightbody\"><span class=\"fm-combinumeral\">\u2777<\/span> Unlock<\/p>\n<p class=\"copyrightbody\"><span class=\"fm-combinumeral\">\u2778<\/span> Lock again<\/p>\n<p class=\"copyrightbody\"><span class=\"fm-combinumeral\">\u2779<\/span> Tests whether already added by another thread<\/p>\n<p class=\"copyrightbody\">Here, we check the dictionary again instead of blindly calling <code class=\"fm-code-in-text\">Add<\/code> or operator <code class=\"fm-code-in-text\">[]<\/code> after the initialization. If we find the item is now in the dictionary, we drop the copy we initialized and use the one from the dictionary (because we want all threads to use the same object). We add the item only if it is still not in the dictionary.<a id=\"calibre_link-1120\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><\/p>\n<p class=\"copyrightbody\">As you can see, this code is quite complicated and difficult to follow compared to the single-threaded version in listing 13.1. Luckily, we don\u2019t have to write it because we have the concurrent collections.<a id=\"calibre_link-1121\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-1122\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><\/p>\n<h2 class=\"fm-head\" id=\"calibre_link-112\">13.2 The concurrent collections<\/h2>\n<p class=\"copyrightbody\">The collections in the <code class=\"fm-code-in-text\">System.Collections.Concurrent<\/code> are thread-safe versions of the most popular collections. The concurrent collections employ clever fine-grained locking strategies and lockless techniques to stay thread safe even when the collection is accessed by many threads simultaneously. This means all the methods and properties of the concurrent collection can be used concurrently from different threads without causing corruptions or unexpected behavior. <a id=\"calibre_link-1123\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-216\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-1124\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><\/p>\n<p class=\"copyrightbody\">The concurrent collections have a different interface than the collections we all know and love from the <code class=\"fm-code-in-text\">System.Collections.Generic<\/code> namespace because, as we\u2019ve seen earlier in this chapter, just making all the normal collection\u2019s methods callable from multiple threads would not, by itself, result in thread-safe code.<\/p>\n<p class=\"copyrightbody\">This section covers the commonly used concurrent collections, starting with <code class=\"fm-code-in-text\">ConcurrentDictionary&lt;TKey,TValue&gt;<\/code>, that will elegantly solve the problems we\u2019ve talked about in this chapter so far.<\/p>\n<h3 class=\"fm-head\" id=\"calibre_link-113\">13.2.1 ConcurrentDictionary&lt;TKey,TValue&gt;<\/h3>\n<p class=\"copyrightbody\">Unsurprisingly, <code class=\"fm-code-in-text\">ConcurrentDictionary&lt;TKey,TValue&gt;<\/code> is a thread-safe alternative for <code class=\"fm-code-in-text\">Dictionary&lt;TKey,TValue&gt;<\/code>, but because of the problems we\u2019ve seen when trying to use locks with <code class=\"fm-code-in-text\">Dictionary&lt;TKey,TValue&gt;<\/code>, it has a slightly different interface geared toward solving multithreaded problems. Let\u2019s go back to the original single-threaded code of our <code class=\"fm-code-in-text\">Dictionary&lt;TKey,TValue&gt;<\/code>-based cache.<a id=\"calibre_link-1125\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-1126\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><\/p>\n<p class=\"fm-code-listing-caption\">Listing 13.6 Non&ndash;thread-safe cache again<\/p>\n<pre class=\"programlisting\">if(!dictionary.TryGetValue(itemId, out var item))\n{\n   item = CreateAndInitializeItem(itemId);\n   dictionary.Add(itemId,item);\n}<\/pre>\n<p class=\"copyrightbody\">This is the same code from listing 13.1. It tests whether an item is in the dictionary-based cache, and if not, it creates and initializes a new item object and adds it to the cache.<\/p>\n<p class=\"copyrightbody\">Now let\u2019s do the minimal amount of work to replace <code class=\"fm-code-in-text\">Dictionary&lt;TKey,TValue&gt;<\/code> with <code class=\"fm-code-in-text\">ConcurrentDictionary&lt;TKey,TValue&gt;<\/code>. The <code class=\"fm-code-in-text\">ConcurrentDictionary&lt;TKey,TValue&gt;<\/code> class has a <code class=\"fm-code-in-text\">TryGetValue<\/code> method that works the same as <code class=\"fm-code-in-text\">Dictionary&lt;TKey,TValue&gt;<\/code>\u2019s <code class=\"fm-code-in-text\">TryGetValue<\/code>. If a value with the provided key exists in the dictionary, it returns <code class=\"fm-code-in-text\">true<\/code> and puts the value in an <code class=\"fm-code-in-text\">out<\/code> parameter. If a value with the key does not exist in the dictionary, it returns <code class=\"fm-code-in-text\">false<\/code>.<a id=\"calibre_link-1127\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><\/p>\n<p class=\"copyrightbody\">But <code class=\"fm-code-in-text\">ConcurrentDictionary&lt;TKey,TValue&gt;<\/code> doesn\u2019t have an <code class=\"fm-code-in-text\">Add<\/code> method because, as we saw in listing 13.3, in multithreaded code, there\u2019s aways a chance another thread will add an item right before we call <code class=\"fm-code-in-text\">Add<\/code> and cause it to fail with an exception. For this reason, <code class=\"fm-code-in-text\">ConcurrentDictionary&lt;TKey,TValue&gt;<\/code> doesn\u2019t have an <code class=\"fm-code-in-text\">Add<\/code> method&mdash;it is replaced with <code class=\"fm-code-in-text\">TryAdd<\/code>.<a id=\"calibre_link-1128\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><\/p>\n<p class=\"copyrightbody\">As we\u2019ve seen, no matter how small the time window between <code class=\"fm-code-in-text\">TryGetValue<\/code> and <code class=\"fm-code-in-text\">Add<\/code> is, there is always a chance that another thread will manage to add the item in that timeframe. To address this problem, we must treat the case where a key is already present in the dictionary, not as an exceptional error condition, but as a normal occurrence. This is what <code class=\"fm-code-in-text\">TryAdd<\/code> does.<\/p>\n<p class=\"copyrightbody\">This difference between <code class=\"fm-code-in-text\">Add<\/code> and <code class=\"fm-code-in-text\">TryAdd<\/code> manifests itself in a tiny change in the method interface. While <code class=\"fm-code-in-text\">Add<\/code> will throw an exception if the key is already in the dictionary, <code class=\"fm-code-in-text\">TryAdd<\/code> will only return <code class=\"fm-code-in-text\">false<\/code>.<a id=\"calibre_link-249\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><\/p>\n<p class=\"copyrightbody\">Just replacing <code class=\"fm-code-in-text\">Add<\/code> with <code class=\"fm-code-in-text\">TryAdd<\/code> in the code from listing 13.6 gives this simple code that is thread safe but has a small problem. (Hint: It\u2019s the same problem from listing 13.4.)<\/p>\n<p class=\"fm-code-listing-caption\">Listing 13.7 Thread-safe cache with <code class=\"fm-code-in-text1\">ConcurrentDictionary.TryAdd<\/code><\/p>\n<pre class=\"programlisting\">if(!dictionary.TryGetValue(itemId, out var item))\n{\n   item = CreateAndInitializeItem(itemId);\n   dictionary.TryAdd(itemId,item);\n}<\/pre>\n<p class=\"copyrightbody\">This listing replaces <code class=\"fm-code-in-text\">Add<\/code> with <code class=\"fm-code-in-text\">TryAdd<\/code>. And because <code class=\"fm-code-in-text\">TryAdd<\/code> doesn\u2019t throw an exception if the key is already in the dictionary, this code works and is thread safe. It just has a variation of the problem we had in listing 13.4. If multiple threads initialize the same item at the same time, each will have its own copy of the <code class=\"fm-code-in-text\">Item<\/code> object. If the <code class=\"fm-code-in-text\">Item<\/code> object isn\u2019t immutable, or all those copies are not identical, this can cause a real problem.<\/p>\n<p class=\"copyrightbody\">What we really want is to combine <code class=\"fm-code-in-text\">TryGetValue<\/code> and <code class=\"fm-code-in-text\">TryAdd<\/code> into a single atomic operation in a way that eliminates this problem. <code class=\"fm-code-in-text\">ConcurrentDictionary&lt;TKey,TValue&gt;<\/code> does this with the <code class=\"fm-code-in-text\">GetOrAdd<\/code> method.<a id=\"calibre_link-1129\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><\/p>\n<p class=\"fm-code-listing-caption\">Listing 13.8 Thread-safe cache with <code class=\"fm-code-in-text1\">ConcurrentDictionary.GetOrAdd<\/code><\/p>\n<pre class=\"programlisting\">var item = dictionary.GetOrAdd(itemId,CreateAndInitializeItem);<\/pre>\n<p class=\"copyrightbody\">This single line calling to <code class=\"fm-code-in-text\">GetOrAdd<\/code> is equivalent to the 21 lines in listing 13.5. If the item is already in the dictionary, it will return the item. If not, it will call <code class=\"fm-code-in-text\">CreateAndInitialize<\/code> to create the item. If multiple threads call <code class=\"fm-code-in-text\">GetOrAdd<\/code> before the item completed initialization and was added to the dictionary, all of them will run <code class=\"fm-code-in-text\">CreateAndInitialize<\/code>, but <code class=\"fm-code-in-text\">GetOrAdd<\/code> will return the same object in all threads.<\/p>\n<p class=\"copyrightbody\"><code class=\"fm-code-in-text\">GetOrAdd<\/code> has a version that accepts the value to add to the dictionary as the second parameter, as well as the version we used that accepts a delegate to call to initialize the value. <code class=\"fm-code-in-text\">ConcurrentDictionary&lt;TKey,TValue&gt;<\/code> uses fine-grained locking so that <code class=\"fm-code-in-text\">GetOrAdd<\/code> calls for different keys can run concurrently.<\/p>\n<p class=\"copyrightbody\">Note that if you use the version of the method that accepts a delegate, and you call <code class=\"fm-code-in-text\">GetOrAdd<\/code> from multiple threads simultaneously, the initialization code can run more than once. The first thread to finish will get to add the value to the dictionary, and the result of the initialization code from other threads will be ignored. You should be aware whether your item requires cleanup or if you can\u2019t run the initialization code multiple times.<\/p>\n<p class=\"copyrightbody\"><code class=\"fm-code-in-text\">ConcurrentDictionary&lt;TKey,TVale&gt;<\/code> also has a <code class=\"fm-code-in-text\">TryRemove<\/code> method that will remove the value and return <code class=\"fm-code-in-text\">true<\/code> if the value existed and was removed. However, it will return <code class=\"fm-code-in-text\">false<\/code> if the value doesn\u2019t exist in the dictionary. Having a <code class=\"fm-code-in-text\">TryRemove<\/code> instead of a <code class=\"fm-code-in-text\">Remove<\/code> method solves the same kind of race condition we\u2019ve seen when we\u2019ve talked about <code class=\"fm-code-in-text\">Add<\/code> and <code class=\"fm-code-in-text\">TryAdd<\/code>.<a id=\"calibre_link-1130\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-1131\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><\/p>\n<p class=\"copyrightbody\">And finally, <code class=\"fm-code-in-text\">ConcurrentDictionary&lt;TKey,TVale&gt;<\/code> also has a <code class=\"fm-code-in-text\">TryUpdate<\/code> method. This method solves a problem where one thread might overwrite data written by another thread. As an example of this problem, let\u2019s write a method that increments a value in the dictionary. <a id=\"calibre_link-1132\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-291\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><\/p>\n<p class=\"fm-code-listing-caption\">Listing 13.9 Non&ndash;thread-safe increment<\/p>\n<pre class=\"programlisting\">private ConcurrentDictionary&lt;string, int&gt; _dictionary = new();\n \npublic void Increment(string key)\n{\n   int prevValue = _dictionary[key];\n   _dictionary[key] = prevValue+1;\n}<\/pre>\n<p class=\"copyrightbody\">This method reads the value associated with a key, adds one to the value, and writes the new value into the dictionary.<\/p>\n<p class=\"copyrightbody\">This code also has a race condition bug. Let\u2019s say the current value for a given key is 1, and we call <code class=\"fm-code-in-text\">Increment<\/code> simultaneously from two different threads. The expected result is that the value will be 3 (we started with 1 and incremented it twice), but if we\u2019re unlucky with our timing, we might get the following sequence:<\/p>\n<ol class=\"calibre9\">\n<li class=\"fm-list-bullet1\">\n<p class=\"list\">Thread 1 reads the value and gets 1.<\/p>\n<\/li>\n<li class=\"fm-list-bullet1\">\n<p class=\"list\">Thread 2 reads the value. Because the first thread hasn\u2019t written the new value yet, it also gets 1.<\/p>\n<\/li>\n<li class=\"fm-list-bullet1\">\n<p class=\"list\">Thread 1 increments and saves the value; the value in the dictionary is now 2.<\/p>\n<\/li>\n<li class=\"fm-list-bullet1\">\n<p class=\"list\">Thread 2 increments and saves the value; the value in the dictionary is still 2.<\/p>\n<\/li>\n<\/ol>\n<p class=\"copyrightbody\">To solve this problem, we must either add a lock around the entire operation or at least have a way to detect this problem so we can correct it. This is what <code class=\"fm-code-in-text\">TryUpdate<\/code> does.<\/p>\n<p class=\"fm-code-listing-caption\">Listing 13.10 Thread-safe increment with <code class=\"fm-code-in-text1\">ConcurrentDictionary.TryUpdate<\/code><\/p>\n<pre class=\"programlisting\">private ConcurrentDictionary&lt;string, int&gt; _dictionary = new();\n \npublic void Increment(string key)\n{\n   while(true)\n   {\n      int prevValue = _dictionary[key];\n      if(_dictionary.TryUpdate(key, prevValue+1, prevValue))\n         break;\n   }\n}<\/pre>\n<p class=\"copyrightbody\">Now the method enters a loop, and it reads the current value into the <code class=\"fm-code-in-text\">prevValue<\/code> variable. It then calls <code class=\"fm-code-in-text\">TryUpdate<\/code> with both the new value (<code class=\"fm-code-in-text\">prevValue+1<\/code>) and the old value (<code class=\"fm-code-in-text\">prevValue<\/code>). If the current value in the dictionary is still <code class=\"fm-code-in-text\">prevValue<\/code>, <code class=\"fm-code-in-text\">TryUpdate<\/code> will update the value and return <code class=\"fm-code-in-text\">true<\/code>. This will make our code break out of the loop. But if someone else changed the value in the dictionary, <code class=\"fm-code-in-text\">TryUpdate<\/code> will leave the dictionary unchanged and will return <code class=\"fm-code-in-text\">false<\/code>, which will make our code repeat the loop and retry incrementing the value until it succeeds.<\/p>\n<p class=\"copyrightbody\"><code class=\"fm-code-in-text\">ConcurrentDictionary&lt;TKey,TValue&gt;<\/code> doesn\u2019t have asynchronous interfaces, but it only blocks for a very short time, and it works very well with asynchronous code.<a id=\"calibre_link-221\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-1133\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-1134\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><\/p>\n<h3 class=\"fm-head\" id=\"calibre_link-114\">13.2.2 BlockingCollection&lt;T&gt;<\/h3>\n<p class=\"copyrightbody\"><code class=\"fm-code-in-text\">BlockingCollection&lt;T&gt;<\/code> adds blocking producer&ndash;consumer operations on top of another collection. Basically, it adds the ability to wait until an item becomes available. The options for the collection backing a <code class=\"fm-code-in-text\">BlockingCollection&lt;T&gt;<\/code> are <code class=\"fm-code-in-text\">ConcurrentQueue&lt;T&gt;<\/code>, <code class=\"fm-code-in-text\">ConcurrentStack&lt;T&gt;<\/code>, and <code class=\"fm-code-in-text\">ConcurrentBag&lt;T&gt;<\/code>. (We\u2019ll talk about them more in the next section.) <a id=\"calibre_link-1135\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-1136\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><\/p>\n<p class=\"copyrightbody\">The default option, and most used by an enormous margin, is <code class=\"fm-code-in-text\">ConcurrentQueue&lt;T&gt;<\/code>. A <code class=\"fm-code-in-text\">BlockingCollection&lt;T&gt;<\/code> backed by a <code class=\"fm-code-in-text\">ConcurrentQueue&lt;T&gt;<\/code> keeps the item order&mdash;like in a queue, the first item in is the first item out. We\u2019ve already seen back in chapter 8 how it can be used as the basis for a very simple and effective work queue.<\/p>\n<p class=\"copyrightbody\">The second used option is <code class=\"fm-code-in-text\">ConcurrentStack&lt;T&gt;<\/code>. A <code class=\"fm-code-in-text\">BlockingCollection&lt;T&gt;<\/code> backed by a <code class=\"fm-code-in-text\">ConcurrentStack&lt;T&gt;<\/code> acts like a stack&mdash;the last item to be added is the first item out. This is useful if you have a multithreaded algorithm that requires a thread-safe stack, which makes the consumer wait until another thread adds items to the stack if the stack is empty.<\/p>\n<p class=\"copyrightbody\">The last option, <code class=\"fm-code-in-text\">ConcurrentBag&lt;T&gt;<\/code>, is rarely used. <code class=\"fm-code-in-text\">ConcurrentBag&lt;T&gt;<\/code> is a specialized collection that is optimized for the case where the same thread both reads and writes from\/to the collection (more about this later in this chapter).<\/p>\n<p class=\"copyrightbody\">Apart from adding the ability to wait until an item is available, <code class=\"fm-code-in-text\">BlockingCollection&lt;T&gt;<\/code> also lets you specify the maximum size of the collection; this is useful in preventing the producer from getting too far ahead of the consumer. This feature is called <i class=\"fm-italics\">bounded capacity<\/i>.<\/p>\n<p class=\"copyrightbody\">The most common usage for <code class=\"fm-code-in-text\">BlockingCollection&lt;T&gt;<\/code> is as a work queue (like our work queue example in chapter 8, where we wrote a work queue implementation with a single background thread). Let\u2019s extend the code from chapter 8 and write a <code class=\"fm-code-in-text\">BlockingCollection&lt;T&gt;<\/code>-based queue with multiple consumer threads.<a id=\"calibre_link-1137\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><\/p>\n<p class=\"fm-code-listing-caption\">Listing 13.11 <code class=\"fm-code-in-text1\">BlockingCollection<\/code> with 10 processing threads<\/p>\n<pre class=\"programlisting\">BlockingCollection&lt;int&gt; blockingCollection = new BlockingCollection&lt;int&gt;();\nThread[] workers =  new Thread[10];\nfor(int i=0; i&lt;workers.Length; i++)                       <span class=\"fm-combinumeral\">\u2776<\/span>\n{\n   workers[i] = new Thread(threadNumber =&gt;\n   {\n      var rng = new Random((int)threadNumber);\n      int count = 0;\n      foreach (var currentValue in\n            blockingCollection.GetConsumingEnumerable())\n      {\n         Console.WriteLine($\"thread {threadNumber} value {currentValue}\");\n         Thread.Sleep(rng.Next(500));\n         count++;\n      }\n      Console.WriteLine($\"thread {threadNumber}, total {count} items\");\n   });\n   workers[i].Start(i);\n}\nfor(int i=0;i&lt;100;i++)                                    <span class=\"fm-combinumeral\">\u2777<\/span>\n{\n   blockingCollection.Add(i);\n}\nblockingCollection.CompleteAdding();                      <span class=\"fm-combinumeral\">\u2778<\/span>\nforeach (var curentThread in workers)                     <span class=\"fm-combinumeral\">\u2779<\/span>\n   curentThread.Join();<\/pre>\n<p class=\"copyrightbody\"><span class=\"fm-combinumeral\">\u2776<\/span> Creates 10 worker threads<\/p>\n<p class=\"copyrightbody\"><span class=\"fm-combinumeral\">\u2777<\/span> Adds 100 items to process<\/p>\n<p class=\"copyrightbody\"><span class=\"fm-combinumeral\">\u2778<\/span> Signals no more items<\/p>\n<p class=\"copyrightbody\"><span class=\"fm-combinumeral\">\u2779<\/span> Waits for all threads to finish<\/p>\n<p class=\"copyrightbody\">This code creates a <code class=\"fm-code-in-text\">BlockingCollection&lt;int&gt;<\/code> to hold the data we need to process in the background. It then starts 10 background threads to do this processing, and each thread uses <code class=\"fm-code-in-text\">foreach<\/code> and <code class=\"fm-code-in-text\">GetConsumingEnumerable<\/code> to get the items to process. To simulate the processing, we just wait a small random amount of time and print the number. We insert the numbers 0 to 99 into the queue as a stand-in for the data we want to process.<\/p>\n<p class=\"copyrightbody\">When we run this code, we see that it works&mdash;all the data is processed, each data item is processed exactly once, and data items are mostly processed in order. The items are processed mostly in order because while the <code class=\"fm-code-in-text\">BlockingCollection&lt;T&gt;<\/code> provides the items in order, timing problems will sometimes cause one thread to overtake a previous thread, making it look like the two items swapped position.<\/p>\n<p class=\"copyrightbody\">The bounded capacity feature mentioned earlier is mainly implemented by the <code class=\"fm-code-in-text\">Add<\/code> method. The <code class=\"fm-code-in-text\">Add<\/code> method adds an item to the collection. If the collection is at maximum capacity, it will block until some other thread removes an item. The <code class=\"fm-code-in-text\">TryAdd<\/code> method is similar but adds a timeout (that can be zero). If the collection is at maximum capacity, it will block until another thread removes an item or until the timeout elapses. If the timeout elapses, <code class=\"fm-code-in-text\">TryAdd<\/code> will fail and return <code class=\"fm-code-in-text\">false<\/code>. If the timeout is zero, <code class=\"fm-code-in-text\">TryAdd<\/code> will always return immediately.<a id=\"calibre_link-1138\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-1139\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><\/p>\n<p class=\"copyrightbody\">The <code class=\"fm-code-in-text\">Take<\/code> method returns the next item in the collection and removes it in a single thread-safe operation. The next item will be the oldest item in the collection if it\u2019s backed by a <code class=\"fm-code-in-text\">ConcurrentQueue&lt;T&gt;<\/code>, the newest if it\u2019s backed by a <code class=\"fm-code-in-text\">ConcurrentStack&lt;T&gt;<\/code>, or any of the items if the backing collection is a <code class=\"fm-code-in-text\">ConcurrentBag&lt;T&gt;<\/code>. If the collection is empty, <code class=\"fm-code-in-text\">Take<\/code> will block until another thread adds an item using <code class=\"fm-code-in-text\">Add<\/code> or <code class=\"fm-code-in-text\">TryAdd<\/code>. <code class=\"fm-code-in-text\">TryTake<\/code> (like <code class=\"fm-code-in-text\">TryAdd<\/code>) is the same as <code class=\"fm-code-in-text\">Take<\/code> with an added timeout. If the collection is empty, and the timeout elapses before an item becomes available, <code class=\"fm-code-in-text\">TryTake<\/code> will fail and return <code class=\"fm-code-in-text\">false<\/code>. If you pass zero as the timeout, <code class=\"fm-code-in-text\">TryTake<\/code> will always return immediately. <a id=\"calibre_link-1140\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><\/p>\n<p class=\"copyrightbody\">The most common way to read data from a <code class=\"fm-code-in-text\">BlockingCollection&lt;T&gt;<\/code> is to use <code class=\"fm-code-in-text\">foreach<\/code> with <code class=\"fm-code-in-text\">GetConsumingEnumerable<\/code>, like we did in chapter 8, instead of calling <code class=\"fm-code-in-text\">Take<\/code> or <code class=\"fm-code-in-text\">TryTake<\/code> directly. <code class=\"fm-code-in-text\">GetConsumingEnumerable<\/code> returns an <code class=\"fm-code-in-text\">IEnumerable&lt;T&gt;<\/code> that, when used with <code class=\"fm-code-in-text\">foreach<\/code>, removes the current item at every iteration of the loop and, if the collection is empty, blocks until another thread adds an item to the collection. It is basically equivalent to calling <code class=\"fm-code-in-text\">Take<\/code> at the beginning of every loop iteration.<\/p>\n<p class=\"copyrightbody\">If we use <code class=\"fm-code-in-text\">GetConsumingEnumerable<\/code> and <code class=\"fm-code-in-text\">foreach<\/code>, we need a way to signal that there are no new items and we can exit the loop. This is done with <code class=\"fm-code-in-text\">CompleteAdding<\/code>. After calling <code class=\"fm-code-in-text\">CompleteAdding<\/code>, the <code class=\"fm-code-in-text\">foreach<\/code> loop will continue to process all remaining items in the collection and then exit. Calling <code class=\"fm-code-in-text\">Add<\/code> or <code class=\"fm-code-in-text\">TryAdd<\/code> after <code class=\"fm-code-in-text\">CompleteAdding<\/code> will throw an <code class=\"fm-code-in-text\">InvalidOperationException<\/code>.<a id=\"calibre_link-1141\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><\/p>\n<p class=\"copyrightbody\"><code class=\"fm-code-in-text\">BlockingCollection&lt;T&gt;<\/code> also has the static <code class=\"fm-code-in-text\">AddToAny<\/code>, <code class=\"fm-code-in-text\">TryAddToAny<\/code>, <code class=\"fm-code-in-text\">TakeFromAny<\/code>, and <code class=\"fm-code-in-text\">TryTakeFromAny<\/code> methods. They work like their non-static counterparts except that they accept an array of <code class=\"fm-code-in-text\">BlockingCollection&lt;T&gt;<\/code> objects and use one of them based on the number of items in each collection. They look like a good way to build a system with multiple consumer threads where every thread has its own <code class=\"fm-code-in-text\">BlockingCollection&lt;T&gt;<\/code>, but they\u2019re not. <a id=\"calibre_link-1142\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-1143\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-1144\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-146\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-1145\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><\/p>\n<p class=\"copyrightbody\"><code class=\"fm-code-in-text\">AddToAny<\/code> and <code class=\"fm-code-in-text\">TryAddToAny<\/code> do not provide any load balancing. They\u2019re optimized to complete the <code class=\"fm-code-in-text\">AddToAny<\/code> operation as quickly as possible, so they will always look for the fastest option to add to a collection. In most cases, they will just add the item to the first collection that is not at maximum capacity. So <code class=\"fm-code-in-text\">AddToAny<\/code> and <code class=\"fm-code-in-text\">TryAddToAny<\/code> will tend to add items to the same <code class=\"fm-code-in-text\">BlockingCollection&lt;T&gt;<\/code>. If you use them to build a multiple processing threads system, then one thread will receive most of the work, and the rest of the threads will be idle most of the time.<\/p>\n<p class=\"copyrightbody\"><code class=\"fm-code-in-text\">BlockingCollection&lt;T&gt;<\/code> is very useful if you manage your own threads, but as its name implies, it uses blocking operations and thus doesn\u2019t fit the asynchronous programming model. <a id=\"calibre_link-1146\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-1147\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><\/p>\n<h3 class=\"fm-head\" id=\"calibre_link-115\">13.2.3 Async alternatives for BlockingCollection<\/h3>\n<p class=\"copyrightbody\">As of .NET version 8, the .NET standard library does not have asynchronous collections in general and does not have an asynchronous version of <code class=\"fm-code-in-text\">BlockingCollection&lt;T&gt;<\/code>. However, it does have several other classes that can be repurposed as an asynchronous queue. One of those is <code class=\"fm-code-in-text\">Channel&lt;T&gt;<\/code>, a thread-safe multiple-producers multiple-consumers queue, designed for communication between software components.<a id=\"calibre_link-1148\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-1149\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><\/p>\n<p class=\"copyrightbody\">The <code class=\"fm-code-in-text\">Channel&lt;T&gt;<\/code> class represents a communication channel; each channel has a writer that can add messages to the channel and a reader that can take messages from the channel. The channel keeps the message ordering, which makes it equivalent to a queue. Both the reader and the writer explicitly support concurrent access.<a id=\"calibre_link-1150\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-220\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><\/p>\n<p class=\"copyrightbody\">We can translate listing 13.11 to use <code class=\"fm-code-in-text\">Channel&lt;T&gt;<\/code> instead of <code class=\"fm-code-in-text\">BlockingCollection&lt;T&gt;<\/code> and get the following.<\/p>\n<p class=\"fm-code-listing-caption\">Listing 13.12 <code class=\"fm-code-in-text1\">Async<\/code> background processing with <code class=\"fm-code-in-text1\">Channel&lt;T&gt;<\/code><\/p>\n<pre class=\"programlisting\">var ch = Channel.CreateUnbounded&lt;int&gt;();\nTask[] tasks = new Task[10];\nfor(int i=0; i&lt;10;++i)                                       <span class=\"fm-combinumeral\">\u2776<\/span>\n{\n   var threadNumber = i;\n   tasks[i] = Task.Run(async () =&gt;\n   {\n      var rng = new Random((int)threadNumber);\n      int count = 0;\n      while (true)\n      {\n         try\n         {\n            var currentValue = await ch.Reader.ReadAsync();  <span class=\"fm-combinumeral\">\u2777<\/span>\n            Console.WriteLine($\"task {threadNumber} value {currentValue}\");\n            Thread.Sleep(rng.Next(500));\n            count++;\n         } \n         catch(ChannelClosedException)                       <span class=\"fm-combinumeral\">\u2778<\/span>\n         {\n            break;\n         }\n      }\n      Console.WriteLine($\"task {threadNumber}, total {count} items\");\n   });\n}\nfor (int i = 0; i &lt; 100; i++)                                <span class=\"fm-combinumeral\">\u2779<\/span>\n{\n   await ch.Writer.WriteAsync(i);\n}\nch.Writer.Complete();                                        <span class=\"fm-combinumeral\">\u277a<\/span>\nTask.WaitAll(tasks);                                         <span class=\"fm-combinumeral\">\u277b<\/span><\/pre>\n<p class=\"copyrightbody\"><span class=\"fm-combinumeral\">\u2776<\/span> Starts 10 async tasks<\/p>\n<p class=\"copyrightbody\"><span class=\"fm-combinumeral\">\u2777<\/span> Awaits next data item<\/p>\n<p class=\"copyrightbody\"><span class=\"fm-combinumeral\">\u2778<\/span> This exception means no more data.<\/p>\n<p class=\"copyrightbody\"><span class=\"fm-combinumeral\">\u2779<\/span> Adds 100 items to process<\/p>\n<p class=\"copyrightbody\"><span class=\"fm-combinumeral\">\u277a<\/span> Signals no more data<\/p>\n<p class=\"copyrightbody\"><span class=\"fm-combinumeral\">\u277b<\/span> Waits for all tasks to complete<\/p>\n<p class=\"copyrightbody\">Here we create a <code class=\"fm-code-in-text\">Channel&lt;T&gt;<\/code> instead of a <code class=\"fm-code-in-text\">BlockingCollection&lt;T&gt;<\/code>, and instead of creating a thread, we use <code class=\"fm-code-in-text\">Task.Run<\/code>. The code we pass to <code class=\"fm-code-in-text\">Task.Run<\/code> will start running on a thread pool thread and then immediately use <code class=\"fm-code-in-text\">await<\/code> to release the thread. We could skip this step with some clever use of <code class=\"fm-code-in-text\">ContinueWith<\/code>, but it would make the code more complicated.<\/p>\n<p class=\"copyrightbody\">The biggest change from listing 13.11 is that instead of using <code class=\"fm-code-in-text\">foreach<\/code>, we need to use <code class=\"fm-code-in-text\">while(true)<\/code>, and we need to use an exception to detect when we should exit. We will see what we can do about this in the next chapter.<\/p>\n<h3 class=\"fm-head\" id=\"calibre_link-116\">13.2.4 ConcurrentQueue&lt;T&gt; and ConcurrentStack&lt;T&gt;<\/h3>\n<p class=\"copyrightbody\"><code class=\"fm-code-in-text\">ConcurrentQueue&lt;T&gt;<\/code> is a thread-safe version of <code class=\"fm-code-in-text\">Queue&lt;T&gt;<\/code>, and <code class=\"fm-code-in-text\">ConcurrentStack&lt;T&gt;<\/code> is a thread-safe version of <code class=\"fm-code-in-text\">Stack&lt;T&gt;<\/code>. <code class=\"fm-code-in-text\">ConcurrentQueue&lt;T&gt;<\/code> is a FIFO (first in, first out) data structure, which means that when you read the next item, you always get the oldest item in the queue. <code class=\"fm-code-in-text\">ConcurrentStack&lt;T&gt;<\/code> is a LIFO (last in, first out) data structure, which means the next item will always be the most recent one.<a id=\"calibre_link-1151\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-1152\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-1153\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-223\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-1154\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><\/p>\n<p class=\"copyrightbody\">Both <code class=\"fm-code-in-text\">ConcurrentQueue&lt;T&gt;<\/code> and <code class=\"fm-code-in-text\">ConcurrentStack&lt;T&gt;<\/code> provide the same methods for adding items as their non&ndash;thread-safe counterparts (<code class=\"fm-code-in-text\">Enqueue<\/code> for <code class=\"fm-code-in-text\">ConcurrentQueue&lt;T&gt;<\/code> and <code class=\"fm-code-in-text\">Push<\/code> for <code class=\"fm-code-in-text\">ConcurrentStack&lt;T&gt;<\/code>), and both provide a way to get the next item (<code class=\"fm-code-in-text\">TryDequeue<\/code> and <code class=\"fm-code-in-text\">TryPop<\/code>, respectively). The interface is different from the non&ndash;thread-safe version for the same reasons that we\u2019ve seen when we\u2019ve talked about <code class=\"fm-code-in-text\">ConcurrentDictionary&lt;TKey,TValue&gt;<\/code>. If we had a thread-safe version with the same interface as <code class=\"fm-code-in-text\">Queue&lt;T&gt;<\/code>, we would need to write code like this:<\/p>\n<pre class=\"programlisting\">var queue = new Queue&lt;int&gt;();\n\/\/ ....\nif(queue.Count &gt; 0)\n{                                                    <span class=\"fm-combinumeral\">\u2776<\/span>\n    var next = queue.Dequeue();\n    \/\/ use next\n}<\/pre>\n<p class=\"copyrightbody\"><span class=\"fm-combinumeral\">\u2776<\/span> Another thread can dequeue the last item here.<\/p>\n<p class=\"copyrightbody\">This code checks whether there are items in the queue and then dequeues the next item; however, in multithread code, another thread can always dequeue the last item between the time we checked and the time we dequeued. This means that even if we had a thread-safe class with the same interface as <code class=\"fm-code-in-text\">Queue&lt;T&gt;<\/code>, it would have been difficult to use it to write thread-safe code. In contrast, with the <code class=\"fm-code-in-text\">ConcurrentQueue&lt;T&gt;<\/code> interface, we write code like this:<\/p>\n<pre class=\"programlisting\">var queue = new ConcurrentQueue&lt;int&gt;();\n\/\/ ....\nif(queue.TryDequeue(out var next))                   <span class=\"fm-combinumeral\">\u2776<\/span>\n{\n    \/\/ use next\n}<\/pre>\n<p class=\"copyrightbody\"><span class=\"fm-combinumeral\">\u2776<\/span> Check and dequeue are combined.<\/p>\n<p class=\"copyrightbody\">Here the check and dequeue operations are combined into a single <code class=\"fm-code-in-text\">TryDequeue<\/code> call, which eliminates the time window between the check and the dequeue operation and solves this problem.<\/p>\n<p class=\"copyrightbody\">You can use <code class=\"fm-code-in-text\">ConcurrentQueue&lt;T&gt;<\/code> and <code class=\"fm-code-in-text\">ConcurrentStack&lt;T&gt;<\/code> directly if you need a thread-safe queue or stack and don\u2019t need a mechanism to signal when an item is available for processing. However, they are most useful in conjunction with <code class=\"fm-code-in-text\">BlockingCollection&lt;T&gt;<\/code>.<\/p>\n<h3 class=\"fm-head\" id=\"calibre_link-117\">13.2.5 ConcurrentBag&lt;T&gt;<\/h3>\n<p class=\"copyrightbody\">Unlike <code class=\"fm-code-in-text\">ConcurrentQueue&lt;T&gt;<\/code> and <code class=\"fm-code-in-text\">ConcurrentStack&lt;T&gt;<\/code>, <code class=\"fm-code-in-text\">ConcurrentBag&lt;T&gt;<\/code> doesn\u2019t have a parallel outside of the concurrent collections. The <code class=\"fm-code-in-text\">ConcurrentBag&lt;T&gt;<\/code> data structure does not enforce item ordering. When you retrieve items from the bag, you can get them in any order. <code class=\"fm-code-in-text\">ConcurrentBag&lt;T&gt;<\/code> can store duplicate items. <code class=\"fm-code-in-text\">ConcurrentBag&lt;T&gt;<\/code> has an <code class=\"fm-code-in-text\">Add<\/code> method for adding items and a <code class=\"fm-code-in-text\">TryTake<\/code> method for retrieving and removing the items in the collection. <a id=\"calibre_link-1155\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-1156\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-1157\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-222\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-1158\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><\/p>\n<p class=\"copyrightbody\">The implementation of <code class=\"fm-code-in-text\">ConcurrentBag&lt;T&gt;<\/code> uses per-thread queues, and <code class=\"fm-code-in-text\">TryTake<\/code> will try to provide items inserted by the same thread. This is helpful because with per-thread queues, the <code class=\"fm-code-in-text\">ConcurrentBag&lt;T&gt;<\/code> doesn\u2019t have to block if two threads try to retrieve an item simultaneously. If an item added by the current thread isn\u2019t available, <code class=\"fm-code-in-text\">TryTake<\/code> will get an item from another thread\u2019s queue (this is called <i class=\"fm-italics\">work stealing<\/i>), which requires thread synchronization and so is slower.<\/p>\n<p class=\"copyrightbody\">That is why you should only use <code class=\"fm-code-in-text\">ConcurrentBag&lt;T&gt;<\/code> if the same thread (or set of threads) both add and retrieve items from the bag. For example, you should only use <code class=\"fm-code-in-text\">ConcurrentBag&lt;T&gt;<\/code> as the backing collection for a <code class=\"fm-code-in-text\">BlockingCollection&lt;T&gt;<\/code>-based work queue if the code that handles items in the collection also adds them. Also, you shouldn\u2019t use <code class=\"fm-code-in-text\">ConcurrentBag&lt;T&gt;<\/code> in asynchronous code because typically, you don\u2019t control which thread runs it.<\/p>\n<h3 class=\"fm-head\" id=\"calibre_link-118\">13.2.6 When to use the concurrent collections<\/h3>\n<p class=\"copyrightbody\"><code class=\"fm-code-in-text\">ConcurrentDictionary&lt;TKey,TValue&gt;<\/code> is a very good thread-safe alternative to <code class=\"fm-code-in-text\">Dictionary&lt;TKey,TValue&gt;<\/code>. We\u2019ve already seen examples of using it as an in-process cache. It can be used anytime we need to access a dictionary from multiple threads at the same time. Also, it can be used in both asynchronous and non-asynchronous code.<a id=\"calibre_link-1159\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-1160\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><\/p>\n<p class=\"copyrightbody\">Likewise, <code class=\"fm-code-in-text\">ConcurrentQueue&lt;T&gt;<\/code> and <code class=\"fm-code-in-text\">ConcurrentStack&lt;T&gt;<\/code> are good thread-safe implementations of the queue and stack data structures. We can use them whenever we need concurrent access to a queue or a stack, and we don\u2019t need a built-in mechanism to signal when items are available. They are also perfectly usable in both asynchronous and non-asynchronous code.<\/p>\n<p class=\"copyrightbody\">If you do need this signal and want the consumer thread to block when there\u2019s no work available, then <code class=\"fm-code-in-text\">BlockingCollection&lt;T&gt;<\/code> is a perfect fit. However, <code class=\"fm-code-in-text\">BlockingCollection&lt;T&gt;<\/code>, especially <code class=\"fm-code-in-text\">Take<\/code> and <code class=\"fm-code-in-text\">GetConsumingEnumerable<\/code>, does not fit the asynchronous programming model.<\/p>\n<h3 class=\"fm-head\" id=\"calibre_link-119\">13.2.7 When not to use the concurrent collections<\/h3>\n<p class=\"copyrightbody\">If we need to use a lock to make our own code thread safe (except for just protecting access to the collection), then we use this lock to synchronize access to our code (and the collection) and don\u2019t need to use a collection that supports concurrent access. In this case, the non&ndash;thread-safe alternatives (<code class=\"fm-code-in-text\">Dictionary&lt;TKey,TValue&gt;<\/code>, <code class=\"fm-code-in-text\">Queue&lt;T&gt;<\/code>, and <code class=\"fm-code-in-text\">Stack&lt;T&gt;<\/code>) are simpler and faster.<a id=\"calibre_link-1161\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-1162\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><\/p>\n<p class=\"copyrightbody\">If you do need thread safety because you pass the collection to some (maybe external) code that doesn\u2019t need to modify the collection and can work if the collection is a little bit stale (that is, not completely up to date), you should look into using the immutable collections instead.<a id=\"calibre_link-1163\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-1164\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><\/p>\n<h2 class=\"fm-head\" id=\"calibre_link-120\">13.3 The immutable collections<\/h2>\n<p class=\"copyrightbody\">The problems of thread safety always boil down to multiple threads modifying the data simultaneously, threads reading while other threads are modifying the data, or timing problems making threads modify data in the wrong order. All those problems are about modifying data&mdash;if you never modify data, you won\u2019t have any of those problems, and your code will be inherently thread safe.<a id=\"calibre_link-149\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-1165\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-1166\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><\/p>\n<p class=\"copyrightbody\">While the concurrent collections use clever locking and lockless strategies to make it safe to modify a collection by multiple threads simultaneously, the immutable collections achieve thread safety by simply being immutable. If they can\u2019t be modified at all, they can\u2019t be modified by two threads at the same time.<\/p>\n<p class=\"copyrightbody\">The immutable collections work like the .NET <code class=\"fm-code-in-text\">String<\/code> class. All the methods that modify the collection actually leave the collection untouched and return a brand-new collection that is a copy of the original collection with the requested modifications.<\/p>\n<p class=\"copyrightbody\">It might seem like all this copying is wasteful and can cause poor performance and excessive memory usage problems, but the immutable collections mitigate this problem by using internal data structures that can share parts of the data between collections. Therefore, creating a modified copy of a collection is cheap (or, at least, cheaper than copying the entire collection).<\/p>\n<h3 class=\"fm-head\" id=\"calibre_link-121\">13.3.1 How immutable collections work<\/h3>\n<p class=\"copyrightbody\">If you look at the standard collections, you will find that they are all based on arrays. The reason is that due to the way the CPU accesses memory, arrays are the most performant data storage option. <code class=\"fm-code-in-text\">List&lt;T&gt;<\/code> is just a wrapper around an array. <code class=\"fm-code-in-text\">Queue&lt;T&gt;<\/code> and <code class=\"fm-code-in-text\">Stack&lt;T&gt;<\/code> are also arrays. <code class=\"fm-code-in-text\">HashSet&lt;T&gt;<\/code> is a hash table implemented by using two arrays, and <code class=\"fm-code-in-text\">Dictionary&lt;TKey,TValue&gt;<\/code> is implemented using four arrays. Everything is based on arrays. However, arrays are just contiguous&nbsp;blocks of memory; you can\u2019t share memory between arrays, which is why the immutable collections generally don\u2019t use them and instead opt for data structures that do support sharing parts of the memory between collections. <a id=\"calibre_link-1167\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-1168\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><\/p>\n<div class=\"fm-sidebar-block\">\n<p class=\"fm-sidebar-title\">Why arrays are more efficient than other data structures<\/p>\n<p class=\"copyrightbody\">The CPU is much faster than the computer\u2019s memory. For example, for a 2GHz CPU, each CPU clock cycle is 0.5 nano seconds, while access to DDR5 memory takes around 16.67 nano seconds, give or take. Applying a little bit of math shows us that a CPU can perform about 33 internal operations in the time it takes it to retrieve anything from memory.<a id=\"calibre_link-1169\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><\/p>\n<p class=\"copyrightbody\">Obviously, having the CPU on idle and waiting for data to arrive from memory most of the time would be bad, so clever CPU designers devised a solution&mdash;just add a little bit of memory into the CPU chip. This memory runs nearly as fast as the CPU processing cores (the reason we can\u2019t make all the computer\u2019s memory this fast is cost). We call this memory the <i class=\"fm-italics\">CPU cache memory<\/i>. We also have a hardware component inside the CPU chip that is called the <i class=\"fm-italics\">cache controller<\/i>. One of the things the cache controller does is try to preload data from the main memory into the CPU cache before we need it.<\/p>\n<p class=\"copyrightbody\">Arrays are contiguous blocks of memory. All the items in the array are stored in memory one after the other; when we iterate an array, we scan this memory sequentially. If you scan memory sequentially, it\u2019s easy for the cache controller to guess the next value you are going to retrieve from memory&mdash;it\u2019s the value immediately after your previous memory access.<\/p>\n<p class=\"copyrightbody\">Other data structures, such as linked lists and trees, are not contiguous in memory. To get the memory address of the next item in a linked list, you must read the current item\u2019s node and extract the \u201cnext\u201d field from it. Linked lists and trees do not have a standard node layout, and the cache controller doesn\u2019t know how to parse nodes of whatever data structure from whichever library your program may be using.<\/p>\n<p class=\"copyrightbody\">That is why when you scan an array, the next value will most likely will be waiting for you in the cache ready for immediate access; however, when you access another data structure, the CPU will spend a significant amount of time waiting for data to be transferred from the computer\u2019s main memory.<\/p>\n<p class=\"copyrightbody\">And a quick note for the readers that know about CPU design and are screaming at the book about cache lines and clock cycles per operation: you are obviously right, but this is not a book about hardware design, and the explanation here is correct enough to explain the performance characteristics of arrays.<\/p>\n<\/p><\/div>\n<p class=\"copyrightbody\">To understand the tricks used by immutable collections, we will implement an immutable stack. But before we do so, we need a regular array-based stack to compare it to.<\/p>\n<p class=\"copyrightbody\">We will implement the simplest thread-safe stack possible. Our stack will only have two methods: a <code class=\"fm-code-in-text\">Push<\/code> method that adds an item to the top of the stack and a <code class=\"fm-code-in-text\">TryPop<\/code> method that retrieves the item at the top of the stack or returns <code class=\"fm-code-in-text\">false<\/code> if the stack is empty. We will also limit our array-based stack to just 10 items because I want to focus on how the immutable stack works and not on how to resize the array-based stack. We will achieve thread safety by using a lock to protect all access to the stack.<a id=\"calibre_link-1170\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-287\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-1171\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><\/p>\n<p class=\"fm-code-listing-caption\">Listing 13.13 Simple stack implementation<\/p>\n<pre class=\"programlisting\">public class MyStack&lt;T&gt;\n{\n   private T?[] _data = new T[10];\n   private int _top = -1;\n   private object _lock = new();\n    \n   public void Push(T item)\n   {\n      lock(_lock)\n      {\n         if(_top == _data.Length-1) throw new Exception(\"Stack full\");\n         _top++;\n         _data[_top] = item;\n      }\n   }\n   public bool TryPop(out T? item)\n   {\n      if(_top==-1)\n      {\n          item = default(T);\n          return false;\n      }\n      item = _data[_top];\n      _data[_top] = default(T);\n      _top--;\n      return true;\n   }\n}<\/pre>\n<p class=\"copyrightbody\">Now let\u2019s see what happens when we run the following test code.<\/p>\n<p class=\"fm-code-listing-caption\">Listing 13.14 Test code for simple stack<\/p>\n<pre class=\"programlisting\">var stack = new MyStack&lt;int&gt;();\nstack.Push(1);\nstack.Push(2);\nstack.TryPop(out var item);<\/pre>\n<p class=\"copyrightbody\">This code creates a stack and then pushes two values (one and two); it will then pop the last value out.<\/p>\n<p class=\"copyrightbody\"><a id=\"calibre_link-1172\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a>Let\u2019s see what happens inside the stack when we run the test code. When we create the stack, <code class=\"fm-code-in-text\">_top<\/code> is set to \u22121 in our constructor (virtually pointing to the nonexistent item before the start of the array), and <code class=\"fm-code-in-text\">_data<\/code> is initialized by the runtime to all zeros (figure 13.2).<\/p>\n<div class=\"figure\">\n<p class=\"figure1\"><img decoding=\"async\" alt=\"\" class=\"calibre29\" src=\"\/images\/CSConcurrency_Asynchronous\/000016.png\" \/><\/p>\n<p class=\"figure1\">Figure 13.2 Simple stack initial state<\/p>\n<\/p><\/div>\n<p class=\"copyrightbody\">After the <code class=\"fm-code-in-text\">Push(1)<\/code> call, we increment <code class=\"fm-code-in-text\">_top<\/code> to zero, making it point at the current top of the stack and store 1 into the new top (which is <code class=\"fm-code-in-text\">_data[0]<\/code>; figure 13.3).<\/p>\n<div class=\"figure\">\n<p class=\"figure1\"><img decoding=\"async\" alt=\"\" class=\"calibre29\" src=\"\/images\/CSConcurrency_Asynchronous\/000017.png\" \/><\/p>\n<p class=\"figure1\">Figure 13.3 Simple stack after first push<\/p>\n<\/p><\/div>\n<p class=\"copyrightbody\">The <code class=\"fm-code-in-text\">Push(2)<\/code> call will increment <code class=\"fm-code-in-text\">_top<\/code> again to 1, indicating that <code class=\"fm-code-in-text\">_data[1]<\/code> is now top of the stack, and store 2 into the new top (figure 13.4).<\/p>\n<div class=\"figure\">\n<p class=\"figure1\"><img decoding=\"async\" alt=\"\" class=\"calibre30\" src=\"\/images\/CSConcurrency_Asynchronous\/000018.png\" \/><\/p>\n<p class=\"figure1\">Figure 13.4 Simple stack after second push<\/p>\n<\/p><\/div>\n<p class=\"copyrightbody\"><a id=\"calibre_link-258\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a>The <code class=\"fm-code-in-text\">TryPop<\/code> call will return the item at the current top of the stack (<code class=\"fm-code-in-text\">_data[1]<\/code>) using the item <code class=\"fm-code-in-text\">out<\/code> parameter. It will also zero out the current top and decrement <code class=\"fm-code-in-text\">_top<\/code> to zero indicating the new top is <code class=\"fm-code-in-text\">_data[0]<\/code>, effectively returning the stack to the same state as before the last push (figure 13.5).<\/p>\n<div class=\"figure\">\n<p class=\"figure1\"><img decoding=\"async\" alt=\"\" class=\"calibre29\" src=\"\/images\/CSConcurrency_Asynchronous\/000017.png\" \/><\/p>\n<p class=\"figure1\">Figure 13.5 Simple stack after pop<\/p>\n<\/p><\/div>\n<p class=\"copyrightbody\">Now that you understand how a standard stack works, let\u2019s implement an immutable stack. With an immutable stack, we no longer change the stack. Instead, each call will return a new stack. We will have a <code class=\"fm-code-in-text\">Push<\/code> method, a <code class=\"fm-code-in-text\">Pop<\/code> method, and an <code class=\"fm-code-in-text\">IsEmpty<\/code> property. In the regular implementation, we had to combine <code class=\"fm-code-in-text\">Pop<\/code> and <code class=\"fm-code-in-text\">IsEmpty<\/code> into a single <code class=\"fm-code-in-text\">TryPop<\/code> method because we have no way to prevent another thread from modifying the stack between the <code class=\"fm-code-in-text\">IsEmpty<\/code> check and the <code class=\"fm-code-in-text\">Pop<\/code> call. With the immutable stack, no one can modify the stack at all, so no one can modify the stack between the <code class=\"fm-code-in-text\">IsEmpty<\/code> check and the <code class=\"fm-code-in-text\">Pop<\/code> call. As the stack is immutable, <code class=\"fm-code-in-text\">Push<\/code> and <code class=\"fm-code-in-text\">Pop<\/code> will not modify the stack but will return a new stack with an item added or removed.<a id=\"calibre_link-1173\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-1174\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-1175\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-1176\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><\/p>\n<p class=\"copyrightbody\">If we keep using an array, we\u2019ll have to copy the entire array on every <code class=\"fm-code-in-text\">Push<\/code> and <code class=\"fm-code-in-text\">Pop<\/code>, and obviously, we don\u2019t want that. Luckily, we can implement a stack using a singly linked list.<\/p>\n<p class=\"fm-code-listing-caption\">Listing 13.15 Immutable stack implementation<\/p>\n<pre class=\"programlisting\">public class MyImmutableStack&lt;T&gt;\n{\n   private record class StackItem(T Value, StackItem Next);\n   private readonly StackItem? _top;\n   public MyImmutableStack() {}\n   private MyImmutableStack(StackItem? top)\n   {\n      _top = top;\n   }\n   public MyImmutableStack&lt;T&gt; Push(T item)\n   {\n      return new MyImmutableStack&lt;T&gt;(new StackItem(item,_top); \n   }\n   public MyImmutableStack&lt;T&gt; Pop(out T? item)\n   {\n      if(_top == null)\n         throw new InvalidOperationException(\"Stack is empty\");\n      item = _top.Value;\n      return new MyImmutableStack&lt;T&gt;(_top.Next);\n   }\n   public bool IsEmpty =&gt; _top == null;\n}<\/pre>\n<p class=\"copyrightbody\">Now we\u2019ll run the equivalent code to listing 13.14 on this new immutable stack.<a id=\"calibre_link-295\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><\/p>\n<p class=\"fm-code-listing-caption\">Listing 13.16 Test code for immutable stack<\/p>\n<pre class=\"programlisting\">var stack1 = new MyImmutableStack&lt;int&gt; ();\nvar stack2 = stack1.Push(1);\nvar stack3 = stack2.Push(2);\nvar Stack4 = stack3.Pop(out var item);<\/pre>\n<p class=\"copyrightbody\">This code creates a new empty stack and assigns it to the <code class=\"fm-code-in-text\">stack1<\/code> variable. Next, it calls <code class=\"fm-code-in-text\">Push<\/code>, which creates another stack with the new item and assigns it to the <code class=\"fm-code-in-text\">stack2<\/code> variable. It then calls <code class=\"fm-code-in-text\">Push<\/code> again, which also creates a new stack with an additional item and stores it as <code class=\"fm-code-in-text\">stack3<\/code>. Finally, it calls <code class=\"fm-code-in-text\">Pop<\/code>, which creates yet another stack, but this time with the top item removed, and puts it in the <code class=\"fm-code-in-text\">stack4<\/code> variable.<a id=\"calibre_link-1177\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-1178\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-1179\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-1180\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><\/p>\n<p class=\"copyrightbody\">Let\u2019s see what happens inside the immutable stack when we run the test code. The <code class=\"fm-code-in-text\">MyImmutableStack<\/code> parameterless constructor will create a new stack that has no <code class=\"fm-code-in-text\">StackItem<\/code> (<code class=\"fm-code-in-text\">_top<\/code> will be <code class=\"fm-code-in-text\">null<\/code>) (figure 13.6).<\/p>\n<div class=\"figure\">\n<p class=\"figure1\"><img decoding=\"async\" alt=\"\" class=\"calibre31\" src=\"\/images\/CSConcurrency_Asynchronous\/000019.png\" \/><\/p>\n<p class=\"figure1\">Figure 13.6 Immutable stack initial state<\/p>\n<\/p><\/div>\n<p class=\"copyrightbody\">The <code class=\"fm-code-in-text\">Push(1)<\/code> call will also create a new stack, which will have a single stack item with <code class=\"fm-code-in-text\">Value<\/code> set to 1 and <code class=\"fm-code-in-text\">Next<\/code> set to the previous <code class=\"fm-code-in-text\">_top<\/code> (<code class=\"fm-code-in-text\">null<\/code>) (figure 13.7).<\/p>\n<div class=\"figure\">\n<p class=\"figure1\"><img decoding=\"async\" alt=\"\" class=\"calibre32\" src=\"\/images\/CSConcurrency_Asynchronous\/000020.png\" \/><\/p>\n<p class=\"figure1\">Figure 13.7 Immutable stack after first push<\/p>\n<\/p><\/div>\n<p class=\"copyrightbody\">The <code class=\"fm-code-in-text\">Push(2)<\/code> call will create a new stack and a new <code class=\"fm-code-in-text\">StackItem<\/code>. The new <code class=\"fm-code-in-text\">StackItem<\/code> will have <code class=\"fm-code-in-text\">Value<\/code> set to 2 and <code class=\"fm-code-in-text\">Next<\/code> pointing to <code class=\"fm-code-in-text\">stack2<\/code>\u2019s _<code class=\"fm-code-in-text\">top<\/code>, which is the existing <code class=\"fm-code-in-text\">StackItem<\/code> storing the value 1. Note that now two stacks are sharing this first <code class=\"fm-code-in-text\">StackItem<\/code> (figure 13.8).<\/p>\n<div class=\"figure\">\n<p class=\"figure1\"><img decoding=\"async\" alt=\"\" class=\"calibre33\" src=\"\/images\/CSConcurrency_Asynchronous\/000021.png\" \/><\/p>\n<p class=\"figure1\">Figure 13.8 Immutable stack after second push<\/p>\n<\/p><\/div>\n<p class=\"copyrightbody\"><a id=\"calibre_link-1181\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a>Finally, the <code class=\"fm-code-in-text\">Pop<\/code> call will, unsurprisingly, create a new stack. The new stack will point to <code class=\"fm-code-in-text\">_top.Next<\/code>, that is, to the old <code class=\"fm-code-in-text\">StackItem<\/code> with the value 1 that will now be shared between the three stacks (figure 13.9).<\/p>\n<div class=\"figure\">\n<p class=\"figure1\"><img decoding=\"async\" alt=\"\" class=\"calibre34\" src=\"\/images\/CSConcurrency_Asynchronous\/000022.png\" \/><\/p>\n<p class=\"figure1\">Figure 13.9 Immutable stack after pop<\/p>\n<\/p><\/div>\n<p class=\"copyrightbody\">Usually, we will reuse the same variable and not create a new variable for each version of the stack (we\u2019ll have just one variable instead of <code class=\"fm-code-in-text\">stack1<\/code>, <code class=\"fm-code-in-text\">stack2<\/code>, <code class=\"fm-code-in-text\">stack3<\/code>, and <code class=\"fm-code-in-text\">stack4<\/code>); however, this does not change anything (except that, with the separate variable names, the figures area is easier to understand). Even if we reuse the variables, all the old stacks will still hang around in memory until the next time the garbage collector runs and frees them.<\/p>\n<p class=\"copyrightbody\">Now you can see how every operation on the immutable stack creates a new stack with a negligible amount of work and without copying any of the items already in the stack. This is at the cost of using a little bit more memory (each item now has the <code class=\"fm-code-in-text\">Next<\/code> reference and all the overhead of an object) and having the items spread around in memory instead of being stored sequentially in an array (which, because of CPU cache design, slows down the access to them).<\/p>\n<p class=\"copyrightbody\">I\u2019ve chosen to demonstrate how the immutable stack works because this is the simplest of the immutable collections; however, they all use the same basic tactic&mdash;place the data inside node objects and design your operation so that every \u201cmodified\u201d copy can share most of the previous collection\u2019s nodes. As we\u2019ve seen, a stack can be implemented with just one linked list. A queue needs two linked lists, and most of the other immutable collections use some kind of binary tree. The implementation details of all the immutable collections are outside the scope of this book.<a id=\"calibre_link-1182\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-1183\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><\/p>\n<h3 class=\"fm-head\" id=\"calibre_link-122\">13.3.2 How to use the immutable collections<\/h3>\n<p class=\"copyrightbody\">Some data changes so rarely that storing it in a data structure that cannot change doesn\u2019t pose problems. For example, the list of countries in the world does change sometimes, but it\u2019s rare enough that we can accept having to restart our service to refresh this list. However, the data that\u2019s really critical for our software, that data that we manage, tends to change all the time.<a id=\"calibre_link-255\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-1184\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-1185\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><\/p>\n<p class=\"copyrightbody\">Let\u2019s say we are building an e-commerce site that sells books. Obviously, the survival of the company depends on selling a lot of books, so we really want to be able to sell more than one book simultaneously. For this reason, we\u2019ve decided to use the immutable collection to store our inventory due to the inherent thread safety. Let\u2019s write some code to manage our inventory.<\/p>\n<p class=\"fm-code-listing-caption\">Listing 13.17 Non&ndash;thread-safe stack management with <code class=\"fm-code-in-text1\">ImmutableDictionary<\/code><\/p>\n<pre class=\"programlisting\">public class InventoryManager\n{\n   private ImmutableDictionary&lt;string,int&gt; _bookIdToQuantity;\n \n   public bool TryToBuyBook(string bookId)\n   {\n      if(!_bookIdToQuantity.TryGetValue(bookId, out var copiesInStock)) <span class=\"fm-combinumeral\">\u2776<\/span>\n          return false;\n      if(copiesInStock == 0)\n          return false;\n      _bookIdToQuantity = \n          _bookIdToQuantity.SetItem(bookId, copiesInStock-1);           <span class=\"fm-combinumeral\">\u2777<\/span>\n      return true;\n   }\n}<\/pre>\n<p class=\"copyrightbody\"><span class=\"fm-combinumeral\">\u2776<\/span> Gets previous quantity<\/p>\n<p class=\"copyrightbody\"><span class=\"fm-combinumeral\">\u2777<\/span> Sets new quantity<\/p>\n<p class=\"copyrightbody\">We wrote the <code class=\"fm-code-in-text\">InventoryManager<\/code> class with a single method called <code class=\"fm-code-in-text\">TryToBuyBook<\/code>. This method first retrieves the number of copies we have in stock from an <code class=\"fm-code-in-text\">ImmutableDictionary&lt;string,int&gt;<\/code> that\u2019s referenced by the _<code class=\"fm-code-in-text\">bookIdToQuantity<\/code> variable. If the book doesn\u2019t exist in the shop, or there are no copies in stock, the method returns <code class=\"fm-code-in-text\">false<\/code> to indicate the customer can\u2019t buy the book. If everything is okay, the method updates the stock by using the dictionary\u2019s <code class=\"fm-code-in-text\">SetItem<\/code> to create a new dictionary with the updated number of copies and stores the new dictionary in the same variable. It then returns <code class=\"fm-code-in-text\">true<\/code>.<a id=\"calibre_link-1186\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-1187\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-1188\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><\/p>\n<p class=\"copyrightbody\">If you think about what happens when this code runs on multiple threads simultaneously, it\u2019s easy to see the problem: the dictionary can\u2019t change, it\u2019s immutable, and it\u2019s impossible for another thread to modify the dictionary. However, if that dictionary is referenced by a normal mutable variable, another thread can change the variable swapping the dictionary with another one, and that change is not protected by the immutable data structure. See figure 13.10.<\/p>\n<div class=\"figure\">\n<p class=\"figure1\"><img decoding=\"async\" alt=\"\" class=\"calibre35\" src=\"\/images\/CSConcurrency_Asynchronous\/000023.png\" \/><\/p>\n<p class=\"figure1\">Figure 13.10 Synchronization needs of immutable collections versus concurrent collections<\/p>\n<\/p><\/div>\n<p class=\"copyrightbody\">The simplest solution is to place a lock around the entire method. This solves our data corruption problem, but it completely nullifies any benefits we get from the immutable collection\u2019s thread safety. If we place a lock around any access to the dictionary, we might as well use the simpler non&ndash;thread-safe <code class=\"fm-code-in-text\">Dictionary&lt;TKey,TValue&gt;<\/code>.<\/p>\n<p class=\"copyrightbody\">The complicated solution is to use <code class=\"fm-code-in-text\">ImmutableInterlocked<\/code>.<\/p>\n<h3 class=\"fm-head\" id=\"calibre_link-123\">13.3.3 ImmutableInterlocked<\/h3>\n<p class=\"copyrightbody\">The <code class=\"fm-code-in-text\">ImmutableInterlocked<\/code> class gives us lock-free operations for modifying a variable referencing an immutable collection. It contains methods that implement the same operation we\u2019ve seen in the concurrent collection, but this time for the immutable collection.<a id=\"calibre_link-1189\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-1190\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-1191\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-254\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><\/p>\n<p class=\"copyrightbody\">For example, for <code class=\"fm-code-in-text\">ImmutableDictionary&lt;TKey,TValue&gt;<\/code>, <code class=\"fm-code-in-text\">ImmutableInterlocked<\/code> gives us <code class=\"fm-code-in-text\">AddOrUpdate<\/code>, <code class=\"fm-code-in-text\">GetOrAdd<\/code>, <code class=\"fm-code-in-text\">TryAdd<\/code>, <code class=\"fm-code-in-text\">TryRemove<\/code>, and <code class=\"fm-code-in-text\">TryUpdate<\/code>, which are similar to the <code class=\"fm-code-in-text\">ConcurrentDictionary&lt;TKey,TValue&gt;<\/code> methods with the same name.<\/p>\n<p class=\"copyrightbody\">If you remember from listing 13.10, <code class=\"fm-code-in-text\">ConcurrentDictionary&lt;TKey,TValue&gt;.TryUpdate<\/code> ensures that the value we are trying to update hasn\u2019t been changed by someone else. Then, if the value hasn\u2019t been changed, it will replace that value in the dictionary. <code class=\"fm-code-in-text\">ImmutableInterlocked.TryUpdate<\/code> does the same for immutable dictionaries; it will make sure that the value we are trying to update hasn\u2019t been changed by someone else. Then, if the value hasn\u2019t changed, it will replace the entire dictionary with a new dictionary with one different value.<\/p>\n<p class=\"copyrightbody\">Just like <code class=\"fm-code-in-text\">ConcurrentDictionary&lt;TKey,TValue&gt;.TryUpdate<\/code>, it will return false without changing anything if the value was changed by another thread, and we need to deal with it, typically by reading the new value and redoing our processing until we succeed.<\/p>\n<p class=\"fm-code-listing-caption\">Listing 13.18 Thread-safe stock management with <code class=\"fm-code-in-text1\">ImmutableInterlocked<\/code><\/p>\n<pre class=\"programlisting\">   private ImmutalbeDictionery&lt;string,int&gt; _bookIdToQuantity = new();\n   public bool TryToBuyBook(string bookId)\n   {\n      while(true)\n      {\n         if(!_bookIdToQuantity.TryGetValue(bookId, \n               out var copiesInStock))                        <span class=\"fm-combinumeral\">\u2776<\/span>\n            Return false;\n         if(copiesInStock == 0)\n            return false;\n         if(ImmutableInterlocked.TryUpdate(                   <span class=\"fm-combinumeral\">\u2777<\/span>\n               ref _bookIdToQuantity, bookId,                 <span class=\"fm-combinumeral\">\u2777<\/span>\n               copiesInStock-1, copiesInStock))               <span class=\"fm-combinumeral\">\u2777<\/span>\n            return true;                                      <span class=\"fm-combinumeral\">\u2778<\/span>\n      }                                                       <span class=\"fm-combinumeral\">\u2779<\/span>\n   }\n}<\/pre>\n<p class=\"copyrightbody\"><span class=\"fm-combinumeral\">\u2776<\/span> Gets previous quantity<\/p>\n<p class=\"copyrightbody\"><span class=\"fm-combinumeral\">\u2777<\/span> Sets new quantity only if it didn\u2019t change<\/p>\n<p class=\"copyrightbody\"><span class=\"fm-combinumeral\">\u2778<\/span> On success, returns<\/p>\n<p class=\"copyrightbody\"><span class=\"fm-combinumeral\">\u2779<\/span> If changed, repeats loop<\/p>\n<p class=\"copyrightbody\">This is the safe version of listing 13.17. It reads the number of copies in stock and tries to decrease it by 1, and if the number of copies has already changed since we\u2019ve read it, this code will read the value again, validate that it has a copy to sell again, and try to decrease the value in the <code class=\"fm-code-in-text\">_bookIdToQuantity<\/code> dictionary. It will continue doing this either until it succeeds or until transactions running on other threads cause the number of copies in stock to go down to zero.<\/p>\n<p class=\"copyrightbody\"><code class=\"fm-code-in-text\">ImmutableInterlocked<\/code> also provides <code class=\"fm-code-in-text\">Push<\/code> and <code class=\"fm-code-in-text\">TryPop<\/code> methods for use with <code class=\"fm-code-in-text\">ImmutableStack&lt;T&gt;<\/code>, and <code class=\"fm-code-in-text\">Enqueue<\/code> and <code class=\"fm-code-in-text\">TryDequeue<\/code> for <code class=\"fm-code-in-text\">ImmutableQueue&lt;T&gt;<\/code>. Note that using <code class=\"fm-code-in-text\">ImmutableInterlocked<\/code> is an all-or-nothing deal&mdash;it\u2019s only safe if all your modifications use <code class=\"fm-code-in-text\">ImmutableInterlocked<\/code>. Also note that you cannot use <code class=\"fm-code-in-text\">ImmutableInterlocked<\/code> to update multiple collections in a thread-safe way. If, for example, you need to add the same key to two dictionaries, there is no way to do it with <code class=\"fm-code-in-text\">ImmutableInterlocked<\/code> without having a time window where another thread can view the change in the first dictionary before you updated the second. This also goes for multiple changes in the same dictionary&mdash;you can\u2019t use <code class=\"fm-code-in-text\">ImmutableInterlocked<\/code> to change two values at once.<a id=\"calibre_link-1192\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-1193\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><\/p>\n<h3 class=\"fm-head\" id=\"calibre_link-124\">13.3.4 ImmutableDictionary&lt;TKey,TValue&gt;<\/h3>\n<p class=\"copyrightbody\"><code class=\"fm-code-in-text\">ImmutableDictionary&lt;TKey,TValue&gt;<\/code> is, predictably, the immutable version of <code class=\"fm-code-in-text\">Dictionary&lt;TKey,TValue&gt;<\/code>. <code class=\"fm-code-in-text\">ImmutableDictionary&lt;TKey,TValue&gt;<\/code>, just like <code class=\"fm-code-in-text\">Dictionary&lt;TKey,TValue&gt;<\/code>, lets us check whether a key exists by using <code class=\"fm-code-in-text\">ContainsKey<\/code>, retrieve a value by using the <code class=\"fm-code-in-text\">[]<\/code> operator, and do both in a single call by using <code class=\"fm-code-in-text\">TryGetValue<\/code>.<a id=\"calibre_link-1194\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-252\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-1195\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-1196\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><\/p>\n<p class=\"copyrightbody\">It also has most of the methods used in <code class=\"fm-code-in-text\">Dictionary&lt;TKey,TValue&gt;<\/code> to modify the dictionary (<code class=\"fm-code-in-text\">Add<\/code>, <code class=\"fm-code-in-text\">Remove<\/code>, and so on), but in <code class=\"fm-code-in-text\">ImmutableDictionary&lt;TKey,TValue&gt;<\/code>, they leave the dictionary untouched and return a new dictionary with the modifications. To change a specific value inside the dictionary, you use the <code class=\"fm-code-in-text\">UpdateValue<\/code> method instead of the <code class=\"fm-code-in-text\">[]<\/code> operator because there\u2019s no good way for the <code class=\"fm-code-in-text\">[]<\/code> operator to return a new dictionary.<a id=\"calibre_link-1197\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-145\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><\/p>\n<p class=\"copyrightbody\">The <code class=\"fm-code-in-text\">ImmutableDictionary&lt;TKey,TValue&gt;<\/code> does not itself have any of the special operations found in <code class=\"fm-code-in-text\">ConcurrentDictionary&lt;TKey,TValue&gt;<\/code>, such as <code class=\"fm-code-in-text\">GetOrAdd<\/code>, because since the <code class=\"fm-code-in-text\">ImmutableDictionary&lt;TKey,TValue&gt;<\/code> is immutable, it can\u2019t change between the <code class=\"fm-code-in-text\">Get<\/code> and the <code class=\"fm-code-in-text\">Add<\/code>.<\/p>\n<p class=\"copyrightbody\">If you need to add, remove, or update multiple values simultaneously, <code class=\"fm-code-in-text\">ImmutableDictionary&lt;TKey,TValue&gt;<\/code> provides the <code class=\"fm-code-in-text\">AddRange<\/code>, <code class=\"fm-code-in-text\">RemoveRange<\/code>, and <code class=\"fm-code-in-text\">UpdateItems<\/code> methods. These methods are important for writing high-performance code because they create just one new <code class=\"fm-code-in-text\">ImmutableDictionary&lt;TKey,TValue&gt;<\/code> for the entire method call instead of one new dictionary for each and every value changed.<\/p>\n<p class=\"copyrightbody\">If you need to make multiple modifications of different types (for example, adding a value and removing another), or your algorithm doesn\u2019t let you easily group changes (for example, if you can\u2019t replace several <code class=\"fm-code-in-text\">Add<\/code> calls with one <code class=\"fm-code-in-text\">AddRange<\/code> call), you can use a builder object. A builder object is created using the dictionary\u2019s <code class=\"fm-code-in-text\">ToBuilder<\/code> method. The builder is not immutable, and you can use it to make multiple modifications without creating a new dictionary. When you\u2019ve finished with the modifications, you call the builder\u2019s <code class=\"fm-code-in-text\">ToImmutable<\/code> method that created one new <code class=\"fm-code-in-text\">ImmutableDictionary&lt;TKey,TValue&gt;<\/code> with all the modifications.<a id=\"calibre_link-1198\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-1199\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><\/p>\n<p class=\"copyrightbody\">The builder is not immutable and not thread safe. It is a fast and efficient way to create new <code class=\"fm-code-in-text\">ImmutableDictionary&lt;TKey,TValue&gt;<\/code> objects, but it does not do anything to help with multithreading.<\/p>\n<p class=\"copyrightbody\">As we\u2019ve seen earlier in this chapter, the variable holding the up-to-date version of the dictionary is just a simple variable and has the same threading behavior as any other variable (not thread-safe without locking if there are any write operations). As we\u2019ve also seen earlier in this chapter, if you want a fast, lock-free way to synchronize access to that variable, you can use <code class=\"fm-code-in-text\">ImmutableInterlocked<\/code>. It provides the <code class=\"fm-code-in-text\">AddOrUpdate<\/code>, <code class=\"fm-code-in-text\">GetOrAdd<\/code>, <code class=\"fm-code-in-text\">TryAdd<\/code>, <code class=\"fm-code-in-text\">TryRemove<\/code>, and <code class=\"fm-code-in-text\">TryUpdate<\/code> methods, which work the same way as the <code class=\"fm-code-in-text\">ConcurrentDictionary&lt;TKey,TValue&gt;<\/code> methods with the same name (except that, being immutable, the dictionary never changes, and those operation swap the dictionary with a new dictionary that has the requested modifications).<a id=\"calibre_link-1200\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-1201\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-1202\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-1203\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-1204\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><\/p>\n<p class=\"copyrightbody\">If you use <code class=\"fm-code-in-text\">ImmutableInterlocked<\/code> with <code class=\"fm-code-in-text\">ImmutableDictionary&lt;TKey,TValue&gt;<\/code>, it\u2019s likely you are doing it to get basically the same behavior that you get with <code class=\"fm-code-in-text\">ConcurrentDictionary&lt;TKey,TValue&gt;<\/code>. If this is the case, you will probably be better off just using <code class=\"fm-code-in-text\">ConcurrentDictionary&lt;TKey,TValue&gt;<\/code> instead.<\/p>\n<p class=\"copyrightbody\">Remember that you can either use <code class=\"fm-code-in-text\">ImmutableDictionary&lt;TKey,TValue&gt;<\/code>\u2019s methods (and the builder) to create modified copies, or you can use <code class=\"fm-code-in-text\">ImmutableInterlocked<\/code>. Using both is not thread safe.<\/p>\n<h3 class=\"fm-head\" id=\"calibre_link-125\">13.3.5 ImmutableHashSet&lt;T&gt; and ImmutableSortedSet&lt;T&gt;<\/h3>\n<p class=\"copyrightbody\">Naturally, <code class=\"fm-code-in-text\">ImmutableHashSet&lt;T&gt;<\/code> and <code class=\"fm-code-in-text\">ImmutableSortedSet&lt;T&gt;<\/code> are the immutable versions of <code class=\"fm-code-in-text\">HashSet&lt;T&gt;<\/code> and <code class=\"fm-code-in-text\">SortedSet&lt;T&gt;<\/code>. They both represent a set from set theory&mdash;they contain zero or more items with no duplicates and can also perform set theory operations (<code class=\"fm-code-in-text\">Except<\/code>, <code class=\"fm-code-in-text\">Intersect<\/code>, <code class=\"fm-code-in-text\">IsSubsetOf<\/code>, <code class=\"fm-code-in-text\">IsSupersetOf<\/code>, and so forth).<a id=\"calibre_link-1205\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-1206\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-1207\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-1208\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-1209\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-253\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-1210\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><\/p>\n<p class=\"copyrightbody\">When you enumerate an <code class=\"fm-code-in-text\">ImmutableHashSet&lt;T&gt;<\/code> (for example, by using <code class=\"fm-code-in-text\">foreach<\/code>), the items\u2019 order is completely arbitrary and is not under your control, but operations on the set, especially lookup, are very fast. In contrast, if you enumerate an <code class=\"fm-code-in-text\">ImmutableSortedSet&lt;T&gt;<\/code>, you get the item in sorted order (you can control the sort order by passing an <code class=\"fm-code-in-text\">IComparer&lt;T&gt;<\/code> to the static <code class=\"fm-code-in-text\">ImmutableSortedSet.Create&lt;T&gt;<\/code> method), but operation on the set will be slower. Because of the performance difference, it\u2019s recommended to prefer <code class=\"fm-code-in-text\">ImmutableHashSet&lt;T&gt;<\/code> and only use <code class=\"fm-code-in-text\">ImmutableSortedSet&lt;T&gt;<\/code> if you care about the items\u2019 order during enumeration.<a id=\"calibre_link-1211\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><\/p>\n<p class=\"copyrightbody\">As with all the immutable collections, all the methods that would normally change the collection return a new collection with the modifications instead. Also, like we\u2019ve seen with <code class=\"fm-code-in-text\">ImmutableDictionary&lt;TKey,TValue&gt;<\/code>, both <code class=\"fm-code-in-text\">ImmutableHashSet&lt;T&gt;<\/code> and <code class=\"fm-code-in-text\">ImmutableSortedSet&lt;T&gt;<\/code> have a <code class=\"fm-code-in-text\">ToBuilder<\/code> method that returns an object you can use to efficiently perform many modifications and then create only one new immutable set for all the modifications. Remember, the builder object is not thread safe.<a id=\"calibre_link-1212\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><\/p>\n<p class=\"copyrightbody\">In addition, as with all of the immutable collections, if you have a variable referencing the up-to-date version of the collection, you need to synchronize access to the variable yourself (most likely, using locks). Unlike <code class=\"fm-code-in-text\">ImmutableDictionary&lt;TKey,TValue&gt;<\/code>, you can\u2019t use <code class=\"fm-code-in-text\">ImmutableInterlocked<\/code> with the immutable set classes.<\/p>\n<h3 class=\"fm-head\" id=\"calibre_link-126\">13.3.6 ImmutableList&lt;T&gt;<\/h3>\n<p class=\"copyrightbody\"><code class=\"fm-code-in-text\">ImmutableList&lt;T&gt;<\/code> is, unsurprisingly, the immutable version of <code class=\"fm-code-in-text\">List&lt;T&gt;<\/code> and, also unsurprisingly, works the same way as the previous immutable collections. All the methods that don\u2019t modify the list work exactly like in <code class=\"fm-code-in-text\">List&lt;T&gt;<\/code>. All the methods that do modify the list return a new <code class=\"fm-code-in-text\">ImmutableList&lt;T&gt;<\/code> instead. To set an item at a specific location, use the <code class=\"fm-code-in-text\">SetItem<\/code> method instead of the <code class=\"fm-code-in-text\">[]<\/code> operator because the operator has no good way to return a new <code class=\"fm-code-in-text\">ImmutableList&lt;T&gt;<\/code> object.<a id=\"calibre_link-1213\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-1214\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-1215\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-1216\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><\/p>\n<p class=\"copyrightbody\">Like all the previous immutable collections, <code class=\"fm-code-in-text\">ImmutableList&lt;T&gt;<\/code> has a <code class=\"fm-code-in-text\">ToBuilder<\/code> method that returns a mutable object you can use to perform multiple modifications without creating an excessive number of <code class=\"fm-code-in-text\">ImmutableList&lt;T&gt;<\/code> objects. As always, the builder object is not thread safe.<a id=\"calibre_link-1217\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><\/p>\n<p class=\"copyrightbody\">If you have a variable holding an <code class=\"fm-code-in-text\">ImmutableList&lt;T&gt;<\/code> object that is accessed by different threads, you need to synchronize access to this variable. <code class=\"fm-code-in-text\">ImmutableInterlocked<\/code> does not support <code class=\"fm-code-in-text\">ImmutableList&lt;T&gt;<\/code>.<\/p>\n<h3 class=\"fm-head\" id=\"calibre_link-127\">13.3.7 ImmutableQueue&lt;T&gt; and ImmutableStack&lt;T&gt;<\/h3>\n<p class=\"copyrightbody\"><code class=\"fm-code-in-text\">ImmutableQueue&lt;T&gt;<\/code> and <code class=\"fm-code-in-text\">ImmutableStack&lt;T&gt;<\/code> are, obviously, the immutable versions of <code class=\"fm-code-in-text\">Queue&lt;T&gt;<\/code> and <code class=\"fm-code-in-text\">Stack&lt;T&gt;<\/code>. Because queue and stack are almost always used as temporary storage, with items added and removed all the time, in almost all cases, <code class=\"fm-code-in-text\">ConcurrentQueue&lt;T&gt;<\/code> and <code class=\"fm-code-in-text\">ConcurrentStack&lt;T&gt;<\/code> are a better choice, with the notable exception of functional programming.<a id=\"calibre_link-1218\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-1219\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-1220\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-1221\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-1222\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-1223\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><\/p>\n<p class=\"copyrightbody\">If you do use the immutable queue and stack, then the <code class=\"fm-code-in-text\">ImmutableQueue&lt;T&gt;.IsEmpty<\/code> and <code class=\"fm-code-in-text\">ImmutableStack&lt;T&gt;.IsEmpty<\/code> properties will tell you the collection is empty, and <code class=\"fm-code-in-text\">ImmutableQueue&lt;T&gt;.Enqueue<\/code> and <code class=\"fm-code-in-text\">ImmutableStack&lt;T&gt;.Push<\/code> will create a new queue or stack with the added item. <code class=\"fm-code-in-text\">ImmutableQueue&lt;T&gt;.Peek<\/code> and <code class=\"fm-code-in-text\">ImmutableStack&lt;T&gt;.Peek<\/code> will both return the next item without removing it from the collection, and <code class=\"fm-code-in-text\">ImmutableQueue&lt;T&gt;.Dequeue<\/code> and <code class=\"fm-code-in-text\">ImmutableStack&lt;T&gt;.Pop<\/code> will return a new stack with an item removed and (optionally) will place the removed item in an out parameter.<\/p>\n<p class=\"copyrightbody\">The <code class=\"fm-code-in-text\">Peek<\/code>, <code class=\"fm-code-in-text\">Dequeue<\/code>, and <code class=\"fm-code-in-text\">Pop<\/code> methods will throw an exception if the queue or stack is empty. There\u2019s no way for another thread to modify the collection between checking the <code class=\"fm-code-in-text\">IsEmpty<\/code> property and calling <code class=\"fm-code-in-text\">Peek<\/code>, <code class=\"fm-code-in-text\">Dequeue<\/code>, or <code class=\"fm-code-in-text\">Pop<\/code>&mdash;the collection is immutable, it can\u2019t be modified at all, and thus it can\u2019t be modified by another thread. <a id=\"calibre_link-1224\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-1225\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-1226\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><\/p>\n<p class=\"copyrightbody\">If your queue or thread is referenced by a variable that is writable by other threads, you need to synchronize access to this variable and, at the minimum, copy the reference to a local variable before reading <code class=\"fm-code-in-text\">IsEmpty<\/code> so another thread can\u2019t replace the queue or stack between you reading <code class=\"fm-code-in-text\">IsEmpty<\/code> and calling <code class=\"fm-code-in-text\">Peek<\/code>, <code class=\"fm-code-in-text\">Dequeue<\/code>, or <code class=\"fm-code-in-text\">Pop<\/code>.<\/p>\n<p class=\"copyrightbody\"><code class=\"fm-code-in-text\">ImmutableInterlocked<\/code> supports both <code class=\"fm-code-in-text\">ImmutableQueue&lt;T&gt;<\/code> and <code class=\"fm-code-in-text\">ImmutableStack&lt;T&gt;<\/code> with operations similar to those available in <code class=\"fm-code-in-text\">ConcurrentQueue&lt;T&gt;<\/code> and <code class=\"fm-code-in-text\">ConcurrentStack&lt;T&gt;<\/code>. However, if you need them, it\u2019s almost guaranteed you\u2019ll be better off just using <code class=\"fm-code-in-text\">ConcurrentQueue&lt;T&gt;<\/code> or <code class=\"fm-code-in-text\">ConcurrentStack&lt;T&gt;<\/code> instead.<\/p>\n<h3 class=\"fm-head\" id=\"calibre_link-128\">13.3.8 ImmutableArray&lt;T&gt;<\/h3>\n<p class=\"copyrightbody\">When I started talking about the immutable collections, I said all the non&ndash;thread-safe collections use arrays because they are fast, but immutable collections don\u2019t use arrays because this would have required them to copy all the data every time a collection is modified (that is, a new collection is created with the modification). <code class=\"fm-code-in-text\">ImmutableArray&lt;T&gt;<\/code> is an exception that, like the name suggests, does use an array.<a id=\"calibre_link-1227\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-1228\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-1229\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-237\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><\/p>\n<p class=\"copyrightbody\">Because <code class=\"fm-code-in-text\">ImmutableArray&lt;T&gt;<\/code> is not exempt from the disadvantages of arrays, this means that the immutable array does have to copy all the data every time it creates a modified collection, and this makes <code class=\"fm-code-in-text\">ImmutableArray&lt;T&gt;<\/code> the slowest immutable collection to write to. However, because it uses an array, it is also the fastest immutable collection to read from. This makes <code class=\"fm-code-in-text\">ImmutableArray&lt;T&gt;<\/code> more similar to frozen collections (described later in this chapter) compared to other immutable collections.<\/p>\n<p class=\"copyrightbody\"><code class=\"fm-code-in-text\">ImmutableArray&lt;T&gt;<\/code> is a very good choice if you need to pass a read-only array to some code that isn\u2019t under your control. Being an array, it\u2019s fast to scan and even supports read-only memory and span objects.<\/p>\n<p class=\"copyrightbody\">Conversely, <code class=\"fm-code-in-text\">ImmutableArray&lt;T&gt;<\/code> is typically not a good choice for your internal data structure because modifications are slow and require a lot of memory. This can still be acceptable if modifications are very rare or the array is small, but you need to be very careful about it.<\/p>\n<p class=\"copyrightbody\">You can use <code class=\"fm-code-in-text\">ImmutableArray.Create&lt;T&gt;<\/code> to create a new immutable array from a normal array or from up to four individual data items. You can use <code class=\"fm-code-in-text\">ImmutableArray.ToImmutable&lt;T&gt;<\/code> to create an immutable array from any collection, and you can use <code class=\"fm-code-in-text\">ImmutableArray.CreateRange<\/code> to create an immutable array from a subset of another collection.<\/p>\n<p class=\"copyrightbody\">As always, if the variable referencing the immutable array is accessible from multiple threads, you need to synchronize access yourself. <code class=\"fm-code-in-text\">ImmutableInterlocked<\/code> supports <code class=\"fm-code-in-text\">ImmutableArray&lt;T&gt;<\/code> with the <code class=\"fm-code-in-text\">InterlockedCompereExchange<\/code>, <code class=\"fm-code-in-text\">InterlockedExchange<\/code>, and <code class=\"fm-code-in-text\">InterlockedInitilize<\/code> methods, but you generally shouldn\u2019t use them. They are complicated and error prone compared to a <code class=\"fm-code-in-text\">lock<\/code> statement, and unless you are in a very performance-critical code path, the trade-offs are just not worth it. <a id=\"calibre_link-1230\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-1231\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-1232\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><\/p>\n<p class=\"copyrightbody\">Generally, <code class=\"fm-code-in-text\">ImmutableArray&lt;T&gt;<\/code> should be used like the frozen collections (which we\u2019ll discuss in just a few paragraphs). <code class=\"fm-code-in-text\">ImmutableArray&lt;T&gt;<\/code> is inefficient to create (both in speed and memory usage) but very efficient to use. It should be used when we need a sequential collection (like <code class=\"fm-code-in-text\">List&lt;T&gt;<\/code> or an array) that is read only and inherently thread safe. However, because recreating it is expensive, it should only be used when we do not intend to change it (that is, create a new modified copy) at all.<\/p>\n<h3 class=\"fm-head\" id=\"calibre_link-129\">13.3.9 When to use the immutable collections<\/h3>\n<p class=\"copyrightbody\">Immutable collections are very common in functional programming. If you write code in functional style or use functional algorithms, the immutable collections are perfect for you.<a id=\"calibre_link-1233\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-1234\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-251\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><\/p>\n<p class=\"copyrightbody\">Immutable collections are also convenient if you need to preserve previous states of the system, for example, as a way to provide undo functionality. Note that immutable collections are irrelevant if you need to preserve the state of the system for auditing or regulatory purposes because then you need to preserve the state of the system on disk, and the immutable collections are only in-memory.<\/p>\n<p class=\"copyrightbody\">Immutable collections are also very helpful if you need to pass the collection to code that is not under your control. That way, you don\u2019t have to defensively duplicate the data and send a copy to the outside code.<\/p>\n<p class=\"copyrightbody\">But whenever you use the immutable collections, you must remember that while the immutable collections themselves are completely thread safe, \u201cchanging the collection\u201d involves creating a new collection, and the collection is usually assigned to the same variable as the previous collection. This variable is now modified with every change, and access to it needs to be synchronized like any other variable that is concurrently accessed from multiple threads. This often requires holding a lock when updating the collection or using <code class=\"fm-code-in-text\">ImmutableInterlocked<\/code>, and in those cases, the code is likely to be simpler and faster if you use the concurrent collections instead.<\/p>\n<p class=\"copyrightbody\">Finally, in cases where the data really never changes, you should consider using the frozen collections.<a id=\"calibre_link-1235\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-1236\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><\/p>\n<h2 class=\"fm-head\" id=\"calibre_link-130\">13.4 The frozen collections<\/h2>\n<p class=\"copyrightbody\">We\u2019ve seen that the immutable collections never change in the sense that if you want to change them, you need to create a copy of the collection with the required modification, and we\u2019ve also seen that as a trade-off, the immutable collection uses less-efficient data structures to make the creation of modified copies faster. But what if we don\u2019t want to make this trade-off? What if the data really never changes? What if we don\u2019t want to sacrifice read performance to support write operations we don\u2019t need? This is why we have the frozen collections.<a id=\"calibre_link-1237\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-1238\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><\/p>\n<p class=\"copyrightbody\">Frozen collections are read-only collections optimized for reading. Creating them is slower than creating regular, concurrent, or immutable collections, but reading from them is as fast as possible.<\/p>\n<p class=\"copyrightbody\">Frozen collections are meant only for reading. They can\u2019t be modified at all, and they don\u2019t even have methods to create modified copies like the immutable collections.<\/p>\n<p class=\"copyrightbody\">Currently, there are only two types of frozen collections&mdash;<code class=\"fm-code-in-text\">FrozenDictionary&lt;TKey,TValue&gt;<\/code> and <code class=\"fm-code-in-text\">FrozenSet&lt;T&gt;<\/code>&mdash;which are read-only versions of <code class=\"fm-code-in-text\">Dictionary&lt;TKey,TValue&gt;<\/code> and <code class=\"fm-code-in-text\">HashSet&lt;T&gt;<\/code>, respectively. If you want a frozen version of <code class=\"fm-code-in-text\">List&lt;T&gt;<\/code>, you can use <code class=\"fm-code-in-text\">ImmutableArray&lt;T&gt;<\/code> (we talked about it earlier in this chapter). There are no frozen queues and stacks because those don\u2019t make sense.<\/p>\n<p class=\"copyrightbody\">To create a <code class=\"fm-code-in-text\">FrozenSet&lt;T&gt;<\/code>, you can take any collection and call the <code class=\"fm-code-in-text\">ToFrozenSet<\/code> extension method.<a id=\"calibre_link-1239\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-248\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><\/p>\n<p class=\"fm-code-listing-caption\">Listing 13.19 Initializing a <code class=\"fm-code-in-text1\">FrozenSet<\/code><\/p>\n<pre class=\"programlisting\">var data = new List&lt;int&gt; {1,2,3,4};\nvar set = data.ToFrozenSet();<\/pre>\n<p class=\"copyrightbody\">This code creates a <code class=\"fm-code-in-text\">List&lt;int&gt;<\/code> with some numbers and then calls <code class=\"fm-code-in-text\">ToFrozenSet<\/code> on it to create a <code class=\"fm-code-in-text\">FrozenSet&lt;int&gt;<\/code> with the same content.<\/p>\n<p class=\"copyrightbody\">To create a <code class=\"fm-code-in-text\">FrozenDictionary&lt;TKey,TValue&gt;<\/code>, you can take any collection and call the <code class=\"fm-code-in-text\">ToFrozenDictionary<\/code> extension method. The easiest way to create a <code class=\"fm-code-in-text\">FrozenDictionary&lt;TKey,TValue&gt;<\/code> is by using a <code class=\"fm-code-in-text\">Dictionary&lt;TKey,TValue&gt;<\/code>.<a id=\"calibre_link-1240\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><\/p>\n<p class=\"fm-code-listing-caption\">Listing 13.20 Initializing a <code class=\"fm-code-in-text1\">FrozenDictionary<\/code> from a <code class=\"fm-code-in-text1\">Dictionary<\/code><\/p>\n<pre class=\"programlisting\">var numberNames = new Dictionary&lt;int,string&gt;\n{\n   {1, \"one\"},\n   {2, \"two\"}\n};\nvar frozenDict = numberNames.ToFrozenDictionary();<\/pre>\n<p class=\"copyrightbody\">This code creates a <code class=\"fm-code-in-text\">Dictionary&lt;int,string&gt;<\/code> that maps numbers to the English name of the numbers (only for one and two, just to keep the code short) and then uses <code class=\"fm-code-in-text\">ToFrozenDictionary<\/code> to create a <code class=\"fm-code-in-text\">FrozenDictionary&lt;int,string&gt;<\/code> with the same content. There\u2019s also an overload of <code class=\"fm-code-in-text\">ToFrozenDictionary<\/code> that accepts delegates to extract the key and value so it can be used on any collection.<a id=\"calibre_link-1241\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><\/p>\n<p class=\"fm-code-listing-caption\">Listing 13.21 Initializing a <code class=\"fm-code-in-text1\">FrozenDictionary<\/code> from a <code class=\"fm-code-in-text1\">List<\/code><\/p>\n<pre class=\"programlisting\">var data = new List&lt;int&gt; {1,2,3,4};\nvar frozenDict = data.ToFrozenDictionary(x=&gt;x,x=&gt;x.ToString());<\/pre>\n<p class=\"copyrightbody\">This code creates a <code class=\"fm-code-in-text\">List&lt;int&gt;<\/code> with some numbers and then uses <code class=\"fm-code-in-text\">ToFrozenDictionary<\/code> to create a <code class=\"fm-code-in-text\">FrozenDictionary&lt;int,string&gt;<\/code>, which maps the numbers in the list to their string representation. Note that if the source data contains duplicates (in the case of <code class=\"fm-code-in-text\">ToFrozenSet<\/code>) or duplicate keys (in the case of <code class=\"fm-code-in-text\">ToFrozenDictionary<\/code>), the latest entry will be used, which is different than the behavior of <code class=\"fm-code-in-text\">Dictionary&lt;TKey,TValue&gt;<\/code> and <code class=\"fm-code-in-text\">HashSet&lt;T&gt;<\/code> that throws an exception in case of duplicate keys.<\/p>\n<h3 class=\"fm-head\" id=\"calibre_link-131\">13.4.1 When to use the frozen collections<\/h3>\n<p class=\"copyrightbody\"><a id=\"calibre_link-1242\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a>The frozen collection should only be used when data (almost) never changes. The frozen collections optimize for reads at the cost of making the collection creation much slower. If the data is frequently accessed but never modified, this can improve performance. In contrast, if the data changes frequently, the time it takes to create the frozen collection after each change can easily be much more than the time saved due to the faster lookups.<\/p>\n<h2 class=\"fm-head\" id=\"calibre_link-1243\">Summary<\/h2>\n<ul class=\"calibre9\">\n<li class=\"fm-list-bullet\">\n<p class=\"list\">It is possible to read from the regular collections in the <code class=\"fm-code-in-text\">System.Collections.Generic<\/code> namespace from multiple threads simultaneously.<\/p>\n<\/li>\n<li class=\"fm-list-bullet\">\n<p class=\"list\">Writing from multiple threads simultaneously or writing from one thread while reading from others is not allowed and might cause the collections to return incorrect results and even corrupt them.<\/p>\n<\/li>\n<li class=\"fm-list-bullet\">\n<p class=\"list\">The concurrent collections in the <code class=\"fm-code-in-text\">System.Collections.Concurrent<\/code> namespace are fully thread safe and support both reading and writing from multiple threads at the same time.<\/p>\n<\/li>\n<li class=\"fm-list-bullet\">\n<p class=\"list\">There are concurrent versions of <code class=\"fm-code-in-text\">Dictionary&lt;TKey,TValue&gt;<\/code>, <code class=\"fm-code-in-text\">Queue&lt;T&gt;<\/code>, and <code class=\"fm-code-in-text\">Stack&lt;T&gt;<\/code> called <code class=\"fm-code-in-text\">ConcurrentDictionary&lt;TKey,TValue&gt;<\/code>, <code class=\"fm-code-in-text\">ConcurrentQueue&lt;T&gt;<\/code>, and <code class=\"fm-code-in-text\">ConcurrentStack&lt;T&gt;<\/code>. Their interface is different from the regular collections&mdash;it combines operations that are commonly used together into a single operation to avoid race conditions.<\/p>\n<\/li>\n<li class=\"fm-list-bullet\">\n<p class=\"list\">There is also a <code class=\"fm-code-in-text\">ConcurrentBag&lt;T&gt;<\/code> collection that is useful when you don\u2019t care about the items\u2019 order; it is designed to be used when the same threads both read and write from\/to the collection.<\/p>\n<\/li>\n<li class=\"fm-list-bullet\">\n<p class=\"list\">The <code class=\"fm-code-in-text\">BlockingCollection&lt;T&gt;<\/code> class adds support for producer&ndash;consumer scenarios and for limiting the collection\u2019s size. <code class=\"fm-code-in-text\">BlockingCollection&lt;T&gt;<\/code> works as a queue by default but can also be used as a stack.<\/p>\n<\/li>\n<li class=\"fm-list-bullet\">\n<p class=\"list\">The <code class=\"fm-code-in-text\">ConcurrentDictionary&lt;TKey,TValue&gt;<\/code>, <code class=\"fm-code-in-text\">ConcurrentQueue&lt;T&gt;<\/code>, <code class=\"fm-code-in-text\">Concurrent<\/code><code class=\"fm-code-in-text\">Stack&lt;T&gt;<\/code>, and <code class=\"fm-code-in-text\">ConcurrentBag&lt;T&gt;<\/code> collections can be used with asynchronous code.<\/p>\n<\/li>\n<li class=\"fm-list-bullet\">\n<p class=\"list\">Like the name suggests, the <code class=\"fm-code-in-text\">BlockingCollection&lt;T&gt;<\/code> class is blocking, and it should be used carefully (or not at all) with asynchronous code.<\/p>\n<\/li>\n<li class=\"fm-list-bullet\">\n<p class=\"list\">There is no asynchronous version of <code class=\"fm-code-in-text\">BlockingCollection&lt;T&gt;<\/code>, but we can use <code class=\"fm-code-in-text\">Channel&lt;T&gt;<\/code> to make an asynchronous version of its most common use case (more about this in the next chapter).<\/p>\n<\/li>\n<li class=\"fm-list-bullet\">\n<p class=\"list\">The immutable collections in the <code class=\"fm-code-in-text\">System.Collections.Immutable<\/code> namespace are collections that can\u2019t be changed (every change leaves the collection untouched and creates a new collection). They are thread safe because, since they can\u2019t be modified at all, by definition, they can\u2019t be modified by another thread while you are accessing them.<\/p>\n<\/li>\n<li class=\"fm-list-bullet\">\n<p class=\"list\">However, if the variable that references the collections is accessed by multiple threads, you need to synchronize access yourself. The <code class=\"fm-code-in-text\">ImmutableInterlocked<\/code> class can help with that (for dictionary, queue, and stack).<\/p>\n<\/li>\n<li class=\"fm-list-bullet\">\n<p class=\"list\">If you need to make multiple modifications to an immutable collection, you can call <code class=\"fm-code-in-text\">ToBuilder<\/code> to get a builder object that collects the modifications without creating new collections. After you make all the modifications to the builder, you call its <code class=\"fm-code-in-text\">ToImmutable<\/code> method to create just one new collection with all the changes. The builder object is not thread safe.<\/p>\n<\/li>\n<li class=\"fm-list-bullet\">\n<p class=\"list\">There are <code class=\"fm-code-in-text\">ImmutableDictionary&lt;TKey,TValue&gt;<\/code>, <code class=\"fm-code-in-text\">ImmutableHashSet&lt;T&gt;<\/code>, <code class=\"fm-code-in-text\">ImmutableSortedSet&lt;T&gt;<\/code>, <code class=\"fm-code-in-text\">ImmutableQueue&lt;T&gt;<\/code>, <code class=\"fm-code-in-text\">ImmutableStack&lt;T&gt;<\/code>, and <code class=\"fm-code-in-text\">ImmutableList&lt;T&gt;<\/code> classes that are immutable versions of classes with the same name but without the <code class=\"fm-code-in-text\">Immutable<\/code> prefix.<\/p>\n<\/li>\n<li class=\"fm-list-bullet\">\n<p class=\"list\">Those collections are slower to read than the regular or concurrent collections, but making copies of them is fast, which is important because every time you need to modify the collection, you create a copy of it.<\/p>\n<\/li>\n<li class=\"fm-list-bullet\">\n<p class=\"list\">The <code class=\"fm-code-in-text\">ImmutableArray&lt;T&gt;<\/code> collection is an immutable array. It is faster to access than the other immutable collections but slower to modify (that is, create a modified copy). It also supports read-only <code class=\"fm-code-in-text\">Span&lt;T&gt;<\/code> and <code class=\"fm-code-in-text\">Memory&lt;T&gt;.<\/code><\/p>\n<\/li>\n<li class=\"fm-list-bullet\">\n<p class=\"list\">The frozen collections are optimized for reading. Creating them is slow, but reading from them is fast. They cannot be modified.<\/p>\n<\/li>\n<li class=\"fm-list-bullet\">\n<p class=\"list\">Like the immutable collections, the frozen collections are inherently thread safe.<\/p>\n<\/li>\n<li class=\"fm-list-bullet\">\n<p class=\"list\">There are only two frozen collections: <code class=\"fm-code-in-text\">FrozenDictionary&lt;TKey,TValue&gt;<\/code> and <code class=\"fm-code-in-text\">FrozenSet&lt;T&gt;<\/code>.<\/p>\n<\/li>\n<li class=\"fm-list-bullet\">\n<p class=\"list\">Typically, to create a frozen collection, you first use a regular collection and then <code class=\"fm-code-in-text\">ToFrozenSet<\/code> or <code class=\"fm-code-in-text\">ToFrozenDictionary<\/code> to create a frozen collection from the data they contain.<a id=\"calibre_link-1244\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><\/p>\n<\/li>\n<\/ul>\n<\/div>\n<\/div>\n<\/div>\n<div class=\"calibre1\" id=\"calibre_link-132\">\n<div id=\"calibre_link-1245\" class=\"calibre2\">\n<div id=\"calibre_link-1246\" class=\"calibre3\">\n<h1 class=\"copyrighta\" id=\"calibre_link-1247\">14 Generating collections asynchronously\/await foreach and IAsyncEnumerable<a id=\"calibre_link-1248\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><\/h1>\n<p class=\"copyrightbody\">This chapter covers:<a id=\"calibre_link-1249\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-183\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><\/p>\n<ul class=\"calibre9\">\n<li class=\"co-summary-bullet\">How <code class=\"fm-code-in-text\">await<\/code> <code class=\"fm-code-in-text\">foreach<\/code> works<\/li>\n<li class=\"co-summary-bullet\">Using <code class=\"fm-code-in-text\">yield<\/code> <code class=\"fm-code-in-text\">return<\/code> in <code class=\"fm-code-in-text\">async<\/code> methods<\/li>\n<li class=\"co-summary-bullet\">Iterating over asynchronous data using <code class=\"fm-code-in-text\">IAsyncEnumerable&lt;T&gt;<\/code> and <code class=\"fm-code-in-text\">await<\/code> <code class=\"fm-code-in-text\">foreach<\/code><\/li>\n<\/ul>\n<p class=\"copyrightbody\">Sometimes, we may want to use <code class=\"fm-code-in-text\">foreach<\/code> to iterate over a sequence of items we generate on the fly or retrieve from an external source without first adding the entire set of items to a collection. For example, we\u2019ve seen in chapters 8 and 13 how <code class=\"fm-code-in-text\">BlockingCollection&lt;T&gt;<\/code>\u2019s support for <code class=\"fm-code-in-text\">foreach<\/code> makes it easy to use for building a work queue. C# makes this easy with the <code class=\"fm-code-in-text\">yield<\/code> <code class=\"fm-code-in-text\">return<\/code> keyword, as discussed in chapter 2. However, both the versions of <code class=\"fm-code-in-text\">yield<\/code> <code class=\"fm-code-in-text\">return<\/code> we covered in chapter 2 and <code class=\"fm-code-in-text\">BlockingCollection&lt;T&gt;<\/code> don\u2019t support asynchronous programming.<a id=\"calibre_link-1250\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><\/p>\n<p class=\"copyrightbody\">In this chapter, we\u2019ll cover the asynchronous version of <code class=\"fm-code-in-text\">foreach<\/code> (called <code class=\"fm-code-in-text\">await foreach<\/code>) and the <code class=\"fm-code-in-text\">yield<\/code> <code class=\"fm-code-in-text\">return<\/code> enhancement from C# 8, which allows us to use it for asynchronous code. And finally, we\u2019ll employ all of those to write an asynchronous version of <code class=\"fm-code-in-text\">BlockingCollection&lt;T&gt;<\/code> and a fully asynchronous work queue.<\/p>\n<h2 class=\"fm-head\" id=\"calibre_link-133\">14.1 Iterating over an asynchronous collection<\/h2>\n<p class=\"copyrightbody\">To understand how the asynchronous <code class=\"fm-code-in-text\">await<\/code> <code class=\"fm-code-in-text\">foreach<\/code> works, we need to first take a look at the good old non-asynchronous <code class=\"fm-code-in-text\">foreach<\/code>. The <code class=\"fm-code-in-text\">foreach<\/code> keyword is syntactic sugar. It\u2019s just a nicer way to write code relative to using more basic language features. Specifically, <code class=\"fm-code-in-text\">foreach<\/code> is just a nicer way to write a <code class=\"fm-code-in-text\">while<\/code> loop. You can think of the compiler\u2019s implementation of <code class=\"fm-code-in-text\">foreach<\/code> as a simple text replacement. The compiler takes code like<a id=\"calibre_link-1251\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-1252\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-1253\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-187\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><\/p>\n<pre class=\"programlisting\">foreach(var x in collection)\n{\n     Console.WriteLine(x);\n}<\/pre>\n<p class=\"copyrightbody\">and transforms it into<\/p>\n<pre class=\"programlisting\">using(var enumerator = collection.GetEnumerator())\n{\n   while(enumerator.MoveNext())\n   {\n       var x = enumerator.Current;\n       Console.WriteLine(x);\n   }\n}<\/pre>\n<p class=\"copyrightbody\">As you can see, <code class=\"fm-code-in-text\">foreach<\/code> translates into a call to <code class=\"fm-code-in-text\">GetEnumerator<\/code> that retrieves an <code class=\"fm-code-in-text\">IEnumerator&lt;T&gt;<\/code> and a <code class=\"fm-code-in-text\">while<\/code> loop that uses <code class=\"fm-code-in-text\">MoveNext<\/code> to get the next item for each iteration of the loop. More generally, you can say the compiler takes code in the form of <a id=\"calibre_link-1254\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><\/p>\n<pre class=\"programlisting\">foreach([loop-variable-type] [loop-variable] in [collection])\n{\n     [loop-body]\n}<\/pre>\n<p class=\"copyrightbody\">and translates it to<\/p>\n<pre class=\"programlisting\">using(var enumerator = [collection].GetEnumerator())\n{\n   while(enumerator.MoveNext())\n   {\n       [loop-variable-type] [loop-variable] = enumerator.Current;\n       [loop-body];\n   }\n}<\/pre>\n<p class=\"copyrightbody\">Obviously, I\u2019m skipping a lot of details here; there are a lot of special cases and optimizations that the compiler can use to improve this code, but functionally, the <code class=\"fm-code-in-text\">foreach<\/code> loop is equivalent to this <code class=\"fm-code-in-text\">while<\/code> loop.<\/p>\n<p class=\"copyrightbody\">This works very well for non-asynchronous code, but to use a collection where items are retrieved asynchronously, that is, a collection where getting the next item is an asynchronous operation, we\u2019re going to have to make some changes to the way <code class=\"fm-code-in-text\">foreach<\/code> works. Specifically, we\u2019re going to need to add an <code class=\"fm-code-in-text\">await<\/code> inside the <code class=\"fm-code-in-text\">while<\/code> loop condition (third line in the previous code snippet), and to make that <code class=\"fm-code-in-text\">await<\/code> possible, we need <code class=\"fm-code-in-text\">MoveNext<\/code> to return a <code class=\"fm-code-in-text\">Task&lt;bool&gt;<\/code> instead of a <code class=\"fm-code-in-text\">bool<\/code>.<\/p>\n<p class=\"copyrightbody\">And that\u2019s what the <code class=\"fm-code-in-text\">await foreach<\/code> keyword and the <code class=\"fm-code-in-text\">IAsyncEnumerable&lt;T&gt;<\/code> interface are. The <code class=\"fm-code-in-text\">IAsyncEnumerable&lt;T&gt;<\/code> interface is similar to <code class=\"fm-code-in-text\">IEnumerable&lt;T&gt;<\/code>. It has just one method called <code class=\"fm-code-in-text\">GetAsyncEnumerator<\/code> (like <code class=\"fm-code-in-text\">IEnumerable&lt;T&gt;.GetEnumerator<\/code>) that returns an object implementing the <code class=\"fm-code-in-text\">IAsyncEnumerator&lt;T&gt;<\/code> interface (like <code class=\"fm-code-in-text\">IEnumerator&lt;T&gt;<\/code>). That method itself is not asynchronous and should return quickly. Any lengthy asynchronous initialization should happen the first time the enumerator\u2019s <code class=\"fm-code-in-text\">MoveNextAsync<\/code> method is called. The <code class=\"fm-code-in-text\">IAsyncEnumerator&lt;T&gt;<\/code> interface has a method named <code class=\"fm-code-in-text\">MoveNextAsync<\/code> that acts like the <code class=\"fm-code-in-text\">IEnumerator&lt;T&gt;.MoveNext<\/code> method, except it returns a <code class=\"fm-code-in-text\">ValueTask&lt;bool&gt;<\/code> instead of a <code class=\"fm-code-in-text\">bool<\/code>. <a id=\"calibre_link-1255\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-1256\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-1257\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-1258\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-1259\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-1260\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-1261\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-1262\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-193\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><\/p>\n<p class=\"copyrightbody\">Here is the comparison between the <code class=\"fm-code-in-text\">IEnumerable&lt;T&gt;<\/code> and <code class=\"fm-code-in-text\">IAsyncEnumerable&lt;T&gt;<\/code> (table 14.1) and <code class=\"fm-code-in-text\">IEnumerator<\/code> and <code class=\"fm-code-in-text\">IAsyncEnumerator<\/code> (table 14.2).<\/p>\n<p class=\"copyrightbody\">Table 14.1 <code class=\"fm-code-in-text\">IEnumerable<\/code> vs. <code class=\"fm-code-in-text\">IAsyncEnumerable<\/code><\/p>\n<table border=\"1\" class=\"contenttable-1-table\" id=\"calibre_link-1263\" width=\"100%\">\n<colgroup class=\"contenttable-0-colgroup\">\n<col class=\"contenttable-0-col\" span=\"1\" width=\"50%\"><\/col>\n<col class=\"contenttable-0-col\" span=\"1\" width=\"50%\"><\/col>\n<\/colgroup>\n<thead class=\"contenttable-1-thead\">\n<tr class=\"contenttable-c-tr\">\n<th class=\"contenttable-1-th\">\n<p class=\"copyrightfiguresb\">IEnumerable&lt;T&gt;<\/p>\n<\/th>\n<th class=\"contenttable-1-th\">\n<p class=\"copyrightfiguresb\">IAsyncEnumerable&lt;T&gt;<\/p>\n<\/th>\n<\/tr>\n<\/thead>\n<tbody class=\"contenttable-1-thead1\">\n<tr class=\"contenttable-c-tr\">\n<td class=\"contenttable-1-td\">\n<p class=\"copyrightfiguresb\"><code class=\"fm-code-in-text\">IEnumerator&lt;T&gt; GetEnumerator()<\/code><\/p>\n<\/td>\n<td class=\"contenttable-1-td\">\n<p class=\"copyrightfiguresb\"><code class=\"fm-code-in-text\">IAsyncEnumerator&lt;T&gt;<\/code><\/p>\n<p class=\"copyrightfiguresb\"><span class=\"fm-code-continuation-arrow\">\u27a5<\/span> <code class=\"fm-code-in-text\">GetAsyncEnumerator()<\/code><\/p>\n<\/td>\n<\/tr>\n<\/tbody>\n<\/table>\n<p class=\"copyrightbody\">Table 14.2 <code class=\"fm-code-in-text\">IEnumerator<\/code> vs. <code class=\"fm-code-in-text\">IAsyncEnumerator<\/code><\/p>\n<table border=\"1\" class=\"contenttable-1-table\" id=\"calibre_link-1264\" width=\"100%\">\n<colgroup class=\"contenttable-0-colgroup\">\n<col class=\"contenttable-0-col\" span=\"1\" width=\"50%\"><\/col>\n<col class=\"contenttable-0-col\" span=\"1\" width=\"50%\"><\/col>\n<\/colgroup>\n<thead class=\"contenttable-1-thead\">\n<tr class=\"contenttable-c-tr\">\n<th class=\"contenttable-1-th\">\n<p class=\"copyrightfiguresb\">IEnumerator&lt;T&gt;<\/p>\n<\/th>\n<th class=\"contenttable-1-th\">\n<p class=\"copyrightfiguresb\">IAsyncEnumerator&lt;T&gt;<\/p>\n<\/th>\n<\/tr>\n<\/thead>\n<tbody class=\"contenttable-1-thead1\">\n<tr class=\"contenttable-c-tr\">\n<td class=\"contenttable-1-td\">\n<p class=\"copyrightfiguresb\"><code class=\"fm-code-in-text\">T Current {get;}<\/code><\/p>\n<\/td>\n<td class=\"contenttable-1-td\">\n<p class=\"copyrightfiguresb\"><code class=\"fm-code-in-text\">T Current {get;}<\/code><\/p>\n<\/td>\n<\/tr>\n<tr class=\"contenttable-c-tr1\">\n<td class=\"contenttable-1-td\">\n<p class=\"copyrightfiguresb\"><code class=\"fm-code-in-text2\">bool MoveNext()<\/code><\/p>\n<\/td>\n<td class=\"contenttable-1-td\">\n<p class=\"copyrightfiguresb\"><code class=\"fm-code-in-text2\">ValueTask&lt;bool&gt; MoveNextAsync()<\/code><\/p>\n<\/td>\n<\/tr>\n<tr class=\"contenttable-c-tr\">\n<td class=\"contenttable-1-td\">\n<p class=\"copyrightfiguresb\"><code class=\"fm-code-in-text\">void Dispose()<\/code><\/p>\n<\/td>\n<td class=\"contenttable-1-td\">\n<p class=\"copyrightfiguresb\"><code class=\"fm-code-in-text\">ValueTask DisposeAsync()<\/code><\/p>\n<\/td>\n<\/tr>\n<\/tbody>\n<\/table>\n<p class=\"copyrightbody\">As you can see from the tables, the asynchronous and non-asynchronous interfaces are almost exactly the same, just with support for <code class=\"fm-code-in-text\">async<\/code>\/<code class=\"fm-code-in-text\">await<\/code>. The tables do not contain <code class=\"fm-code-in-text\">IEnumerable&lt;T&gt;<\/code>\u2019s support for the older nongeneric <code class=\"fm-code-in-text\">IEnumerable<\/code> interface because it\u2019s practically never used. Also, I\u2019ve ignored <code class=\"fm-code-in-text\">IAsyncEnumerator&lt;T&gt;.GetAsync<\/code><code class=\"fm-code-in-text\">Enumerator<\/code>\u2018s cancellation token parameter because we\u2019ll talk about it in detail later in this chapter.<a id=\"calibre_link-1265\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><\/p>\n<p class=\"copyrightbody\">The last piece of the puzzle is the awkwardly named <code class=\"fm-code-in-text\">await foreach<\/code> loop, which is just like <code class=\"fm-code-in-text\">foreach<\/code>, except it uses <code class=\"fm-code-in-text\">IAsyncEnumerable&lt;T&gt;<\/code> instead of <code class=\"fm-code-in-text\">IEnumerable&lt;T&gt;<\/code> and adds the required <code class=\"fm-code-in-text\">await<\/code> to make everything work. So this loop<a id=\"calibre_link-1266\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><\/p>\n<pre class=\"programlisting\">await foreach(var x in collection)\n{\n     Console.WriteLine(x);\n}<\/pre>\n<p class=\"copyrightbody\">translates into<\/p>\n<pre class=\"programlisting\">await using(var enumerator = collection.GetAsyncEnumerator())\n{\n   while(await enumerator.MoveNext())                         <span class=\"fm-combinumeral\">\u2776<\/span>\n   {\n       var x = enumerator.Current;\n       Console.WriteLine(x);\n   }\n}<\/pre>\n<p class=\"copyrightbody\"><span class=\"fm-combinumeral\">\u2776<\/span> Adds an await here<a id=\"calibre_link-1267\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-1268\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><\/p>\n<h2 class=\"fm-head\" id=\"calibre_link-134\">14.2 Generating an asynchronous collection<\/h2>\n<p class=\"copyrightbody\">Now we know how to use an asynchronous collection, but asynchronous collections don\u2019t actually exist, at least not out of the box. All the collections included in the .NET library are data structures that hold items in memory, and with the items ready in memory, there is no need to retrieve them (asynchronously or otherwise). <a id=\"calibre_link-171\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-1269\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><\/p>\n<p class=\"copyrightbody\">When we talk about support for asynchronous collections, what we really want is the ability to use an <code class=\"fm-code-in-text\">await foreach<\/code> loop to process a sequence of data items that are asynchronously generated or retrieved: we want an asynchronous version of the <code class=\"fm-code-in-text\">yield return<\/code> keyword we\u2019ve talked about in chapter 2. In chapter 2, we also used the following code to dynamically generate values 1 and 2.<a id=\"calibre_link-1270\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-1271\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><\/p>\n<p class=\"fm-code-listing-caption\">Listing 14.1 <code class=\"fm-code-in-text1\">yield return<\/code> example from chapter 2<\/p>\n<pre class=\"programlisting\">private IEnumerable&lt;int&gt; YieldDemo()\n{\n   yield return 1;\n   yield return 2;\n}\n \npublic void UseYieldDemo()\n{\n   foreach(var current in YieldDemo())\n   {\n         Console.WriteLine($\"Got {current}\");\n   }\n}<\/pre>\n<p class=\"copyrightbody\">Now let\u2019s add an asynchronous call to the method generating the values. We\u2019ll use <code class=\"fm-code-in-text\">Task.Delay<\/code> for simplicity.<\/p>\n<p class=\"fm-code-listing-caption\">Listing 14.2 Async <code class=\"fm-code-in-text1\">yield<\/code> <code class=\"fm-code-in-text1\">return<\/code> example<\/p>\n<pre class=\"programlisting\">private async IAsyncEnumerable&lt;int&gt; AsyncYieldDemo()          <span class=\"fm-combinumeral\">\u2776<\/span>\n{\n   yield return 1;\n   await Task.Delay(1000);                                    <span class=\"fm-combinumeral\">\u2777<\/span>\n   yield return 2;\n}\n \npublic async Task UseAsyncYieldDemo()\n{\n   await foreach(var current in AsyncYieldDemo())             <span class=\"fm-combinumeral\">\u2778<\/span>\n   {\n         Console.WriteLine($\"Got {current}\");\n   }\n}<\/pre>\n<p class=\"copyrightbody\"><span class=\"fm-combinumeral\">\u2776<\/span> Changes IEnumerable&lt;int&gt; to async IAsyncEnumerable&lt;int&gt;<\/p>\n<p class=\"copyrightbody\"><span class=\"fm-combinumeral\">\u2777<\/span> We can use await.<\/p>\n<p class=\"copyrightbody\"><span class=\"fm-combinumeral\">\u2778<\/span> Changes foreach to await foreach<\/p>\n<p class=\"copyrightbody\">We had to change the generator method to return <code class=\"fm-code-in-text\">IAsyncEnumerable&lt;int&gt;<\/code> instead of <code class=\"fm-code-in-text\">IEnumerable&lt;int&gt;<\/code> and mark it as <code class=\"fm-code-in-text\">async<\/code>&mdash;and that\u2019s it. We can now use <code class=\"fm-code-in-text\">await<\/code> inside of it and the <code class=\"fm-code-in-text\">await foreach<\/code> keyword we talked about earlier to iterate over the generated sequence.<a id=\"calibre_link-1272\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-1273\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-1274\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><\/p>\n<p class=\"copyrightbody\">As we\u2019ve seen in chapter 2, for the non-async <code class=\"fm-code-in-text\">yield<\/code> <code class=\"fm-code-in-text\">return<\/code>, when we compile this, the compiler will transform the <code class=\"fm-code-in-text\">AsyncYieldDemo<\/code> method into classes that implement <code class=\"fm-code-in-text\">IAsyncEnumerable&lt;int&gt;<\/code> and <code class=\"fm-code-in-text\">IAsyncEnumerator&lt;int&gt;.<\/code> If we use the same transformations from chapter 2, we get the following listing.<a id=\"calibre_link-1275\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-1276\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-192\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-1277\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><\/p>\n<p class=\"fm-code-listing-caption\">Listing 14.3 Code generated by the compiler from listing 14.2<\/p>\n<pre class=\"programlisting\">public class AsyncYieldDemo_Enumerable : I<b class=\"fm-bold\">Async<\/b>Enumerable&lt;int&gt;\n{\n   public I<b class=\"fm-bold\">Async<\/b>Enumerator&lt;int&gt; Get<b class=\"fm-bold\">Async<\/b>Enumerator(CancellationToken _)\n   {\n      return new YieldDemo_Enumerator();\n   }\n}\n \npublic class YieldDemo_Enumerator : I<b class=\"fm-bold\">Async<\/b>Enumerator&lt;int&gt;\n{\n   public int Current { get; private set; }\n \n   private <b class=\"fm-bold\">async Task<\/b> Step0()\n   {\n      Current = 1;\n   }\n   private <b class=\"fm-bold\">async Task<\/b> Step1()\n   {\n      await Task.Delay(1000);\n      Current = 2;\n   }\n \n   private int _step = 0;\n   public <b class=\"fm-bold\">async ValueTask<\/b>&lt;bool&gt; MoveNext<b class=\"fm-bold\">Async<\/b>()\n   {\n      switch(_step)\n      {\n         case 0:\n            <b class=\"fm-bold\">await<\/b> Step0();\n            ++_step;\n            break;\n         case 1:\n            <b class=\"fm-bold\">await<\/b> Step1();\n            ++_step;\n            break;\n         case 2:\n            return false;\n      }\n      return true;\n   }\n   public ValueTask DisposeAsync() =&gt; ValueTask.CompletedTask;\n}\n \npublic IAsyncEnumerable&lt;int&gt; AsyncYieldDemo()\n{\n   return new AsyncYieldDemo_Enumerable();\n}<\/pre>\n<p class=\"copyrightbody\">This is exactly the same transformation we\u2019ve seen in chapter 2 (except for the added <code class=\"fm-code-in-text\">async<\/code>, <code class=\"fm-code-in-text\">await<\/code>, and the occasional <code class=\"fm-code-in-text\">Task<\/code> where needed; changes are in bold). You can go back to listing 2.5 for a complete breakdown of this code. The short version is<\/p>\n<ul class=\"calibre9\">\n<li class=\"fm-list-bullet\">\n<p class=\"list\">The compiler breaks the method into chunks whenever it finds a <code class=\"fm-code-in-text\">yield<\/code> <code class=\"fm-code-in-text\">return<\/code>. Each <code class=\"fm-code-in-text\">yield return<\/code> ends a chunk.<\/p>\n<\/li>\n<li class=\"fm-list-bullet\">\n<p class=\"list\">The <code class=\"fm-code-in-text\">yield return<\/code> keyword is changed to <code class=\"fm-code-in-text\">Current =<\/code>.<\/p>\n<\/li>\n<li class=\"fm-list-bullet\">\n<p class=\"list\">The compiler generates the <code class=\"fm-code-in-text\">MoveNextAsync<\/code> method that calls the first chunk the first time it\u2019s called, the second chunk the second time it\u2019s called, and so forth.<a id=\"calibre_link-1278\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-273\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><\/p>\n<\/li>\n<\/ul>\n<p class=\"copyrightbody\">We\u2019ve used <code class=\"fm-code-in-text\">await<\/code> extensively in this code, but as we\u2019ve seen in chapter 3, <code class=\"fm-code-in-text\">await<\/code> (like <code class=\"fm-code-in-text\">yield return<\/code>) is implemented by the compiler rewriting your code into a class. Let\u2019s see how the compiler generates code for the <code class=\"fm-code-in-text\">async<\/code> methods in listing 14.3. We\u2019ll start with the <code class=\"fm-code-in-text\">Step0<\/code> method:<\/p>\n<pre class=\"programlisting\">   private Task Step0()\n   {\n      Current = 1;\n      return Task.CompletedTask;\n   }<\/pre>\n<p class=\"copyrightbody\">That was easy because <code class=\"fm-code-in-text\">Step0<\/code> doesn\u2019t do anything asynchronous, the compiler doesn\u2019t need to change it, and we just drop the <code class=\"fm-code-in-text\">async<\/code> keyword and return <code class=\"fm-code-in-text\">Task.CompletedTask<\/code> explicitly. Now let\u2019s look at <code class=\"fm-code-in-text\">Step1<\/code>:<\/p>\n<pre class=\"programlisting\">   private TaskCompletionSource _step1tcs = new();\n   private Task Step1()\n   {\n      Task.Delay(1000).ContinueWith(Step1Part2);\n      return _step1tcs.Task;\n   }\n   private void Step1Part2(Task task)\n   {\n      Current = 2;\n      _step1tcs.SetResult();\n   }<\/pre>\n<p class=\"copyrightbody\">Unlike <code class=\"fm-code-in-text\">Step0<\/code>, <code class=\"fm-code-in-text\">Step1<\/code> really performs an asynchronous operation, namely <code class=\"fm-code-in-text\">Task.Delay<\/code>, so as we\u2019ve seen in chapter 3, everything after the <code class=\"fm-code-in-text\">await<\/code> is moved into a different method that is passed to <code class=\"fm-code-in-text\">ContinueWith<\/code>. The <code class=\"fm-code-in-text\">Step1<\/code> method needs to return a <code class=\"fm-code-in-text\">Task,<\/code> so we used the <code class=\"fm-code-in-text\">TaskCompletionSource<\/code> class we talked about in chapter 10 to create this <code class=\"fm-code-in-text\">Task<\/code>. To keep the code simple, I\u2019ve ignored all error handling. The compiler translates the <code class=\"fm-code-in-text\">MoveNextAsync<\/code> method in the same way.<a id=\"calibre_link-1279\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-1280\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-1281\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-1282\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><\/p>\n<h2 class=\"fm-head\" id=\"calibre_link-135\">14.3 Canceling an asynchronous collection<\/h2>\n<p class=\"copyrightbody\">Asynchronous operations often support cancellation, and we obviously want to be able to support cancellation in operations called from <code class=\"fm-code-in-text\">await<\/code> <code class=\"fm-code-in-text\">foreach<\/code> loops. To support cancellation, the <code class=\"fm-code-in-text\">GetAsyncEnumerator<\/code> method accepts a cancellation token as an optional parameter, but this by itself doesn\u2019t solve our problem because<a id=\"calibre_link-1283\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-1284\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-1285\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-169\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><\/p>\n<ul class=\"calibre9\">\n<li class=\"fm-list-bullet\">\n<p class=\"list\">The code calling <code class=\"fm-code-in-text\">GetAsyncEnumerator<\/code> is generated by the compiler when we use <code class=\"fm-code-in-text\">await foreach<\/code>, and we have no obvious way to pass a cancellation token.<\/p>\n<\/li>\n<li class=\"fm-list-bullet\">\n<p class=\"list\">The <code class=\"fm-code-in-text\">GetAsyncEnumerator<\/code> code is also generated by the compiler, and we have no obvious way to access the method\u2019s parameter.<\/p>\n<\/li>\n<\/ul>\n<p class=\"copyrightbody\">The first problem is solved by the <code class=\"fm-code-in-text\">WithCancellation<\/code> extension method. This method can be called on any <code class=\"fm-code-in-text\">IAsyncEnumerable&lt;T&gt;<\/code>, and it returns a new object that also implements the <code class=\"fm-code-in-text\">IAsyncEnumerable&lt;T&gt;<\/code> interface. This new object\u2019s <code class=\"fm-code-in-text\">GetAsyncEnumerator<\/code> method simply calls the original object\u2019s <code class=\"fm-code-in-text\">GetAsyncEnumerator<\/code> with a cancellation token you provide. To use <code class=\"fm-code-in-text\">WithCancellation<\/code>, you just call it and use the returned object. The simplest way to use it is directly in the <code class=\"fm-code-in-text\">await<\/code> foreach clause:<a id=\"calibre_link-1286\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-1287\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-1288\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-1289\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><\/p>\n<pre class=\"programlisting\">await foreach(var item in collection.WithCancellation(token))<\/pre>\n<p class=\"copyrightbody\">The <code class=\"fm-code-in-text\">WithCancellation<\/code> method is pretty simple. If you want to implement it yourself, all you need to do is write a class as shown in the following listing.<a id=\"calibre_link-1290\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><\/p>\n<p class=\"fm-code-listing-caption\">Listing 14.4 <code class=\"fm-code-in-text1\">WithCancellation<\/code> implementation<\/p>\n<pre class=\"programlisting\">public class WithCancellation&lt;T&gt; : IAsyncEnumerable&lt;T&gt;\n{\n   private IAsyncEnumerable&lt;T&gt; _originalEnumerable;          <span class=\"fm-combinumeral\">\u2776<\/span>\n   private CancellationToken _cancellationToken;             <span class=\"fm-combinumeral\">\u2776<\/span>\n      \n   public WithCancellation(\n       IAsyncEnumerable&lt;T&gt; originalEnumerable,\n       CancellationToken cancellationToken)\n   {\n       _originalEnumerable = originalEnumerable;             <span class=\"fm-combinumeral\">\u2777<\/span>\n       _cancellationToken = cancellationToken;               <span class=\"fm-combinumeral\">\u2777<\/span>\n   }\n   \n   public IAsyncEnumerator&lt;T&gt; GetAsyncEnumerator(\n       CancellationToken dontcare)\n   {\n      return _originalEnumerable.                            <span class=\"fm-combinumeral\">\u2778<\/span>\n         GetAsyncEnumerator(_cancellationToken);             <span class=\"fm-combinumeral\">\u2778<\/span>\n   }\n} <\/pre>\n<p class=\"copyrightbody\"><span class=\"fm-combinumeral\">\u2776<\/span> Fields for original enumerable and cancellation token<\/p>\n<p class=\"copyrightbody\"><span class=\"fm-combinumeral\">\u2777<\/span> Constructs to store original enumerable and cancellation token<\/p>\n<p class=\"copyrightbody\"><span class=\"fm-combinumeral\">\u2778<\/span> Calls original enumerable with cancellation token<\/p>\n<p class=\"copyrightbody\">Most of this code just stores an <code class=\"fm-code-in-text\">async<\/code> enumerable and a cancellation token, so it can, in the <code class=\"fm-code-in-text\">GetAsyncEnumerator<\/code> method, call the original enumerable\u2019s <code class=\"fm-code-in-text\">GetAsyncEnumerator<\/code> method and pass the cancellation token as a parameter. <a id=\"calibre_link-1291\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-1292\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><\/p>\n<p class=\"copyrightbody\">This solves the first problem. It lets us pass a cancellation token to <code class=\"fm-code-in-text\">GetAsyncEnumerator<\/code> when it\u2019s used by <code class=\"fm-code-in-text\">await<\/code> <code class=\"fm-code-in-text\">foreach<\/code>. However, it leaves us with the second problem&mdash;receiving the token in the method generating the values.<\/p>\n<p class=\"copyrightbody\">Luckily, the C# compiler can do this; it will pass the cancellation token as a parameter to the method generating the sequence if we just tell it which parameter to use. To indicate which parameter to use, we need to decorate it with the <code class=\"fm-code-in-text\">[EnumeratorCancellation]<\/code> attribute. We now know how to modify the code from listing 14.2 to use a cancellation token.<a id=\"calibre_link-212\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-1293\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><\/p>\n<p class=\"fm-code-listing-caption\">Listing 14.5 Async <code class=\"fm-code-in-text1\">yield return<\/code> example with cancellation<\/p>\n<pre class=\"programlisting\">private async IAsyncEnumerable&lt;int&gt; AsyncYieldDemo( \n   [EnumeratorCancellation] CancellationToken cancellationToken = default) <span class=\"fm-combinumeral\">\u2776<\/span>\n{\n   yield return 1;\n   await Task.Delay(1000, cancellationToken);\n   yield return 2;\n}\n \npublic async Task UseAsyncYieldDemo()\n{\n   var cancel = new CancellationTokenSource();\n   var collection = AsyncYieldDemo();\n   await foreach(var current in \n        collection.WithCancellation(cancel.Token))                         <span class=\"fm-combinumeral\">\u2777<\/span>\n   {\n         Console.WriteLine($\"Got {current}\");\n   }\n}<\/pre>\n<p class=\"copyrightbody\"><span class=\"fm-combinumeral\">\u2776<\/span> Parameter to receive cancellation token<\/p>\n<p class=\"copyrightbody\"><span class=\"fm-combinumeral\">\u2777<\/span> Uses WithCancellation to pass cancellation token<\/p>\n<p class=\"copyrightbody\">In this listing, we added a <code class=\"fm-code-in-text\">CancellationToken<\/code> parameter to the <code class=\"fm-code-in-text\">AsyncYieldDemo<\/code> and decorated it with the <code class=\"fm-code-in-text\">[EnumeratorCancellation]<\/code> attribute to allow <code class=\"fm-code-in-text\">AsyncYieldDemo<\/code> to be canceled. We then used <code class=\"fm-code-in-text\">WithCancellation<\/code> to pass the cancellation token to <code class=\"fm-code-in-text\">AsyncYieldDemo<\/code>. <a id=\"calibre_link-1294\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-1295\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><\/p>\n<p class=\"copyrightbody\">Obviously, because we call <code class=\"fm-code-in-text\">AsyncYieldDemo<\/code> and iterate over it in the same method, we can just pass the cancellation token to <code class=\"fm-code-in-text\">AsyncYieldDemo<\/code> directly, but this isn\u2019t always possible. The code that creates the <code class=\"fm-code-in-text\">IAsyncEnumerable&lt;T&gt;<\/code> and the code that iterates over it might be in different components. We might not have access to source code that creates the <code class=\"fm-code-in-text\">IAsyncEnumerable&lt;T&gt;<\/code> at all, or the code can be in different methods, and using <code class=\"fm-code-in-text\">WithCancellation<\/code> is just simpler than passing the cancellation token all the way to the code that created the enumerable.<\/p>\n<p class=\"copyrightbody\">While this sample supports cancellation, it will never cancel the operation. Now let\u2019s see what happens when we do cancel. We\u2019ll start with cancellation before the loop even starts.<\/p>\n<p class=\"fm-code-listing-caption\">Listing 14.6 Canceling the iteration before the loop starts<\/p>\n<pre class=\"programlisting\">private async IAsyncEnumerable&lt;int&gt; AsyncYieldDemo( \n   [EnumeratorCancellation] CancellationToken cancellationToken=default)\n{\n   yield return 1;\n   await Task.Delay(1000, cancellationToken);\n   yield return 2;\n}\n \npublic async Task UseYieldDemo()\n{\n   var cancel = new CancellationTokenSource();\n   cancel.Cancel();                                         <span class=\"fm-combinumeral\">\u2776<\/span>\n   await foreach(var current in \n        AsyncYieldDemo().WithCancellation(cancel.Token))\n   {\n         Console.WriteLine($\"Got {current}\");\n   }\n}<\/pre>\n<p class=\"copyrightbody\"><span class=\"fm-combinumeral\">\u2776<\/span> Cancels the loop before starting<\/p>\n<p class=\"copyrightbody\">In this example, we call the cancellation token source\u2019s <code class=\"fm-code-in-text\">Cancel<\/code> method before the loop starts. If we run this, we\u2019ll see that the program will print \u201cGot 1\u201d and only then crash with a <code class=\"fm-code-in-text\">TaskCanceledException<\/code>. Why did it run the first iteration of the loop if the cancellation token was already canceled before we started?<a id=\"calibre_link-1296\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><\/p>\n<p class=\"copyrightbody\">We need to remember that, as discussed in chapter 9, a <code class=\"fm-code-in-text\">CancellationToken<\/code> is just a thread-safe flag we can use to check whether an operation needs to be canceled. In this listing, we don\u2019t check for cancellation in the loop at all. In the <code class=\"fm-code-in-text\">AsyncYieldDemo<\/code> method, we also generate the first value without checking for cancellation; the first time anyone checks for cancellation is inside the <code class=\"fm-code-in-text\">Task.Delay<\/code> call.<a id=\"calibre_link-1297\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-170\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-1298\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><\/p>\n<h2 class=\"fm-head\" id=\"calibre_link-136\">14.4 Other options<\/h2>\n<p class=\"copyrightbody\">In addition to the <code class=\"fm-code-in-text\">WithCancellation<\/code> method, there\u2019s also a <code class=\"fm-code-in-text\">ToBlockingEnumerable<\/code> method that wraps the <code class=\"fm-code-in-text\">IAsyncEnumerable&lt;T&gt;<\/code> in a non-asynchronous <code class=\"fm-code-in-text\">IEnumerable&lt;T&gt;<\/code> you can use in a normal <code class=\"fm-code-in-text\">foreach<\/code> loop in non-asynchronous code. The <code class=\"fm-code-in-text\">ToBlockingEnumerable<\/code> method lets you consume an asynchronous API from non-asynchronous code. This is equivalent to calling <code class=\"fm-code-in-text\">Wait()<\/code> on each task returned by <code class=\"fm-code-in-text\">MoveNextAsync<\/code>. <a id=\"calibre_link-1299\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-1300\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-1301\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-1302\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-1303\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-1304\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-1305\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-1306\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-1307\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-1308\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><\/p>\n<p class=\"copyrightbody\">The <code class=\"fm-code-in-text\">ToBlockingEnumerable<\/code> method, like other ways of calling <code class=\"fm-code-in-text\">Wait()<\/code>, negates the benefits of using asynchronous operation and can cause deadlocks in some situations. It should be used only when you must use an asynchronous collection from non-asynchronous code and have no other choice. <a id=\"calibre_link-1309\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><\/p>\n<p class=\"copyrightbody\">And finally, there\u2019s the <code class=\"fm-code-in-text\">ConfigureAwait<\/code> extension method. Calling <code class=\"fm-code-in-text\">ConfigureAwait<\/code> on the <code class=\"fm-code-in-text\">IAsyncEnumerable&lt;T&gt;<\/code> object is equivalent to calling <code class=\"fm-code-in-text\">ConfigureAwait<\/code> on all tasks returned by <code class=\"fm-code-in-text\">MoveNextAsync<\/code>. <a id=\"calibre_link-1310\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-1311\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-1312\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><\/p>\n<p class=\"copyrightbody\">The <code class=\"fm-code-in-text\">ConfigureAwait<\/code> method lets you decide if the code after the <code class=\"fm-code-in-text\">await<\/code> will run in the same context as the code before the <code class=\"fm-code-in-text\">await<\/code>. This typically only matters in local UI applications (see chapter 11 for more details).<a id=\"calibre_link-1313\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><\/p>\n<h2 class=\"fm-head\" id=\"calibre_link-137\">14.5 IAsyncEnumerable&lt;T&gt; and LINQ<\/h2>\n<p class=\"copyrightbody\">LINQ is a C# feature that lets us use SQL-like operators (such as <code class=\"fm-code-in-text\">Select<\/code> and <code class=\"fm-code-in-text\">Where<\/code>) to transform any sequence of items (usually used with the .NET collections). LINQ uses the <code class=\"fm-code-in-text\">IEnumerable&lt;T&gt;<\/code> interface to interact with the sequence you are transforming.<a id=\"calibre_link-1314\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-1315\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-1316\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-1317\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-1318\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-1319\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-1320\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-184\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><\/p>\n<p class=\"copyrightbody\">At the time of this writing, the latest version of .NET (version 9) does not support LINQ with <code class=\"fm-code-in-text\">IAsyncEnumrable&lt;T&gt;<\/code>. However, the .NET Reactive Extensions (RX) team has published the <code class=\"fm-code-in-text\">System.Linq.Async<\/code> library (available via NuGet), which adds support for all the LINQ operators to <code class=\"fm-code-in-text\">IAsyncEnumerable&lt;T&gt;<\/code> (and as such, to all asynchronous collections and sequences as well).<a id=\"calibre_link-1321\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-1322\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><\/p>\n<p class=\"copyrightbody\">If .NET adds built-in support for asynchronous LINQ in the future, it\u2019s likely they will use the <code class=\"fm-code-in-text\">System.Linq.Async<\/code> library from the RX team (<code class=\"fm-code-in-text\">IAsyncEnumerable&lt;T&gt;<\/code> itself was originally written by the RX team) or, at least, make the built-in LINQ support compatible with <code class=\"fm-code-in-text\">System.Linq.Async<\/code>.<a id=\"calibre_link-1323\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><\/p>\n<h2 class=\"fm-head\" id=\"calibre_link-138\">14.6 Example: Iterating over asynchronously retrieved data<\/h2>\n<p class=\"copyrightbody\">Let\u2019s say we need to process a binary-stream-containing numbers. We\u2019ll write two methods. One reads the stream and extracts the numbers (using <code class=\"fm-code-in-text\">yield<\/code> <code class=\"fm-code-in-text\">return<\/code>) and one processes the numbers. This stream can be a file, but it can also be a network connection. For simplicity, we\u2019ll start with a non-asynchronous version.<a id=\"calibre_link-1324\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-1325\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><\/p>\n<p class=\"fm-code-listing-caption\">Listing 14.7 Reading a stream of numbers non-asynchronously<\/p>\n<pre class=\"programlisting\">public class NumbersProcessor\n{\n   private IEnumerable&lt;int&gt; GetNumbers(Stream stream)\n   {\n      var buffer = new byte[4];\n      while(stream.Read(buffer, 0, 4) == 4)                  <span class=\"fm-combinumeral\">\u2776<\/span>\n      {\n         var number = BitConverter.ToInt32(buffer);          <span class=\"fm-combinumeral\">\u2777<\/span>\n         yield return number;                                <span class=\"fm-combinumeral\">\u2778<\/span>\n      }\n   }\n \n   public void ProcessStream(Stream stream)\n   {\n      foreach(var number in GetNumbers(stream))              <span class=\"fm-combinumeral\">\u2779<\/span>\n      {\n         Console.WriteLine(number);                          <span class=\"fm-combinumeral\">\u277a<\/span>\n      }\n   }\n}<\/pre>\n<p class=\"copyrightbody\"><span class=\"fm-combinumeral\">\u2776<\/span> Gets the next 4 bytes from the stream<\/p>\n<p class=\"copyrightbody\"><span class=\"fm-combinumeral\">\u2777<\/span> Converts them to an int<\/p>\n<p class=\"copyrightbody\"><span class=\"fm-combinumeral\">\u2778<\/span> Returns the int<\/p>\n<p class=\"copyrightbody\"><span class=\"fm-combinumeral\">\u2779<\/span> For each number in stream<\/p>\n<p class=\"copyrightbody\"><span class=\"fm-combinumeral\">\u277a<\/span> Processes the number<\/p>\n<p class=\"copyrightbody\">The first method, <code class=\"fm-code-in-text\">GetNumbers<\/code>, reads the stream and produces a sequence of numbers. It stops as soon as it can\u2019t retrieve a whole number. The second method, <code class=\"fm-code-in-text\">ProcessStream<\/code>, uses the first method and then does something with the numbers (because this is sample code, we\u2019re going to just print them to the console).<a id=\"calibre_link-1326\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-1327\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><\/p>\n<p class=\"copyrightbody\">As we\u2019ve said earlier in this book, operations such as reading from a file or a communication channel are often best done asynchronously. So let\u2019s take everything we\u2019ve discussed in this chapter and make the code asynchronous.<\/p>\n<p class=\"fm-code-listing-caption\">Listing 14.8 Reading a stream of numbers asynchronously<\/p>\n<pre class=\"programlisting\">public class Async NumbersProcessor\n{\n   private async IAsyncEnumerable&lt;int&gt;\n      <span class=\"fm-code-continuation-arrow\">\u27a5<\/span>GetNumbers(Stream stream)                           <span class=\"fm-combinumeral\">\u2776<\/span>\n   {\n      var buffer = new byte[4];\n      while(await stream.ReadAsync(buffer, 0, 4) == 4)      <span class=\"fm-combinumeral\">\u2777<\/span>\n      {\n         var number = BitConverter.ToInt32(buffer);\n         yield return number;\n      }\n   }\n \n   public async Task ProcessStream(Stream stream)           <span class=\"fm-combinumeral\">\u2778<\/span>\n   {\n      await foreach(var number in GetNumbers(stream))       <span class=\"fm-combinumeral\">\u2779<\/span>\n      {\n         Console.WriteLine(number);\n      }\n   }\n}<\/pre>\n<p class=\"copyrightbody\"><span class=\"fm-combinumeral\">\u2776<\/span> IEnumerable&lt;int&gt; to async IAsyncEnumerable&lt;int&gt;<\/p>\n<p class=\"copyrightbody\"><span class=\"fm-combinumeral\">\u2777<\/span> stream.Read to await stream.ReadAsync<\/p>\n<p class=\"copyrightbody\"><span class=\"fm-combinumeral\">\u2778<\/span> void to async Task<\/p>\n<p class=\"copyrightbody\"><span class=\"fm-combinumeral\">\u2779<\/span> foreach to await foreach<\/p>\n<p class=\"copyrightbody\"><a id=\"calibre_link-1328\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a>The asynchronous code is the same as the non-asynchronous code, except that we added the words <code class=\"fm-code-in-text\">async<\/code> and <code class=\"fm-code-in-text\">await<\/code> in some places. To read the stream asynchronously, we need to call <code class=\"fm-code-in-text\">Stream.ReadAsync<\/code> instead of <code class=\"fm-code-in-text\">Stream.Read<\/code>, which is an important change. We want to await the <code class=\"fm-code-in-text\">ReadAsync<\/code> call, so we add an <code class=\"fm-code-in-text\">await<\/code> before <code class=\"fm-code-in-text\">ReadAsync<\/code>. To be able to use <code class=\"fm-code-in-text\">await<\/code>, we have to make the method <code class=\"fm-code-in-text\">async<\/code>, and <code class=\"fm-code-in-text\">async<\/code> methods can\u2019t return <code class=\"fm-code-in-text\">IEnumerable&lt;int&gt;<\/code>, so we mark the method as <code class=\"fm-code-in-text\">async<\/code> and change the return type to <code class=\"fm-code-in-text\">IAsyncEnumerable&lt;int&gt;.<\/code><\/p>\n<p class=\"copyrightbody\">Now we\u2019ve finished modifying the <code class=\"fm-code-in-text\">GetNumbers<\/code> method and move on to <code class=\"fm-code-in-text\">Process<\/code><code class=\"fm-code-in-text\">Stream<\/code>. To process the <code class=\"fm-code-in-text\">IAsyncEnumrable&lt;int&gt;<\/code> returned by <code class=\"fm-code-in-text\">GetNumbers<\/code>, we need to replace the <code class=\"fm-code-in-text\">foreach<\/code> with an <code class=\"fm-code-in-text\">await foreach<\/code>. We can only use <code class=\"fm-code-in-text\">await foreach<\/code> in an <code class=\"fm-code-in-text\">async<\/code> method, so we mark the method as <code class=\"fm-code-in-text\">async<\/code> and change the return type from <code class=\"fm-code-in-text\">void<\/code> to <code class=\"fm-code-in-text\">Task<\/code> (we talked about the problems with <code class=\"fm-code-in-text\">async void<\/code> methods near the end of chapter 3).<a id=\"calibre_link-1329\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-1330\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><\/p>\n<h2 class=\"fm-head\" id=\"calibre_link-139\">14.7 Example: BlockingCollection&lt;T&gt;-like asynchronous queue<\/h2>\n<p class=\"copyrightbody\">In the previous chapter, in listing 13.11, we used <code class=\"fm-code-in-text\">BlockingCollection&lt;T&gt;<\/code> to implement a work queue with 10 worker threads. <code class=\"fm-code-in-text\">BlockingCollection&lt;T&gt;<\/code> has the <code class=\"fm-code-in-text\">GetConsumingEnumerable<\/code> method that lets the code using it use <code class=\"fm-code-in-text\">foreach<\/code>, which results in clean and readable code. However, <code class=\"fm-code-in-text\">BlockingCollection&lt;T&gt;<\/code> does not support asynchronous operations.<a id=\"calibre_link-1331\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-1332\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-1333\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-1334\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-1335\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><\/p>\n<p class=\"copyrightbody\">In listing 13.12, we used <code class=\"fm-code-in-text\">Channel&lt;T&gt;<\/code> to write an asynchronous version of the same program, but the <code class=\"fm-code-in-text\">Channel&lt;T&gt;<\/code> interface isn\u2019t as nice. We had to use an infinite loop to read the items from the queue and use an exception to signal the work is done and that there will be no more items.<a id=\"calibre_link-1336\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><\/p>\n<p class=\"copyrightbody\"><a id=\"calibre_link-185\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a>Now, with <code class=\"fm-code-in-text\">IAsyncEnumerable&lt;T&gt;<\/code>, we can easily write a class that implements a <code class=\"fm-code-in-text\">BlockingCollection&lt;T&gt;<\/code>-like <code class=\"fm-code-in-text\">GetConsumingEnumerable<\/code> on top of <code class=\"fm-code-in-text\">Channel&lt;T&gt;<\/code>. This example only implements the <code class=\"fm-code-in-text\">Add<\/code> and <code class=\"fm-code-in-text\">GetConsumingEnumerable<\/code> methods (which are all we need to implement our work queue).<a id=\"calibre_link-1337\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-1338\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><\/p>\n<p class=\"fm-code-listing-caption\">Listing 14.9 Async version of <code class=\"fm-code-in-text1\">BlockingCollection&lt;T&gt;.GetConsumingEnumerable<\/code><\/p>\n<pre class=\"programlisting\">public class ChannelAsyncCollection&lt;T&gt;\n{\n   private Channel&lt;T&gt; _channel = Channel.CreateUnbounded&lt;T&gt;();\n   public void Add(T item)\n   {\n      _channel.Writer.TryWrite(item);\n   }\n \n   public void CompleteAdding()\n   {\n      _channel.Writer.Complete();\n   }\n   public async IAsyncEnumerable&lt;T&gt; GetAsyncConsumingEnumerable()\n   {\n      while (true)\n      {\n         T next;\n         try\n         {\n            next = await _channel.Reader.ReadAsync();\n         }\n         catch (ChannelClosedException)\n         {\n            yield break;\n         }\n         yield return next;\n      }\n   }\n}<\/pre>\n<p class=\"copyrightbody\">The <code class=\"fm-code-in-text\">Add<\/code> method just calls the channel writer\u2019s <code class=\"fm-code-in-text\">TryWrite<\/code> method. <code class=\"fm-code-in-text\">TryWrite<\/code> shouldn\u2019t fail on unbounded channels, but in production code, we should probably check the value returned from <code class=\"fm-code-in-text\">TryWrite<\/code> and throw an exception if it\u2019s <code class=\"fm-code-in-text\">false<\/code>.<a id=\"calibre_link-1339\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-1340\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><\/p>\n<p class=\"copyrightbody\">The <code class=\"fm-code-in-text\">GetAsyncConsumingEnumerable<\/code> method is a bit more complicated; at its core, it is just a loop calling the channel reader\u2019s <code class=\"fm-code-in-text\">ReadAsync:<\/code><code class=\"fm-code-in-text\"><a class=\"pcalibre2 pcalibre pcalibre3 pcalibre1 calibre8\" id=\"calibre_link-1341\"><\/a><\/code><\/p>\n<pre class=\"programlisting\">   public async IAsyncEnumerable&lt;T&gt; GetAsyncConsumingEnumerable()\n   {\n      while (true)\n      {\n         yield return await _channel.Reader.ReadAsync();\n      }\n   }<\/pre>\n<p class=\"copyrightbody\">But this code doesn\u2019t detect when there is no more data and we should end the loop. When there is no more data, <code class=\"fm-code-in-text\">ReadAsync<\/code> will throw an exception. We need to catch this exception and end the iteration:<\/p>\n<pre class=\"programlisting\">   public async IAsyncEnumerable&lt;T&gt; GetAsyncConsumingEnumerable()\n   {\n      while (true)\n      {\n         try\n         {\n            yield return await _channel.Reader.ReadAsync();\n         }\n         catch (ChannelClosedException)                 <span class=\"fm-combinumeral\">\u2776<\/span>\n         {\n            yield break;\n         }\n      }\n   }<\/pre>\n<p class=\"copyrightbody\"><span class=\"fm-combinumeral\">\u2776<\/span> Detects when iteration is complete<\/p>\n<p class=\"copyrightbody\"><a id=\"calibre_link-1342\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a>However, this version of <code class=\"fm-code-in-text\">GetAsyncConsumingEnumerable<\/code> doesn\u2019t compile because you can\u2019t use <code class=\"fm-code-in-text\">yield<\/code> <code class=\"fm-code-in-text\">return<\/code> inside a <code class=\"fm-code-in-text\">try<\/code> block. We must move the <code class=\"fm-code-in-text\">yield<\/code> <code class=\"fm-code-in-text\">return<\/code> outside of the <code class=\"fm-code-in-text\">try<\/code> block, and then we get the code from listing 14.7:<\/p>\n<pre class=\"programlisting\">   public async IAsyncEnumerable&lt;T&gt; GetAsyncConsumingEnumerable()\n   {\n      while (true)\n      {\n         T next;\n         try\n         {\n            next = await _channel.Reader.ReadAsync();\n         }\n         catch (ChannelClosedException)\n         {\n            yield break;\n         }\n         yield return next;                             <span class=\"fm-combinumeral\">\u2776<\/span>\n      }\n   }<\/pre>\n<p class=\"copyrightbody\"><span class=\"fm-combinumeral\">\u2776<\/span> Moves the yield return outside of the try block<\/p>\n<p class=\"copyrightbody\">Now that we have our asynchronous channel-based collection, we can use it to write a work queue. This is an asynchronous adaptation of the <code class=\"fm-code-in-text\">BlockingCollection&lt;T&gt;-<\/code>based work queue from listing 13.11.<\/p>\n<p class=\"fm-code-listing-caption\">Listing 14.10 Async work queue with 10 threads<\/p>\n<pre class=\"programlisting\">ChannelAsyncCollection &lt;int&gt; asyncCollection = \n   new ChannelAsyncCollection &lt;int&gt;();\nTask[] workers =  new Task[10];\nfor(int i=0; i&lt;workers.Length; i++)                    <span class=\"fm-combinumeral\">\u2776<\/span>\n{\n   var threadNumber = i;\n   workers[i] = Task.Run(async () =&gt;\n   {\n      var rng = new Random((int)threadNumber);\n      int count = 0;\n      await foreach (var currentValue in\n            asyncCollection.GetAsyncConsumingEnumerable())\n      {\n         Console.WriteLine($\"thread {threadNumber} value {currentValue}\");\n         Thread.Sleep(rng.Next(500));\n         count++;\n      }\n      Console.WriteLine($\"thread {threadNumber}, total {count} items\");\n   });\n}\nfor(int i=0;i&lt;100;i++)                                 <span class=\"fm-combinumeral\">\u2777<\/span>\n{\n   asyncCollection.Add(i);\n}\nasyncCollection.CompleteAdding();                      <span class=\"fm-combinumeral\">\u2778<\/span>\nawait Task.WhenAll(workers);                           <span class=\"fm-combinumeral\">\u2779<\/span><\/pre>\n<p class=\"copyrightbody\"><span class=\"fm-combinumeral\">\u2776<\/span> Creates 10 worker threads<\/p>\n<p class=\"copyrightbody\"><span class=\"fm-combinumeral\">\u2777<\/span> Adds 100 items to process<\/p>\n<p class=\"copyrightbody\"><span class=\"fm-combinumeral\">\u2778<\/span> Signals no more items<\/p>\n<p class=\"copyrightbody\"><span class=\"fm-combinumeral\">\u2779<\/span> Waits for all threads to finish<\/p>\n<p class=\"copyrightbody\">This code creates a <code class=\"fm-code-in-text\">ChannelAsyncCollection&lt;int&gt;<\/code> to hold the data we need to process in the background. It then starts 10 background tasks to do this processing, and each thread uses <code class=\"fm-code-in-text\">foreach<\/code> and <code class=\"fm-code-in-text\">GetAsyncConsumingEnumerable<\/code> to get the items to process. To simulate the processing, we just wait a small random amount of time and print the number. We insert the numbers 0 to 99 into the queue as a stand-in for the data we want to process.<a id=\"calibre_link-1343\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-1344\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-1345\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-1346\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-186\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><a id=\"calibre_link-1347\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><\/p>\n<h2 class=\"fm-head\" id=\"calibre_link-1348\">Summary<\/h2>\n<ul class=\"calibre9\">\n<li class=\"fm-list-bullet\">\n<p class=\"list\">The <code class=\"fm-code-in-text\">yield return<\/code> and <code class=\"fm-code-in-text\">yield break<\/code> keywords can be used in conjunction with <code class=\"fm-code-in-text\">async<\/code>\/<code class=\"fm-code-in-text\">await<\/code>. You mark the method as <code class=\"fm-code-in-text\">async<\/code> and return <code class=\"fm-code-in-text\">IAsyncEnumerable&lt;T&gt;<\/code> instead of an <code class=\"fm-code-in-text\">IEnumerable&lt;T&gt;<\/code>, and then you can use <code class=\"fm-code-in-text\">await<\/code> in the iterator method.<\/p>\n<\/li>\n<li class=\"fm-list-bullet\">\n<p class=\"list\"><code class=\"fm-code-in-text\">IAsyncEnumerable&lt;T&gt;<\/code> and <code class=\"fm-code-in-text\">IAsyncEnumerator&lt;T&gt;<\/code> are the asynchronous, <code class=\"fm-code-in-text\">async<\/code>\/<code class=\"fm-code-in-text\">await<\/code>-compatible versions of <code class=\"fm-code-in-text\">IEnumerable&lt;T&gt;<\/code> and <code class=\"fm-code-in-text\">IEnumerator&lt;T&gt;.<\/code><\/p>\n<\/li>\n<li class=\"fm-list-bullet\">\n<p class=\"list\">The compiler transforms the method into a class, performing both the <code class=\"fm-code-in-text\">yield return<\/code> transformation we talked about in chapter 2 and the <code class=\"fm-code-in-text\">await<\/code> transformation we discussed in chapter 3.<\/p>\n<\/li>\n<li class=\"fm-list-bullet\">\n<p class=\"list\">To iterate over the resulting <code class=\"fm-code-in-text\">IAsyncEnumerable&lt;T&gt;<\/code>, use <code class=\"fm-code-in-text\">await<\/code> <code class=\"fm-code-in-text\">foreach<\/code> instead of <code class=\"fm-code-in-text\">foreach<\/code>.<\/p>\n<\/li>\n<li class=\"fm-list-bullet\">\n<p class=\"list\"><code class=\"fm-code-in-text\">await<\/code> <code class=\"fm-code-in-text\">foreach<\/code> is like a regular <code class=\"fm-code-in-text\">foreach<\/code>, except it performs an <code class=\"fm-code-in-text\">await<\/code> at each iteration.<\/p>\n<\/li>\n<li class=\"fm-list-bullet\">\n<p class=\"list\">You can cancel an iteration by using the <code class=\"fm-code-in-text\">WithCancellation<\/code> extension method. This method will pass a cancellation token to the <code class=\"fm-code-in-text\">IAsyncEnumerable&lt;T&gt;<\/code> (or, if the <code class=\"fm-code-in-text\">IAsyncEnumerable&lt;T&gt;<\/code> was created with <code class=\"fm-code-in-text\">yield return<\/code>, it optionally passes the cancellation token to the method generating the sequence). As always with cancellation tokens, the token is just a flag. To stop the iteration, there needs to be code that checks the status of the token and stops the iteration.<\/p>\n<\/li>\n<li class=\"fm-list-bullet\">\n<p class=\"list\">The <code class=\"fm-code-in-text\">ConfigureAwait<\/code> extension method for <code class=\"fm-code-in-text\">IAsyncEnumerable&lt;T&gt;<\/code> works like calling <code class=\"fm-code-in-text\">Task.ConfigureAwait<\/code> at every iteration. We discussed the pros and cons of <code class=\"fm-code-in-text\">ConfigureAwait<\/code> in chapter 11.<\/p>\n<\/li>\n<li class=\"fm-list-bullet\">\n<p class=\"list\">The <code class=\"fm-code-in-text\">ToBlockingEnumerable<\/code> extension method wraps the <code class=\"fm-code-in-text\">IAsyncEnumerable&lt;T&gt;<\/code> in an <code class=\"fm-code-in-text\">IEnumerable&lt;T&gt;<\/code> that does the equivalent of calling <code class=\"fm-code-in-text\">Task.Wait<\/code> at every iteration. Like <code class=\"fm-code-in-text\">Task.Wait<\/code>, it can cause performance problems and deadlocks. It should be used only for calling asynchronous APIs from non-asynchronous code and only if the API supports this use case.<\/p>\n<\/li>\n<li class=\"fm-list-bullet\">\n<p class=\"list\">There is no built-in support for LINQ for asynchronous sequences, but the <code class=\"fm-code-in-text\">System.Linq.Async<\/code> NuGet by the .net RX teams adds asynchronous LINQ support.<\/p>\n<\/li>\n<li class=\"fm-list-bullet\">\n<p class=\"list\"><code class=\"fm-code-in-text\">yield<\/code> <code class=\"fm-code-in-text\">return<\/code> and <code class=\"fm-code-in-text\">await<\/code> <code class=\"fm-code-in-text\">foreach<\/code> can be used to write simple code that generates and processes sequences of asynchronous generated or retrieved data items (see listing 14.8).<\/p>\n<\/li>\n<li class=\"fm-list-bullet\">\n<p class=\"list\"><code class=\"fm-code-in-text\">yield<\/code> <code class=\"fm-code-in-text\">return<\/code> and <code class=\"fm-code-in-text\">await<\/code> <code class=\"fm-code-in-text\">foreach<\/code> can also be used to build asynchronous work queues and other multithreaded infrastructure (see listing 14.9).<a id=\"calibre_link-1349\" class=\"pcalibre2 pcalibre calibre5 pcalibre3 pcalibre1\"><\/a><\/p>\n<\/li>\n<\/ul>\n<\/div>\n<\/div>\n<\/div>\n","protected":false},"excerpt":{"rendered":"<p>C# Concurrency Asynchronous and multithreaded programming &nbsp; Nir Dobovizki \u00a92025 by Manning Publications Co. All rights reserved. dedication To my wonderful wife, Analia contents &nbsp;&nbsp; &nbsp;&nbsp; &nbsp; &nbsp;&nbsp;Front matter preface acknowledgments about this book about the author about the cover illustration &nbsp;&nbsp; Part 1. &nbsp;Asynchronous programming and multithreading basics &nbsp;&nbsp;1&nbsp;&nbsp; Asynchronous programming and multithreading &nbsp;&nbsp;1.1&nbsp;&nbsp; [&hellip;]<\/p>\n","protected":false},"author":1,"featured_media":0,"comment_status":"open","ping_status":"open","sticky":false,"template":"","format":"standard","meta":{"footnotes":""},"categories":[3],"tags":[],"class_list":["post-948","post","type-post","status-publish","format-standard","hentry","category-csharp"],"_links":{"self":[{"href":"https:\/\/diji.net\/index.php?rest_route=\/wp\/v2\/posts\/948","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/diji.net\/index.php?rest_route=\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/diji.net\/index.php?rest_route=\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/diji.net\/index.php?rest_route=\/wp\/v2\/users\/1"}],"replies":[{"embeddable":true,"href":"https:\/\/diji.net\/index.php?rest_route=%2Fwp%2Fv2%2Fcomments&post=948"}],"version-history":[{"count":0,"href":"https:\/\/diji.net\/index.php?rest_route=\/wp\/v2\/posts\/948\/revisions"}],"wp:attachment":[{"href":"https:\/\/diji.net\/index.php?rest_route=%2Fwp%2Fv2%2Fmedia&parent=948"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/diji.net\/index.php?rest_route=%2Fwp%2Fv2%2Fcategories&post=948"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/diji.net\/index.php?rest_route=%2Fwp%2Fv2%2Ftags&post=948"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}