In early 2019, I was working on an app (Mental Canvas Draw) that was in private beta on the Windows Store. There was a nice, robust system to show you which crashes were most common your app. Then suddenly – it disappeared, and instead there was a big stream of “Unknown” class crashes.

This caused much wailing and gnashing of teeth. I assumed that it would be fixed. Microsoft had recently acquired HockeyApp and was revamping it into Visual Studio AppCenter. Surely that would provide a replacement! Six months passed, a year passed, two years passed, and… nothing for C++ users. (I understand that AppCenter provides a solution for C# users.)

That app was released widely in March 2021, and I realized an important fact: if you have a large volume of users and/or crashes, you get a valid list of stack traces! There seems to be something about the level of usage per package version that’s important. For <100 crashes per version, I get 0% stack traces; for <250 I get very few; and for the version with 750 crashes I get good (64%) stack traces.

Even for the “higher usage” package version, however, I’m still not getting solid data on the “rare” crash types – just the frequent crashes.

So… what’s to be done? We don’t have access to any off-the-shelf Win32 crash reporting tools, as the necessary APIs are all blocked off from UWP apps. There’s no easy way to get a minidump. There might be some really elaborate solution involving Project Reunion APIs to monitor the UWP process from Win32-land, but I haven’t explored those technologies much, and I’m not confident that the Win32 code gets sufficient privilege to dig deep on the UWP process’ behaviour.

But… UWP apps do have access to one key API: CaptureStackBackTrace.

A bare bones solution

A full-fledged crash handling and stack trace solution is quite complicated: running in a separate guard process to sidestep any memory/stack corruption; multiple threads; full analysis of both the app portion of the stack trace and the system (Windows) portion. My main needs were more narrow, and I built a solution focused on that

• Single thread: only show stack of active (crashing) thread
• App portion of stack is critical; system/Windows portion is desirable, but less important
• Severe memory corruption doesn’t need to be handled initially
• Only handle C++/CX and x64. It probably works for other situations, but that’s all I’ve tested to date.

With those criteria, I came up with a five-part solution:

1. Pre-crash: log system info to disk
2. Crash time: set a callback to get notified, and capture stack to disk
3. Next app startup: transmit log+stack trace to server
4. [OPTIONAL] Server: symbolify stack trace
5. [OPTIONAL] Server: aggregate results

Let’s take a quick look at each piece.

Log System Info

When the crash happens, we want to do the bare minimum necessary. Memory may be corrupted and we want to avoid crashing while trying to log the crash. So: we log system information to disk at startup, prior to any crash happening. We particularly need the app version and the operating system version in order to be able to symbolify the stack trace, and the date/time of the session; but of course other data (screen size, RAM available, graphics driver versions, etc.) may also be relevant.

Crash Capture: Callback on Crash

There are several potential mechanisms to get notified on crashes:

• Assertion failures (if enabled in production): it’s easy enough to write a custom assertion macro that captures __LINE__ and__FILE__ to get the source location of a failure, and it can then also trigger capture of a stack trace.
• Invalid memory access: the best bet seems to be __try / __catch / _set_se_translator for Windows Structured Exception Handling (SEH)

These were also options, but didn’t seem to actually get called for relevant situations like null pointer dereferences:

• A different SEH Win32 C API: SetUnhandledExceptionFilter

• UWP event handlers: Windows::ApplicationModel::Core::CoreApplication::UnhandledErrorDetected and Windows::UI::Xaml::UnhandledException

What is SEH? It’s a C API that handles hardware exceptions on x86/x64 chips; while it uses the __try and __catch keywords, it’s not about software exceptions (either C++ or managed code). There’s some good discussion of it in the CrashRpt documentation. It’s a key part of Microsoft’s own error reporting mechanism, from the Dr. Watson era through to today. (I believe the rough data path is SEH → Windows Error Reporting (WER) → Microsoft-hosted database → Windows Store stack traces.) There are all sorts of complicated nuances to how it works, and I’ve understood… relatively few of them. I just use the _set_se_translator function as a hook to:

• Get called when a crash happens, on the crashing thread.
• Grab a stack trace and record it (typically skipping the first 8 frames that are in VCRUNTIME and NTDLL)
• Also grab and record the exception type (EXCEPTION_ACCESS_VIOLATION, EXCEPTION_STACK_OVERFLOW, etc.)

A single call to _set_se_translator appears to be sufficient to get a callback when any thread crashes. (Which is the main reason I use it instead of __try / __catch or _set_terminate, which have to be applied on a per-thread basis.)

The actual implementation is pretty straightforward:

#include <eh.h>

void se_trans_func( unsigned int u, _EXCEPTION_POINTERS *pExp) {
  // Skip 8 stack frames - we usually see the ones below.
  // 00:MyApp.exe+0x009a7b98		(this function)
  // 01 .. 05:VCRUNTIME140D_APP.dll
  // 06 .. 08:ntdll.dll
  Char *backTrace =GetBackTrace(8);
  Str desc;
  switch (u) {
  case EXCEPTION_ACCESS_VIOLATION:
    desc = L"ACCESS_VIOLATION";	     break;
  case EXCEPTION_ARRAY_BOUNDS_EXCEEDED:
    desc = L"ARRAY_BOUNDS_EXCEEDED"; break;
  // ... etc. ...
  case EXCEPTION_STACK_OVERFLOW:
    desc = L"STACK_OVERFLOW";        break;
  default:
    desc = StrPrintf(TEXT("%d"), u); break;
  }

  LogPrintf(L"Structured Exception Handling failure type %s. Stack trace:\n%s\n"),
    desc.Data(), backTrace);
  delete[] backTrace;

  // A bit irrelevant... we mostly just want the stack trace.
  throw L”Hardware exception”;
}

App::App() {
  // ...
  _set_se_translator(se_trans_func);
  // ...
}

Crash Capture: Record Stack Trace

From a UWP app, we don’t have access to many Win32 APIs – but we can call CaptureStackBackTrace. If we combine that with calls to RtlPcToFileHeader and GetModuleName, then we can get the module name (EXE and DLL filename) and the offset within that module for each entry in the stack trace. Unlike conventional Win32 crash handlers, we cannot symbolify at crash time. We get a module-relative offset:

myapp.exe+0x00001234

Rather than the symbolified (actual function name and signature) with a function-relative offset:

myapp.exe crashyFunction(int, const std::string &) + 0x0000001a

Or even better, with source filenames and line numbers:

myapp.exe crashyFunction(int, const std::string &) + 0x0000001a
myapp.cpp:465

In theory, you could try to walk the module’s PE header data manually with an IMAGE_DOS_HEADER to get the IMAGE_EXPORT_DIRECTORY for the exported symbols from each module. But in practice, we need non-exported private function names, for both trace entries in our code and in Windows DLLs.

So – there’s no API call to do the symbolification locally in-app. We’ll have to do it out-of-app with the help of a server. Given that situation, we just dump the CaptureStackBackTrace outputs to disk, and let the app merrily crash.

The actual capture code looks like this:

Str GetBackTrace(int SkipFrames)
{
  constexpr uint TRACE_MAX_STACK_FRAMES = 99;
  void *stack[TRACE_MAX_STACK_FRAMES];
  ULONG hash;
  const int numFrames = CaptureStackBackTrace(SkipFrames + 1, TRACE_MAX_STACK_FRAMES, stack, &hash);
  Str result = StrPrintf(L"Stack hash: 0x%08lx\n", hash);
  for (int i = 0; i < numFrames; ++i) {
    void *moduleBaseVoid = nullptr;
    RtlPcToFileHeader(stack[i], &moduleBaseVoid);
    auto moduleBase = (const unsigned char *)moduleBaseVoid;
    constexpr auto MODULE_BUF_SIZE = 4096U;
    wchar_t modulePath[MODULE_BUF_SIZE];
    const wchar_t *moduleFilename = modulePath;
    if (moduleBase != nullptr) {
      GetModuleFileName((HMODULE)moduleBase, modulePath, MODULE_BUF_SIZE);
      int moduleFilenamePos = Str(modulePath).FindLastOf(L"\\");
      if (moduleFilenamePos >= 0)
        moduleFilename += moduleFilenamePos + 1;
      result += StrPrintf(L"%02d:%s+0x%08lx\n"), i, moduleFilename, 
        (uint32)((unsigned char *)stack[i] - moduleBase));
     }
     else
       result += StrPrintf(L"%02d:%s+0x%016llx\n"), i, moduleFilename, 
         (uint64)stack[i]);
   }
   return result;
}

Next App Startup: Transmit Log

The UWP lifecycle APIs let us detect whether the last run of the app had a clean exit. We can use that to detect a crash, and transmit the recorded log to our server for symbolification. It does mean that we don’t get crashes immediately, and we may miss crashes if the user doesn’t restart the app. But in practice, this is largely acceptable.

We do try to capture the app version and crash date/time in our log, as the version and date may be different by the time the log is transmitted.

[OPTIONAL] Symbolify Stack Trace

The server is – by necessity – a Windows VM listening to HTTPS requests.

On the server, we maintain a set of PDB files for each app version (extracted from the .msixpackage zip file). At present, we only handle x64 and not ARM64 crashes.

We also maintain a set of key system DLLs for each major (semiannual) Windows release. We don’t try to keep the DLLs for each minor release, as that’s basically a Herculean task.

When a log file comes in, we:

• Parse the log to retrieve the app version and Windows version
• Match up the relevant PDB file and directory of Windows system DLLs
• For each line of the stack trace, detect whether it’s in our app or a system DLL
• Run CDB.EXE to convert the module name + offset to a function name, offset, source filename and line number. The inspiration for this came from Raymond Chen’s oldnewthing blog.

The heart of this is the call to CDB, which looks like this:

export CDB=/mnt/c/Progra\~2/Windows\ Kits/10/Debuggers/x64/cdb.exe
# Typical raw output, prior to sed expressions:
#   MyApp!MyApp::App::CrashyFunction+0x25fb
#   [C:\Users\MyUser\source\myapp\MyApp.cpp @ 757]:
# Sed expressions simplify it to:
#   App::CrashyFunction+0x25fb [MyApp.cpp @ 757]
"$CDB" -lines -z myapp.exe -c "u $entry; q" -y \
  "cache*c:\\Symbols;srv*https://msdl.microsoft.com/download/symbols"\
  | grep -m 1 -A 1 "^0:000>" \
  | tail -1 \
  | sed 's/:$//;' \
  | sed 's/MyApp:://g;' \
  | sed 's/\[[^@[]*\\\([A-Za-z0-9_.]*.\(h\|cpp\) @ \)/\[\1/g'

For Windows system DLL entries, we can choose a $SYS32DIR to match the client’s Windows version, and then change the -z argument to

-z $SYS32DIR\\$DLLFILENAME

This ensures that CDB uses the client’s Windows version to decide which symbols to retrieve for the DLL, rather than the normal behaviour, which would use the server VM’s Windows version. We’ll still get a fair bit of mismatch – as we usually don’t have the DLLs that precisely match the client’s Windows version.

If there’s some way to specify a Windows version when telling CDB about the symbol server – let me know! That would be a huge timesaver.

[OPTIONAL] Aggregate results

Ideally, we want to build a database of all stack traces, merge duplicates, and present a ranked list of the most common crashes over (say) a month, and a graph of the crash frequency of any given bug per day.

But I haven’t actually implemented this yet. For this purpose, an off-the-shelf tool will probably suffice – a service like Sentry or Visual Studio App Center would do the trick, and both accept submission of crash data via an API.

What if we don’t symbolify?

If you want a simpler solution: you can easily use the module name + module-relative offset in a Visual Studio debugger session to manually find the source location. This makes it painstaking to analyze each individual crash, but might be acceptable if you maintain a very low crash rate in your app. I took this route through 2019, but added stack trace capture by 2020 and finally built out the symbolification code in 2021 when it became obvious that Microsoft wasn’t going to fix this themselves.

Conclusion

So – this is a very bare bones process for detecting crashes, capturing a C++ stack trace, transmitting to a server and determining filename + line numbers for each entry in the stack trace.

I … still really wish Microsoft would just re-enable this code in the Microsoft Store. For the life of me, I can’t understand why they turned it off. They must still be collecting all this information in the WER database for their own use, and just not exposing it to developers.

task<void> FooAsync(StorageFolder ^folder) {
  return create_task(folder->TryGetItemAsync(L"foo.txt"))
    .then([](IStorageItem ^item) {
      // do some stuff, cast to a file, etc.
    });
}

It’s all running on the UI thread, so it’s in a Single Threaded Apartment, and each task in your chain of .then() continuations is guaranteed to also be on the UI thread.

Now, you learn about Microsoft’s relatively new co_await feature, recently accepted in an adapted form in the C++20 spec. So you start using it:

task<void> FooAsyncCo(StorageFolder ^folder) {
  IStorageItem ^item =
    co_await folder->TryGetItemAsync(L"foo.txt");
  // do some stuff, cast to a file, etc.
}

So far so good: all code inside FooAsyncCo() also runs on the UI thread, nice and clean.

Finally, you integrate a little of this co_await code into your heavily PPL codebase. Helpfully, co_await returns a task, just like your existing async PPL method. Another developer sees that you have a bunch of methods returning task<void> and decides to start building on that API using PPL:

FooAsyncCo().then([]() {
  // more stuff, after coroutine.
  // KABOOM. Running on a threadpool thread, *not* the UI thread.
  // We accidentally busted out of the STA.
});

Uh-oh. When you mix the two async approaches… things break. And none of the documentation – or honestly anything I’ve read on the web to date – gives any hint of this issue.

Not A Fix

Well… let’s see. The docs do give us one tip: a task chain is only guaranteed to remain inside the Single Threaded Apartment if the chain starts with an IAsyncAction or IAsyncOperation

The UI of a UWP app runs in a single-threaded apartment (STA). A task whose lambda returns either an IAsyncAction or IAsyncOperation is apartment-aware. If the task is created in the STA, then all of its continuations will run also run in it by default, unless you specify otherwise. In other words, the entire task chain inherits apartment-awareness from the parent task. This behavior helps simplify interactions with UI controls, which can only be accessed from the STA.

Asynchronous programming in C++/CX: Managing the Thread Context

Well… TryGetItemAsync does return an IAsyncOperation. That would appear to be the root task in the chain… so coroutines must be treated differently, with the coroutine itself being the root.

Well, what if we tried making the coroutine return an IAsyncAction?

IAsyncAction ^FooAsyncCoAction(StorageFolder ^folder) {
  return create_async([folder]() -> task<void> {
    // KABOOM - this is now out of the apartment.
    IStorageItem ^item =
      co_await folder->TryGetItemAsync(L"foo.txt");
    // do some stuff, cast to a file, etc.
  });
}
create_task(FooAsyncCo())
.then([]() {
  // more stuff, after coroutine.
  // ok now!
});

No dice. Now the coroutine runs off-thread, while the continuation runs correctly on the UI thread.

Two Actual Fixes

With a little more reading, I found Raymond Chen’s blog post about PPL and apartment-aware tasks. That led to this successful solution:

task<void> completed_apartment_aware_task() {
  return create_task(create_async([](){}));
}

completed_apartment_aware_task()
.then(FooAsyncCo)
.then([]() {
  // Ok!
});

This one actually works. By rooting the PPL chain in an IAsyncAction, the rest of the chain retains apartment awareness, and everything stays on the UI thread.

And I’d earlier found a different but more fragile solution:

create_task(FooAsyncCo, task_continuation_context::use_current())
.then([]() {
  // Ok!
});

While this works, it’s… a bit hard to tell whether the root task, or the continuation, or what-all needs use_current(), and it’s always felt fragile to me. And if it gets called from a threadpool thread, it’s unclear to the caller what happens with use_current().

Conclusion

I’ve got to say… this is a brutal pitfall. Any existing codebase is going to have a lot of PPL tasks in it, and wholesale migration to co_await isn’t going to happen all in one go, at least if there’s any conditional/loop/exception logic in the PPL-based code. Anyone who’s tried to migrate to co_await has probably run into this pitfall.

We haven’t adopted the completed_apartment_aware_task() as a root task throughout our codebase yet, but I’m hopeful that will at least offer a path forward. Just… still quite error-prone.

What’s interesting about our porting approach? Well, it’s just an unusual mix:

• It’s a UWP (Universal Windows Platform) app. UWP was Microsoft’s effort to modernize Win32 and add iOS mobile paradigms, so it is already touch-centric, relatively sandboxed and has a more mobile-like lifecycle
• We didn’t use React Native, Flutter, Electron, Xamarin, Qt or even Fuschia’s namesake Pink. We just… wrote some native code. And a lightweight abstraction layer.
• We completed the porting effort in seven months, with three developers.
• We stayed with the MVVM architecture that is the norm on Windows. Many iOS developers would call that… exceptionally ok
• We didn’t use the latest and greatest Swift tools, just plain old C++11 and Objective-C for the most part. We didn’t switch to SwiftUI when it was released half way through our port.

What combination of circumstances led to this approach? Mostly just a real life constraint: a desire to rewrite/redesign as little working code as possible, and keep the codebase’s size down.

1. Starting Point
2. UI Framework Choice
3. Restructuring the UI Thread
4. Lightweight iOS Bindings
5. What About SwiftUI?
6. Incremental Porting
7. The Upshot: Code Reuse

Starting Point

We architected our app to be portable from day one, using a C++ games engine that had previously shipped for Windows, Linux, iOS and Android. It’s a professional 3D illustration tool and native user interface elements are expected, so an architecture was chosen to keep much of the application portable while still allowing quick development of a native UI.

At the outset of the port, our app was only running on Windows. From a portability standpoint there were three main considerations:

• User interface: the Windows UI logic was sound, but—as it was written in C++/CX—was not immediately portable to iOS
• Graphics API: Apple deprecated OpenGL 18 months prior to the start of our port, although they ultimately elected to allow it to survive 2019
• Platform: threading, file I/O, app lifecycle, networking and async primitives/APIs would all need some level of revamping. While a C++ app would normally be able to easily migrate file I/O, early UWP versions forced us to use platform-specific async I/O APIs

I’m going to focus on the user interface in this article, as that was the single largest hurdle that we faced, and the bulk of my effort. Before I get there, it’s worth a quick glance at each portion of our user interface structure:

• Model: the render thread holds the model (i.e., the contents of a 3D scene)
• ViewModel: the UI thread maintains a mirror copy of relevant parts of the model as a C++/CX object, plus some UI state. This allows use of simple binding between the View and ViewModel properties.
• View: native UI controls and their responsive layout are defined declaratively in XAML, with bindings to ViewModel properties established at compile-time

There is almost no shared memory across threads. Communication between threads is done using a dedicated incoming message queue for each thread.

UI Framework Choice

Should we use a cross-platform framework? We had a few unusual considerations

• Platforms: the combination of desktop (UWP) and mobile (iOS) narrows our choices, and we would like to protect for a future MacOS port (with Wacom tablet for input)
• Input devices: first-class pen support is unusual, particularly on mobile-focused frameworks

And some more common considerations in games or other apps:

• Look and feel: a “fun” feel is key to our app, and benefits from an “easy, responsive” user interface and native feel.
• Graphics: UI framework must be lightweight, and co-operate and overlay cleanly over a 60 fps (or even 120 fps) graphics thread
• Memory: our app is quite memory intensive, especially for mobile devices with only 3GB of RAM

We evaluated a number of frameworks before proceeding. The main frameworks under consideration were React Native, Xamarin and Unity. React Native was the strongest contender, with a Microsoft-maintained UWP port, pen support feasible (with a little effort), and a declarative/reactive UI language that was nicer than native UIKit’s imperative design. We built a quick, working prototype of our app in React Native to get a feel for the technology’s strengths and weaknesses.

In the end, though, we chose a native port. The main downsides that we saw in React Native were:

• no MacOS port
• a less “native” feel
• risk from one additional vendor dependency (Facebook) and one new technology dependency (Microsoft UWP port)
• complex toolchain

And as a more short-term issue, it was worth considering our staff’s lack of React experience. There’s always a fair bit of risk when you can’t “ease in” to a technology, and have to go straight to architecture without much concrete experience.

Restructuring the UI thread

As shown in the earlier figure, the non-portable UI code consisted of both ViewModel (~15%) and View code (~10%). The View code is unavoidably native, but what about the ViewModel code? ViewModels manage communication with the Model, which should be entirely portable; and they expose properties for the View to bind against… which depends on the platform binding mechanism.

So… let’s think about those bindings. Each ViewModel has a set of member variables that are “bindable properties”, and a notification mechanism when a change happens. In our app, we almost always use one-way bindings, and we use commands used to modify any ViewModel properties. Our UI is relatively simple, with limited animation and only a modest amount of content. We had already adopted a declarative mindset for the UI, with the aim of ensuring a single source of truth for the UI state.

The main issues we faced in making this portable were:

1. Windows: the {x:Bind} mechanism requires the ViewModel to be a native object (in C++/CX, a ref class), and each bindable property has to be a special special native type.
2. iOS: at the time of port, there was no native binding mechanism. (SwiftUI was released halfway through our port effort.) We would have to roll our own.

None of this was insurmountable, and we were ultimately successful in making the ViewModel entirely portable, leaving only the View code platform-dependent.

Lightweight iOS Bindings

As a newcomer to Apple development, I found it curious that Cocoa Bindings existed on MacOS, but were never ported to iOS. Apparently they were slow and fragile, but… so are all of the awful hacks people seem to do in UIKit to keep their UI in sync.

At any rate, it proved fairly simple to write a few methods that simply track a list of source-target pair:

There are two little niceties that I may elaborate in a separate post:

1. Compile-time keypath validity checks: borrowed from Nick Forge’s post, to catch typos earlier and avoid a compile + run cycle.
2. Multi-bindings, boolean ops, and type conversions: various ways to combine/convert multiple ViewModel properties prior to binding to a UIView property.

Suffice it to say that the final syntax is something like this:

m_bindings->add(
BIND_CHECK2(modeSegmented, setSelectedSegmentTintColor),
VmFn::IfElse(m_vm->IsNavMode, SNavModeColor, SDrawModeColor));

which is a continuously updating version of

self.modeSegmented.selectedSegmentTintColor =
m_vm->IsNavMode ? SNavModeColor : SDrawModeColor;

What About SwiftUI?

While I agree that MVVM is exceptionally ok, SwiftUI is clearly the “next stop” that Ash Furrow imagined. SwiftUI is a great fit for our architecture: bindings, declarative, relatively low-state, and the ability to use Combine to maintain the dependencies between different properties.

However, we haven’t pursued SwiftUI yet for a few reasons:

1. Swift interoperability with C++ remains painful. We would need to maintain a lot of Objective C code to bridge our C++ data structures over to Swift… unless things change some day.
2. Ship Timing: our ship date was September 2019 with a target of iOS11 and up. It’ll be a little while before we can limit the software to iOS 13 only.
3. Development Timing: we had already ported 60% of the app by the time SwiftUI was announced. We’d heard the Catalyst rumours and very faint mentions of Amber ahead of WWDC, but there was nothing we could rely on.

I’m sure that we could use Objective C++ to bridge our C++ ViewModel data over to a SwiftUI-friendly data structure. Once enough of the market is on iOS13, we’ll face the following trade-off:

• Pro: Accelerated UI iteration using SwiftUI vs. UIKit. Less AutoLayout agony.
• Con: Pain of maintaining an Objective C++ bridge between C++11 ViewModels and Swift Views

Once Apple inevitably starts making some UI controls Swift-only, the decision will probably tip in favour of SwiftUI.

At the end of the day… if you’re going for portable, you need to use portable languages. Swift deliberately ain’t that; it’s Apple’s ecosystem accelerator and lock-in mechanism.

Incremental Porting

We had the good fortune of having a relatively well-composed set of ViewModels. While it was once a single massive ViewModel, steady refactors broke it into about 10 major ViewModels corresponding to each of the major on-screen UI elements.

One of the most pleasing benefits of that factoring was that we could port them over one at a time, in priority order. At any stage during the port, we could have:

• an iOS version that was demoable with a subset of UI
• a Windows version that still compiled and worked 100%

Towards the end of the port, business demands forced us to put all resources into getting the iOS version ready, at the cost of maintaining a fully working Windows build, but we paid that technical debt down promptly.

The Upshot: Code Reuse

Here are the architecture diagrams after completing the port.

And here’s an analysis of the source code size before and after the port:

Not too shabby. And note that a lot of that portable ViewModel code was not really a rewrite: it was more of a line-by-line translation from one dialect to another.

A few statistics:

• The size of the Windows build grew by 5% due to the port.
• Windows-specific code was 25,000 lines before the port. Only 14,000 lines of iOS-specific code was required with this platform-independent framework.
• If we hadn’t ported, and instead had 30,000 lines of iOS-specific code (including Metal backend), we’d probably be looking at a 110,000 line app. So we likely reduced our codebase size by about 10% using this approach.

In the iOS app, we can run with either an OpenGL ES 2.0 backend or a Metal backend. Given the much better Metal performance, we don’t intend to ship the OpenGL ES version, but it can be useful to have it occasionally to isolate bugs or to test in the iOS Simulator without MacOS Catalina.

So there you have it. Sometimes, doing a port the old way is a reasonable choice. No bragging rights for using the latest technologies, but… relatively few new bugs.

1. The issue: a transient memory spike
2. iOS / iPadOS memory limits
3. Forming hypotheses
4. Tools at hand
5. Findings
6. Conclusion
7. References

The issue: a transient memory spike

Our sketching app does a lot of rendering to intermediate, offscreen textures. In the process, we generate (and quickly discard) a lot of intermediate textures. A lot of that rendering happens in a continuous batch on a dedicated thread, without yielding execution back to the operating system.

A consequence of that behavior: our memory footprint grows rapidly until we hit the critical threshold — on a 3 GB iPad Air, about 1.8 GB — and then iOS summarily kills the app. From our app’s perspective, memory footprint is only growing gradually, as most of the memory usage is temporary intermediate rendertargets; they should be freed and available for reuse. But from the operating system’s perspective, it considers all of those temporaries to still be in use.

Which led us to the question: why? And how do we figure out which temporaries are leaking, and which Metal flag / call will allow us to return that data to the operating system?

iOS / iPadOS memory limits

From our empirical reviews of the various tools, we can say the following:

• The XCode Memory Gauge precisely reflects what the operating system thinks your app’s size is (as advertised in many WWDC talks).
• The great new os_proc_available_memory() call in iOS13 appears to precisely match the XCode Memory Gauge. A delta between os_proc_available_memory() at app startup and later in the app represents memory consumption in the same manner that the OS sees it.
• The operating system seems to kill an app once its usage hits roughly system memory minus 1GB
  • Test systems: a 3GB iPad Air (2019) and a 4GB iPad Pro (2018), running both iOS12 and iOS13
  • API reported RAM: 2.8GB and 3.6GB respectively
  • Crashes at 1.8GB and 2.7GB memory usage
• Be cautious of other memory metrics: neither XCode’s GPU Frame Capture memory view, the Metal System Trace Instrument nor the Memory Graph Instrument appear to give totals that line up cleanly with the XCode Memory Gauge.
• Ultimately, I got GPU Frame Capture to give me great data — but with an awareness of when its snapshot is taken, which is typically at the end of rendering a visible frame, and after some operating system activity has happened.

Forming hypotheses

One thing that caught my eye immediately: when working with a smaller batch of data (which didn’t hit the memory limit), the XCode memory graph showed an “overshoot.” During processing in the graph here, we hit a peak of 1.1GB memory used, but then subsided back down to a steady state of about 840MB once processing completed.

This suggested that there was not a true memory leak — clearly our code only referenced 840MB of memory, and once the operating system / GPU / drivers had time to “clean up” any unreferenced memory, 260MB was being released. If we could avoid that spike, our peak memory usage would be 25% lower.

So, why would that happen? Where are those large blocks of data being held?

The large data objects are virtually all MTLTexture objects. They’re being written (i.e., used as rendertargets) in one phase of our processing, then being read (rendered to another rendertarget) in a later phase. Mechanically in Metal, that means a reference is being held by one or more MTLCommandBuffers that hasn’t completed executing yet.

As pseudocode on the CPU side, that looks like this:

1   start visible frame
2   for each item in batch {
3     allocate MTLCommandBuffer
4     allocate temporary MTLTexture
5     add "Write to temporary MTLTexture" commands to MTLCommandBuffer
6     add "Read from temporary MTLTexture" command to MTLCommandBuffer
7     send list of commands to GPU ("commit")
      // Optional. This throttles throughput in favour of reducing memory
      // footprint.
8     CPU wait until GPU completes execution of MTLCommandBuffer
9   }
10  render batch results to visible frame
11  present visible frame to user

Those MTLTexture objects are therefore held in several places, via reference counting. This allows us to formulate several hypotheses:

1. CPU-side reference counting of MTLTexture in line 4. When a loop iteration completes in line 9, the last CPU pointer to the MTLTexture (and MTLCommandBuffer) goes out of scope, and the CPU will not hold any active references. However, Objective C / Swift may not free the MTLTexture memory immediately, as it relies on autorelease pools for reference-counted objects.
2. Reference to MTLTexture held by MTLCommandBuffer. Even if there are no CPU-side MTLTexture references outstanding, there’s obviously still several references to the MTLTexture held by the command buffer. (i.e., “Write to here… now, read from here”.) Presumably, once the GPU executes all commands referencing a given MTLTexture, it will release the references to those MTLTextures. But — what is the timing of that release? How does it interact with autorelease pools, given that there’s potential for GPU/CPU contention?
3. Requirement to use MTLPurgeable flags. There are various Metal MTLPurgeable flags that can be set on a texture/buffer that might be required for more immediate reuse of a buffer. Metal is currently a little thin on documentation, and it’s hard to tell what’s required.
4. Incorrect GPU parallelism. In theory, the GPU will execute the “write to temporary” commands (line 4) before “read from temporary” (line 5). But what if the parallelism there isn’t specified correctly, and the reading task happens in parallel with the writing, and maybe even completes before writing has completed? Then, the wait in line 8 will still leave “writing” tasks executing, and their temporary memory still in use. Multiple loop iterations might execute in parallel, with higher memory usage.
5. Requirement for more advanced Metal data structures. Metal does offer the MTLHeap data structure for more manual control over memory management. This structure has an explicit setAliasable call to reuse a texture/buffer’s memory (i.e., free it). It’s possible that the behaviour we want is only possible via an MTLHeap.

Tools at hand

• The Metal System Trace instrument gives a good history of app execution across both CPU and GPU and was helpful for confirming that GPU parallelism was correct. While it shows the timing of mid-frame memory allocations, it doesn’t tell us anything useful about memory release timing.
• The Memory Graph instrument wasn’t useful. It’s not really helpful for GPU-side information, and it didn’t give any clear way to understand autorelease pool behaviour on the CPU side.
• XCode’s GPU Frame Capture feature provides a great snapshot of memory usage, including a browseable list of all allocated textures, their sizes and their flags. It’s designed to work on a single visible frame of animation, and the snapshot of memory that it normally displays is taken after line 11 of my pseudocode — i.e., the “steady state” memory usage, but not the intermediate “peak” mid-loop. However, if you use the manual MTLCaptureScope class, you can control the timing of the memory snapshot, and get a view of the peak memory usage. As an alternative, you can actually use breakpoints to control GPU frame capture.

Findings

Of the five hypotheses I presented, it turned out that #1 was the key. We had CPU-side references that lasted longer than we wanted — because of the way that autorelease pools operate.

Let’s talk through each hypothesis:

1. CPU-side references: at the end of each loop iteration, we indeed had no CPU-side or GPU-side references remaining. But — the CPU-side references do not get freed until the end of an autorelease pool block is reached. That didn’t happen until we returned control to the operating system, after presenting our visible frame.
   
   We found this using a GPU Frame Capture memory snapshot at the end of a loop iteration. In that snapshot, MTLTextures were still showing up in the list of allocated objects. We added an @autoreleasepool block around each loop iteration, and took a new memory snapshot after the autorelease pool drained — and lo and behold, the memory was now freed promptly.
2. References held by MTLCommandBuffers: it appears that MTLCommandBuffers are quite smart about tracking their data dependencies. We didn’t confirm whether textures references are released as commands execute, but clearly references are fully released when the MTLCommandBuffer completes.
   • Documentation on topics such as MTLHazardTrackingMode suggests that you can turn off the data dependency tracking, implying that intelligent dependency tracking is the default.
3. GPU flags like MTLPurgeableState: at WWDC, we got a tip from an Apple engineer to use an MTLCommandBuffer completionHandler and use that to set the purgeable state on the MTLTextures to make them freeable. That might be helpful with an MTLHeap, but was unnecessary for us — with CPU side references released via @autoreleasepool, the purgeable state didn’t need to be set.
4. Incorrect GPU parallelism: using MTLCommandBuffer and regular MTLTextures, this was not an issue; it understood our data dependencies pretty well and ensured sensible parallelism. This was confirmed with the Metal System Trace instrument. When we tried using MTLHeap — with more manual memory management — it was certainly possible to get incorrect GPU parallelism.

5. Advanced data structures (MTLHeap): we explored this more manual memory management system extensively, but it didn’t prove necessary for our situation, and didn’t address the underlying CPU-side autorelease pool issue.

Conclusion

With a newfound respect for autorelease pools, we’d solved the issue. The revised pseudocode is shown below, including debugging capture after processing item #10. New lines are in bold.

1   start visible frame
2   start GPU Frame Capture
3   for each item in batch {
4     @autoreleasepool {
5       allocate MTLCommandBuffer
6       allocate temporary MTLTexture
7       add "Write to temporary MTLTexture" commands to MTLCommandBuffer
8       add "Read from temporary MTLTexture" command to MTLCommandBuffer
9       send list of commands to GPU ("commit")
10      CPU wait until GPU completes execution of MTLCommandBuffer 
11      print "Before drain: " + os_proc_memory_available()
12    }
13    print "After drain: " + os_proc_memory_available()
14    if (index == 10)
15      end GPU Frame Capture
16  }
10  render batch results to visible frame
11  present visible frame to user 

And indeed, the transient memory spike was gone. The memory available after draining the autoreleasepool appeared to match the size of the temporary buffers allocated. We had a nice smooth rise to the steady state, and a 25% reduction in peak memory usage. We still had to work some magic to operate on big content — 1.7GB will still only get you so far — but predictable transient memory behaviour was a big step forward.

References

• Reducing the Memory Footprint of Metal Apps
• Developing Optimized Metal Apps and Games video Part 3: Memory Footprint. (Do use the searchable, hyperlinked transcript!)
• Image Filter Graph with heaps and fences sample code
• Archived documentation on MTLHeap and fences adds useful supplemental detail beyond the current documentation.

Welcome to Emme 3. During the years that I worked in travel demand forecasting, this was the main tool available to me.

Emme was undoubtedly a trailblazing innovator when it first came out in 1982 and remained a power user’s dream through to the early 90s. But it clearly missed the Windows boat; the software seems to have stagnated until beginning a revival in the late 00s.

Like any early 80s software, the original version is old enough that I’ve never even heard of the hardware: it was implemented on the Pixel 100/AP Supermicro, a 32-bit 68000 based UNIX workstation. The later shift to DOS was in the pre-486 era when CPUs didn’t have floating-point capabilities and required a separate co-processor chip or board, as this 1986 press release hypes:

“The first computational tests show that the [16 MHz co-processor board] DSI-780 beats even our most optimistic expectations. In raw computing power, it is more powerful than a full size VAX 11/780 and is 3 times faster than the already astonishing DSI-32.”

By the early 2000s, the vendor had misguidedly put energy into a basic Unix GUI, just as the final users abandoned Unix. The vendor belatedly added a real interactive GUI with 2007’s Emme 3, offering a Windows interface on top of an unchanged command-line core. The revival gained steam with 2012’s Emme 4 – which began to repackage the core algorithms with both a Python API and GUI, including IPython Notebook. It’s now a pleasure to use – a shiny, modern and easy-to-use front-end with a very powerful core under the hood.

But I’m going to talk today about the earlier intermediate version, Emme 3. This article is about masochistic techno archaeology, not productivity. Emme 3 was the awkward teenage years, when the transformation to full adulthood wasn’t quite complete yet.

Next sections:

• The Pain
• The Promise
• My Own Path
• Conclusion

The Pain

Menus & Macros

Analysis and database management in Emme 3 was still entirely a 1980s experience, driven by a console menu system. And – the kicker – the programming/macro language is actually just a recording of a menu session. If your interactive session looked like this, with user input shown in red:

3. M A T R I X   E D I T O R
3.01 Input / modify / output zone groups
3.11 Input matrices using batch entry
3.12 Input / modify matrices interactively
3.13 Plot matrices
3.14 Output matrices
3.16 Plot histogram of matrices
3.21 Matrix calculations
3.22 Matrix balancing
3.23 Triple-index Operations
Enter: Next module=3.12

3.12 Input / modify matrices interactively
1= initialize a matrix
2= delete a matrix
3= modify a matrix
4= copy a matrix
5= list a matrix
6= list matrix directory
7= initialize matrix directory
8= change matrix protection flags
Enter: next=2
Enter: Matrix=mf13
mf13 diftrt transit time difference     (12-09-13 10:31:21)
Delete this matrix?y
Deleted

3.12 Input / modify matrices interactively
1= initialize a matrix
2= delete a matrix
3= modify a matrix
4= copy a matrix
5= list a matrix
6= list matrix directory
7= initialize matrix directory
8= change matrix protection flags
Enter: next= q

Then your “source code” would look like this:

3.12
2
mf13
y
q

Or, if you took advantage of the shorthand notation, you could instead say

~+|3.12|2|mf13|y|q

Perfectly legible – a nice, succinct way to say “I deleted a matrix!”, right? The menus themselves are mostly in the manual, and they’re mostly consistent between software versions. A particular delight is that the sequence of menu questions is state-dependent, with no easy way to predict whether an extra confirmation will pop up in any given situation. If matrix mf13 doesn’t exist, you’ll get a different series of questions.

Variably Painful

The data model is pretty straightforward, mostly:

• a map represented as a graph of nodes and directed edges, with per-node and per-edge custom data
• transit routes
• origin-destination data such as matrices
• global variables

The pain is in working with this data. Most of these were accessed by numerical IDs, not by name – mf123 is an origin-destination matrix with ID 123. The macro language offered no arithmetic operators to let you work with numerical IDs. Matrices and per-node/edge data were the rare exception – you can refer to them using a six-character name. Unfortunately, mf”ttawq6″ wasn’t really enough to clearly define “am weighted travel time for the home-station leg of commuter rail trips”.

The global variables were also painful: a small set of floating-point registers, no scope management when calling between macros, and painful string operations. The whole experience felt a lot like programming DOS batch files, or working in assembly language. You can do it, but roll up your sleeves and write a lot of comments.

The Promise

So why did people put up with this, instead of just using a normal GIS system – say a Python+PostGIS combination? Like with any domain-specific language, you have to consider the trade-offs against a general-purpose system, and I’d describe four main reasons:

1. A data model that includes transit lines.
2. Ready-made implementations of most of the standard operations you’ll need, like traffic and transit assignment, management of park & ride demand, etc.
3. Base of existing trained users
4. A domain-specific GUI and graphing system. (While I’ve complained here about the unmodernized parts of Emme 3, the GUI front-end was modernized and was on an equal footing with peers of its era like ArcGIS.)

I have little experience with peer software like TransCAD or CUBE, but I’ve heard that Emme’s advantages over those include:

1. High-quality, battle-tested algorithms
2. Customizability

While Emme 2 was still an ugly DOS application in 1996, it made good use of the 1980s and 1990s, building a truly powerful database system for the era, with a sound data model and good algorithms that were well-tailored to their problem domain. I’m sure that if you were an Emme expert in the late 90s, you could do some truly mind-blowing things compared to your peers. (For the Emme veterans in the crowd, which 1986 tool would you choose: the Emme network calculator or… uh… ArcINFO and its network tools?)

Even in the mid-2000s, that tradeoff still tipped in favour of Emme and its competitors like TransCAD or CUBE. Recreating the Emme tools in a general-purpose platform would far too big an investment for a Metropolitan Planning Organization or other transportation agency.

My Own Path

Despite the obstacles, I got a lot done in Emme 3, and found some good patterns to work around its pain points. Perhaps the most surprising is that Windows filenames proved the best abstraction around the agonizing internals. If I needed to delete three matrices, I didn’t have to just repeat the earlier 3.12 incantation three times; instead, I had a nice file called matrix-delete.mac that allowed me to just write:

~<matrix-delete mf3 mf4 mf15

The windows filenames aren’t limited by the awful 6-character limits that pervade everything else, and it became possible to make my code vastly more legible. (And no, I never imagined that I’d praise the virtues of Microsoft’s 6~n.3 file naming.)

I’m sure that if I’d chosen some standard auxiliary tool as my second home – like shelling out to Python to generate custom macros on demand – I could have gone a lot further. But… taking on external dependencies is also a challenge, particularly when working in a team environment with a lot of non-software staff who can’t readily install/configure Python themselves. Not to mention having to fight the government IT staff every step of the way.

Good software practices can still emerge in such an environment – some day, ask me about how we implemented version control on our network data.

Conclusion

I’m being deliberately snarky about a legacy piece of software in this article, but Emme was utterly invaluable to me as a modeller, and it has advanced by leaps and bounds in the last decade. I’m writing about it today mostly as an entertaining anecdote: a glance back at computing/data science history, and a snapshot in time as Emme’s vendor took the painful steps necessary to modernize 1980s-era software. I honestly agree with the vendor’s decisions – I’m sure when they planned Emme 3, it was painful to limit the scope and leave the macro language untouched, but it was the right choice. That version kept their software alive, and gave them the breathing room to make Emme 4. I remain a staunch supporter of evolutionary software improvement rather than the “clean slate rewrite.”

References

There’s a great article on the history of Emme from Michael Florian. And there’s clearly some drama in the backstory – it’s clear that long-time contributor Heinz Spiess had a major falling out with the company in 2005, when the Unix GUI “Enif” was abandoned in favour of the Emme 3’s Windows GUI. Speiss also keeps a great archive of the 80s and 90s Emme 2 newsletters.

In September 2017, Microsoft released a rewritten XAML Designer program within Visual Studio. It’s only enabled for a tiny fraction of apps and got a very quiet launch, so almost no one knows about it. The new version runs as UwpSurface.exe instead of XDesProc.exe and is only enabled for UWP apps targetting Fall Creators Update SDK or newer.
For my app, the new Designer simply broke everything initially. Why? Presumably for technical reasons, it only works with {Binding} and not {x:Bind} – but this was not made at all clear in the launch announcements. UWP developers have been encouraged to use {x:Bind}: it’s compiled, type-safe and faster, and x:Bind functions are the only way to do multibinding. For my 64-bit app, I never got design data or design instances working under XAML Designer (xdesproc), so I relied entirely upon {x:Bind}‘s FallbackValue parameter to preview different modes of my UI – but {Binding} has no equivalent mechanism.
After a lot of tinkering, I’ve finally learned a few important things about the new XAML Designer, and got a usable workflow.

Top Takeaways

• UwpSurface is much faster and stabler than XDesProc. The dialog above (“Click here to reload the designer”) is largely history.
• It works for both 32-bit and 64-bit apps (x86 or x64), which is a big step forward
• Only {Binding} is evaluated; {x:Bind} is completely ignored.
• DesignInstances (a live ViewModel) can be attached via DataContext or d:DataContext, although the DesignInstance parameter doesn’t seem to work
• ViewModel code executes, but I don’t see any indication that View code executes, despite discussion to the contrary in Microsoft’s launch blog post
• For C++/CX apps: due to a bug, only single-class ViewModels (without any C++/CX base classes) work as of Visual Studio 15.8.x. They’re fine in C#.
  (Update Jan. 2019: Visual Studio 15.9 fixed this bug, but ViewModels that implement property change notifications still do not work.)
• You can attach a debugger and see debug output from your ViewModel, or any exceptions. I haven’t been able to set breakpoints.
• Update Jan. 2019: Visual Studio 15.9 added support for something I requested in mid-2018: the FallbackValue parameter was added to {Binding}, which makes that an equally viable way to work with XAML Designer. FallbackValue doesn’t work for {x:Bind} in the new Designer.

My strategy for a C++/CX app

• Stick with {x:Bind} and its functions in most of my code
• For the few properties that are central to a clean layout (usually about 2-5), use {Binding} and type converters
• For those properties, build a duplicate “DesignTimeMock” ViewModel class – with no C++/CX base classes – and return the design-time property values there. Most properties can be safely omitted.
• In the XAML code, define two different DataContexts like this:
  

  <UserControl.DataContext>
      <local:MyViewModel />
  </UserControl.DataContext>
  <d:UserControl.DataContext>
      <local:MyViewModel_DesignTimeMock/>
  </d:UserControl.DataContext>

  
  

  This attaches one ViewModel for runtime, and the mock for design time.

  
  
• Update Jan. 2019: Visual Studio 15.9 now allows a different approach: instead of a DesignTimeMock, you can just have a single DataContext using the “real” view model, but instead change {x:Bind} to {Binding} in the few places where it matters, and then add a FallbackValue parameter to choose the desired value in XAML Designer. The biggest advantage of FallbackValue: you can edit it in place and see it immediately update, without recompiling and relinking the DesignTimeMock view model.

It’s not ideal. But… it’s better than nothing.

Closing Thoughts

Despite the difficulties, I do look forward to further improvements in the XAML Designer. The old version was dated and crash-prone, and a clean slate rewrite was the only reasonable path forward. It’s just going to take some time to reach feature parity with the old version, which will mean some teething pain for “guinea pig” developers like myself.

This is part two in a series of articles on asynchronous coding in C++/CX. See the introduction here.

1. Prefer a task chain to nested tasks
2. Be aware of thread scheduling rules
3. Be aware of object and parameter lifetimes
4. Consider the effect of OS suspend/resume
5. Style: never put a try/catch block around a task chain.
6. References

2. Be Aware of Thread Scheduling Rules

• When working with non-threadsafe code, you will usually prefer to continue on the same thread and not have to deal with multiple threads contending for the same data.
• Helpfully, Universal Windows Platform (UWP) apps have a user interface thread inside a Single Threaded Apartment. On that thread, continuations (either a task .then() statement or code after a co_await statement) will almost always be scheduled to continue on the same thread.
  • Exception #1: if the initial task in a chain is not an IAsyncAction or IAsyncOperation (or their WithProgress variants), then the continuation may “break out” of the apartment to a different thread.
  • Exception #2: in my tests, I found that mixing coroutines and task-based continuations could still break out of the apartment. Calling a coroutine and then following it with a .then() task-based continuation seemed to cause it, although I haven’t dug very deep into the exact conditions.
• If a continuation is not on the UI thread, then the guarantees go out the window. For threadpool threads, a continuation can be scheduled on any thread.
  • So, partway through a coroutine, you may find yourself on an entirely different thread.
  • I imagine this is to prevent “starvation” of asynchronous chains when running on a compute-intensive thread, for example. But it can be quite a gotcha.
  • The concurrency::create_task() method can take a task_continuation_context::use_current() parameter to (try) to force execution to stay on the same thread, but there’s no equivalent for coroutines. It’s not clear to me that this always works, however; I need to test further and explore.
• When in doubt: use std::this_thread::get_id() to check the thread id over the course of an asynchronous chain of operation.
• When on a threadpool thread, my preference is to write a standalone coroutine in a functional style rather than as a traditional method within a class. I avoid using the this pointer, pass inputs to the coroutine by value and return a result from the asynchronous chain. If I want to modify an object, I’ll write an accompanying method that calls the coroutine, then schedules a final task on the original thread to mutate the object. Here’s an example:
  

  class MyClass {
  private:
    static concurrency::task<std::wstring> Coroutine(wstring filename) {
      // ... do some stuff, open file with co_await, read data, etc...
      co_return result;
    }
  public:
    void MemberFnAsync() {
      concurrency::create_task(Coroutine(m_filename),
        task_continuation_context::use_current())
      .then([this](wstring result) {
        this->SetTextFromFile(result);
      });
    }
  };

  
  

3. Be Aware of Object and Parameter Lifetimes

• When passing data into asynchronous code, you want to pass by value. That applies to both lambda captures (for continuation tasks) and to coroutine parameters.
• Why? If you pass do a traditional C++ calling convention like this:
  

  concurrency::task<void> MyCoroutineAsync (const wstring &str) {
  // do some stuff.
  co_await OtherFn();
  AnotherFn(str);
  }

  
  

  … the str parameter will typically be valid until the first co_await statement, but at that point execution will return to the caller until OtherFn() completes. The str parameter may well then be destroyed—especially if it was an rvalue or a stack variable. By the time the coroutine resumes and AnotherFn() is called, str will be a dangling pointer.

• The underlying issue is that the coroutine task chain outlives its caller and therefore can’t count on references to data from its caller.
• This applies to reference and pointer data. Pass-by-value is usually preferred, but of course smart pointer types are also valid.
  • Just be sure to pass smart pointers in a manner that creates a separate reference count: std::shared_ptr<T>, not const std::shared_ptr<T>&

For me, the steepest learning curves with the Universal Windows Platform (UWP) was the use of asynchronous APIs and the various libraries for dealing with them. Any operation that may take more than 50ms is now asynchronous, and in many cases you can’t even call the synchronous equivalent from Win32 or C. This includes networking operations, file I/O, picker dialogs, hardware device enumeration and more. While these APIs are pretty natural when writing C# code, in C++/CX it tends to be a pretty ugly affair. After two years of use, I now have a few “best practices” to share.
C++/CX offers two different approaches for dealing with asynchronous operations:

1. task continuations using the Parallel Patterns Library (PPL)
2. coroutines (as of early 2016)

Personally, I vastly prefer coroutines; having co_await gives C++/CX a distinctly C# flavour, and the entire API starts to feel “natural.” However, at my current job we have not yet standardized on coroutines, and have a mix of both approaches instead. And to be fair – despite Microsoft’s assurances that they are “production ready”, I’ve personally hit a few coroutine bugs and they do occasionally completely break with compiler updates.
I’m going to write up my advice in a series of posts, as the examples can be pretty lengthy.

1. Prefer a task chain to nested tasks
2. Be aware of thread scheduling rules
3. Stay aware of object and parameter lifetimes
4. Consider the effect of OS suspend/resume
5. Style: never put a try/catch block around a task chain.
6. References

1. Prefer a Task Chain to Nested Tasks

When writing a series of API calls that need local variables, conditional logic, or loops, it’s tempting to write it as a nest of tasks. But a nest will:

• hurts legibility: an extra indent level for every sequential API call, and very wordy
• painful/missing exception handling: every level of the nest needs its own exception handler. Exceptions will not propagate automatically from an inner task to the outer exception handler, but will instead raise an unobserved exception error.
• makes it hard to return a waitable/gettable task that can track when the entire chain completes.

Consider this example nested code:

concurrency::create_task(folder->GetFileAsync())
.then([](StorageFile ^file) {
  if(file != nullptr) {
    concurrency::create_task(file->ReadAsync())
    .then([](IRandomAccessStream ^stream) {
      /* do something with stream */
    })
    .then([](concurrency::task<void> t) {
      try { t.get(); }
      catch (COMException ^) { /* do something */}
      catch (...) { /* do something */ }
    });
  }
})
.then([](concurrency::task<void> t) {
  try { t.get(); }
  catch (COMException ^) { /* do something */}
  catch (...) { /* do something */ }
});

Here’s the equivalent implemented as a task chain:

concurrency::create_task(folder->GetFileAsync())
.then([](StorageFile ^file) {
   if(file == nullptr)
     concurrency::cancel_current_task();
   return file->ReadAsync();
}).then([](IRandomAccessStream ^stream) {
   /* do something with stream */
}).then([](concurrency::task<void> t) {
   try { t.get(); }
   catch (std::task_cancelled ) { }
   catch (COMException ^) { /* do something */}
   catch (...) { /* do something */ }
});

Let’s look at a few other situations and the best way to make a chain:

• Need access to local variable in earlier stage of chain: the best solution is to define a custom struct with the local variables that are needed throughout the chain, heap-allocate it with a std::sharedptr, and pass it in via lambda-capture:
  

  struct StackFrame { String ^filename; }
  auto stack = std::make_shared<StackFrame>();
  concurrency::create_task(folder->GetFileAsync())
  .then([stack](StorageFile ^file) {
     stack->filename = file->Name;
     return file->ReadAsync();
  }).then([stack](IRandomAccessStream ^stream) {
     /* do something with stream and stack->filename */
  })

  
  
• Need a loop with asynchronous calls on each item: collect the tasks for each item in the loop into a std::vector and return when_all on that vector.
  

  concurrency::create_task(folder->GetFilesAsync())
  .then([stack](IVector<StorageFile> ^files) {
     std::vector<concurrency::task<void> > tasks;
     for (auto file : files) {
       tasks.push_back(concurrency::create_task(file->DeleteAsync()));
     return concurrency::when_all(tasks.begin(), tasks.end());
  });

  
  

Of course—just in case you’re curious—as a coroutine this is all trivial and highly readable.

try {
  StorageFile ^file = co_await folder->GetFileAsync();
  if (file != nullptr) {
    IRandomAccessStream ^stream = co_await file->ReadAsync();
    /* do something with stream and file->Name */
  }
}
catch (COMException ^) { /* do something */}
catch (...) { /* do something */ }

Continues in Part 2

I recently found a neat XAML user interface trick that I hadn’t seen in my usual resources. Suppose you have:

• a grid-based responsive user interface that you want to grow/shrink to fit the window
• suppose it has a fixed width, and each row has a “core” minimum height it needs.
• then there’s some extra vertical space that you want to sprinkle around
• you have some priorities – first give row #1 extra space, then row #2 any extra.

XAML makes it easy to do proportional space allocation – e.g., give row #1 two-thirds and row #2 one-third by giving them “2*” and “*” height respectively. But it doesn’t do priorities.
The trick: combine a massive star size with a MaxHeight. That looks like this:

<Grid>
  <Grid.RowDefinitions>
    <RowDefinition Height="1000*" MaxHeight="200" />
    <RowDefinition Height="*" />
  </Grid.RowDefinitions>
</Grid>

Essentially, row #1 gets “first claim” on any extra space, up to a limit of 200 pixels. Any extra space beyond 200 pixels falls over to row #2.

I’m a latecomer to Microsoft’s user interface technologies. I never used Windows Framework (WPF) on top of .net and I never used Silverlight on the web. The last year was my first taste of these tools through the XAML framework that is part of the “Universal Windows Platform” (UWP) – that is, the Windows 10 user interface layer (and Win8).
XAML has steadily evolved since the WPF days, and it took a little while to really understand the different major eras of the technology, especially since the UWP flavour of XAML strips out some of the older syntaxes in the name of efficiency on mobile platforms, better error checking at compile-time and code readability and ease-of-use. The technology’s old enough that much of the Google search hits and StackOverflow results are not applicable on the modern UWP platform.

My Tips

So what were a few of my first lessons when using XAML on UWP?

• Prefer x:Bind to Binding
• Responsive Design
• Expressions in x:Bind calls
• Prefer XAML or ViewModels over code-behind
• Use XAML Designer
• Use Commands, get disabling for free
• More to read

Prefer x:Bind to Binding

The main reason: x:Bind gives you compile-time checks and better performance. Be aware of the small differences:

• OneTime binding by default instead of OneWay binding
• Binding path is the framework element (control) not the DataContext (view model)

Responsive Design

Combining VisualState and AdaptiveTriggers is quite a powerful way to hide/show, relocate
or resize different parts of a user interface. The only pain point with this is that you can’t alter a style in response to a window size change (or other trigger), only modify the properties of each individual control explicitly. I tried one workaround: making a dummy ViewModel DependencyProperty that gets updated by the trigger, and then binding the styles to that property. This works, but can’t be previewed in XAML Designer, which I found useful. Instead, I created a dummy invisible control, set the triggers to modify that control,
and then bound the style to the invisible control’s properties. This works both “live” and in XAML Designer, even updating live as the XAML Designer target device resolution is changed.
I found this reference useful on this subject.

Expressions in x:Bind calls

In the Windows Anniversary Edition (Fall 2016), Microsoft added some great new
capabilities that allow some really nice, clean syntax in XAML, without the use of converters. You can now do the following, provided that your ViewModel class implements the xAnd and xMult functions:

<Button Visibility="{x:Bind Vm.xAnd(Vm.IsVisible, Vm.IsStateOn)}"
 Width={x:Bind Vm.xMult(Vm.Width, 0.5)}">

Notice a few things here:

• despite having only boolean ViewModel properties, we can do a boolean operation on them and auto-convert the boolean result to a Visibility type, without any converters. Always prefer x:Bind expressions to convertors.
• you can write single or multi-operand functions. (In Visual Studio 2015, XAML Designer didn’t support multi-operand, but Visual Studio 2017 added full support.)
• you can embed constants and work with integer or double types
• you cannot nest functions or overload function names

This opens up a huge number of ways of writing cleaner and more readable XAML code.

Prefer XAML or ViewModels over code-behind

Code-behind (the C++ or C# source for the XAML View) should be a last resort. It’s already challenging enough to keep track of a XAML file and a ViewModel; burying logic in the View divides the reader’s attention even further.
There are situations where something is part of the “View” rather than the ViewModel: for example, a property that has nothing to do with the Model and only exists to enable the XAML implementation – such as a control spacing property or some such. This is perhaps the one case where View code-behind might make sense. But even there – if you can do it in XAML, that’s usually better.

Use XAML Designer

XAML Designer – the Visual Studio built-in visual editor for XAML – hasn’t had much love in a long time. Many things are broken, and it can’t handle some useful things. And if you don’t put effort into setting up the XAML correctly, a page/control can be totally illegible.
Why prefer XAML Designer?

• Compile times for XAML – especially include C++ code generations – are brutal. You can iterate much faster if you avoid the compile.
• XAML Designer can do a lot of responsive design without even doing a build
• It’s a much quicker way to learn XAML, and even explore events/properties that you weren’t aware of.

How to make XAML Designer more useable:

• Ensure your UserControl has d:DesignWidth and d:DesignHeight settings
• Ensure ViewModel has a default zero-parameter constructor
• Bind the ViewModel to the DataContext in XAML, not in code-behind. e.g.,
  

  <Page.DataContext><local:MyViewModel/></Page.DataContext>

  
  
• Use AdaptiveTriggers for responsive design, rather than ViewModel or View logic
• Add FallbackValues for x:Binds that XAML Designer can’t understand. They’ll only be used at design-time.
• Don’t bother trying to get “real” design-time data working via d:DesignInstance; it doesn’t work with a 64-bit application or with x:Bind.
  
  (In theory, you’re supposed to be able to write
  

  d:DataContext="{d:DesignInstance local:MyViewModel, IsDesignTimeCreatable=True}"

  
  

  and get XAML Designer to actually construct an instance of your real ViewModel, and query its values to get the “right” default values when you’re designing. But… it clearly hasn’t been maintained in a long time, it only works in 32-bit and with Binding.)

Use Commands, get disabling for free

Why use Commands as the mechanism for the XAML/View to modify the view model’s state?
For one, it’s often less code: XAML can directly bind to the viewmodel’s command property, instead of XAML having a click event, and the View’s click event codebehind then modifies the viewmodel.
But also: you can set it up so that when the command “cannot execute”, then the user interface will automatically grey out and prevent clicking. The details:

• the command should be a ViewModel property, it should implement a CanExecute method, and that CanExecute method should issue a PropertyChanged notification
• the XAML control should be bound to the command
• when the command cannot be executed, the XAML control will then enter the “Disabled” visual state.
  
  

More to Read

• Best Practices for Developing UWP Applications: a bit C#-centric, but some good tips
  • Refer to the Right documentation: surprisingly hard. Google tends to bring up .NET docs rather than UWP, and Visual Studio 2013/15 over the latest 2017 docs.
  • Use the Live Visual Tree and Live Property Explorer
  • Use templated controls over user controls
  • If you have troubles with Visual Studio stability (or speed), try disabling XAML Designer