Exploring the .NET Core Part 17: Videotaped API Review

March 4, 2015 Leave a comment

This is part 17 of my Exploring the .NET Core Series.

Microsoft’s .NET Core team has posted a videotaped API review session where they show how they review API enhancement suggestions. I thought the video was quite educational.

Categories: Programming Tags: ,

Exploring the .NET Core Part 16: Platform-Specific Builds Using Compile-Time Polymorphism

March 1, 2015 Leave a comment

This is part 16 of my Exploring the .NET Core Series.

While .NET has historically been limited to Windows machines, Mono notwithstanding, the introduction of the cross-platform .NET Core runtime has introduced the possibility of running .NET Core applications on Unix machines. With this possibility, developers may have the need of writing platform-specific code.

One way to write platform-specific code is:

  1. Define a conceptual base class which will have an identical name and methods across all platforms. This does not need to be a C# interface, as we will be using compile-time rather than run-time polymorphism.
  2. Provide an implementation of this class for each target platform.
  3. Use build-time conditions to include the platform-specific class based on target compilation platform.

An example from the .NET Core is the System.Console.ConsolePal class from the System.Console library. The library includes two implementations of this class:

  1. ConsolePal.Unix.cs, which provides a Unix-compatible implementation of the ConsolePal class
  2. ConsolePal.Windows.cs, which provides a Windows-compatible implementation of the ConsolePal class

The project file for this library, System.Console.csproj, then selects the appropriate file to build based on the target platform at compile time:

<!-- System.Console.csproj -->
...
<ItemGroup Condition=" '$(OS)' == 'Windows_NT' ">
  <Compile Include="System\ConsolePal.Windows.cs" />
  ...
</ItemGroup>
<ItemGroup Condition=" '$(OS)' == 'Unix' ">
  <Compile Include="System\ConsolePal.Unix.cs" />
  ...
</ItemGroup>

The advantage of this approach is that it has no run-time polymorphism overhead and thus provides maximum performance. The disadvantage of this approach is that the resulting binaries are platform-specific.

Recommendations

  • Avoid writing platform-specific .NET code unless it is completely unavoidable.
  • Consider using compile-time polymorphism to implement platform-specific code.
Categories: Programming Tags: ,

Exploring the .NET Core Part 15: Using Non-Generic Factory Classes to Enable Type Inference

February 18, 2015 Leave a comment

This is part 15 of my Exploring the .NET Core Series.

While C# supports type inference for generic methods, it does not support type inference for constructors. In other words, while this code works:

public class FooFactory
{
   public static Foo<T> Create<T>(T value)
   {
      return new Foo<T>(value);
   }
}
var myObj = FooFactory.Create(212);

This code does not:

public class Foo<T>
{
   private readonly T field;
   public Foo(T value) { field = value; }
}

var obj = new Foo(212); // DOES NOT WORK

For more background on why this is, see this StackOverflow post.

Because of this, every generic type in System.Collections.Immutable includes a factory class of the same name which makes construction more convenient. For example:

// Using the generic class which requires explicitly-specified types
var l = ImmutableList<int>.Empty.Add(1);
// Using the factory class to use inferred types
var l = ImmutableList.Create(1);

The same trick is also used with System.Tuple.

Recommendations

  • If you author a generic class, consider also providing a factory class with generic methods to enable type inference.

Exploring the .NET Core Part 14: Inside Immutable Collections

February 13, 2015 Leave a comment

This is part 14 of my Exploring the .NET Core Series.

Back in 2013, Immo Landwerth and Andrew Arnott recorded a Going Deep video called Inside Immutable Collections which describes how and why System.Collections.Immutable is built the way it is. It’s great background material to understand System.Collections.Immutable.

Exploring the .NET Core Part 13: ImmutableList is an AVL Tree

January 13, 2015 Leave a comment

This is part 13 of my Exploring the .NET Core Series.

Most implementations of IList, including System.Collections.Generic.List<T>, are dynamic arrays. System.Collections.Immutable.ImmutableList<T> is different — it is an AVL tree. This results in significantly different performance characteristics:

  List<T> ImmutableList<T>
Indexing O(1) O(log n)
Append O(1) average, O(n) worst-case O(log n)
Insert at arbitrary index O(n) O(log n)
Remove O(n) O(log n)
Memory layout Contiguous for value types Non-contiguous

The data structure behind ImmutableList was likely chosen so that modifications to the list are non-destructive and require minimal data copying.

Here’s a visual representation of what List and ImmutableList look like behind the scenes:

List<T> ImmutableList<T>
List<int> l = new List<int>();
Array0
ImmutableList<int> l = ImmutableList.Create<int>();
Empty
l.Add(1);
Array1
l = l.Add(1);
1
l.Add(2);
Array2
l = l.Add(2);
2
l.Add(3);
Array3
l = l.Add(3);
3
l.Add(4);
Array4
l = l.Add(4);
4

Exploring the .NET Core Part 12: Aggressive Inlining

January 5, 2015 Leave a comment

This is part 12 of my Exploring the .NET Core Series.

In C++, the inline keyword allows a developer to provide a hint to the compiler that a particular method should be inlined. C# has the identical ability but uses an attribute instead:

internal class SecurePooledObject<T>
{
    ....

    [MethodImpl(MethodImplOptions.AggressiveInlining)]
    internal bool IsOwned<TCaller>(ref TCaller caller)
        where TCaller : struct, ISecurePooledObjectUser
    {
        return caller.PoolUserId == _owner;
    }
}

In System.Collections.Immutable, this attribute is used highly selectively — only once, in fact.

Recommendations

  • In rare cases, consider using MethodImpl(MethodImplOptions.AggressiveInlining) to suggest to the .NET runtime that a particular method should be inlined.

Exploring the .NET Core Part 11: Code Contracts

December 17, 2014 Leave a comment

This is part 11 of my Exploring the .NET Core Series.

In 2008, Microsoft Research published Code Contracts, which provide a language-agnostic way to express coding assumptions in .NET programs. The assumptions take the form of pre-conditions, post-conditions, and object invariants.

Here is a simple example of code which uses Code Contracts:

using System.Diagnostics.Contracts;

public class StringUtils
{
    internal static string Append(string s1, string s2)
    {
        Contract.Requires(s1 != null);
        Contract.Requires(s2 != null);
        Contract.Ensures(Contract.Result<string>() != null);
        return s1 + s2;
    }
}

Code Contracts assertions are not limited to runtime enforcement. They may instead be enforced by compile-time static analysis. For example, it is very simple to annotate methods with Code Contracts, set up a continuous integration (CI) server to perform static analysis, and fail the build if there are any failed assertions. This gives us the best of both worlds: a guarantee our code enforces our assumptions with essentially zero runtime penalty.

By design, Code Contracts are not enforced unless the appropriate tools are configured to check them. For this reason they are usually not appropriate for parameter validation on public methods; there is still the need for traditional parameter validation. However you can combine traditional parameter validation on public methods with Code Contract-based assertions for internal methods as follows:

public class StringUtils
{
    // This is the method that external callers would use, as we can't
    // guarantee they will enforce Code Contract checking
    public static string Append(string s1, string s2)
    {
        if (s1 == null)
            throw new ArgumentNullException("s1");
        if (s2 == null)
            throw new ArgumentNullException("s2");
        // The Code Contracts static analyzer is quite clever and it
        // realizes that the AppendInternal pre-conditions are satisfied
        // due to the above two statements, so no Contract.Assert()s
        // are required.
        return AppendInternal(s1, s2);
    }

    // This is the method that other code in this assembly would use,
    // as we can guarantee that this code is checked at compile-time
    // with the Code Contracts static analyzer
    internal static string AppendInternal(string s1, string s2)
    {
        Contract.Requires(s1 != null);
        Contract.Requires(s2 != null);
        Contract.Ensures(Contract.Result<string>() != null);
        return s1 + s2;
    }
}

You can write Code Contracts assertions with just the .NET 4.5 SDK installed, but they will not be enforced. To enforce them at compile-time within Visual Studio:

  1. Install the Code Contracts for .NET extension using NuGet:
    Code Contracts for .NET
  2. Restart Visual Studio
  3. Open up the Project Properties dialog and click on the Code Contracts tab
  4. Click “Perform Static Contract Checking”
    Code Contracts Project Properties

System.Collections.Immutable uses Code Contracts only to express post-conditions and object invariants, never to validate pre-conditions. This is presumably to integrate well with client code which uses Code Contracts.

For more information on Microsoft Code Contracts, please read:

Recommendations

  1. Liberally annotate all methods with Code Contracts post-conditions and object invariants.
  2. If you can guarantee that a method will be called only by code that you control (e.g. internal methods), use Code Contracts to enforce pre-conditions. If you cannot, use traditional parameter validation.
  3. Integrate Code Contracts static code analysis into your CI pipeline, and fail the build on any warnings.
Follow

Get every new post delivered to your Inbox.

Join 36 other followers