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​
public interface IFramework : IDalamudService
Properties​
LastUpdate​
Gets the last time that the Framework Update event was triggered.
DateTime LastUpdate { get; }
LastUpdateUTC​
Gets the last time in UTC that the Framework Update event was triggered.
DateTime LastUpdateUTC { get; }
UpdateDelta​
Gets the delta between the last Framework Update and the currently executing one.
TimeSpan UpdateDelta { get; }
IsInFrameworkUpdateThread​
Gets a value indicating whether currently executing code is running in the game's framework update thread.
bool IsInFrameworkUpdateThread { get; }
IsFrameworkUnloading​
Gets a value indicating whether game Framework is unloading.
bool IsFrameworkUnloading { get; }
Methods​
GetTaskFactory()​
Gets a System.Threading.Tasks.TaskFactory that runs tasks during Framework Update event.
TaskFactory GetTaskFactory()
Returns​
System.Threading.Tasks.TaskFactory: The task factory.
DelayTicks(long, CancellationToken)​
Returns a task that completes after the given number of ticks.
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.
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.
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.
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.
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.
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.
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.
[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.
[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.
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.
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.
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.
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.
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.
event IFramework.OnUpdateDelegate Update