diff --git a/src/Abstractions/Entities/CallEntityOptions.cs b/src/Abstractions/Entities/CallEntityOptions.cs index b9462b5b..abd9cfac 100644 --- a/src/Abstractions/Entities/CallEntityOptions.cs +++ b/src/Abstractions/Entities/CallEntityOptions.cs @@ -8,21 +8,8 @@ namespace Microsoft.DurableTask.Entities; /// public record CallEntityOptions { - /// - /// Gets options indicating whether to signal the entity or not. - /// - /// - /// Setting this to non-null will signal the entity without waiting for a response. - /// - /// - /// Signal without start time: - /// new CallEntityOptions { Signal = true }; - /// - /// - /// Signal with start time: - /// new CallEntityOptions { Signal = DateTimeOffset }; - /// - public SignalEntityOptions? Signal { get; init; } + // No call options at the moment. Keeping this class so we can ship with options in the API. This will + // allow us to easily add them later without adjusting API surface. } /// diff --git a/src/Abstractions/Entities/TaskOrchestrationEntityFeature.cs b/src/Abstractions/Entities/TaskOrchestrationEntityFeature.cs index 27b81125..30df27b6 100644 --- a/src/Abstractions/Entities/TaskOrchestrationEntityFeature.cs +++ b/src/Abstractions/Entities/TaskOrchestrationEntityFeature.cs @@ -1,6 +1,8 @@ // Copyright (c) Microsoft Corporation. // Licensed under the MIT License. +using System.Diagnostics.CodeAnalysis; + namespace Microsoft.DurableTask.Entities; /// @@ -9,64 +11,78 @@ namespace Microsoft.DurableTask.Entities; public abstract class TaskOrchestrationEntityFeature { /// - /// Calls an operation on an entity and waits for it to complete. Does not wait for completion if - /// is set on . + /// Calls an operation on an entity and waits for it to complete. /// - /// The result of the entity operation. + /// The result type of the entity operation. /// The target entity. /// The name of the operation. /// The operation input. /// The call options. - /// - /// The result of the entity operation, or default() in the signal-only case. - /// + /// The result of the entity operation. public abstract Task CallEntityAsync( EntityInstanceId id, string operationName, object? input = null, CallEntityOptions? options = null); /// - /// Calls an operation on an entity and waits for it to complete. Does not wait for completion if - /// is set on . + /// Calls an operation on an entity and waits for it to complete. /// - /// The result of the entity operation. + /// The result type of the entity operation. /// The target entity. /// The name of the operation. /// The call options. - /// - /// The result of the entity operation, or default() in the signal-only case. - /// + /// The result of the entity operation. public virtual Task CallEntityAsync( EntityInstanceId id, string operationName, CallEntityOptions? options) => this.CallEntityAsync(id, operationName, null, options); /// - /// Calls an operation on an entity and waits for it to complete. Does not wait for completion if - /// is set on . + /// Calls an operation on an entity and waits for it to complete. /// /// The target entity. /// The name of the operation. /// The operation input. /// The call options. - /// - /// A task that completes when the operation has been completed. Or in the signal-only case, a task that is either - /// already complete or completes when the operation has been enqueued. - /// + /// A task that completes when the operation has been completed. public abstract Task CallEntityAsync( EntityInstanceId id, string operationName, object? input = null, CallEntityOptions? options = null); /// - /// Calls an operation on an entity and waits for it to complete. Does not wait for completion if - /// is set on . + /// Calls an operation on an entity and waits for it to complete. /// /// The target entity. /// The name of the operation. /// The call options. - /// - /// A task that completes when the operation has been completed. Or in the signal-only case, a task that is either - /// already complete or completes when the operation has been enqueued. - /// + /// A task that completes when the operation has been completed. public virtual Task CallEntityAsync(EntityInstanceId id, string operationName, CallEntityOptions? options) => this.CallEntityAsync(id, operationName, null, options); + /// + /// Calls an operation on an entity, but does not wait for completion. + /// + /// The target entity. + /// The name of the operation. + /// The operation input. + /// The signal options. + /// + /// A task that represents scheduling of the signal operation. Dependening on implementation, this may complete + /// either when the operation has been signalled, or when the signal action has been enqueued by the context. + /// + public abstract Task SignalEntityAsync( + EntityInstanceId id, string operationName, object? input = null, SignalEntityOptions? options = null); + + /// + /// Calls an operation on an entity, but does not wait for completion. + /// + /// The target entity. + /// The name of the operation. + /// The signal options. + /// + /// A task that represents scheduling of the signal operation. Dependening on implementation, this may complete + /// either when the operation has been signalled, or when the signal action has been enqueued by the context. + /// + public virtual Task SignalEntityAsync( + EntityInstanceId id, string operationName, SignalEntityOptions? options) + => this.SignalEntityAsync(id, operationName, null, options); + /// /// Acquires one or more entity locks. /// @@ -83,15 +99,16 @@ public virtual Task LockEntitiesAsync(params EntityInstanceId[ => this.LockEntitiesAsync((IEnumerable)entityIds); // let the implementation decide how to handle nulls. /// - /// Gets a value indicating whether any entity locks are owned by this instance. + /// Gets a value indicating whether this orchestration is in a critical section, and if true, any entity locks are + /// owned by this instance. /// /// The list of locked entities. /// True if any locks are owned, false otherwise. - public abstract bool HasEntityLocks(out IReadOnlyList entityIds); + public abstract bool InCriticalSection([NotNullWhen(true)] out IReadOnlyList? entityIds); /// - /// Gets a value indicating whether any entity locks are owned by this instance. + /// Gets a value indicating whether this orchestration is in a critical section. /// /// True if any locks are owned, false otherwise. - public virtual bool HasEntityLocks() => this.HasEntityLocks(out _); + public virtual bool InCriticalSection() => this.InCriticalSection(out _); }