Skip to content

Commit 65b19a0

Browse files
authored
[Messaging Clients] README Concept Updates (Azure#18804)
The focus of these changes is to add content for lifetime, thread-safety, and additional concepts specific to the messaging clients. The content and format is intended to match the common blocks used by the HTTP-based service clients as closely as reasonable. (see: "Thread safety" and "Additional concepts" here: https://github.com/Azure/azure-sdk-for-net/tree/master/sdk/storage/Azure.Storage.Blobs#thread-safety)
1 parent 7860813 commit 65b19a0

File tree

4 files changed

+48
-1
lines changed

4 files changed

+48
-1
lines changed

sdk/eventhub/Azure.Messaging.EventHubs.Processor/README.md

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -66,6 +66,21 @@ For the event processor client to make use of Azure Storage blobs for checkpoint
6666

6767
For more concepts and deeper discussion, see: [Event Hubs Features](https://docs.microsoft.com/azure/event-hubs/event-hubs-features).
6868

69+
### Client lifetime
70+
71+
The `EventProcessorClient` is safe to cache and use as a singleton for the lifetime of the application, which is best practice when events are being read regularly. The clients are responsible for efficient management of network, CPU, and memory use, working to keep usage low during periods of inactivity. Calling `StopProcessingAsync` or `StopProcessing` on the processor is required to ensure that network resources and other unmanaged objects are properly cleaned up.
72+
73+
### Thread safety
74+
75+
We guarantee that all client instance methods are thread-safe and independent of each other ([guideline](https://azure.github.io/azure-sdk/dotnet_introduction.html#dotnet-service-methods-thread-safety)). This ensures that the recommendation of reusing client instances is always safe, even across threads.
76+
77+
### Additional concepts
78+
79+
<!-- CLIENT COMMON BAR -->
80+
[Client options](https://github.com/Azure/azure-sdk-for-net/blob/master/sdk/eventhub/Azure.Messaging.EventHubs.Processor/samples/Sample02_EventProcessorConfiguration.md#event-processor-configuration) | [Event handlers](https://github.com/Azure/azure-sdk-for-net/blob/master/sdk/eventhub/Azure.Messaging.EventHubs.Processor/samples/Sample03_EventProcessorHandlers.md) | [Handling failures](#exception-handling) | [Diagnostics](#logging-and-diagnostics) |
81+
[Mocking](https://github.com/Azure/azure-sdk-for-net/blob/master/sdk/core/Azure.Core/README.md#mocking)
82+
<!-- CLIENT COMMON BAR -->
83+
6984
## Examples
7085

7186
### Creating an Event Processor client

sdk/eventhub/Azure.Messaging.EventHubs/README.md

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -59,6 +59,21 @@ For the Event Hubs client library to interact with an Event Hub, it will need to
5959

6060
For more concepts and deeper discussion, see: [Event Hubs Features](https://docs.microsoft.com/azure/event-hubs/event-hubs-features).
6161

62+
### Client lifetime
63+
64+
Each of the Event Hubs client types is safe to cache and use as a singleton for the lifetime of the application, which is best practice when events are being published or read regularly. The clients are responsible for efficient management of network, CPU, and memory use, working to keep usage low during periods of inactivity. Calling either `CloseAsync` or `DisposeAsync` on a client is required to ensure that network resources and other unmanaged objects are properly cleaned up.
65+
66+
### Thread safety
67+
68+
We guarantee that all client instance methods are thread-safe and independent of each other ([guideline](https://azure.github.io/azure-sdk/dotnet_introduction.html#dotnet-service-methods-thread-safety)). This ensures that the recommendation of reusing client instances is always safe, even across threads.
69+
70+
### Additional concepts
71+
72+
<!-- CLIENT COMMON BAR -->
73+
[Client options](https://github.com/Azure/azure-sdk-for-net/blob/master/sdk/eventhub/Azure.Messaging.EventHubs/samples/Sample02_EventHubsClients.md#configuration) | [Handling failures](#exception-handling) | [Diagnostics](#logging-and-diagnostics) |
74+
[Mocking](https://github.com/Azure/azure-sdk-for-net/blob/master/sdk/core/Azure.Core/README.md#mocking)
75+
<!-- CLIENT COMMON BAR -->
76+
6277
## Examples
6378

6479
### Inspect an Event Hub

sdk/eventhub/Azure.Messaging.EventHubs/samples/Sample02_EventHubsClients.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -24,7 +24,7 @@ The mainstream set of clients provides an approachable onboarding experience for
2424

2525
## Lifetime
2626

27-
Each of the Event Hubs client types is safe to cache and use for the lifetime of the application, which is best practice when the application publishes or reads events regularly or semi-regularly. The clients are responsible for efficient resource management, working to keep resource usage low during periods of inactivity and manage health during periods of higher use. Calling either the `CloseAsync` or `DisposeAsync` method on a client as the application is shutting down will ensure that network resources and other unmanaged objects are properly cleaned up.
27+
Each of the Event Hubs client types is safe to cache and use as a singleton for the lifetime of the application, which is best practice when events are being published or read regularly. The clients are responsible for efficient management of network, CPU, and memory use, working to keep usage low during periods of inactivity. Calling either `CloseAsync` or `DisposeAsync` on a client is required to ensure that network resources and other unmanaged objects are properly cleaned up.
2828

2929
## Configuration
3030

sdk/servicebus/Azure.Messaging.ServiceBus/README.md

Lines changed: 17 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -88,6 +88,23 @@ To interact with these resources, one should be familiar with the following SDK
8888

8989
For more concepts and deeper discussion, see: [Service Bus Advanced Features](https://docs.microsoft.com/azure/service-bus-messaging/service-bus-messaging-overview#advanced-features).
9090

91+
### Client lifetime
92+
93+
The `ServiceBusClient`, senders, receivers, and processors are safe to cache and use as a singleton for the lifetime of the application, which is best practice when messages are being sent or received regularly. They are responsible for efficient management of network, CPU, and memory use, working to keep usage low during periods of inactivity.
94+
95+
These types are disposable and calling either `DisposeAsync` or `CloseAsync` is required to ensure that network resources and other unmanaged objects are properly cleaned up. It is important to note that when a `ServiceBusClient` instance is disposed, it will automatically close and cleanup any senders, receivers, and processors that were created using it.
96+
97+
### Thread safety
98+
99+
We guarantee that all client instance methods are thread-safe and independent of each other ([guideline](https://azure.github.io/azure-sdk/dotnet_introduction.html#dotnet-service-methods-thread-safety)). This ensures that the recommendation of reusing client instances is always safe, even across threads.
100+
101+
### Additional concepts
102+
103+
<!-- CLIENT COMMON BAR -->
104+
[Client options](https://github.com/Azure/azure-sdk-for-net/blob/master/sdk/core/Azure.Core/README.md#configuring-service-clients-using-clientoptions) | [Handling failures](#exception-handling) | [Diagnostics](#logging-and-diagnostics) |
105+
[Mocking](https://github.com/Azure/azure-sdk-for-net/blob/master/sdk/core/Azure.Core/README.md#mocking)
106+
<!-- CLIENT COMMON BAR -->
107+
91108
## Examples
92109

93110
* [Send and receive a message](#send-and-receive-a-message)

0 commit comments

Comments
 (0)