Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Added InternalStableApi annotation #6880

Merged
merged 1 commit into from
Aug 15, 2023
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
8 changes: 8 additions & 0 deletions src/contrib/cluster/Akka.Cluster.Sharding/Shard.cs
Original file line number Diff line number Diff line change
Expand Up @@ -10,6 +10,7 @@
using System.Collections.Immutable;
using System.Linq;
using Akka.Actor;
using Akka.Annotations;
using Akka.Cluster.Sharding.Internal;
using Akka.Coordination;
using Akka.Event;
Expand All @@ -23,6 +24,13 @@ namespace Akka.Cluster.Sharding
using EntityId = String;
using ShardId = String;

/// <summary>
/// INTERNAL API
///
/// This actor creates children entity actors on demand that it is told to be
/// responsible for.
/// </summary>
[InternalStableApi]
internal sealed class Shard : ActorBase, IWithTimers, IWithUnboundedStash
{
#region messages
Expand Down
5 changes: 4 additions & 1 deletion src/contrib/cluster/Akka.Cluster.Sharding/ShardRegion.cs
Original file line number Diff line number Diff line change
Expand Up @@ -11,12 +11,12 @@
using System.Linq;
using System.Threading.Tasks;
using Akka.Actor;
using Akka.Annotations;
using Akka.Cluster.Sharding.Internal;
using Akka.Event;
using Akka.Pattern;
using Akka.Util;
using Akka.Util.Internal;
using Get = Akka.DistributedData.Get;

namespace Akka.Cluster.Sharding
{
Expand All @@ -25,11 +25,14 @@ namespace Akka.Cluster.Sharding
using ShardId = String;

/// <summary>
/// INTERNAL API
///
/// This actor creates children shard actors on demand that it is told to be responsible for.
/// The shard actors in turn create entity actors on demand.
/// It delegates messages targeted to other shards to the responsible
/// <see cref="ShardRegion"/> actor on other nodes.
/// </summary>
[InternalStableApi]
public sealed class ShardRegion : ActorBase, IWithTimers
{
#region messages
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -200,6 +200,7 @@ namespace Akka.Cluster.Sharding
{
public static Akka.Cluster.Sharding.IShardAllocationStrategy LeastShardAllocationStrategy(int absoluteLimit, double relativeLimit) { }
}
[Akka.Annotations.InternalStableApiAttribute()]
public sealed class ShardRegion : Akka.Actor.ActorBase, Akka.Actor.IWithTimers
{
public ShardRegion(string typeName, System.Func<string, Akka.Actor.Props> entityProps, Akka.Cluster.Sharding.ClusterShardingSettings settings, string coordinatorPath, Akka.Cluster.Sharding.ExtractEntityId extractEntityId, Akka.Cluster.Sharding.ExtractShardId extractShardId, object handOffStopMessage, Akka.Cluster.Sharding.Internal.IRememberEntitiesProvider rememberEntitiesProvider) { }
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -200,6 +200,7 @@ namespace Akka.Cluster.Sharding
{
public static Akka.Cluster.Sharding.IShardAllocationStrategy LeastShardAllocationStrategy(int absoluteLimit, double relativeLimit) { }
}
[Akka.Annotations.InternalStableApiAttribute()]
public sealed class ShardRegion : Akka.Actor.ActorBase, Akka.Actor.IWithTimers
{
public ShardRegion(string typeName, System.Func<string, Akka.Actor.Props> entityProps, Akka.Cluster.Sharding.ClusterShardingSettings settings, string coordinatorPath, Akka.Cluster.Sharding.ExtractEntityId extractEntityId, Akka.Cluster.Sharding.ExtractShardId extractShardId, object handOffStopMessage, Akka.Cluster.Sharding.Internal.IRememberEntitiesProvider rememberEntitiesProvider) { }
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -2197,6 +2197,11 @@ namespace Akka.Annotations
{
public InternalApiAttribute() { }
}
[System.AttributeUsageAttribute(System.AttributeTargets.Module | System.AttributeTargets.Class | System.AttributeTargets.Struct | System.AttributeTargets.Enum | System.AttributeTargets.Constructor | System.AttributeTargets.Method | System.AttributeTargets.Property | System.AttributeTargets.Field | System.AttributeTargets.Interface | System.AttributeTargets.All, AllowMultiple=false, Inherited=true)]
public sealed class InternalStableApiAttribute : System.Attribute
{
public InternalStableApiAttribute() { }
}
}
namespace Akka.Configuration
{
Expand Down Expand Up @@ -3204,7 +3209,7 @@ namespace Akka.Dispatch.SysMsg
public Suspend() { }
public override string ToString() { }
}
[Akka.Annotations.InternalApiAttribute()]
[Akka.Annotations.InternalStableApiAttribute()]
public abstract class SystemMessage : Akka.Actor.INoSerializationVerificationNeeded, Akka.Dispatch.SysMsg.ISystemMessage
{
protected SystemMessage() { }
Expand Down Expand Up @@ -5342,6 +5347,7 @@ namespace Akka.Util
public static int StringHash(string s) { }
public static int SymmetricHash<T>(System.Collections.Generic.IEnumerable<T> xs, uint seed) { }
}
[Akka.Annotations.InternalStableApiAttribute()]
[System.Runtime.CompilerServices.IsReadOnlyAttribute()]
public struct Option<T>
{
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -2195,6 +2195,11 @@ namespace Akka.Annotations
{
public InternalApiAttribute() { }
}
[System.AttributeUsageAttribute(System.AttributeTargets.Module | System.AttributeTargets.Class | System.AttributeTargets.Struct | System.AttributeTargets.Enum | System.AttributeTargets.Constructor | System.AttributeTargets.Method | System.AttributeTargets.Property | System.AttributeTargets.Field | System.AttributeTargets.Interface | System.AttributeTargets.All, AllowMultiple=false, Inherited=true)]
public sealed class InternalStableApiAttribute : System.Attribute
{
public InternalStableApiAttribute() { }
}
}
namespace Akka.Configuration
{
Expand Down Expand Up @@ -3196,7 +3201,7 @@ namespace Akka.Dispatch.SysMsg
public Suspend() { }
public override string ToString() { }
}
[Akka.Annotations.InternalApiAttribute()]
[Akka.Annotations.InternalStableApiAttribute()]
public abstract class SystemMessage : Akka.Actor.INoSerializationVerificationNeeded, Akka.Dispatch.SysMsg.ISystemMessage
{
protected SystemMessage() { }
Expand Down Expand Up @@ -5332,6 +5337,7 @@ namespace Akka.Util
public static int StringHash(string s) { }
public static int SymmetricHash<T>(System.Collections.Generic.IEnumerable<T> xs, uint seed) { }
}
[Akka.Annotations.InternalStableApiAttribute()]
public struct Option<T>
{
public static readonly Akka.Util.Option<T> None;
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -377,8 +377,10 @@ namespace Akka.Persistence
public Akka.Persistence.IStashOverflowStrategy DefaultInternalStashOverflowStrategy { get; }
public Akka.Persistence.PersistenceSettings Settings { get; }
public Akka.Persistence.Journal.EventAdapters AdaptersFor(string journalPluginId) { }
[Akka.Annotations.InternalStableApiAttribute()]
public Akka.Actor.IActorRef JournalFor(string journalPluginId) { }
public string PersistenceId(Akka.Actor.IActorRef actor) { }
[Akka.Annotations.InternalStableApiAttribute()]
public Akka.Actor.IActorRef SnapshotStoreFor(string snapshotPluginId) { }
}
public sealed class PersistenceSettings : Akka.Actor.Settings
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -377,8 +377,10 @@ namespace Akka.Persistence
public Akka.Persistence.IStashOverflowStrategy DefaultInternalStashOverflowStrategy { get; }
public Akka.Persistence.PersistenceSettings Settings { get; }
public Akka.Persistence.Journal.EventAdapters AdaptersFor(string journalPluginId) { }
[Akka.Annotations.InternalStableApiAttribute()]
public Akka.Actor.IActorRef JournalFor(string journalPluginId) { }
public string PersistenceId(Akka.Actor.IActorRef actor) { }
[Akka.Annotations.InternalStableApiAttribute()]
public Akka.Actor.IActorRef SnapshotStoreFor(string snapshotPluginId) { }
}
public sealed class PersistenceSettings : Akka.Actor.Settings
Expand Down
3 changes: 3 additions & 0 deletions src/core/Akka.Persistence/Persistence.cs
Original file line number Diff line number Diff line change
Expand Up @@ -11,6 +11,7 @@
using System.Reflection;
using System.Threading;
using Akka.Actor;
using Akka.Annotations;
using Akka.Configuration;
using Akka.Event;
using Akka.Persistence.Journal;
Expand Down Expand Up @@ -231,6 +232,7 @@ internal Config ConfigFor(IActorRef journalPluginActor)
/// This exception is thrown when either the plugin class name is undefined or the configuration path is missing.
/// </exception>
/// <returns>TBD</returns>
[InternalStableApi]
public IActorRef JournalFor(string journalPluginId)
{
var configPath = string.IsNullOrEmpty(journalPluginId) ? _defaultJournalPluginId.Value : journalPluginId;
Expand All @@ -249,6 +251,7 @@ public IActorRef JournalFor(string journalPluginId)
/// This exception is thrown when either the plugin class name is undefined or the configuration path is missing.
/// </exception>
/// <returns>TBD</returns>
[InternalStableApi]
public IActorRef SnapshotStoreFor(string snapshotPluginId)
{
var configPath = string.IsNullOrEmpty(snapshotPluginId) ? _defaultSnapshotPluginId.Value : snapshotPluginId;
Expand Down
33 changes: 25 additions & 8 deletions src/core/Akka/Annotations/Attributes.cs
Original file line number Diff line number Diff line change
Expand Up @@ -11,34 +11,51 @@ namespace Akka.Annotations
{
/// <summary>
/// Marks APIs that are considered internal to Akka and may change at any point in time without any warning.
///
/// <para>
/// For example, this annotation should be used for code that should be inherently internal, but it cannot be
/// due to limitations of .NET encapsulation in areas such as inheritance or serialization.
///
/// </para>
/// <para>
/// If a method/class annotated with this method has a xdoc comment, the first line MUST include
/// in order to be easily identifiable from generated documentation. Additional information
/// may be put on the same line as the INTERNAL API comment in order to clarify further.
/// </para>
/// </summary>
[AttributeUsage(AttributeTargets.Class | AttributeTargets.Struct | AttributeTargets.Enum | AttributeTargets.Interface | AttributeTargets.Constructor | AttributeTargets.Field | AttributeTargets.Property | AttributeTargets.Method | AttributeTargets.Module, Inherited = true, AllowMultiple = false)]
public sealed class InternalApiAttribute : Attribute
{
}

/// <summary>
/// Marks APIs that are considered internal to Akka and should not be accessed by user code but that are used
/// across Akka project boundaries and therefore shouldn't be changed without considering possible usage
/// outside of the Akka core modules.
/// <para>
/// If a method/class annotated with this annotation is part of a public API there should be a xdoc comment
/// where the first line MUST include INTERNAL API in order to be easily identifiable from generated documentation.
/// Additional information may be put on the same line as the INTERNAL API comment in order to clarify further.
/// </para>
/// </summary>
[AttributeUsage(AttributeTargets.Class | AttributeTargets.Struct | AttributeTargets.Enum | AttributeTargets.Interface | AttributeTargets.Constructor | AttributeTargets.Field | AttributeTargets.Property | AttributeTargets.Method | AttributeTargets.Module, Inherited = true, AllowMultiple = false)]
public sealed class InternalStableApiAttribute : Attribute
{
}

/// <summary>
/// Marks APIs that are meant to evolve towards becoming stable APIs, but are not stable APIs yet.
///
/// <para>
/// Evolving interfaces MAY change from one patch release to another (i.e. 1.3.0 to 1.3.1) without up-front notice.
/// A best-effort approach is taken to not cause more breakage than really neccessary, and usual deprecation techniques
/// are utilised while evolving these APIs, however there is NO strong guarantee regarding the source or binary
/// compatibility of APIs marked using this annotation.
///
/// </para>
/// <para>
/// It MAY also change when promoting the API to stable, for example such changes may include removal of deprecated
/// methods that were introduced during the evolution and final refactoring that were deferred because they would
/// have introduced to much breaking changes during the evolution phase.
///
/// Promoting the API to stable MAY happen in a patch release.
///
/// It is encouraged to document in xmldoc how exactly this API is expected to evolve.
/// </para>
/// <para>Promoting the API to stable MAY happen in a patch release.</para>
/// <para>It is encouraged to document in xmldoc how exactly this API is expected to evolve.</para>
/// </summary>
[AttributeUsage(AttributeTargets.Class | AttributeTargets.Struct | AttributeTargets.Enum | AttributeTargets.Interface | AttributeTargets.Constructor | AttributeTargets.Field | AttributeTargets.Property | AttributeTargets.Method | AttributeTargets.Module, Inherited = true, AllowMultiple = false)]
public sealed class ApiMayChangeAttribute : Attribute
Expand Down
10 changes: 4 additions & 6 deletions src/core/Akka/Dispatch/SysMsg/ISystemMessage.cs
Original file line number Diff line number Diff line change
Expand Up @@ -278,27 +278,25 @@ public interface ISystemMessage : INoSerializationVerificationNeeded
/// <see cref="ISystemMessage"/> is an interface and too basic to express
/// all of the capabilities needed to express a full-fledged system message.
/// </summary>
[InternalApi]
[InternalStableApi]
public abstract class SystemMessage : ISystemMessage
{
/// <summary>
/// The next <see cref="ISystemMessage"/> in the linked list.
/// Next fields are only modifiable via the <see cref="SystemMessageList"/> class.
/// </summary>
[NonSerialized]
internal SystemMessage Next;

/// <summary>
/// Unlinks this message from the linked list.
/// </summary>
public void Unlink()
{
Next = null;
}
public void Unlink() => Next = null;

/// <summary>
/// Returns <c>true</c> if we are unlinked.
/// </summary>
public bool Unlinked { get { return Next == null; } }
public bool Unlinked => Next == null;
}

/// <summary>
Expand Down
2 changes: 2 additions & 0 deletions src/core/Akka/Util/Option.cs
Original file line number Diff line number Diff line change
Expand Up @@ -8,6 +8,7 @@
using System;
using System.Collections.Generic;
using System.Runtime.CompilerServices;
using Akka.Annotations;

namespace Akka.Util
{
Expand All @@ -17,6 +18,7 @@ namespace Akka.Util
/// Useful where distinguishing between null (or zero, or false) and uninitialized is significant.
/// </summary>
/// <typeparam name="T">TBD</typeparam>
[InternalStableApi]
public readonly struct Option<T>
{
[MethodImpl(MethodImplOptions.AggressiveInlining)]
Expand Down
Loading