 |
MySQL 9.1.0
Source Code Documentation
|
|
MySQL 9.1.0
Source Code Documentation
|
A reference caching channel service. More...
#include <reference_caching.h>
Public Attributes | |
| mysql_service_status_t(* | create )(const char *service_names[], reference_caching_channel *out_channel) |
| Creates a channel and returns a handle for it. More... | |
| mysql_service_status_t(* | destroy )(reference_caching_channel channel) |
| Destroys a channel handle. More... | |
| mysql_service_status_t(* | invalidate )(reference_caching_channel channel) |
| Invalidate a channel. More... | |
A reference caching channel service.
The goal of this service is to ensure that event producers spend a MINIMAL amount of time in the emitting code when there are no consumers of the produced events.
An event consumer is an implementation of a component service. An event producer is a piece of code that wants to inform all currently registered event consumers about an event. A channel is a device that serves as a singleton of all reference caches for all threads that are to produce events. A reference cache is something each thread producing events must maintain for its lifetime and use it to find the references to event consumers it needs to call.
At init time the event consumer will register implementations of any of the services it's interested in receiving notifications for.
Then optionally it might force a channel invalidation to make sure all existing event producers will start sending notifications to it immediately. Or it can just sit and wait for the natural producer's reference cache refresh cycles to kick in.
Now it is receiving notifications from all event producers as they come.
When it wishes to no longer receive notifications it needs to mark itself as invisible for reference cache fill-ins. In this way all reference cache flushes will not pick this implementation up even if it's still registered in the registry.
Eventually all active references will be removed by the natural producers flush cycles. The consumer may choose to expedite this by triggering a channel invalidation.
As with all service implementations, when all references to the services are released it can unload.
An event producer will usually start at init time by creating channel(s).
Then, for each thread wishing to produce events, a reference cache must be created and maintained until the thread will no longer be producing events.
Now the thread can produce events using the reference cache. This is done by calling the get method and then iterating over the resulting set of references and calling each one in turn as one would normally do for registry service references. It is assumed that the references are owned by the cache and thus they should not be released.
With some cyclical (e.g. at the end of each statement or something) the event producing thread needs to flush the cache. This is to ensure that references to event consumers are not held for very long and that new event consumers are picked up. However flushing the cache is a relatively expensive operation and thus a balance between the number of events produced and the cache being flushed must be achieved.
Channels are something each event producer must have to produce events. Channels are to be created by a single thread before the first event is ever produced. And, once created they are to be kept until after the last event is produced.
Channels serve as singletons for caches and you only need one channel instance per event producer component. There usually will be multiple caches (one per event producing thread) per channel.
Creating and destroying a channel is a relatively "expensive" operation that might involve some synchronization and should not be done frequently.
Channels exist to allow a non-related thread to trigger invalidation of all currently active caches on that channel. This is necessary when for example event consumers are registered and are about to be removed.
Invalidating a channel is a thread-safe operation that can be invoked without synchronization at any time.
Each channel is associated with a specific set of service names.
The names are stored and used in event caches to handle all implementations of that particular service.
| mysql_service_status_t(* s_mysql_reference_caching_channel::create) (const char *service_names[], reference_caching_channel *out_channel) |
Creates a channel and returns a handle for it.
The handle created by this method must be destroyed by the invalidate method otherwise there might be leaks.
The channel should be created before any events are to be produced on it.
| service_names | a list of service names that this channel will operate on. Terminated by a NULL pointer | |
| [out] | out_channel | placeholder for the newly created handle. |
| false | success |
| true | failure |
| mysql_service_status_t(* s_mysql_reference_caching_channel::destroy) (reference_caching_channel channel) |
Destroys a channel handle.
Should make sure no other thread is using the handle and no caches are allocated on it.
| channel | the handle to destroy |
| false | success |
| true | failure |
| mysql_service_status_t(* s_mysql_reference_caching_channel::invalidate) (reference_caching_channel channel) |
Invalidate a channel.
This is thread safe to call without synchronization and relatively fast.
Forces an asynchronous flush on all caches that are allocated on that channel when they're next accessed.
| channel | the handle to destroy |
| false | success |
| true | failure |
1.9.2