C#7: Better Performance with Ref Locals, and Ref and Async Returns

Since the start of the year, we have been taking a look at the various new features coming to C# in C#7. This week, we will look at some of the changes to returning values from our functions that are there for those who need better performance. Before we begin, here is a summary of what we are covering in this series.

Generalized async return types

Up until now, an async method had to return Task, Task, or void (though that last one is generally frowned upon1). However, returning Task or Task can create performance bottlenecks as the reference type needs allocating. For C#7, we can now return other types from async methods, including the new ValueTask, enabling us to have better control over these performance concerns. For more information, I recommend checking out the official documentation.

Ref Locals and Ref Returns

C#7 brings a variety of changes to how we get output from our methods; specifically, out variables, tuples, and ref locals and ref returns. I covered out variables in an earlier post and I will be covering tuples in the next one, so let's take a look at ref locals and ref returns. Like the changes to async return types, this feature is all about performance.

The addition of ref locals and ref returns enable algorithms that are more efficient by avoiding copying values, or performing dereferencing operations multiple times.2

Like many performance-related issues, it is difficult to come up with a simple real world example that is not entirely contrived. So, suspend your engineering minds for a moment and assume that this is a perfectly great solution for the problem at hand so that I can explain this feature to you. Imagine it is Halloween and we are counting how many pieces of candy we have collectively from all of our heaving bags of deliciousness3. We have several bags of candy with different candy types and we want to count them. So, for each bag, we group by candy type, then retrieve current count of each candy type, add the count of that type from the bag, and then store the new count.

void CountCandyInBag(IEnumerable<string> bagOfCandy)
{
    var candyByType = from item in bagOfCandy
                      group item by item;

    foreach (var candyType in candyByType)
    {
        var count = _candyCounter.GetCount(candyType.Key);
        _candyCounter.SetCount(candyType.Key, count + candyType.Count());
    }
}

class CandyCounter
{
    private readonly Dictionary<string, int> _candyCounts = new Dictionary<string, int>();

    public int GetCount(string candyName)
    {
        if (_candyCounts.TryGetValue(candyName, out int count))
        {
            return count;
        }
        else
        {
            return 0;
        }
    }

    public void SetCount(string candyName, int newCount)
    {
        _candyCounts[candyName] = newCount;
    }
}

This works, but it has overhead; we have to look up the candy count value in our dictionary multiple times when retrieving and setting the count. However, by using ref returns, we can create an alternative to our dictionary that minimises that overhead. In writing this example, I learned4 that since IDictionary does not do ref returns from its methods, we can't use it with ref locals directly. However, we also cannot use a local variable as we cannot return a reference to a value that does not live beyond the method call, so we must modify how we store our counts.

void CountCandyInBag(IEnumerable<string> bagOfCandy)
{
    var candyByType = from item in bagOfCandy
                      group item by item;

    foreach (var candyType in candyByType)
    {
        ref int count = ref _candyCounter.GetCount(candyType.Key);
        count += candyType.Count();
    }
}

class CandyCounter
{
    private readonly Dictionary<string, int> _candyCountsLookup = new Dictionary<string, int>();
    private int[] _counts = new int[0];

    public ref int GetCount(string candyName)
    {
        if (_candyCountsLookup.TryGetValue(candyName, out int index))
        {
            return ref _counts[index];
        }
        else
        {
            int nextIndex = _counts.Length;
            Array.Resize(ref _counts, nextIndex + 1);
            _candyCountsLookup[candyName] = _counts.Length - 1;
            return ref _counts[nextIndex];
        }
    }
}

Now we are returning a reference to the actual stored value and changing it directly without repeated look-ups on our data type, making our algorithm perform better5. Be sure to check out the official documentation for alternative examples of usage.

Syntax Gotchas

Before we wrap this up, I want to take a moment to point out a few things about syntax. This feature uses the ref keyword a lot. You have to specify that the return type of a method is ref, that the return itself is a return ref, that the local variable storing the returned value is a ref, and that the method call is also ref. If you skip one of these uses of ref, the compiler will let you know, but as I discovered when writing the examples, the message is not particularly clear regarding how to fix it. Not only that, but you may get caught out when trying to consume by-reference returns as you can skip the two uses at the call-site (e.g. int count =
_candyCounter.GetCount(candyName);
); in such a case, the method call will be as if it were a regular, non-reference return; watch out.

In Conclusion

I doubt any of us will use these performance-related features much, if at all, and nor should we. In fact, I expect that their appearance will be a code smell in a majority of circumstances; a case of "ooo, shiny" usage6. I certainly think that the use of ref return with anything but value types will be highly unusual. That said, in those situations when every nanosecond of performance is required, these new C# additions will most definitely be invaluable.

  1. https://msdn.microsoft.com/en-us/magazine/jj991977.aspx []
  2. https://docs.microsoft.com/en-us/dotnet/articles/csharp/csharp-7#ref-locals-and-returns []
  3. Let's not focus on why we went trick or treating as adults and why anyone gave us candy in the first place []
  4. seems obvious now []
  5. In theory; after all, this is a convoluted example and I am sure there are better ways to improve performance than just using ref locals. Always measure your code to be sure you are making things better; don't guess []
  6. "Ooo, shiny" usage; when someone uses something just because it's new and they want to try it out []

Octokit and the Authenticated Access

Last week, I introduced Octokit and my plans to write a tool that will mine our GitHub repositories for information that can be used to craft release notes. This week, we will look at the first step; authentication. I am using Octokit.NET for my hackery; if you choose to use another variant of Octokit, some of the types and methods available may be different, but you should be able to follow along. In addition, I have no intention of documenting every aspect of Octokit and the GitHub API, so if you are intrigued by anything that I do not discuss, I encourage you to explore the relevant documentation.

The main `GitHubClient` class, used to access the GitHub APIs, has several constructors, some that take credentials (sort of) and some that do not. All but one of the constructors take a `ProductHeaderValue` instance, which provides some basic information about the application that is accessing the API. According to the documentation, this information is used by GitHub for analytics purposes and can be whatever you want.

Now, if you only want to read information about publicly accessible repositories, you do not need to provide any authentication at all. You can create a client instance and just get stuck in, like this:

var githubClient = new GitHubClient(new ProductHeaderValue("Tinkering"));
var repo = await githubClient.Repository.Get("octokit", "octokit.net" );
Console.WriteLine(repo.Name);

However, you can only perform some read-only tasks on public repositories and, unless you are performing the most trivial of tasks, you will hit rate limits for unauthenticated access.

NOTE: All of the Octokit.NET calls are awaitable

Authentication can be achieved in a several ways; via an implementation of `ICredentialStore` passed to a constructor of `GitHubClient`, by providing credentials to the `GitHubClient.Connection.Credentials` property, or by using the `GitHubClient.Oauth`. The `OAuth` API allows an application to authenticate without ever having access to a user's credentials; it is understandably a little more complex than approaches that just take credentials. Since, at this point, our focus is to craft some methods for extending the API functionality, we will worry about the `OAuth` workflow another time. The other two approaches are quite similar, although the constructor-based approach requires a little extra effort. The following two examples will both give you authenticated access, though I think the constructor-based access feels a little less hacky:

// Without the constructor
var githubClient = new GitHubClient(new ProductHeaderValue("tinkering"));
githubClient.Connection.Credentials = new Credentials("username", "password");
// With the constructor
public class CredentialsStore : ICredentialsStore
{
    public Task<Credentials> GetCredentials()
    {
        return Task.Run(() => new Credentials("username","password"));
    }
}

var githubClient = new GitHubClient(new ProductHeaderValue("tinkering"), new CredentialsStore());

Two-factor Authentication

Of course, using your username and password is futile because you have two-factor authentication enabled1. Luckily there is a constructor on the `Credentials` class that takes a token, which you can generate on GitHub.

First, log into your GitHub account and choose Settings from the drop-down at the upper-right. On the fight, select Personal Access Tokens.

The right-hand side will change to the list of personal access tokens you have already created for your account (you may have created these yourself or an application may have created them via OAuth). Click the Generate New Token button and give it a useful name. You can now use this token as your credentials when using Octokit. I keep my token in the LINQPad password manager2 so that I can reference it in my code using the name I gave it, like this:

Util.GetPassword("the.name.I.gave.my.oauth.token")

In conclusion…

And that is it for this week. In the next entry of this series on Octokit, we will start getting to grips with releases and some of the basic pieces for my release note utility library.

  1. If you do not, you should rectify that []
  2. The LINQPad password manager is available via the File menu in LINQPad []

CodeMash 2.0.1.2


It's like riding a unicorn over a double rainbow. CodeMash. All the way across the sky.
One of many CodeMash slogans on display

I went to CodeMash this year. I was one of the 1200 (or 1300 and something, after speakers and other people were counted). It was my first time attending this community-organised conference and I had a thoroughly enjoyable time. I would show you pictures but I neglected to take any as I was having far too good a time to remember that I'd brought a camera.

My wife and I1 arrived at the venue, the Kalahari Waterpark and Resort on Tuesday, the day before everything started with Wednesday's pre-compiler. Tuesday evening was spent meeting fellow mashers in the two resort bars, but ultimately led to a rocky start to Wednesday (breakfast was scheduled for 7am but I had forgotten to schedule bedtime accordingly).

My improvisation when the coffee cups ran out
My improvisation when the coffee cups ran out

At every meal during CodeMash, I enjoyed great food, nerdy conversation and copious quantities of caffeinated beverages with some fascinating people. Most of the time I dined with people I had never met, being sure to introduce myself and making a concerted effort to remember names (though, alas, I forgot a few). Although the pre-compiler day was overshadowed by a number of beverage-related issues varying from no coffee to no Mountain Dew to lots of coffee but no coffee cups (I improvised2), the remainder of the conference catering seemed to go without a hitch. This was in no doubt thanks to the CodeMash organizers and the amazing Kalahari staff.

Every evening after the sessions ended, a copious number of tempting options were available from the game rooms where D&D, poker and various other pastimes were enjoyed to Open Spaces3, from the bars, restaurants and water park to panel discussions. Attendees and CodeMash organizers alike would advertise a plethora of options to while away the hours until sleep was the only option. I was so exhausted after CodeMash that I slept for nearly a day when I got home.

What about the sessions themselves?

Wednesday

Going Independent

I'm not going independent, at least not anytime soon, but considering I have worked with many who are self-employed and might consider it for myself one day, it seemed prudent to learn more. Michael Eaton (@mjeaton) was the speaker for this session. He drew from personal experience and the experiences of those he knew (some of whom provided their own anecdotes) to outline the common practices and pitfalls that beset anyone trying to go it alone.

Michael's conversational style provided a great start to the conference and the information presented gave me a fresh perspective on the overhead, sales and productivity concerns of a business owner (apparently, if you manage 30 billable hours per week, you're doing well).  Even for someone under full-time employment like me, it provided useful details that will help me to continue supporting those who employ me.

HTML5 is here, and the Web will never be the same

Wednesday afternoon was spent with Brandon Sartrom (@BrandonSatrom) and Clark Sell (@csell5) learning all about markup, behavior and presentation with HTML5, javascript and CSS3. I am not a web developer, my acquaintance with HTML and its supporting technologies would probably make a professional sob, but this lab on the latest and greatest was fantastic. Each area of the HTML5 offering was presented with hands-on labs to sink ones teeth into. There was so much to cover that eventually time fell short, but I still have the labs on my desktop and be assured, I intend to complete them. This was a great stuff and the session so popular that we had to move rooms about an hour in. Apparently, this web stuff is a big deal. Who knew?

Thursday

Unlike the pre-compiler format of half-day and full-day workshops and discussions, the remainder of the conference was split into concurrent hour long presentations, open spaces, gaming and other activities. The sheer number of distractions was sometimes overwhelming, making the act of choosing a distraction in itself to the point where a couple of times, I gave up and just took an hour long break.

On Thursday, we had our first keynote speech, Rethinking Enterprise, while munching away at the remnants of breakfast. The speaker, Ted Neward, had an energy that made sure everyone was awake. Although Ted's presentation style was ultimately controversial, I felt the points he made were valid, well thought out and thoroughly enjoyable to learn.

From the keynote, I swiftly headed to see the popular double-act of Jon Skeet(@jonskeet) and Bill Wagner (@billwagner) presenting C# async inside and out. It was a packed out double session. Some only turned up for the much more complicated second session and I'm sure probably left very confused and scared of both C# and async. However, I loved it. Not only did I witness Jon Skeet's passion for C# first hand, but I also learned a lot (a useful mutable struct?).

After the Skeet/Wagner show, I took a break to check on my wife and make sure she was having a good time. I actually had to persuade her to make an appointment in the spa as she was perfectly happy eating homemade gumbo and watching bad daytime TV in the hotel room. Once I'd convinced her to spend some money in the spa (what did I do?!), I headed back down to learn about usability testing with Carol Smith (@carologic), attended a vendor session from Robert Half Technology, and then headed to David Giard (@DavidGiard) and his presentation on data visualization.

I have to say that while I enjoyed all the talks and workshops I attended, David Giard's presentation on data visualization was by far in the top two sessions I attended. Not only did Mr. Giard give a great talk while very much under the weather, but the examples of good and bad data visualizations he presented were useful and clear. I came away with a new found appreciation for graphs and charts, and a new found skepticism of those who create them and their motives.

Thursday was rounded out by dinner, the hilarious Pecha Kucha competition, live music, impromptu free beer in one of the hotel rooms and a late night water park party just for CodeMash attendees. At least, those were the things I attended; as always there was far more going on elsewhere in the resort if one was so inclined to attend.

Friday

Friday started slow. The night had once again taken it's toll but breakfast was thankfully an hour later, which helped. I skipped the first session, opting instead to wander the vendor stands and show my appreciation for their support.

My first session of the day was Dealing with Information Overload delivered by Scott Hanselman. I really wanted to catch one of Scott's two presentations as I had seen him present at the San Francisco StackOverflow DevDays and really enjoyed his presentation style. Just as at DevDays in 2009, Scott gave a very enjoyable presentation packed with useful, necessary tips, tricks and lessons in how to deal with information and stay productive. I have already started to fold some of the techniques into my working day and intend to continue. Along with the Data Visualization presentation from Thursday, Dealing with Information Overload was in my top two talks of the conference.

Lunch followed with our second keynote speech, How We Got Here, And What To Do About It presented by Barry Hawkins. The keynote was excellent and the presenter only went up in my estimation when we spoke and I learned he was both an anglophile and a thoroughly nice chap4.

As lunch digested, I rounded out the conference with some C# Stunt Coding from Bill Wagner (and a little Jon Skeet when he got up to refactor Bill's code; thoroughly entertaining) and some applied F# from the crazy-shirted Gary Short (@garyshort). Both of these talks were wonderful and gave me some inspiration for some crazy and not so crazy things to try in the near future (both code- and fashion-based).

Friday night's raffle was entertaining, but I didn't win so I'm not saying anymore about it. I'm not bitter, but seriously, didn't win. I did, however, win a book from O'Reilly (@oreillymedia) just for singing a couple of lines to a song. O'Reilly had a large collection of books with them on their vendor booth and gave them all away to anyone willing to sing on video. I haven't seen that video surface yet, but I'm sure it will. Still, I now have a spanking new copy of Programming Android and they're not getting it back if they decide they don't like my pipes (but seriously, thanks for the book).

The End

Jafar hamming it up for the camera while the wife and I pose
Jafar hamming it up for the camera while the wife and I pose

And that was that. There was more partying and water park fun but the mashing was over. My wife and I enjoyed the remainder of our stay, including a few photos with Jafar, the Bengal tiger and then travelled home to pass out and catch up on sleep.

Congratulations to all who helped put this together and a hearty thanks to all the folks (speakers, staff, attendees and Jafar) that made my CodeMash experience. It was such a wonderful event to have been a part of and I hope I am fortunate enough to get a ticket next year.

  1. Yes, I took the missus. While I was learning and networking and totally not eating too much bacon or drinking, she was cooing at a Bengal Tiger cub or doing spa type things. []
  2. Okay, so I took at least one photo. []
  3. Open Spaces are free-form discussions on topics suggested by attendees where an open exchange of ideas, experiences, tips and other things can occur. []
  4. My assessment and conclusion of the latter was in no way swayed by learning the former…I swear. []