Anvil.API.NwTask Class Reference

Asynchronous tasks and helpers for running NWN APIs in an async context. More...

Static Public Member Functions
static Task	Delay (TimeSpan delay, CancellationToken? cancellationToken=null)
	Waits until the specified amount of time has passed.
static Task	DelayFrame (int frames, CancellationToken? cancellationToken=null)
	Waits until the specified amount of frames have passed.
static Task	NextFrame ()
	Waits until the next server frame/loop.
static async Task	Run (Func< Task > function)
	Queues the specified work to run on the next server cycle.
static async Task< T >	Run< T > (Func< Task< T > > function)
static IAwaitable	SwitchToMainThread ()
	Safely returns to a NWScript context from another thread. This must ALWAYS be called after an external callback, or thread switch before using any NWN APIs.
static Task	WaitUntil (Func< bool > test, CancellationToken? cancellationToken=null)
	Waits until the specified expression returns true.
static Task	WaitUntilValueChanged< T > (Func< T > valueSource, CancellationToken? cancellationToken=null)
	Waits until the specified value source changes.
static async Task	WhenAll (IEnumerable< Task > tasks)
static async Task	WhenAll (params Task[] tasks)
	Waits until all the specified tasks have completed.
static async Task< TResult[]>	WhenAll< TResult > (IEnumerable< Task< TResult > > tasks)
static async Task< TResult[]>	WhenAll< TResult > (params Task< TResult >[] tasks)
static async Task	WhenAny (IEnumerable< Task > tasks)
static async Task	WhenAny (params Task[] tasks)
	Waits until any of the specified tasks have completed. NOTE: This will not cancel other tasks that have not finished running. Specify a common CancellationToken in each of the source tasks.
static async Task< Task< TResult > >	WhenAny< TResult > (IEnumerable< Task< TResult > > tasks)
static async Task< Task< TResult > >	WhenAny< TResult > (params Task< TResult >[] tasks)

Detailed Description

Asynchronous tasks and helpers for running NWN APIs in an async context.

Examples

/*
 * Example usages of all Async APIs.
 */
 
using System;
using System.Linq;
using System.Threading;
using System.Threading.Tasks;
using Anvil.API;
using Anvil.Services;
 
namespace NWN.Anvil.Samples
{
  [ServiceBinding(typeof(NwTaskExamples))]
  public class NwTaskExamples
  {
    public NwTaskExamples()
    {
      _ = DoAsyncStuff();
      _ = CancellationTokenExample();
    }
 
    private async Task DoAsyncStuff()
    {
      // Do some heavy work on another thread using a standard task, then return to a safe script context.
      await Task.Run(() => Thread.Sleep(1000));
      await NwTask.SwitchToMainThread();
 
      // Wait for a frame, or a certain amount of frames to pass.
      await NwTask.NextFrame();
      await NwTask.DelayFrame(100);
 
      // Wait for 30 seconds to pass. (DelayCommand replacement)
      await NwTask.Delay(TimeSpan.FromSeconds(30));
 
      // Wait for a certain game period to pass.
      await NwTask.Delay(NwTimeSpan.FromRounds(2));
      await NwTask.Delay(NwTimeSpan.FromTurns(3));
      await NwTask.Delay(NwTimeSpan.FromHours(1));
 
      // Wait for an expression to evaluate to true
      await NwTask.WaitUntil(() => NwModule.Instance.Players.Count() > 5);
 
      // Wait for a value to change.
      await NwTask.WaitUntilValueChanged(() => NwModule.Instance.Players.Count());
 
      // Start some tasks.
      Task task1 = Task.Run(() => true); // Executed in the thread pool, you cannot use NWN APIs here.
 
      Task task2 = Task.Run(async () =>
      {
        // Executed in the thread pool, you cannot use NWN APIs here.
        await Task.Delay(TimeSpan.FromSeconds(5));
        return 20;
      });
 
      Task task3 = NwTask.Run(async () =>
      {
        // Executed in the server thread, you can use NWN APIs here.
        await NwTask.Delay(NwTimeSpan.FromRounds(5));
        NwModule.Instance.SendMessageToAllDMs("5 rounds elapsed!");
        return 20;
      });
 
      // ...wait for any of them to complete. The others will still keep running in the background!
      await NwTask.WhenAny(task1, task2, task3);
 
      // ...wait for all of them to complete.
      await NwTask.WhenAll(task1, task2, task3);
    }
 
    private async Task CancellationTokenExample()
    {
      // Create a token that will be used to cancel the other tasks.
      CancellationTokenSource tokenSource = new CancellationTokenSource();
 
      // Start some tasks
      Task task1 = NwTask.WaitUntil(() => NwModule.Instance.Players.Any(), tokenSource.Token);
      Task task2 = NwTask.Delay(TimeSpan.FromSeconds(10), tokenSource.Token);
 
      // When any of them complete, cancel the other tasks.
      await NwTask.WhenAny(task1, task2);
      tokenSource.Cancel();
    }
  }
}

Member Function Documentation

Delay()

static Task Anvil.API.NwTask.Delay ( TimeSpan delay, CancellationToken? cancellationToken = null )

inlinestatic

Waits until the specified amount of time has passed.

Parameters

delay	How long to wait.
cancellationToken	A cancellation token that should be used to cancel the work.

DelayFrame()

static Task Anvil.API.NwTask.DelayFrame ( int frames, CancellationToken? cancellationToken = null )

inlinestatic

Waits until the specified amount of frames have passed.

Parameters

frames	The number of frames to wait.
cancellationToken	A cancellation token that should be used to cancel the work.

Run()

static async Task Anvil.API.NwTask.Run ( Func< Task > function )

inlinestatic

Queues the specified work to run on the next server cycle.

Parameters

function

The task to run.

WaitUntil()

static Task Anvil.API.NwTask.WaitUntil ( Func< bool > test, CancellationToken? cancellationToken = null )

inlinestatic

Waits until the specified expression returns true.

Parameters

test	The test expression.
cancellationToken	A cancellation token that should be used to cancel the work.

WaitUntilValueChanged< T >()

static Task Anvil.API.NwTask.WaitUntilValueChanged< T > ( Func< T > valueSource, CancellationToken? cancellationToken = null )

inlinestatic

Waits until the specified value source changes.

Parameters

valueSource	The watched value source.
cancellationToken	A cancellation token that should be used to cancel the work.

WhenAll()

static async Task Anvil.API.NwTask.WhenAll ( params Task[] tasks )

inlinestatic

Waits until all the specified tasks have completed.

Parameters

tasks

The tasks to wait on for completion.

WhenAny()

static async Task Anvil.API.NwTask.WhenAny ( params Task[] tasks )

inlinestatic

Waits until any of the specified tasks have completed.
NOTE: This will not cancel other tasks that have not finished running. Specify a common CancellationToken in each of the source tasks.

Parameters

tasks

The tasks to wait on for completion.

---

The documentation for this class was generated from the following file:

• NWN.Anvil/src/main/API/Async/NwTask.cs