Avoiding Out of Memory Crashes on Mobile

One reason why it is difficult to develop software for mobile devices is that the hardware is not the best compared to deploying to a console or a “real” computer. Resources are limited. One particularly sparse resource is RAM. Out of memory exceptions are common on both Android and iOS if you’re dealing with large files. Recently, when building a Google VR 360 video player, we went over the 1GB of RAM available on older iOS devices pretty quickly.

What Not to Do

One of my big complaints about the Unity manual and many tutorials is they usually just show you how to do something really quickly and don’t always tell you the exact use case or how it can just flat out fail. For example, using the relatively new UnityWebRequest, you can download a file over HTTP like this:

private IEnumerator loadAsset(string path)
{
  using (UnityWebRequest webRequest = new UnityWebRequest(path))
  {
    webRequest.downloadHandler = new DownloadHandlerBuffer();
    webRequest.Send();
    while (!webRequest.isDone)
    {
      yield return null;
    }
    if (string.IsNullOrEmpty(webRequest.error))
    {
      FileComplete(this, new FileLoaderCompleteEventArgs(
        webRequest.downloadHandler.data));
    }
    else
    {
      Debug.Log("error! message: " + webRequest.error);
    }
  }
}

These are all off the shelf parts from Unity, with the exception of the FileLoaderCompleteEventArg but just assume that we use that to pass off the downloaded bytes as an array eg: byte[]. Notice this returns an IEnumerator and utilizes yield statements so it should be run in a Coroutine. What happens here is that the UnityWebRequest will open up a connection to the given path, download everything into a byte array contained within the DownloadHandlerBuffer. The FileComplete event will fire if there are no errors, sending the entire byte array to the subscribing class. Easy, right? For small files, sure. But we were making a 360 Video player. Our max resolution was 1440p. The first sample files we got for testing were bigger than 400MB. The iPhone 7, with 2GB of RAM, took it like a champ. The iPhone 6, with 1GB of RAM, crashed like a piano dropped from a helicopter.

Why Did my App Just Crash?

Let’s look at the guts of these components. The main focus is on the DownloadHandlerBuffer object. When it is first created, it will start by preallocating memory for a small byte array where it will store all the downloaded bytes. As the bytes come in, it will periodically expand the size of the array. In our test case, it was expanding the array until it could hold 400MB. And because each additional allocation is a guess, it will most likely overshot that amount. Note, I am speculating here because I have not looked at the source code for the DownloadBufferHandler. There is a chance it allocates space based on the Content-Length header returned with the HTTP Response. But, the result is the same; it will use up at least 400MB of RAM. That’s 40% of the 1GB that the iPhone 6 has! We’re already in dangerous territory. I know what you’re saying, “Steff, why did it crash if we only used 40% of the RAM?” There are two ways to find the answer. One (and give Unity credit here) is in the documentation for DownloadHandlerBuffer.

Note: When accessing DownloadHandler.data or DownloadHandler.text on this subclass, a new byte array or string will be allocated each time the property is accessed.

So, by accessing the data property, Unity allocates an additional 400MB of memory to pass off the byte array into the EventArg. Now we have used 800MB of RAM just on handling this one file. The OS has other services running plus you very likely have RAM allocated for bitmaps and UI and logic. You’re doomed!

Profiling Memory Allocations

If you didn’t read the docs, and they’re long: I get it, you could have found this memory leak by running the application in Unity while using the Profiler AND by running the application on an iOS device while using a valuable free tool from Apple: Instruments. The Allocations instrument captures information about memory allocation for an application. I recommend using the Unity Profiler heavily for testing in the Editor and then continuing performance testing on device for each platform. They all act differently. Using the Profiler in the Editor is only your first line of defense. In this case I only properly understood what was happening when I watched it unfold in a recording using the Allocations instrument.

Streams to the Rescue

There is a way to download large files and save them without using unnecessary RAM. Streams! Since we plan on immediately saving these large video files in local storage on device to be ready for offline viewing, we need to send the downloaded bytes right into a File as they are received. When doing that, we can reuse the same byte array and never have to allocate more space. Unity outlines how to do that here, but below is an expanded example that includes a FileStream:

public class ToFileDownloadHandler : DownloadHandlerScript
{
  private int expected = -1;
  private int received = 0;
  private string filepath;
  private FileStream fileStream;
  private bool canceled = false;

  public ToFileDownloadHandler(byte[] buffer, string filepath)
    : base(buffer)
  {
    this.filepath = filepath;
    fileStream = new FileStream(filepath, FileMode.Create, FileAccess.Write);
  }

  protected override byte[] GetData() { return null; }

  protected override bool ReceiveData(byte[] data, int dataLength)
  {
    if (data == null || data.Length < 1)
    {
      return false;
    }
    received += dataLength;
    if (!canceled) fileStream.Write(data, 0, dataLength);
    return true;
  }

  protected override float GetProgress()
  {
    if (expected < 0) return 0;
    return (float)received / expected;
  }

  protected override void CompleteContent()
  {
    fileStream.Close();
  }

  protected override void ReceiveContentLength(int contentLength)
  {
    expected = contentLength;
  }

  public void Cancel()
  {
    canceled = true;
    fileStream.Close();
    File.Delete(filepath);
  }
}

And to use the above in our coroutine:

private IEnumerator loadAsset(string path, string savePath)
{
  using (UnityWebRequest webRequest = new UnityWebRequest(path))
  {
    webRequest.downloadHandler = new ToFileDownloadHandler(new byte[64 * 1024],
      savePath);
    webRequest.Send();
    ...
    ...
  }
}

Looking first at our new ToFileDownloadHandler, we extended Unity’s DownloadHandlerScript and have overridden the required methods. The magic happens in two places. First, we pass in a byte array to the base class via the constructor. This let’s Unity know that we want to re-use that byte array on each ReceiveData callback where we only allocate a small amount of RAM once. Second, we use a FileStream object to write the bytes directly to our desired file. The rest of the code is there to handle canceling the request. Whenever you deal with FileStream objects, you must remember to close them out when you’re done.

Looking at the loadAsset method, we added a parameter for the path to where the file will be saved locally and we defined the size of the buffer at 64MB. This size is dependent on your network speeds. We were focussed on WiFi connections, so a larger buffer made sense. Too small and you will make the download take longer than necessary to complete.

Where to Go from Here

Now you have an understanding of one way that your application can eat up RAM. If you only take away one thing from reading this post it’s this: for managing memory allocations, streams are your friends. And you should be constantly performance testing as you develop your application, unless you’re trying to maximize one-star reviews in the App Store.

Gotchyas

One final note on the code above: we did not end up going to production using UnityWebRequest on iOS. When we tried using a similar streaming solution as above, we found that the request was not clearing from memory if it was canceled due to the user sending the application to the background. Using the Time Profiler Instrument showed that NSURLSession objects were not being cleaned up when the application paused and resumed, so eventually the CPU would max out and crash. We had to seek an alternative solution for iOS using a native plugin. However, in the final code we still used HTTP streaming directly into a file via FileStream. Just not wrapped up in UnityWebRequest objects.