<commit_before># Plugs

Plugs are used to fill "holes" in .NET libraries and replace them with different 
 code. Holes exist for example when a method in .NET library uses a Windows API 
 call. That API call will not be available on Cosmos. Emulating the win32 API would be highly inefficient. Instead, 
 Cosmos replaces specific methods and property implementations that rely on 
 win32 API calls. Plugs can also be used to provide an alternate implementation 
 for a method, even if it does not rely on the Windows API.

## Types of plugs

There are two types of plugs used and supported by Cosmos:

*   Code Plug - A standard C# (or any .NET language) method is used to provide the alternate implementation.
*   X#/Assembly Languge - In a few cases, it is difficult or impossible to write the code using C#/.Net since one needs exact control over the emitted assembly code. An assembly plug are designed for that case. Cosmos itself only uses this type of plug within the Cosmos.Core projects.

## How do plugs work

To explain  how plugs work, we first need to give an overview of how IL2CPU works. Roughly, IL2CPU compiles a kernel using the following steps: 
1. IL2CPU determines a list of all methods and types which are used by the kernel.
2. It then compiles each of these methods into assembly code. 
This is usually done by getting the list of IL instructions which make up the method and translating each of them into some corresponding assembly.
3. Together with a bit of boilerplate code, the emitted assembly for all the methods is compiled using yasm. 

Plugs change what happens in step 2. A normal code plug means that rather taking the IL instructions from the original method, the IL instructions from the plug are used and then converted into assembly. An assembly plug directly states what asm should be emitted. 

# Implementing a Plug

While one always plugs individual methods, plugs are defined class wise. Therefore the first step to plugging any method is to define a new static class to contain all the pluggged methods for some certain type. This class must be decorated with the `Plug` attribute. The plug attribute either takes the type it is plugging(`Plug(Tpe target)`) or a string with the target name(`Plug(string targetName)`). Using the string target name is required when plugging internal or private classes. An example for a plugged class is for the Math class. https://github.com/CosmosOS/Cosmos/blob/8a8393353f1957890c5154650e29847fd22bf893/source/Cosmos.System2_Plugs/System/MathImpl.cs#L8-L9

## Code Plug

Once you have created such a class, you can add methods to the class. If these methods share the signature with a method in the original class they will be used to plug the original methods. For example in the above mentioned Math plug class, the following method plugs the original `double Math.Abs(double)` implementation.<commit_msg>fix typo<commit_after># Plugs

Plugs are used to fill "holes" in .NET libraries and replace them with different 
 code. Holes exist for example when a method in .NET library uses a Windows API 
 call. That API call will not be available on Cosmos. Emulating the win32 API would be highly inefficient. Instead, 
 Cosmos replaces specific methods and property implementations that rely on 
 win32 API calls. Plugs can also be used to provide an alternate implementation 
 for a method, even if it does not rely on the Windows API.

## Types of plugs

There are two types of plugs used and supported by Cosmos:

*   Code Plug - A standard C# (or any .NET language) method is used to provide the alternate implementation.
*   X#/Assembly Languge - In a few cases, it is difficult or impossible to write the code using C#/.Net since one needs exact control over the emitted assembly code. An assembly plug are designed for that case. Cosmos itself only uses this type of plug within the Cosmos.Core projects.

## How do plugs work

To explain  how plugs work, we first need to give an overview of how IL2CPU works. Roughly, IL2CPU compiles a kernel using the following steps: 
1. IL2CPU determines a list of all methods and types which are used by the kernel.
2. It then compiles each of these methods into assembly code. 
This is usually done by getting the list of IL instructions which make up the method and translating each of them into some corresponding assembly.
3. Together with a bit of boilerplate code, the emitted assembly for all the methods is compiled using yasm. 

Plugs change what happens in step 2. A normal code plug means that rather taking the IL instructions from the original method, the IL instructions from the plug are used and then converted into assembly. An assembly plug directly states what asm should be emitted. 

# Implementing a Plug

While one always plugs individual methods, plugs are defined class wise. Therefore the first step to plugging any method is to define a new static class to contain all the pluggged methods for some certain type. This class must be decorated with the `Plug` attribute. The plug attribute either takes the type it is plugging(`Plug(Type target)`) or a string with the target name(`Plug(string targetName)`). Using the string target name is required when plugging internal or private classes. An example for a plugged class is for the Math class. https://github.com/CosmosOS/Cosmos/blob/8a8393353f1957890c5154650e29847fd22bf893/source/Cosmos.System2_Plugs/System/MathImpl.cs#L8-L9

## Code Plug

Once you have created such a class, you can add methods to the class. If these methods share the signature with a method in the original class they will be used to plug the original methods. For example in the above mentioned Math plug class, the following method plugs the original `double Math.Abs(double)` implementation.
{'fraction_non_alphanumeric': 0.036729036729036726, 'fraction_numerical': 0.01593901593901594, 'mean_word_length': 4.257741347905283, 'pattern_counts': {'":': 0, '<': 3, '<?xml version=': 0, '>': 3, 'https://': 2, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '3718045', 'n_tokens_mistral': 1475, 'n_tokens_neox': 1366, 'n_words': 914}