Zomp.SyncMethodGenerator 1.4.11

Sync Method Generator

This .NET source generator produces a sync method from an async one.

Use cases

• A library which exposes both sync and async version of a method
• An application has to process two kinds of data in the same way:
  • Large data from I/O which cannot be stored in memory before processing: Original async method
  • Small sample of data in memory, usually a sample of the larger data: Generated sync method

How it works

CreateSyncVersionAttribute

Decorate your async method with CreateSyncVersionAttribute in your partial class, struct or record

[Zomp.SyncMethodGenerator.CreateSyncVersion]
static async Task WriteAsync(ReadOnlyMemory<byte> buffer, Stream stream, 
CancellationToken ct)
    => await stream.WriteAsync(buffer, ct).ConfigureAwait(true);

And it will generate a sync version of the method:

static void Write(ReadOnlySpan<byte> buffer, Stream stream)
    => stream.Write(buffer);

A list of changes applied to the new synchronized method:

• Remove async modifier

• Remove await from methods as well as foreach statement

• Change types

  From	To
  Task*	void
  Task<T>	T
  Func<Task>	Action
  Func<Task<T>>	Func<T>
  IAsyncEnumerable<T>	IEnumerable<T>
  IAsyncEnumerator<T>	IEnumerator<T>
  ConfiguredCancelableAsyncEnumerable<T>.Enumerator	IEnumerator<T>
  ConfiguredCancelableAsyncEnumerable<T>.GetAsyncEnumerator	IEnumerable<T>.GetEnumerator
  Memory<T>	Span<T>
  ReadOnlyMemory<T>	ReadOnlySpan<T>

• * ValueTasks are handled exactly like Tasks

• Remove parameters

  • CancellationToken
  • IProgress<T>

• Invocation changes

  • Remove ConfigureAwait from Tasks and Asynchronous Enumerations
  • Remove WithCancellation
  • Rewrite asynchronous invocations with Async suffix to call synchronous version (e.g. MoveNextAsync() becomes MoveNext())
  • Remove asynchronous invocations without the Async suffix
  • Remove CancellationToken parameter
  • Remove IProgress<T>.Report(T) call
  • Remove Memory<T>.Span property
  • Change await Task<TResult>.FromResult(value) to value
  • Change await Task.Delay(value) to Thread.Sleep(value)
  • Change any invocation returning ConfiguredCancelableAsyncEnumerable<T> to IEnumerable.GetEnumerator()

• Remove CreateSyncVersionAttribute

• Update XML documentation

Properties

OmitNullableDirective

This source generator detects language version during the compilation. By default it will generate #nullable enable directive if and only if the language version is 8 or above. Since it is impossible to reliably determine whether nullable context is turned on or not, OmitNullableDirective property is available to omit that directive from generating.

[Zomp.SyncMethodGenerator.CreateSyncVersion(OmitNullableDirective = true)]
public async Task MethodAsync()
{
    string f = null;
}

SYNC_ONLY symbol

In case there is logic which should only be executed in the synchronized version of the method, wrap it in SYNC_ONLY #if directive.

SYNC_ONLY must not be defined anywhere. The source generator will scan #if directives for this symbol.

Code inside SYNC_ONLY block will be copied as is. Unless global namespaces are used in the project, this code should contain fully qualified namespaces.

The following syntax:

[Zomp.SyncMethodGenerator.CreateSyncVersion]
public async Task WithSyncOnlyDirectiveAsync(CancellationToken ct)
{
#if SYNC_ONLY
    System.Console.Write("Sync");
#endif
    await Task.CompletedTask;
}

will output:

public void WithSyncOnlyDirective()
{
    System.Console.Write("Sync");
}

If you only want to execute in the original async version, flip the flag like this: #if !SYNC_ONLY.

Note: SYNC_ONLY cannot be mixed with other symbols in a conditional expression and cannot have #elif directive.

Installation

To add the library use:

dotnet add package Zomp.SyncMethodGenerator

Development

Related projects

• SyncToAsyncExtension - Allows switching between sync and async versions of a method. Very useful in development of this library.

Act

This project is fully compatible with act.

Other than required packages to run act itself, GitHub Actions script installs anything else that might be missing, such as node, yarn and dotnet. On Windows platform, software installation is performed on the host itself due to lack of container support.

To build the project using act follow these instructions:

Windows

Install chocolatey if missing.

Install the following packages if missing:

choco install git -y
choco install act-cli -y
refreshenv

In the project directory run:

act -P windows-latest=-self-hosted --artifact-server-path /tmp/artifacts

Linux

Install act by following these instructions.

In the project directory run:

act --artifact-server-path /tmp/artifacts