Interface IFramework

This class represents the Framework of the native game client and grants access to various subsystems.

Remarks

<p>Choosing between RunOnFrameworkThread and Run</p> <ul> <li>If you do need to do use await and have your task keep executing on the main thread after waiting is done, use Run.</li> <li>If you need to call System.Threading.Tasks.Task.Wait or System.Threading.Tasks.Task1.Result, use RunOnFrameworkThread. It also skips the task scheduler if invoked already from the framework thread.</li> </ul> <p>The game is likely to completely lock up if you call above synchronous function and getter, because starting a new task by default runs on System.Threading.Tasks.TaskScheduler.Current, which would make the task run on the framework thread if invoked via Run. This includes Task.Factory.StartNewandTask.ContinueWith. Use Task.Runif you need to start a new task from the callback specified toRun, as it will force your task to be run in the default thread pool.</p> <p>See Dalamud.Interface.Internal.Windows.Data.Widgets.TaskSchedulerWidget` to see the difference in behaviors, and how would a misuse of these functions result in a deadlock.</p>

Assembly: Dalamud.dll

Declaration

public interface IFramework : IDalamudService

Properties

LastUpdate

Gets the last time that the Framework Update event was triggered.

Declaration

DateTime LastUpdate { get; }

LastUpdateUTC

Gets the last time in UTC that the Framework Update event was triggered.

Declaration

DateTime LastUpdateUTC { get; }

UpdateDelta

Gets the delta between the last Framework Update and the currently executing one.

Declaration

TimeSpan UpdateDelta { get; }

IsInFrameworkUpdateThread

Gets a value indicating whether currently executing code is running in the game's framework update thread.

Declaration

bool IsInFrameworkUpdateThread { get; }

IsFrameworkUnloading

Gets a value indicating whether game Framework is unloading.

Declaration

bool IsFrameworkUnloading { get; }

Methods

GetTaskFactory()

Gets a System.Threading.Tasks.TaskFactory that runs tasks during Framework Update event.

Declaration

TaskFactory GetTaskFactory()

Returns

System.Threading.Tasks.TaskFactory: The task factory.

DelayTicks(long, CancellationToken)

Returns a task that completes after the given number of ticks.

Declaration

Task DelayTicks(long numTicks, CancellationToken cancellationToken = default)

Returns

System.Threading.Tasks.Task: A new System.Threading.Tasks.Task that gets resolved after specified number of ticks happen.

Parameters

Type	Name	Description
System.Int64	numTicks	Number of ticks to delay.
System.Threading.CancellationToken	cancellationToken	The cancellation token.

Remarks

The continuation will run on the framework thread by default.

Run(Action, CancellationToken)

Run given function right away if this function has been called from game's Framework.Update thread, or otherwise run on next Framework.Update call.

Declaration

Task Run(Action action, CancellationToken cancellationToken = default)

Returns

System.Threading.Tasks.Task: Task representing the pending or already completed function.

Parameters

Type	Name	Description
System.Action	action	Function to call.
System.Threading.CancellationToken	cancellationToken	The cancellation token.

Remarks

<p>Starting new tasks and waiting on them synchronously from this callback will completely lock up the game. Use await if you need to wait on something from an async callback.</p> <p>See the remarks on Dalamud.Plugin.Services.IFramework if you need to choose which one to use, between Run and RunOnFrameworkThread. Note that RunOnTick is a fancy version of RunOnFrameworkThread.</p>

Run<T>(Func<T>, CancellationToken)

Run given function right away if this function has been called from game's Framework.Update thread, or otherwise run on next Framework.Update call.

Declaration

Task<T> Run<T>(Func<T> action, CancellationToken cancellationToken = default)

Returns

System.Threading.Tasks.Task<<T>>: Task representing the pending or already completed function.

Parameters

Type	Name	Description
System.Func<<T>>	action	Function to call.
System.Threading.CancellationToken	cancellationToken	The cancellation token.

Type Parameters

Name	Description
T	Return type.

Remarks

<p>Starting new tasks and waiting on them synchronously from this callback will completely lock up the game. Use await if you need to wait on something from an async callback.</p> <p>See the remarks on Dalamud.Plugin.Services.IFramework if you need to choose which one to use, between Run and RunOnFrameworkThread. Note that RunOnTick is a fancy version of RunOnFrameworkThread.</p>

Run(Func<Task>, CancellationToken)

Run given function right away if this function has been called from game's Framework.Update thread, or otherwise run on next Framework.Update call.

Declaration

Task Run(Func<Task> action, CancellationToken cancellationToken = default)

Returns

System.Threading.Tasks.Task: Task representing the pending or already completed function.

Parameters

Type	Name	Description
System.Func<System.Threading.Tasks.Task>	action	Function to call.
System.Threading.CancellationToken	cancellationToken	The cancellation token.

Remarks

<p>Starting new tasks and waiting on them synchronously from this callback will completely lock up the game. Use await if you need to wait on something from an async callback.</p> <p>See the remarks on Dalamud.Plugin.Services.IFramework if you need to choose which one to use, between Run and RunOnFrameworkThread. Note that RunOnTick is a fancy version of RunOnFrameworkThread.</p>

Run<T>(Func<Task<T>>, CancellationToken)

Run given function right away if this function has been called from game's Framework.Update thread, or otherwise run on next Framework.Update call.

Declaration

Task<T> Run<T>(Func<Task<T>> action, CancellationToken cancellationToken = default)

Returns

System.Threading.Tasks.Task<<T>>: Task representing the pending or already completed function.

Parameters

Type	Name	Description
System.Func<System.Threading.Tasks.Task<<T>>>	action	Function to call.
System.Threading.CancellationToken	cancellationToken	The cancellation token.

Type Parameters

Name	Description
T	Return type.

Remarks

<p>Starting new tasks and waiting on them synchronously from this callback will completely lock up the game. Use await if you need to wait on something from an async callback.</p> <p>See the remarks on Dalamud.Plugin.Services.IFramework if you need to choose which one to use, between Run and RunOnFrameworkThread. Note that RunOnTick is a fancy version of RunOnFrameworkThread.</p>

RunOnFrameworkThread<T>(Func<T>)

Run given function right away if this function has been called from game's Framework.Update thread, or otherwise run on next Framework.Update call.

Declaration

Task<T> RunOnFrameworkThread<T>(Func<T> func)

Returns

System.Threading.Tasks.Task<<T>>: Task representing the pending or already completed function.

Parameters

Type	Name	Description
System.Func<<T>>	func	Function to call.

Type Parameters

Name	Description
T	Return type.

Remarks

<p>await, Task.Factory.StartNew or alike will continue off the framework thread.</p> <p>Awaiting on the returned System.Threading.Tasks.Task from RunOnFrameworkThread, Run, or RunOnTick right away inside the callback specified to this function has a chance of locking up the game. Do not do await framework.RunOnFrameworkThread(...); directly or indirectly from the delegate passed to this function.</p> <p>See the remarks on Dalamud.Plugin.Services.IFramework if you need to choose which one to use, between Run and RunOnFrameworkThread. Note that RunOnTick is a fancy version of RunOnFrameworkThread.</p>

RunOnFrameworkThread(Action)

Run given function right away if this function has been called from game's Framework.Update thread, or otherwise run on next Framework.Update call.

Declaration

Task RunOnFrameworkThread(Action action)

Returns

System.Threading.Tasks.Task: Task representing the pending or already completed function.

Parameters

Type	Name	Description
System.Action	action	Function to call.

Remarks

<p>await, Task.Factory.StartNew or alike will continue off the framework thread.</p> <p>Awaiting on the returned System.Threading.Tasks.Task from RunOnFrameworkThread, Run, or RunOnTick right away inside the callback specified to this function has a chance of locking up the game. Do not do await framework.RunOnFrameworkThread(...); directly or indirectly from the delegate passed to this function.</p> <p>See the remarks on Dalamud.Plugin.Services.IFramework if you need to choose which one to use, between Run and RunOnFrameworkThread. Note that RunOnTick is a fancy version of RunOnFrameworkThread.</p>

RunOnFrameworkThread<T>(Func<Task<T>>)

Run given function right away if this function has been called from game's Framework.Update thread, or otherwise run on next Framework.Update call.

Declaration

[Obsolete("Use RunOnTick instead.")]
Task<T> RunOnFrameworkThread<T>(Func<Task<T>> func)

Returns

System.Threading.Tasks.Task<<T>>: Task representing the pending or already completed function.

Parameters

Type	Name	Description
System.Func<System.Threading.Tasks.Task<<T>>>	func	Function to call.

Type Parameters

Name	Description
T	Return type.

Remarks

<p>await, Task.Factory.StartNew or alike will continue off the framework thread.</p> <p>Awaiting on the returned System.Threading.Tasks.Task from RunOnFrameworkThread, Run, or RunOnTick right away inside the callback specified to this function has a chance of locking up the game. Do not do await framework.RunOnFrameworkThread(...); directly or indirectly from the delegate passed to this function.</p> <p>See the remarks on Dalamud.Plugin.Services.IFramework if you need to choose which one to use, between Run and RunOnFrameworkThread. Note that RunOnTick is a fancy version of RunOnFrameworkThread.</p>

RunOnFrameworkThread(Func<Task>)

Run given function right away if this function has been called from game's Framework.Update thread, or otherwise run on next Framework.Update call.

Declaration

[Obsolete("Use RunOnTick instead.")]
Task RunOnFrameworkThread(Func<Task> func)

Returns

System.Threading.Tasks.Task: Task representing the pending or already completed function.

Parameters

Type	Name	Description
System.Func<System.Threading.Tasks.Task>	func	Function to call.

Remarks

<p>await, Task.Factory.StartNew or alike will continue off the framework thread.</p> <p>Awaiting on the returned System.Threading.Tasks.Task from RunOnFrameworkThread, Run, or RunOnTick right away inside the callback specified to this function has a chance of locking up the game. Do not do await framework.RunOnFrameworkThread(...); directly or indirectly from the delegate passed to this function.</p> <p>See the remarks on Dalamud.Plugin.Services.IFramework if you need to choose which one to use, between Run and RunOnFrameworkThread. Note that RunOnTick is a fancy version of RunOnFrameworkThread.</p>

RunOnTick<T>(Func<T>, TimeSpan, int, CancellationToken)

Run given function in upcoming Framework.Tick call.

Declaration

Task<T> RunOnTick<T>(Func<T> func, TimeSpan delay = default, int delayTicks = 0, CancellationToken cancellationToken = default)

Returns

System.Threading.Tasks.Task<<T>>: Task representing the pending function.

Parameters

Type	Name	Description
System.Func<<T>>	func	Function to call.
System.TimeSpan	delay	Wait for given timespan before calling this function.
System.Int32	delayTicks	Count given number of Framework.Tick calls before calling this function. This takes precedence over delay parameter.
System.Threading.CancellationToken	cancellationToken	Cancellation token which will prevent the execution of this function if wait conditions are not met.

Type Parameters

Name	Description
T	Return type.

Remarks

<p>await, Task.Factory.StartNew or alike will continue off the framework thread.</p> <p>Awaiting on the returned System.Threading.Tasks.Task from RunOnFrameworkThread, Run, or RunOnTick right away inside the callback specified to this function has a chance of locking up the game. Do not do await framework.RunOnFrameworkThread(...); directly or indirectly from the delegate passed to this function.</p> <p>See the remarks on Dalamud.Plugin.Services.IFramework if you need to choose which one to use, between Run and RunOnFrameworkThread. Note that RunOnTick is a fancy version of RunOnFrameworkThread.</p>

RunOnTick(Action, TimeSpan, int, CancellationToken)

Run given function in upcoming Framework.Tick call.

Declaration

Task RunOnTick(Action action, TimeSpan delay = default, int delayTicks = 0, CancellationToken cancellationToken = default)

Returns

System.Threading.Tasks.Task: Task representing the pending function.

Parameters

Type	Name	Description
System.Action	action	Function to call.
System.TimeSpan	delay	Wait for given timespan before calling this function.
System.Int32	delayTicks	Count given number of Framework.Tick calls before calling this function. This takes precedence over delay parameter.
System.Threading.CancellationToken	cancellationToken	Cancellation token which will prevent the execution of this function if wait conditions are not met.

Remarks

<p>await, Task.Factory.StartNew or alike will continue off the framework thread.</p> <p>Awaiting on the returned System.Threading.Tasks.Task from RunOnFrameworkThread, Run, or RunOnTick right away inside the callback specified to this function has a chance of locking up the game. Do not do await framework.RunOnFrameworkThread(...); directly or indirectly from the delegate passed to this function.</p> <p>See the remarks on Dalamud.Plugin.Services.IFramework if you need to choose which one to use, between Run and RunOnFrameworkThread. Note that RunOnTick is a fancy version of RunOnFrameworkThread.</p>

RunOnTick<T>(Func<Task<T>>, TimeSpan, int, CancellationToken)

Run given function in upcoming Framework.Tick call.

Declaration

Task<T> RunOnTick<T>(Func<Task<T>> func, TimeSpan delay = default, int delayTicks = 0, CancellationToken cancellationToken = default)

Returns

System.Threading.Tasks.Task<<T>>: Task representing the pending function.

Parameters

Type	Name	Description
System.Func<System.Threading.Tasks.Task<<T>>>	func	Function to call.
System.TimeSpan	delay	Wait for given timespan before calling this function.
System.Int32	delayTicks	Count given number of Framework.Tick calls before calling this function. This takes precedence over delay parameter.
System.Threading.CancellationToken	cancellationToken	Cancellation token which will prevent the execution of this function if wait conditions are not met.

Type Parameters

Name	Description
T	Return type.

Remarks

<p>await, Task.Factory.StartNew or alike will continue off the framework thread.</p> <p>Awaiting on the returned System.Threading.Tasks.Task from RunOnFrameworkThread, Run, or RunOnTick right away inside the callback specified to this function has a chance of locking up the game. Do not do await framework.RunOnFrameworkThread(...); directly or indirectly from the delegate passed to this function.</p> <p>See the remarks on Dalamud.Plugin.Services.IFramework if you need to choose which one to use, between Run and RunOnFrameworkThread. Note that RunOnTick is a fancy version of RunOnFrameworkThread.</p>

RunOnTick(Func<Task>, TimeSpan, int, CancellationToken)

Run given function in upcoming Framework.Tick call.

Declaration

Task RunOnTick(Func<Task> func, TimeSpan delay = default, int delayTicks = 0, CancellationToken cancellationToken = default)

Returns

System.Threading.Tasks.Task: Task representing the pending function.

Parameters

Type	Name	Description
System.Func<System.Threading.Tasks.Task>	func	Function to call.
System.TimeSpan	delay	Wait for given timespan before calling this function.
System.Int32	delayTicks	Count given number of Framework.Tick calls before calling this function. This takes precedence over delay parameter.
System.Threading.CancellationToken	cancellationToken	Cancellation token which will prevent the execution of this function if wait conditions are not met.

Remarks

<p>await, Task.Factory.StartNew or alike will continue off the framework thread.</p> <p>Awaiting on the returned System.Threading.Tasks.Task from RunOnFrameworkThread, Run, or RunOnTick right away inside the callback specified to this function has a chance of locking up the game. Do not do await framework.RunOnFrameworkThread(...); directly or indirectly from the delegate passed to this function.</p> <p>See the remarks on Dalamud.Plugin.Services.IFramework if you need to choose which one to use, between Run and RunOnFrameworkThread. Note that RunOnTick is a fancy version of RunOnFrameworkThread.</p>

CreateDebouncer(TimeSpan, Action)

Creates a new Dalamud.Utility.IDebouncer instance.

Declaration

IDebouncer CreateDebouncer(TimeSpan delay, Action action)

Returns

Dalamud.Utility.IDebouncer: A new, thread-safe Dalamud.Utility.Debouncer instance. The caller is responsible for disposing of this instance.

Parameters

Type	Name	Description
System.TimeSpan	delay	The delay to wait after the last request before executing the action.
System.Action	action	The delegate to execute when the debounce period elapses.

Exceptions

System.ArgumentNullException
Thrown when <code class="paramref">action</code> is null.

Events

Update

Event that gets fired every time the game framework updates.

Declaration

event IFramework.OnUpdateDelegate Update

Event Type

Dalamud.Plugin.Services.IFramework.OnUpdateDelegate