Typemock Isolator: A CLR Interception Approach to Unit Testing

Recently I have contacted Typemock and I was offered a license of Typemock Isolator, their flagship tool, in support of my OSS project LINQBridgeVS. Typemock Isolator is a viable tool to incorporate CLR interception for unit testing in .NET.

CLR is the acronym for Common Language Runtime and it is the virtual machine that manages the execution of .NET programs. Typemock Isolator intercepts CLR calls at run-time and offers a fluent API to fake almost anything: static and sealed classes, instances, virtual or non-virtual synchronous and asynchronous methods, P-invoke calls, private and static constructors and also LINQ queries.  Typemock Isolator comes as a Visual Studio extension compatible with Visual Studio from 2010 through 2017 with any .NET Framework version up to 4.7.2 and incorporates four different components: 

  • Typemock Isolate contains the Typemock Isolator Mocking API, a fluent API to fake and mock objects based on the Arrange-Act-Assert pattern, and Insight which gives detailed information about the behaviour setup during test debugging. 
  • Typemock Suggest suggests and creates tests, for either NUnit or MsTest, for methods and classes in legacy or mainstream code that have partial to no test cover. 
  • Typemock SmartRunner is the built-in test runner and identifies and runs only the impacted tests after the solution’s tests have run for the first time. This includes all modified tests and those tests that need to run because the code they test has changed. 
  • Typemock Coverage is a code coverage tool that displays code coverage for tests, methods, all classes or only those that have recently changed or the entire solution. It also display real-time code coverage while code is written.

Licensing System

Typemock Isolator for .NET has three different types of licenses which are offered in two versions: annual or perpetual. The price starts at €479 pa or (€899 perpetual) for Isolator Essential which comes with the mock framework, the test runner and method coverage. Isolator Complete adds Auto-generated test suggestions and it costs €799 pa (€1599 perpetual). The last one is Isolator for Build Server which adds support to run tests on up to five machines and comes at €1119 pa (€2499 perpetual) . For more information visit the pricing page. Typemock is free for MVPs and there is also support for open source projects, although not directly advertised through their website. If you’re interested in having a license for your open source project get in contact with them through the contact us form and send a brief description of your project.

Introduction

Writing unit and integrations tests is a vital part of the software development life-cycle. It is often underestimated and left as the last part of the development. Achieving an extended test coverage is extremely important for the creation of a reliable and stable product. Techniques and principles from Test Driven Development could be used by teams to make the creation of tests easier.

Reality is often different though. It is a rare opportunity to work on a brand new project where both the design and the development process can be decided from the beginning. Often enough a team determined to follow TDD principles ends up not allocating enough time to hit the desired coverage or tests are not strictly written first. In such cases it is preferred to offload developers and delegate QA teams to write automation tests or to test an individual feature manually. Clearly this approach is not scalable and doesn’t guarantee stability over time. When code changes are not monitored by both unit and integration tests it is very hard to estimate and also to predict the impact that a specific change will have to other parts of the system. 

Unless TDD principles are followed and a robust and clean design is made from the very beginning, the process of writing tests in isolation becomes increasingly more difficult as the project evolves and cannot be achieved without proper (and often painful) refactoring.

The Limitation of Mock Frameworks

Mock object frameworks simulate objects’ behaviour. A mock is something that is setup as part of a test so that it returns an expected result. Mocks in a way are determined at runtime since the code that sets the expectations has to run before they do anything. As a rule of thumb mocks are used to ‘fake’ dependencies of a class. When a method or a class is tested in isolation, i.e. when a a unit test is written for it, dependencies to other systems should be mocked.

There are a lot of free open source mock framework for C#: MoqRhinoMocksFakeItEasy and NSubstitute just to name a few. There is also a built in Visual Studio version called Microsoft Fakes.

The aforementioned frameworks (except for Microsoft Fakes) have one peculiar aspect in common: they can only mock a class given its interface or its base class as long as the base class is inheritable and it declares virtual methods for the behaviours to be setup. 

Testing using the Proxy pattern

Sealed classes, static classes and non-virtual methods cannot be mocked with the proxy pattern approach most mock frameworks use. A proxy is a class functioning as an interface to something else. The proxy has to implement the same interface as the Subject so that the Client doesn’t realise that it is using a proxy. Mock frameworks in fact create proxies at run-time based on interfaces or abstract classes and they are able to override any virtual method. 

The Proxy Pattern
The Proxy Pattern class diagram.
public class Auth
{
   public int AuthStatus { get; private set; }
   public virtual bool IsAuthValid(string user, string pwd)
   {
      return false; //this could be an external call to an auth server
   }

   public void AuthenticateUser(string user, string pwd)
   {
      if ( IsAuthValid(user, pwd) )
           AuthStatus = 10;
   }
}

 // Arrange
 var moqAuth = new Mock();
 moqAuth
   .Setup(p => p.IsAuthValid(It.IsAny<string>(), It.IsAny<string>()))
   .Returns(true);
 // Act
 moqAuth.Object.AuthenticateUser("myUser", "myPwd");
 // Assert
 Assert.IsTrue(moqAuth.Object.AuthStatus == 10);

In the arrange section of the snippet above, Moq creates a proxy that inherits from the class Auth. During the setup, a call to IsAuthValid is overridden so an expected value is returned by default when the method is invoked. The method IsAuthValid however must be virtual, otherwise Moq won’t be able override it and will raise an exception. 

Testing using CLR Interception

Let’s see how the test and the class Auth could be re-written using the CLR interception approach adopted by the Typemock API:

public sealed class Auth 
{ 
   public int AuthStatus { get; private set; } 
   public bool IsAuthValid(string user, string pwd) 
   { 
     return false; //this could be an external call to a server or db 
   } 

   public void AuthenticateUser(string user, string pwd)
   { 
      if ( IsAuthValid(user, pwd) )            
         AuthStatus = 10; 
   }
}

//Arrange
var auth = new Auth(); 
Isolate 
 .WhenCalled(() => auth.IsAuthValid(string.Empty, string.Empty)) 
 .WillReturn(true);

//Act
auth.AuthenticateUser("myUser","myPwd");

//Assert 
Assert.IsTrue(auth.AuthStatus == 10);

I changed the class Auth to be sealed instead and I also made the method IsAuthValid non virtual. Classes should either be designed for inheritance or prohibit it. There is a cost to designing for inheritance, and unless there is a good reason, it should be avoided.

In the test code above there is no mock created. The behaviour is overridden directly on the instance of the object. Typemock intercepts the call to the object’s method at runtime and redirects it to return the value setup instead. If I wanted to make the method private it would also require a small change in the test:

Isolate.NonPublic.WhenCalled(auth, "IsAuthValid").WillReturn(true);

Private or non-virtual methods cannot be tested using a proxy based mock framework. The alternative is using Microsoft Fakes, which I mentioned earlier, and it has similar features to Typemock Isolator.
Microsoft Fakes has support for either proxy-based mocks, which are called stubs, and method interception mocks called shims, which diverts method calls at run time. With Microsoft Fakes every assembly needs to be faked manually. For example if you need to generate a mock for a .NET system type, like DateTime, then a Fake for the System.dll must be created and referenced in the test project. Microsoft Fakes has also some other limitations. Please refer to this link for a detailed comparison of Microsoft Fakes vs Typemock.

Improved design using the Bridge pattern

At this stage one could argue that the current design for the Auth class is poor and a better one would be to abstract away the dependency that authenticates the user from the Auth class.

The Bridge Pattern class diagram.

The Bridge pattern, initially designed by the Gang-of-four, is the best structural pattern to decouple an abstraction from its implementation so that the two can vary independently. It removes the compile-time binding and the implementation can be selected at run-time. Let’s use the Bridge pattern in the Auth class, and let’s add two more dependencies for logging and for db access:

public interface IAuthSystem
{
   bool IsAuthValid(string user, string pwd);
}

public interface ILogging
{
   void Log(string msg);
}

public interface IRepository
{
   IEnumerable<T> Get<T>();
}

public sealed class Auth
{
  private readonly IAuthSystem _authSystem;
  private readonly ILogging _logging;
  private readonly IRepository _repository;

  public int AuthStatus { get; private set; }
  
  public Auth(IAuthSystem authSystem, ILogging logging, IRepository repository)
  {
     _authSystem = authSystem;
     _logging = logging;
     _repository = repository;
  }

  private bool FindUser(string userName)
  {
     var result = from user in _repository.Get<User>()
                where user.UserName.Equals(userName)
                select user;

     return result.Any();
  }
  public void AuthenticateUser(string user, string pwd)
  {
       _logging.Log($"User logging in {user}");

      if ( FindUser(userName) && _authSystem.IsAuthValid(user, pwd))
         AuthStatus = 10;
  }
}
//Moq
  //Arrange
  var authSystem = new Mock<IAuthSystem>();
  var logging = new Mock<ILogging>();
  var repository = new Mock<IRepository>();
  
  authSystem
    .Setup(p => p.IsAuthValid(It.Is<string>(s => s == "Coding"), It.Is<string>(w => w == "Adventures")))
    .Returns(true);

  repository
    .Setup(p => p.Get<User>())
    .Returns(new List<User>{ new User{UserName = "Coding"}});
  
  //Act
  var auth = new Auth(authSystem.Object, logging.Object, repository.Object);
  auth.AuthenticateUser("Coding", "Mock");

  //Assert
  Assert.IsTrue(auth.AuthStatus == 10);

//Typemock
  //Arrange
  var auth = Isolate.Fake.Dependencies<Auth>();
  
  var fakeAuthSystem = Isolate.GetFake<IAuthSystem>(auth);
  var fakeRepository = Isolate.GetFake<IRepository>(auth);
  
  Isolate
     .WhenCalled(() => fakeAuthSystem.IsAuthValid("Coding", "Adventures"))
     .WithExactArguments()
     .WillReturn(true);

  Isolate
     .WhenCalled(() => fakeRepository.Get<User>())
     .WillReturnCollectionValuesOf(new List<User> {new User {UserName = "Coding"}});

   //Act
   auth.AuthenticateUser("Coding", "Adventures");
   //Assert
   Assert.IsTrue(auth.AuthStatus == 10);

With this new design it is much easier to mock away the dependency to IAuthSystem, ILogging and also IRepository. In Moq a mock must be created, setup and an instance passed to the constructor of Auth for each dependency declared in the constructorIn Typemock API there is a shortcut instead to fake all dependencies declared in a constructor using the Isolate.Fake.Dependencies<T>() method. With Isolate.GetFake<T>(object) the corresponding faked dependency can be retrieved to setup behaviours on it:

Auth authObject = Isolate.Fake.Dependencies<Auth>();

IAuthSystem fakeDependency = Isolate.GetFake<IAuthSystem>(authObject);
IRepository fakeRepository = Isolate.GetFake<IRepository>(auth);

Mocking static methods

One thing I always wanted to do freely is using static methods or static classes and also have the ability to override behaviours without having to wrap dependencies with an abstraction layer. For example in my OSS project I have a class called CommonRegistryConfigurations that has a lot of helper methods to access the Windows registry. I always refused to create an abstraction layer that wrapped the Registry class to access the windows registry. I  would eventually end up having parts of my code that rely on these helper class un-tested. Typemock supports faking static methods on static classes, so I was able to setup my object behaviour to mock the call to the static method that access the registry:

public static bool IsSolutionEnabled()
{
   string keyPath = "aKey";

   using (var key = Registry.CurrentUser.OpenSubKey(keyPath))
       return (bool)key.GetValue("myValue");
}

// Test 
Isolate
  .WhenCalled(() => 
     CommonRegistryConfigurations.IsSolutionEnabled())
  .WillReturn(true);

There is one important caveat to keep in mind though. When Isolate.WhenCalled is used to define a fake behaviour on static methods and/or static classes, the behaviour has a global scope. This means that the setup will redirect calls from other unit tests also. It is in fact good practice to mark the test class with a specific attribute available in the Typemock API called IsolateAttribute which makes sure all behaviors are reset at the end of a test method.

Typemock and LINQ Queries

Abstracting away the access to a database is no easy task. One common route is to implement the Repository pattern to abstract away the data access logic, so unit tests can use stubs or mocks as implementations of the IRepository interface. Another solution, if an ORM like Entity Framework is used, could involve faking the DbContext itself instead of wrapping everything with the Repository pattern. There’s a good article here with a thorough explanation on the topic. 

A feature that has really caught my attention is the ability to fake the result of a LINQ query.  Let’s look at the following code:

public bool FindUser(string userName)
{
   var result = from user in _repository.Get<User>()
                where user.UserName.Equals(userName)
                select user;

   return result.Any();
}

// Typemock
 //Arrange
 var auth = Isolate.Fake.Dependencies<Auth>();
            
 Isolate
    .WhenCalled(() => from user in Enumerable.Empty<User>()
                    where user.UserName.Equals(string.Empty)
                    select user)
    .WillReturnCollectionValuesOf(new List<User> { new User() });
 //Act
 bool userExists = auth.FindUser("Adventure");

 //Assert
 Assert.IsTrue(userExists);

In the snippet above, the method FindUser fetches users from a repository using a LINQ query. Instead of changing the behaviour of the method, or faking the repository, it is also possible to fake the result of the query itself. It’s a bit obscure to me though the criteria the API uses to swap the original LINQ query with the one setup in the unit test. I looked up at their official documentation on the topic, but I couldn’t found anything that hints at how linq expressions are swapped around. Regardless of the gore details this feature is very powerful.

Build Server Integration

Typemock Isolator integrates with the several famous build and continuous integration servers like CruiseControl.NET, Jenkins CI, TeamCity and Team Foundation Server, as well as custom build servers. There is a good bit of documentation on their website about Server-side integration. I personally use Appveyor, a free continuos integration solution for Windows and Linux that integrates nicely with GitHub.

Typemock doesn’t integrate with Appveyor as easily as it does with the official supported build servers. Tests that use CLR interception must be run by TMockRunner, a utility part of Typemock Isolator that launches external programs like code coverage tools or a unit test runner like MSTest.

There is some documentation that explains how to run TMockRunner and also how to install it on a custom build server. I’d have preferred to have everything in a single page (or section) so I didn’t have to jump around to find what I needed.

It took me a while to figure out a powershell script that worked nicely with Appveyor. Appveyor runs any custom script with low privileges, thus access to the windows registry is forbidden. TMockRunner needs to access the registry for the initial setup, so I had to come up with a hack to set some specific environment variables to trick TMockRunner into thinking there was no windows registry available. Luckily the support team in Typemock offered a better solution by suggesting to elevate the privileges of my custom powershell script.

I’ll share with you both solutions, in case you need to setup TMockRunner in Appveyor like I did. In the first solution I had to setup the following environment variables in my yml file:

TM_INSTALLDIR: c:\PathToTMockRunner\ 
TMOCK_NO_REGISTRY: 0x1 #this actually tells TMockRunner
there's no registry available
TM_LICENSE:
secure: the encrypted licence number
TM_COMPANY_NAME:
secure: the encrypted company name

Which lead me to this powershell script:

TMockRunner.exe 
   -deploy AutoDeployFolder 
    vstest.console.exe "mytest.dll" "mytest2.dll" 
    /logger:Appveyor

The proper fix though involved elevating the privileges of the powershell script. Then the setup of those four environment variables was no longer needed:

$args = TMockRunner.exe 
   -deploy AutoDeployFolder 
   -register yourLicense vstest.console.exe 
   "test.dll" "test2.dll" /logger:Appveyor

Start-Process powershell -Verb runAs -ArgumentList '$args'

Conclusions

The ability to override methods and classes everywhere, and also in some .NET  classes, is very powerful. It enable developers to write unit tests in isolation in both legacy code where there is none to very little degree of freedom and also in mainstream code. Such freedom shouldn’t be an encouragement to write poorly designed software and TDD (or BDD) should always be the preferred approach when possible so that tests are guaranteed to be part of the product from the very early stages.

The other side of the coin is that a software architecture should always be designed around the problems it solves and the tasks it performs. Being forced to declare methods virtual, avoid sealed or static classes or create a lot of interfaces to abstract any dependency, if not for some technical limitation of mock frameworks, is in my opinion unnecessary. 

On the cons Typemock is not yet compatible with .NET Core and I guess the reason is the different common language runtime (the CoreCLR) .NET Core uses. Also Typemock Suggest needs to be disabled or it will crash if you’re working on a .NET Core project.

I also struggled a bit to setup Typemock in Appveyor, adding the relevant steps I highlighted in this article in their official documentation would be of great help. Another improvement is keeping the Visual Studio extension in sync with the version of the Typemock API. If they mismatch, e.g. you update the Typemock API to a newer version using NuGet but not the extension then an exception is thrown when unit tests are run. 

I really had fun creating tests on my OSS project using Typemock.
For long time I didn’t have much test coverage and finally I was able to increase it in relative short time without doing a huge refactor. The fluent API is very intuitive and easy to use. I hope Typemock will add support for .NET Core in the near future.

This is it, I hope you enjoyed reading this article, see you soon!

NDepend: A Static Analyser for .NET and .NET Core

NDepend is static analyser for .NET and .NET Core. Recently I was contacted by its creator, Patrick Smacchia, who kindly offered a license in support of my OSS project LINQBridgeVs.

Overview

NDepend is a tool mainly targeted for software architects who want to have a deep insight into their projects. NDepend gathers data from a code base and includes code quality metrics, test coverage statistics, assembly dependencies, evolution and changes, state mutability, usage of tier code, tech debt estimation and more. Another interesting feature is the ability to write custom rules using a domain specific language called CQLinq, which is based on LINQ, C# and the NDepend API.

NDepend comes with tons of features and it feels overwhelming at first. It has a quite steep learning curve before getting familiar with it. However there is lot of documentation, both on the official website and also in App which helps a lot.

Licensing System

There are two types of licenses: per seat (€ 399.00) for developers that use the UI (or the stand-alone app), and per machine ( 799.00) for servers that integrate NDepend into their build process. This price model is probably not a problem for companies but it might be a for individual developers. Although it is not advertised on the website there is official support for MVP and open source projects. Microsoft MVP are eligible for a free personnal license. Get in touch at this email address mvp@ndepend.com.

Installation

NDepend does not have an installer, it comes in a zip file, but its setup and first activation are pretty straightforward. Check out the introduction video on how to install it and get started.

NDepend can be run either as a stand alone application, using the executable VisualNDepend or within Visual Studio, by installing the extension (support for 2012 through 2017). There are also two console applications:

  • NDepend.Console is the command-line version of NDepend and can be used to automate the report generation using a CI server. NDepend has built-in integration with TeamCity, FinalBuilder, TFS and CruiseControl.NET
  • NDepend.PowerTools shows how to make the best out of the NDepend API syntax. It contains a lot of examples for code rules checker, code diff reporter, handy development tools, build process checker, etc.

First Impressions

I’ve been using NDepend for quite a while now and honestly it took me some time to get my head around the UI and the tons of features this tool is shipped with. The amount of information is at first overwhelming, and in my opinion the UI at times contains a lot of information. However after a few hours of usage I felt I was more confident to use it and it became easier to search and find what I needed.

The Visual Studio integration is handy, as you don’t have to leave Visual Studio. New reports are generated after successful build and it’s possible to compare metrics across different analysis. Having a second monitor is advised though as it makes it tidier and easier to keep the NDepend window on one monitor and avoid annoying switching between windows.

One feature that caught my eye is the technical debt estimation (TB). The TB metaphor was coined in 1992 by Ward Cunningam, a design pattern and extreme programming pioneer. Think of TB as a financial debt. It must be paid at some stage and it accumulates with other debts, generating interests and prolonging the time needed to pay it back.

I’m sure at some stage in every software developer’s carrier there grows an urge to refactor the code and reality is there is never time for it. Unfortunately strict deadlines or difficult targets lash back leading to hacks, quick fixes and poor design decisions in favour of quicker releases to satisfy customers. Technical debt is often underestimated as it is seen as a cost that doesn’t produce an immediate benefit. “It’s just code!” as they might say.

The technical debt estimation in NDepend produces an estimate, expressed in man-hour to fix code issues found. Settings can also be changed for the average cost of man-hour of development, the currency, the estimated number of man days to develop 1000 logical lines of code, scale debt rating percentage etc in the debt settings. The ability to calculate the cost of technical debt and monitor it over time is a great advantage especially to communicate it to non technical people and justify how a refactor or a new re-design could save a lot of time and money over time.

DebtSettings

Smart Technical Debt Estimation – Configuration

Under the hood NDepend uses code rules, i.e. code metrics, to calculate debt and are grouped by: application, assemblies, namespaces, types, and methods. When a rule is violated then there could be a code smell, poor object oriented design, immutability and/or threading issues, naming convention consistency across types, methods and namespaces, source file organisation and so on.

NDepend and LINQBridgeVs

LINQBridgeVs is a Visual Studio extension that transmits debugging variables from VS to LINQPad. I’ve been working on it for quite some time now but the code base is not huge. There are over 1700 lines of code over 6 assemblies. Let’s have a look at the NDepend dashboard:

Dashboard

NDepend Dashboard – I got a B!

The dashboard page has several panels on top and trend graphs on the bottom or on the side if your monitor has enough resolution. Panels contain info about code metrics, technical debt estimation, test code coverage, method cyclomatic complexity, quality gates and violated rules. NDepend also supports trend metrics, which is the ability to monitor the evolution of the project by comparing metrics across different analysis. Trend graphs can be found below the metric panels:

TrendGraphs

Trend Graphs

Every number in the dashboard is interactive. Clicking on any of them generates a reports, which is essentially a specific CQLinq query run in a temporary preview tab (like the temporary preview documents in Visual Studio), which can be found in the “Rule Editor Window”, i.e. the NDepend query editor.

ViolatedRules

Rules Violated Tab in the Rule Editor Window

Tabs are divided in two sections: the description on top and the result of the query below in a data grid form, which is highly interactive. It’s possible to switch between description and source code view to personalize the corresponding query:

ViolatedRules_CQLINQ

Rules Violated – CQLinq Source

The result is shown in the grid at the bottom. For each rule there are the number of issues:

  • Debt: the estimated effort to fix the issues.
  • Annual interest: The amount of time needed required to fix the issue if left unfixed.
  • Breaking point: it represents the time-point from now to when the estimated cost-to-fix the issue will reach the estimated cost to leave the issue unfixed. It is calculated by dividing the estimated debt by the annual interest. The breaking point is inversely proportional to the Return On Investment of fixing an issue. Thus the lower the breaking point, the higher the ROI.

Based on this assumption I modified the query above for violated rules to filter only those that have a breaking point within 1 and 365 days:

// Rules violated
from r in Rules
where r.IsViolated() && r.BreakingPoint() < TimeSpan.Zero && r.BreakingPoint() <= TimeSpan.FromDays(365)
orderby r.BreakingPoint().TotalMinutes ascending
select new
{
r,
Issues = r.Issues(),
Debt = r.Debt(),
AnnualInterest = r.AnnualInterest(),
BreakingPoint = r.BreakingPoint(),
Category = r.Category
}

The grid in the image below shows 19 rules that need to be addressed, two of which are flagged as critical. In NDepend critical rules represent high priority rules that must never be violated. They are marked with a red triangle over the exclamation mark.

ViolatedRulesResult

Hovering the mouse over a rule or clicking on it opens a floating panel that contains a thorough description of the issue and often link to a discussion page on the topic. Double clicking on a rule opens instead its corresponding CQLinq source.

InfoRuleViolatedThe two violated critical rules are: “Avoid having different types with the same name”, and “Avoid non-readonly static fields”.

I only agree with the first rule partially. I wouldn’t want to have a huge number of different types with the same name as that in fact could easily generates confusion (and probably is a sign of bad design). However if there are only a few types with the same name I believe it’s not going to be an issue. It is not uncommon to have shared names across types in different domains. For instance, in the .NET Framework, the class Timer is defined either in the System.Windows.Forms.Timer and also in System.Threading.Timer namespace. The former is a timer suitable for Windows Form environment and it runs on the main thread as it is often used to modify properties on a form. The latter instead is a thread timer and provides a mechanism for executing a method on a thread pool’s thread at specified intervals. The two classes, despite the same name, do similar things in a very different way. One could argue that the two timers could be called with different names, e.g. FormTimer and ThreadTimer but the disambiguation is better managed at namespace level.

Conditions for a rule to be violated can be changed though in its corresponding CQLinq source. For example I changed the minimum number of types before the rule is considered violated and reported:

DifferentTypesSameNAme_2

Increasing the minimum number of types allowed with same name.

The second critical rule “Avoid non-readonly static fields” is a warning for an OOP design flaw. Static fields are states shared with every instance of the class where they are declared. If they are mutable then extreme care must be taken to initialise and to reset them correctly.  In a multi-threaded environment mutable static fields are not thread-safe. Race conditions cannot be avoided, and in this scenario bugs could be very hard to trace and even to replicate. It is important to make static fields immutable and private. The rule however suggests to declare them as readonly but that by itself doesn’t enforce complete immutability. Readonly guarantees that the instance can only be assigned once during the construction and it cannot be changed during its lifetime in the AppDomain. For instance, in a readonly List or a Dictionary, values can still be added or removed. Clearly it’s up to us to “protect” those fields from being modified by enforcing immutability. To read more on the topic a good explanation can be found here.

In my specific case I declared a public static string in a class (I know it’s horrible) called RavenWrapper. Such class has been designed to be a Singleton that uses lazy instantiation.  I wrote this class as a separation layer for the Raven SDK, a library that sends errors to Sentry (an open source error tracking system). More on the singleton later.

RavenWrapper

6 methods use the public static field VisualStudioVersion directly.

The public static string represents the version of the Visual Studio instance where LINQBridgeVs is running on. For “convenience” (truth is laziness) I set this field once outside the class so that I don’t have to pass the vs version all the time as a method parameter. The choice of a singleton class doesn’t help either. I can’t overload the constructor to do the most obvious thing: make the field private, non-static and read-only and let the constructor initialise it.

In fairness this class has too many design flaws and issues, so I decided to isolate it in a query and see what NDepend thinks about it:

RavenWrapper_rules

Violated Rules in Raven Wrapper

As I imagined this class is violating many more rules than I expected: immutability, visibility, OOP design and naming convention. Let’s have a look at the class code:

public sealed class RavenWrapper {
 private static Lazy _instance = new Lazy(() => new RavenWrapper());

 public static RavenWrapper Instance => _instance.Value;

 private RavenClient _ravenClient;
 public static string VisualStudioVersion;

 private RavenWrapper() { /*init stuff*/ }

 public void Capture(Exception exception, ErrorLevel errorLevel, strIng message){ }
}

Looking back at it now, I realise there was no real benefit in having this class as a singleton. I should probably have made the RavenClient static, readonly and private. Even in that case there is no advantage really. RavenClient doesn’t open or reserve a connection when it is instantiated, so there wouldn’t’ be any benefit in “caching” its instance.

In my first refactor attempt to the class I changed the way the static instance of the object is created using a method instead of a property so that I can pass along the vs version as a parameter to the constructor. This class is still designed as a singleton:

private static RavenWrapper _instance;
public readonly string _visualStudioVersion;

public static RavenWrapper Instance(string vsVersion)
{
   if (_instance == null)
         _instance = new RavenWrapper(vsVersion);
   return _instance;
};
private RavenWrapper(string vsVersion)
{
   _visualStudioVersion = vsVersion;
}

When I ran another analysis on the solution I surprisingly found that the debt went up by 2%. Also 4 more rules were violated (1 of which was critical). It didn’t seem the change I made to the class was the right one.

NewDebt

~2% Tech Debt Increase.

Let’s see again what NDepend thinks about RavenWrapper now, and how many rules I fixed/broke.

RavenWrapper_rules_first_change

RavenWrapper – More violated rules.

Despite the number of violated rules hasn’t changed, the total cost, the debt and annual interest has halved just by resolving the first critical rule. Although I am not quite there yet, I think I’m on the right track.

Interestingly NDepend now recognises the RavenWrapper uses the singleton pattern while it didn’t when the it was implemented using lazy instantiation. The singleton is considered by many an anti-pattern and there can be found a lot of different opinions around the web. On the corresponding violated rule there’s an interesting link to an article that treats the topic extensively.

In my third refactor attempt I decided to remove entirely the singleton implementation. This is what I came up with:

public sealed class RavenWrapper
{
    private readonly RavenClient _ravenClient;

    private readonly string _visualStudioVersion;

    public RavenWrapper(string vsVersion)
{
_visualStudioVersion = vsVersion;
}
}

Only now I understand how complicated and unnecessary the original design was. The simplest solution is most of the time the best. When I ran again the query I finally got a good result:

final_Raven_wrapper

RavenWrapper – Two violated rules only.

The “API breaking changes Methods/Fields” rule warns that the current API has changed since the baseline and a method or a field has been removed. These warnings are very important for SDK development because a change in the API can break that rely on them. This is not relevant to me though as this is a Visual Studio extension and not a library like JSON.NET or Moq for instance.

Final Thoughts

It’s been fun to play around with NDepend. I brushed up my skills on code metrics, OOP design practices and code smells. Although it is a software targeted for skilled software architects I also believe it could be a great learning opportunity for mid and senior developers.

I can’t of course say if this software is the right one for you as it very much depends on your needs, budget and size of your project.

NDepend has a lot of features and it’s fully configurable although the first few hours will be a bit of a pain. NDepend is very broad it might take a long time to master it. There are plans though to release with the next version of NDepend a simplified beginners VS menu, that can be switched to the actual one at any time. Also a series of 2 minutes intro video will be released soon for each feature.

I hope you enjoyed this article. Try NDepend if you get a chance, you can download a 14-day trial evaluation here. If you instead want a boost during your debugging sessions try LINQBridgeVs, and let me know what you think in the comments below!

See you soon!

Unity (Pre 5.5) Memory Safe Enumerators with C5 Generic Collection Library

DISCLAIMER: The topic treated in this article is only valid for version of Unity up to 5.4

Long time ago I posted an article on how disposable value types were treated in Unity and why they used to generate unnecessary and unwanted garbage. It emerged that in the official Mono compiler as well as in the Microsoft C# compiler (but not in Unity) a violation of the C# specification lead to an optimisation of disposable structs within a using statement. Disposable value types are used in C# mainly to implement iterator blocks, which are used to iterate over collections. Two years ago I  decided to fix this issue by re-implementing the enumerators in a library called C5 which is a project for generic collection classes for C# and other CLI languages. However with the release of Unity 5.5 back in March 2017 version 4.4 of the Mono C# compiler was shipped and finally this issue was properly fixed and became history.

This solution is not relevant anymore 🙂 unless you use an old version of Unity but I would still like to share with you the solution I came up with before the release of the new Mono compiler.

C5 implements a lot of data structures not provided by the standard .NET Framework, such as persistent trees, heap based priority queues, hash indexed array lists and linked lists, and events on collection changes. The source code is available on GitHub and MIT license makes you free to modify and re-distribute it if you want. I started my journey in creating my own enumerator implementation for the main collections (ArrayList, DictionaryHash, SortedDictionary etc) and I came up with the idea of a “reusable” enumerator.

With this approach only one enumerator instance per collection iterated is used at a time. Naturally this has some limitations. For example, multiple iterations of the same collection, multithread access and LINQ will not work.

To accommodate all the cases I implemented three memory models called:

  1. Normal: An enumerator is created anytime the collection is iterated. This is the normal behaviour expected and thus is not memory safe, but supports multiple iterations, multithread and LINQ.
  2. Safe: An enumerator is created once and then re-used. This approach doesn’t generate garbage. However, if the collection is iterated using nested loops or accessed by multiple threads, a new enumerator is created. The collection will save memory unless it is forced not to do so.
  3. Strict: An enumerator is created only once. This approach doesn’t generate garbage at all cost.  if the collection is iterated using nested loops or accessed by multiple threads an exception is thrown.

The memory model is implemented as an enum and it is passed to the constructor. For example:

   HashSet<inta = new HashSet<int>(MemoryType.Strict);

Screen Shot 2016-03-02 at 14.36.38

Figure 1 – MemoryType.Normal – 56 bytes of garbage every frame

Figure 1 and 2 shows two different scenarios: in the former garbage is generated by iterating over an ArrayList while in the latter no garbage is reported by the memory profiler.

MemoryType.Normal replicates the normal behaviour. The amount of garbage generated depends really on the size of the struct that is used to iterate the collection, therefore its size can vary. Figure 2 shows instead that no garbage is generated when an ArrayList is iterated.

Screen Shot 2016-03-02 at 14.35.43
Figure 2 – C5 ArrayList with MemoryType.Safe – No garbage

This is possible by reusing the same enumerator. Although it is not shown, 56 bytes are allocated only the first time the collection is iterated.

 

Currently the garbage free memory model is implemented for the following collections:

  • ArrayList<T>
  • HashedArrayList<T>
  • SortedArray<T>
  • WrappedArray<T>
  • CircularQueue<T>
  • HashSet<T>
  • TreeBag<T>
  • HashBag<T>
  • HashDictionary<T>
  • TreeDictionary<T>
  • TreeSet<T>
  • LinkedList<T>
  • HasedLinkedList<T>
  • IntervalHeap<T>

This is the source code for the MemorySafeEnumerator:

 internal abstract class MemorySafeEnumerator<T> : IEnumerator<T>, IEnumerable<T>, IDisposable {
     private static int MainThreadId;
 
     //-1 means an iterator is not in use.
     protected int IteratorState;
 
     protected MemoryType MemoryType { getprivate set; }
 
     protected static bool IsMainThread {
         get { return Thread.CurrentThread.ManagedThreadId == MainThreadId; }
     }
 
     protected MemorySafeEnumerator(MemoryType memoryType) {
         MainThreadId = Thread.CurrentThread.ManagedThreadId;
 
         IteratorState = -1;
     }
 
     protected abstract MemorySafeEnumerator<TClone();
     public abstract bool MoveNext();
     public abstract void Reset();
 
     public T Current { getprotected set; }
 
     object IEnumerator.Current {
         get { return Current; }
     }
 
     public virtual void Dispose() {
         IteratorState = -1;
     }
 
     public IEnumerator<TGetEnumerator()
     {
         MemorySafeEnumerator<Tenumerator;
 
         switch (MemoryType) {
             case MemoryType.Normal:
                 enumerator = Clone();
                 break;
             case MemoryType.Safe:
                 if (IsMainThread) {
                     enumerator = IteratorState != -1 
                     ? Clone() 
                     : this;
                     IteratorState = 0;
                 }
                 else {
                     enumerator = Clone();
                 }
                 break;
             case MemoryType.Strict:
                 if (!IsMainThread) {
                     throw new ConcurrentEnumerationException("Multithread access detected! In Strict memory mode is not possible to iterate the collection from different threads");
                 }
 
                 if (IteratorState != -1) {
                     throw new MultipleEnumerationException("Multiple Enumeration detected! In Strict memory mode is not possible to iterate the collection multiple times");
                 }
 
                 enumerator = this;
                 IteratorState = 0;
 
                 break;
             default:
                 throw new ArgumentOutOfRangeException();
         }
 
 
         return enumerator;
     }
 
     IEnumerator IEnumerable.GetEnumerator() {
         return GetEnumerator();
     }
 }

Everything happens in the GetEnumerator() method. In normal mode the enumerator is always cloned while in safe mode the enumerator is cloned only for multithread access and/or multiple enumerations, otherwise the same instance is reused. The strict model optimise at all cost but throws an exception for the other cases.

Conclusions

This solution is clearly outdated and I’m glad that Unity has eventually adopted a proper version of the Mono compiler. However I had a lot of fun coding a hand-made solution, and it was also a good opportunity to dive into the nitty-gritty implementation of C5 and I learnt a lot about data structures. Next time I will remember to publish an article on time 😀

See you soon!

A Static Code Analysis in C++ for Bullet Physics

Introduction

Hello folks! I’m here again this time to talk about static analysis. If you are a developer with little to no knowledge on the subject this is the right article for you. Static analysis is the process of analyzing the code of a program without actually running it as opposed to dynamic analysis where code is analysed at run time. This process helps developers to identify potential design issues, bugs, to improve performances and to ensure conformance to coding guidelines. Continue reading “A Static Code Analysis in C++ for Bullet Physics”

Unity Mono Runtime – The Truth about Disposable Value Types

When I started making games using Unity, after almost 10 years of C# development, I was very concerned to acknowledge that foreach loops are highly avoided in Unity because they allocate unnecessary memory on the heap. Personally I love the clean syntax of a foreach. It aids readably and clarity and it also increases the abstraction level. However a very clear and neat explanation of the memory issue problem can be found in a blog article posted on Gamasutra by Wendelin Reich.

From Wendelin’s analysis it emerged that the version of the Mono compiler adopted in Unity has a different behaviour from Microsoft implementation. In particular enumerators, which are usually implemented in the .NET framework as mutable value types, are boxed by the compiler, causing an unnecessary generation of garbage. Boxing is the process of converting a value type (allocated on the stack) into a reference type, thus allocating a new instance on the heap.  Continue reading “Unity Mono Runtime – The Truth about Disposable Value Types”

Unity and Reflection – Optimising Memory using Caching on iOS

Summary

Reflection

I really love reflection. Reflection is a technique used for obtaining type information at run-time. It’s not only that, with reflection is possible to examine and change information of objects, to generate (technically to emit IL) new classes, methods and so on still at runtime. It’s a powerful technique but it is known, under certain circumstances, for being slow. If you are a game developer and you are targeting mobile devices (iOS or Android for instance) using Unity, you definitely want to preserve your memory and save precious clock cycles. Moreover, with AOT (Ahead of Time compilation)  IL cannot be emitted at run-time as it is pre-generated at compile time. Therefore a large part of reflection, e.g. expression trees, anonymous types etc., is just not available.

The Problem

Recently I have worked on a dynamic prefab serializer and I needed to use reflection to retrieve types from their string representations. In general to retrieve a type in C# you have three options:

  • typeof(MyClass), which is an operator to obtain a type known at compile-time.
  • GetType() is a method you call on individual objects, to get the execution-time type of the object.
  • Type.GetType(“Namespace.MyClass, MyAssembly”) gives you a type from its string representation at runtime.

Continue reading “Unity and Reflection – Optimising Memory using Caching on iOS”

Profiling CUDA on Tegra K1 (Shield Tablet)

Recently I have struggled a lot to profile a CUDA application on the Shield Tablet. If you were thinking “What the hell would you need a CUDA app for, on a tablet?” I would understand :D. CUDA it’s not for everyday use but can be very powerful.

As of now (Late 2015), the Shield has the most powerful mobile GPU on the market (Tegra Kepler architecture with 192 streaming processors). I decided to evaluate and profile physics algorithms using such architecture.

Reading through documentations, keynotes from GDC, and presentations I found out that is currently not possible to profile a CUDA application from an APK!

NVIDIA offers the Android Works package, previously called Tegra Android Development Pack. This package provides developers with a big suite of handy tools to debug, test and deploy applications on the Shield. Recently, I’ve found this presentation from the GPU Technology Conference in 2014 about profiling CUDA apps. In general, there exist several graphical and command-line tools, but only one is available for Android. See the image below:

Graphical and Command-Line Profiling Tools

Graphical and Command-Line Profiling Tools

As you see, for Android, you can only use nvprof. Nvprof is a command-line tool to profile CUDA applications and it will be explained in the next paragraph. If you look at the red rectangle at the bottom of the picture you will notice that CUDA APK profiling is not supported yet! I.e., if you have in your APK any CUDA kernel, or calls to any library that uses CUDA….you simply can’t profile it. Continue reading “Profiling CUDA on Tegra K1 (Shield Tablet)”

Deploying Assimp Using Visual Studio and Android NDK for Tegra Devices

Hello folks, welcome back to my blog, hope you are ready for a new adventure. This time I promise it is going to be an adventure with the capital A. I’ve been working on a finite element method algorithm using C++ (and later CUDA) to prove that the latest generation of mobile devices (more specifically the Kepler architecture in the Shield Tablet) is capable of running such complex algorithms.

The Shield is shipped with Android Kit-Kat 4.4 thus using C++ or Java and OpenGL ES 2.0 is not a problem…well not just yet 😀

Setting up the environment is not too difficult too. I used the Tegra Android Development Pack, that installs, all the tools you need to start developing on Android (including extensions for Visual Studio and the whole Eclipse IDE). After a few clicks you have everything up and running.

Summary

The Problem

I need to load 3D models. Albeit I could have written my own parser (which I think it could have been less painful) I decided to use Assimp instead. Assimp is a very handy library that can handle a plenitude of different file formats. I’ve used it extensively in all my projects so far. It supports Android and iOS (as it is stated on its GitHub page).

I read the doc a lot, but I found no easy way (well at least under Windows) to generate a Visual Studio solution (sorry I’m a Visual Studio addicted) to compile it using the Android NDK. I searched on the web for a long while and I found a couple of articles that explain how to compile Assimp for Android (this: Assimp on Desktop and Mobile and this other: Compile Assimp Open Source Library For Android). The procedure is quite troublesome, requires Cygwin under Windows and a lot of patience. Luckily in the second article mentioned above, the author posted a pre-compiled assimp 3.0 version lib with headers included.

Download Assimp 3.0 lib for Android here.

Having Assimp already compiled was truly helpful. It saved me a lot of time that I would have spent figuring out how to put everything together.

Here it comes the tricky part. Assimp was compiled as a shared library (an .so). To reference it is pretty easy. The include and the lib path have to be set and then the name of the library specified. Visual Studio doesn’t use the Android.mk (whereas Eclipse does I think) that tells the Ant build and the the apk builder how pack the apk, which local shared lib to include. It is to be done in the project’s properties instead.

After setting up the whole thing, the solution compiled, linked and the apk was created correctly. I was confident that Assimp would be deployed with the apk, but I soon found out it was not. Surprisingly I got this error instead on the tablet when I ran the application:

Unfortunately, NativeActivity has stopped…

Looking at the LogCat I found this error message too:

Error1

Figure 1

“java.lang.IllegalArgumentException: Unable to load native library: /data/app-lib/com.shield.fem-1/libShieldFiniteElementMethod.so”,  which told me absolutely nothing about the nature of the problem. Fortunately the only thing I knew I changed was the reference to Assimp. It was clear to me what was that the cause of the problem. But why and how wasn’t explained at all by the log files. It was easy to spot it though. I looked at the output window and libassimp.so (see Figure 2 below) was not included at all.

Output library list

Figure 2

The Solutions

I found  two solutions for this issue. I like to call them respectively  “The easy way”, and “The way of pain”. I had already added an external library (I had to use libpng for loading textures), but in that case it went smoothly because it was a static library. Static libraries are .a (or in Windows .lib) files. All the code relating to the library is in this file, and it is directly linked into the program at compile time. Shared libraries are .so (or in Windows .dll, or in OS X .dylib) files. All the code relating to the library is in this file, and it is referenced by programs using it at run-time, reason why it is not deployed with the apk unless explicitly told.

Way of pain

DISCLAIMER: This solution involves rooting your device, so I’m not responsible if warranty voids. Please do it at your own risk

This was my first attempt to shove in libassimp. By default all the libraries stored in /system/lib on the device are loaded automatically at startup, so it is very seamless. If any lib is there the running process can use it. I used the command adb shell, (adb is installed as part of the development pack)  which gave me access to the bash-like shell on the Tablet. As I was expecting Assimp was not in the system lib folder. My first idea was to upload manually the lib into /system/lib so I ran:

 adb push libassimp.so /system/lib

Unless your Android device is rooted and the /system mounted as read-write this is the message you will get:

Failed to copy ‘libassimp.so’ to ‘/system/lib/libassimp.so’: Read-only file system

The only solution as I said is to root your device first. This can be quite painful and it depends on your model. There are a few good guides around. Use google, take a cup of coffee and have a lot of patience. Personally to root mine (a Shield Tegra) I used this guide, and the app adbd Insecure available on google play,  that lets you run adbd in root mode once your device has been rooted.

At this stage I assume your Android friend is rooted so you can finally remount the system folder in order to add read-write permissions. Use this command:

adb shell
root@shieldtablet:/ # mount -o rw,remount /system

Later if you want you can restore its original read-only permission by executing:

adb shell
root@shieldtablet:/ # mount -o ro,remount /system

OK, at that stage I had permissions to do whatever I wanted with system so I was finally able  to upload Assimp. Execututing again the command adb push showed no error this time:

uploading assimp

Figure 3 – Upload has been successful!

At this stage I didn’t have to do anything really. Once the application starts it will load Assimp (and any other libs in there) automatically.

The Easy Way

I found out this easier solution only after I went through hell using the first painful approach (trust me it took me a while to understand how to root the device and which commands to run). Here you don’t need to root your device at all, but you will have to change your code a little bit to dynamically load Assimp (shared libs in general though). Let’s start!

First of all I didn’t know it was possible to upload shared libraries through Visual Studio (d’oh!). I didn’t find it written anywhere (well maybe I didn’t search well) but looking at my projects properties I found this:

project properties

Figure 4

In the Ant build it is possible to specify Native library dependencies! At this very stage I would imagine you laughing knowing what I went through with the “way of pain” 😀

Anyway, I set references to Assimp right here, look at figure 5:

project properties 2

Figure 5

Using this approach the shared library is built seamlessly into the apk! The only drawback is that it won’t be loaded automatically! For this  issue another little trick is needed. If you try to execute/debug your program now, you will likely get again the same error message as in Figure 1.

You need to load any shared library before your native activity. To do this a Java class is to be used. Something like:


package com.your.package;

public class Loader extends android.app.NativeActivity {
   static
   {
     System.loadLibrary("assimp");
   }
}

It is important that Loader.java goes under the folder src in your project and that it is wrapped in a folder structure that respects your package declaration (I know if you’re a Java guy it is evident for you, but I’m more a C#/C++ one so it took me again a while to figure it out 😛 ).

The last bit: change your AndroidManifest.xml android:hasCode must be equal to True and change the android:name in the activity tag from android.app.NativeActivity to Loader (i.e. the name of your Java class)


 <!-- Our activity is the built-in NativeActivity framework class.  This will take care of integrating with our NDK code. -->

That’s finally it!

Conclusions

I’m a total newbie with Android development and it’s been quite hard for me to figure out how to deploy a shared library in Visual Studio as it wasn’t very intuitive. A lot of examples I found online use command line scripts to compile and/or different IDEs. The most common approach is using an .mk file where properties, libraries etc are defined inside. Mk files are (apparently) completely ignored by VS so it wasn’t possible for me to use one.

I really hope this article can help you. I am looking forward to reading your comments, hoping that there are other simpler ways to achieve what I did today.

See you soon!

C++ Tail Recursion Using 64-bit variables – Part 2

In my previous post I talked about recursion problems in a Fibonacci function using 64-bit variables as function parameters, compiled using the Microsoft Visual C++ compiler. It turned out that while tail recursion was enabled by the compiler using 32-bit types it didn’t really when switching to 64-bit ones. Just as a reminder, Tail Recursion is an optimization performed by the compiler. It is the process of transforming certain types of tail calls into jumps instead of function calls. More about tail recursion here.

My conclusion was that tail recursion is not handled properly by the Visual C++ compiler and a possible explanation could be the presence of a bug.

The calculation of Fibonacci sequences of big integers is not an everyday task but it can still be a reliable example to show how tail calls are implemented.

Not happy with my conclusions and following several suggestions of users’ comments (here on the blog, on Reddit and on StackOverflow) I wanted to understand more about this issue and to explore other solutions using different compilers.

Continue reading “C++ Tail Recursion Using 64-bit variables – Part 2”

C++ Tail Recursion Using 64-bit variables

For this second coding adventure I want to share with you a problem I run into comparing iterative and recursive functions in C++. There are several differences between recursion and iteration, this article explains the topic nicely if you want to know more. In general languages like Java, C, and Python, recursion is fairly expensive compared to iteration because it requires the allocation of a new stack frame. It is possible to eliminate this overhead in C/C++ enabling compiler optimization to perform tail recursion, which transforms certain types of recursion (actually, certain types of tail calls) into jumps instead of function calls. To let the compiler performs this optimization it is necessary that the last thing a function does before it returns is call another function (in this case itself). In this scenario it should be safe to jump to the start of the second routine. Main disadvantage of Recursion in imperative languages is the fact that not always is possible to have tail calls, which means an allocation of the function address (and relative variables, like structs for instance) onto the stack at each call. For deep recursive function this can cause a stack-overflow exception because of a limit to the maximum size of the stack, which is typically less than the size of RAM by quite a few orders of magnitude.

I have written a simple Fibonacci function as an exercise in C++ using Visual Studio to test Tail Recursion and to see how it works: Continue reading “C++ Tail Recursion Using 64-bit variables”