Why?

You probably know what a wrapper is. As its name suggests, it’s a practice of putting another layer on a piece of something. In our case, wrapping a piece of code in another piece of code

But why would you do that? To make your life easier!
Wrapping external libraries lets you abstract your code from their implementation details. In effect, it makes your life a lot easier when you want to keep the behavior, but change the library providing it. This approach also lets you use only those features from a given external dependency that you actually need.
Let’s see that with an example.

Wrapping HTTP client

A very good example is HTTP client wrapper. HTTP calls are used in almost every web application. In order to perform them, we need to choose an HTTP client. We can either use fetch, or something more sophisticated like axios.

However, with time, we may decide to replace it with something else. There might be many reasons for that – either the library stops to be maintained or something new and better is out there. It would be a shame if we’d now need to change the code in those thousands of places where the current library is being used. This would take a lot of time and might be error-prone. We can definitely prepare better for such cases

Create HttpClient wrapper for axios

Let’s say that, for now, we will go with axios. Instead of calling it directly from our code:

import { useEffect, useState } from "react";
import axios from "axios";
import { Product } from "../types/product";
import { DummyJsonProductsResult } from "../types/dummyJsonProductsResult";

export const ProductsList = () => {
  const [products, setProducts] = useState<Product[] | null>(null);

  useEffect(() => {
    axios
      .get<DummyJsonProductsResult>("https://dummyjson.com/products")
      .then((result) => {
        setProducts(result.data.products);
      });
  }, []);
 
 // ...
};

I will create an HttpClient wrapper for it and use it instead.

First, I create httpClient.ts file in wrappers folder. I like to have such a catalog in my React projects and keep all the wrappers there.

I start writing all wrappers with an interface. In that case, I treat the interface as a contract. It should say what I need this small wrapper to do, without worrying about implementation details.

IHttpClient interface initially looks as follows:

interface IHttpClient {
  get<TResponse>(url: string): Promise<TResponse>;
}

That’s what we have so far. We just need to retrieve the data with GET method.

Next step is to create the actual implementation of IHttpClient using axios. This is pretty straightforward using a class implementing IHttpClient interface and taking a look at axios‘s documentation:

class AxiosHttpClient implements IHttpClient {
  private instance: AxiosInstance | null = null;

  private get axiosClient(): AxiosInstance {
    return this.instance ?? this.initAxiosClient();
  }

  private initAxiosClient() {
    return axios.create();
  }

  get<TResponse>(url: string): Promise<TResponse> {
    return new Promise<TResponse>((resolve, reject) => {
      this.axiosClient
        .get<TResponse, AxiosResponse<TResponse>>(url)
        .then((result) => {
          resolve(result.data);
        })
        .catch((error: Error | AxiosError) => {
          reject(error);
        });
    });
  }
}

This implementation lets us encapsulate a simple singleton inside the class.

The last step here is to expose the instance of our HTTP client. Remember to always export the interface type variable:

export const httpClient: IHttpClient = new AxiosHttpClient();

That’s basically how we wrap external libraries in TypeScript. Easy-peasy

Using the wrapper

I can now use our wrapper in ProductsList.tsx component:

import { useEffect, useState } from "react";
import { httpClient } from "../wrappers/httpClient"; // we don't import axios here anymore
import { Product } from "../types/product";
import { DummyJsonProductsResult } from "../types/dummyJsonProductsResult";

export const ProductsList = () => {
  const [products, setProducts] = useState<Product[] | null>(null);

  useEffect(() => {
    httpClient // instead of axios, we use our wrapper in components
      .get<DummyJsonProductsResult>("https://dummyjson.com/products")
      .then((result) => {
        setProducts(result.data.products);
      });
  }, []);
 
 // ...
};

Notice how easy that was. Since now, we only import stuff from axios package in httpClient.ts file. Only this single file is dependent on axios npm package. None of our components (and other project files) know about axios. Our IDE only knows that the wrapper is an object instance fulfilling IHttpClient contract:

Extra wrapper features

Apart from nicely isolating us from dependencies, wrappers have more advantages. One of them is a possibility to configure the library in a single place. In our example with axios – imagine that one day you want to add custom headers to each HTTP request. Having all API calls going via AxiosHttpClient, you can configure such things there, in a single place. That way, you follow the DRY principle and keep all the logic related to axios (or to any other external dependency) in a single place. It also comes with benefits like easy testability etc.

For clarity, I also added post support to our IHttpClient. You can check it here.

Replacing the wrapped library

Ok, it’s time to have our solution battle-tested. We have the HTTP client nicely wrapped and exposed as an instance of IHttpClient. However, we came to the conclusion that axios is not good enough, and we want to have it replaced with fetch.

Remember that in the real web application, you would have hundreds or thousands of usages of IHttpClient instance. That’s where the power of wrappers comes into play

So how do I make sure those thousands of usages will now use fetch instead of axios? That’s actually pretty straightforward. I’ll simply add a new class – FetchHttpClient implementing IHttpClient interface:

class FetchHttpClient implements IHttpClient {
  get<TResponse>(url: string): Promise<TResponse> {
    return new Promise<TResponse>((resolve, reject) => {
      fetch(url)
        .then((response) =>
          response
            .json()
            .then((responseJson) => {
              resolve(responseJson as TResponse);
            })
            .catch((error: Error) => {
              reject(`Response JSON parsing error: ${error}`);
            })
        )
        .catch((error: Error) => {
          reject(error);
        });
    });
  }

  post<TResponse>(url: string, data?: object): Promise<TResponse> {
    return new Promise<TResponse>((resolve, reject) => {
      fetch(url, {
        method: "POST",
        headers: {
          "Content-Type": "application/json",
        },
        body: JSON.stringify(data),
      })
        .then((response) =>
          response
            .json()
            .then((responseJson) => {
              resolve(responseJson as TResponse);
            })
            .catch((error: Error) => {
              reject(`Response JSON parsing error: ${error}`);
            })
        )
        .catch((error: Error) => {
          reject(error);
        });
    });
  }
}

For completion, I included POST here as well.

The one last thing I have to do to make our new FetchHttpClient be used in the whole app in place of AxiosHttpClient is to change a single line with export:

export const httpClient: IHttpClient = new FetchHttpClient(); // instead of new AxiosHttpClient()

and that’s it! Our whole application now uses fetch for GET and POST HTTP requests And it even still works

Summary and source code

I hope that now you see how important it is to wrap external libraries. We have seen that on JavaScript/TypeScript app example, but this is applicable to any programming language and framework.

It’s always good to be as independent as possible of 3rd party stuff. Too many times I’ve been in a situation that some npm package is so extensively used in a project, directly in the source code in hundreds of places, that it cannot be replaced without spending several days on it. Creating wrappers forces us to think abstract, which is another great advantage.

You can find the complete source code here: https://github.com/dsibinski/codejourney/tree/main/wrapping-external-libraries

The post How (And Why?) To Wrap External Libraries? appeared first on CodeJourney.net.

Unmanaged resources and finalizers

First of all we should all get familiar with what unmanaged resources are. These ones can be files or folders on the disk, database connections, GUI elements or network resources. You can also think of them as some external elements we need to interact with in our applications through some protocol (e.g. database queries or file system manipulation methods). They’re called unmanaged not without a reason – any unmanaged resources accessed from .NET code will not be automatically cleaned by the garbage collector. That’s how they are not(un)managed.

Maybe you’ve heard about destructors in C++ – remember methods called after class’s name (like its constructor) starting with ‘~’ character? This also exists in .NET, but it’s not what you’d expect from C++. In .NET, such methods are referred to as finalizers.

Finalizers and destructors in .NET

Nonetheless, you can define a finalizer in your class in one of the following ways:

 Using “destructor-like” syntax:

Using Finalize() method:

If you examine the IL code of both versions, it turns out that the destructor can be seen as a syntax sugar for the finalizer. In fact, the ~MyTestClass() method is translated into Finalize() method:

The only difference is that – as you can see on the IL above – Finalize() method created by the compiler from the destructor is implicitly calling the Finalize() method on the base class of the object (you can see it in the finally block in the IL generated). So in case of using a destructor-like syntax, we are actually creating a finalizer by overriding Finalize() method, whereas when implementing a Finalize() method directly we do it as we’d use the new keyword (hiding base class’s implementation of Finalize() method).

Will GC call the finalizer for me?

As you may know, finalizers methods are normally used to clean-up some unmanaged resources (e.g. to release a file handle or database connection). You may think that as soon as your object is ready to be collected (nothing references it anymore), garbage collector will firstly call the finalizer (to ensure everything is cleaned up) and then reclaim the memory used by the object.

Unfortunately not. If you think about it one more time – GC cannot know what’s inside your Finalize() method. You can put there the code which downloads the whole Internet just like that:

… and even though we have nowadays a bit faster bandwidths than the one from the gif , you can clearly see it wouldn’t be a good idea to block garbage collection because of some costly process being executed before the memory for the object is reclaimed.

In order to avoid the above-described scenario, which would slow down the GC’s work significantly, .NET contributors decided that the finalizers on the objects are called periodically on a separate thread, completely independently from the GC.

This way the main GC thread is not blocked. However, it adds a bit of complexity to the garbage collection process – continue reading for more details.

Finalization mechanism

As we said in one of the previous posts, one of the various sources of references to objects in our .NET application (GC roots) are “objects finalization references”. Let’s now make this mysterious term clear.

In order to prevent having a finalizable object (containing finalizer method) reclaimed before its Finalize() method is called (which happens independently from the GC as you already know), there’s a separate references list called finalization queue maintained by the GC. As soon as memory for a new finalizable object is allocated, a reference to it is also put on the finalization queue, which becomes a finalization root for this object (it’s not the same kind of root as “normal” GC roots – it’s treated a bit more differently).

The diagram below presents the memory state just after few new objects were allocated on the managed heap.

As you can see, objects ob2, ob3, ob5, ob6 and ob10 are all placed on the finalization queue, which means all of them contain Finalize() method.

Within these objects, ob2 and ob5 don’t have any references (roots) – it’s visible on the left side (heap). It means that these two objects are not used (are not referenced by anything) so they’re ready to be garbage collected. However, each of them contains a finalization root on the finalization queue.

As soon as the next garbage collection occurs, ob2 and ob5 cannot be reclaimed straightaway, as there’s a Finalize() method to be called on them first. Instead, when GC examines these two objects, it sees that they are not referenced from “normal” roots, but they have finalization references on the finalization queue. If that’s the case, GC moves finalization reference to another data structure called fReachable queue (also visible on the diagram above).

After, both queues and the heap look as follows:

That’s what I meant by stating that finalization roots are “special” kind of GC roots. Apart from that, ob2 and ob5 are still seen as “rooted” (as still being referenced) and because of that are not reclaimed by the GC. In that moment, standard generational GC rules apply, so if the collection below was a gen 1 collection, both objects will be promoted to gen 2.

Periodically, the finalization runs on a separate thread exploring the fReachable queue and calling Finalize() method on each object referenced from it. Then it removes the reference to this object from the queue. At this moment, finalizable object becomes rootless and can be reclaimed in the next garbage collection cycle.

Dispose for the rescue

In order to unify usage of finalizers and allow developers to correctly free their resources without unnecessarily prolonging their objects’ lifetime (as you saw above, finalizable objects stay uncollected for at least 1 more GC round than “normal” objects), programmer can (and should) implement a dispose pattern. The purpose of it is to allow the developer to free unmanaged resources “manually” as soon as they are not needed anymore.

The framework also provides a GC.SuppressFinalize method which tells GC that the object has been manually disposed and no more finalization is necessary. As soon as it’s called, the object reference is removed from finalization/fReachable queue. The goal is to prevent finalizing the object twice.

IDisposable

.NET Framework provides a System.IDisposable interface which should be implemented by a class which works with unmanaged resources.

Sample implementation of dispose pattern can look as follows:

Implementing IDisposable interface only forces us to add Dispose() method. Inside, we perform the resources clean-up and call GC.SuppressFinalize(this) to mark our object as finalized. We also implemented a separate method, in the example called CleanUp(bool disposing), which performs the actual releasing of unmanaged resources. But why do we need this bool disposing parameter?

It may be important to differentiate when the resources cleanup is called directly from code (we’ll see how it can be done in the next section) or by the finalization thread. As you already know, finalization is executed periodically on a separate thread. It means that if our UnmanagedClass needs any thread-specific resources cleanup, it’s not a good idea to execute it on totally independent, finalization thread, which is out-of-context at that moment.

That’s why we added a boolean parameter to the CleanUp method, which will be set to “true” as soon as Dispose() method is called directly from code. In that case we know that we can execute thread-specific cleanup code.

Additionally, we implemented the Finalize() method, which also calls CleanUp(), but passing “false” parameter’s value. In that case, as the finalization thread is out-of-context, we shouldn’t execute thread-specific cleanup code. We should treat Finalize() method as a last resort in case Dispose() has not been called because of some reason.

You can also check Microsoft dosc to see what’s their recommendation on implementing IDisposable interface.

Using statement

As mentioned above, the programmer can explicitly call Dispose() method on the class:

but there’s another – and preferred – way: wrapping usage of the class within using statement:

How does using statement ensure that Dispose() is called on our object created within it?

Let’s see the IL:

As you can see, the compiler translates using statement into try-finally block. In the finally part Dispose() method is called on our object’s instance.

This way the compiler ensures that even if there’s any exception thrown in the using block, the object will be disposed. That’s why we should always work with objects that may use unmanaged resources in such a way.

Summary

In this 7th post from .NET Internals series we examined how unmanaged resources are handled within .NET Framework and what’s the GC’s role in that process. We got to know two new GC-internal data structures: finalization and fReachable queues. In the end, we got familiar with dispose pattern and using statement.

I hope it helped you to clarify these topics a bit

See you next week!

The post [.NET Internals 07] Unmanaged resources: finalization, fReachable queue and dispose pattern appeared first on CodeJourney.net.