Skip to main content
Version: v1

SharedObjectCore Class

Base class from which all shared objects derive

Signature​

export declare abstract class SharedObjectCore<TEvent extends ISharedObjectEvents = ISharedObjectEvents> extends EventEmitterWithErrorHandling<TEvent> implements ISharedObject<TEvent>

Extends: EventEmitterWithErrorHandling

Implements: ISharedObject

Type Parameters​

Parameter Constraint Default Description
TEvent ISharedObjectEvents ISharedObjectEvents

Constructors​

Constructor Description
(constructor)(id, runtime, attributes) Constructs a new instance of the SharedObjectCore class

Properties​

Property Type Description
attributes IChannelAttributes
connected boolean Gets the connection state
handle IFluidHandle The handle referring to this SharedObject
id string
IFluidLoadable this
logger ITelemetryLogger Telemetry logger for the shared object
runtime IFluidDataStoreRuntime

Methods​

Method Return Type Description
applyStashedOp(content) unknown Apply changes from an op. Used when rehydrating an attached container with pending changes. This prepares the SharedObject for seeing an ACK for the op or resubmitting the op upon reconnection.
bindToContext() void Binds the given shared object to its containing data store runtime, causing it to attach once the runtime attaches.
connect(services) void Enables the channel to send and receive ops.
didAttach() void Allows the distributive data type the ability to perform custom processing once an attach has happened. Also called after non-local data type get loaded.
dirty() void Marks this object as dirty so that it is part of the next summary. It is called by a SharedSummaryBlock that want to be part of summary but does not generate ops.
getAttachSummary(fullTree, trackState, telemetryContext) ISummaryTreeWithStats Generates summary of the channel synchronously. It is called when an attach message for a local channel is generated. In other words, when the channel is being attached to make it visible to other clients. Note: Since Attach Summary is generated for local channels when making them visible to remote clients, they don't have any previous summaries to compare against. For this reason, The attach summary cannot contain summary handles (paths to sub-trees or blobs). It can, however, contain ISummaryAttachment (handles to blobs uploaded async via the blob manager).
getGCData(fullGC) IGarbageCollectionData Returns the GC data for this shared object. It contains a list of GC nodes that contains references to other GC nodes.
handleDecoded(decodedHandle) void Called when a handle is decoded by this object. A handle in the object's data represents an outbound reference to another object in the container.
initializeLocal() void Initializes the object as a local, non-shared object. This object can become shared after it is attached to the document.
initializeLocalCore() void Allows the distributed data type to perform custom local loading.
isAttached() boolean Checks if the channel is attached to storage.
load(services) Promise<void> A shared object, after construction, can either be loaded in the case that it is already part of a shared document. Or later attached if it is being newly added.
loadCore(services) Promise<void> Allows the distributed data type to perform custom loading
newAckBasedPromise(executor) Promise<T> Promises that are waiting for an ack from the server before resolving should use this instead of new Promise. It ensures that if something changes that will interrupt that ack (e.g. the FluidDataStoreRuntime disposes), the Promise will reject. If runtime is disposed when this call is made, executor is not run and promise is rejected right away.
onConnect() void Called when the object has fully connected to the delta stream Default implementation for DDS, override if different behavior is required.
onDisconnect() any Called when the object has disconnected from the delta stream.
processCore(message, local, localOpMetadata) any Derived classes must override this to do custom processing on a remote message.
reSubmitCore(content, localOpMetadata) void Called when a message has to be resubmitted. This typically happens after a reconnection for unacked messages. The default implementation here is to resubmit the same message. The client can override if different behavior is required. It can choose to resubmit the same message, submit different / multiple messages or not submit anything at all.
rollback(content, localOpMetadata) void Revert an op
submitLocalMessage(content, localOpMetadata) void Submits a message by the local client to the runtime.
summarize(fullTree, trackState, telemetryContext) Promise<ISummaryTreeWithStats> Generates summary of the channel asynchronously. This should not be called where the channel can be modified while summarization is in progress.

Constructor Details​

(constructor)​

Constructs a new instance of the SharedObjectCore class

Signature​

constructor(id: string, runtime: IFluidDataStoreRuntime, attributes: IChannelAttributes);

Parameters​

Parameter Type Description
id string The id of the shared object
runtime IFluidDataStoreRuntime The IFluidDataStoreRuntime which contains the shared object
attributes IChannelAttributes Attributes of the shared object

Property Details​

attributes​

Signature​

readonly attributes: IChannelAttributes;

Type: IChannelAttributes

connected​

Gets the connection state

Signature​

get connected(): boolean;

Type: boolean

handle​

The handle referring to this SharedObject

Signature​

readonly handle: IFluidHandle;

Type: IFluidHandle

id​

Signature​

id: string;

Type: string

IFluidLoadable​

Signature​

get IFluidLoadable(): this;

Type: this

logger​

Telemetry logger for the shared object

Signature​

protected readonly logger: ITelemetryLogger;

Type: ITelemetryLogger

runtime​

Signature​

protected runtime: IFluidDataStoreRuntime;

Type: IFluidDataStoreRuntime

Method Details​

applyStashedOp​

Apply changes from an op. Used when rehydrating an attached container with pending changes. This prepares the SharedObject for seeing an ACK for the op or resubmitting the op upon reconnection.

Signature​

protected abstract applyStashedOp(content: any): unknown;

Parameters​

Parameter Type Description
content any Contents of a stashed op.

Returns​

localMetadata of the op, to be passed to process() or resubmit() when the op is ACKed or resubmitted, respectively

Return type: unknown

bindToContext​

Binds the given shared object to its containing data store runtime, causing it to attach once the runtime attaches.

Signature​

bindToContext(): void;

connect​

Enables the channel to send and receive ops.

Signature​

connect(services: IChannelServices): void;

Parameters​

Parameter Type Description
services IChannelServices Services to connect to

didAttach​

Allows the distributive data type the ability to perform custom processing once an attach has happened. Also called after non-local data type get loaded.

Signature​

protected didAttach(): void;

dirty​

Marks this object as dirty so that it is part of the next summary. It is called by a SharedSummaryBlock that want to be part of summary but does not generate ops.

Signature​

protected dirty(): void;

getAttachSummary​

Generates summary of the channel synchronously. It is called when an attach message for a local channel is generated. In other words, when the channel is being attached to make it visible to other clients. Note: Since Attach Summary is generated for local channels when making them visible to remote clients, they don't have any previous summaries to compare against. For this reason, The attach summary cannot contain summary handles (paths to sub-trees or blobs). It can, however, contain ISummaryAttachment (handles to blobs uploaded async via the blob manager).

Signature​

abstract getAttachSummary(fullTree?: boolean, trackState?: boolean, telemetryContext?: ITelemetryContext): ISummaryTreeWithStats;

Parameters​

Parameter Modifiers Type Description
fullTree optional boolean flag indicating whether the attempt should generate a full summary tree without any handles for unchanged subtrees.
trackState optional boolean optimization for tracking state of objects across summaries. If the state of an object did not change since last successful summary, an ISummaryHandle can be used instead of re-summarizing it. If this is false, the expectation is that you should never send an ISummaryHandle since you are not expected to track state. Note: The goal is to remove the trackState and automatically decided whether the handles will be used or not: https://github.com/microsoft/FluidFramework/issues/10455
telemetryContext optional ITelemetryContext

Returns​

A summary capturing the current state of the channel.

Return type: ISummaryTreeWithStats

getGCData​

Returns the GC data for this shared object. It contains a list of GC nodes that contains references to other GC nodes.

Signature​

abstract getGCData(fullGC?: boolean): IGarbageCollectionData;

Parameters​

Parameter Modifiers Type Description
fullGC optional boolean true to bypass optimizations and force full generation of GC data.

Returns​

Return type: IGarbageCollectionData

handleDecoded​

Called when a handle is decoded by this object. A handle in the object's data represents an outbound reference to another object in the container.

Signature​

protected handleDecoded(decodedHandle: IFluidHandle): void;

Parameters​

Parameter Type Description
decodedHandle IFluidHandle The handle of the Fluid object that is decoded.

initializeLocal​

Initializes the object as a local, non-shared object. This object can become shared after it is attached to the document.

Signature​

initializeLocal(): void;

initializeLocalCore​

Allows the distributed data type to perform custom local loading.

Signature​

protected initializeLocalCore(): void;

isAttached​

Checks if the channel is attached to storage.

Signature​

isAttached(): boolean;

Returns​

True iff the channel is attached.

Return type: boolean

load​

A shared object, after construction, can either be loaded in the case that it is already part of a shared document. Or later attached if it is being newly added.

Signature​

load(services: IChannelServices): Promise<void>;

Parameters​

Parameter Type Description
services IChannelServices Services used by the shared object

Returns​

Return type: Promise<void>

loadCore​

Allows the distributed data type to perform custom loading

Signature​

protected abstract loadCore(services: IChannelStorageService): Promise<void>;

Parameters​

Parameter Type Description
services IChannelStorageService Storage used by the shared object

Returns​

Return type: Promise<void>

newAckBasedPromise​

Promises that are waiting for an ack from the server before resolving should use this instead of new Promise. It ensures that if something changes that will interrupt that ack (e.g. the FluidDataStoreRuntime disposes), the Promise will reject. If runtime is disposed when this call is made, executor is not run and promise is rejected right away.

Signature​

protected newAckBasedPromise<T>(executor: (resolve: (value: T | PromiseLike<T>) => void, reject: (reason?: any) => void) => void): Promise<T>;
Type Parameters​
Parameter Description
T

Parameters​

Parameter Type Description
executor (resolve: (value: T | PromiseLike<T>) => void, reject: (reason?: any) => void) => void

Returns​

Return type: Promise<T>

onConnect​

Called when the object has fully connected to the delta stream Default implementation for DDS, override if different behavior is required.

Signature​

protected onConnect(): void;

onDisconnect​

Called when the object has disconnected from the delta stream.

Signature​

protected abstract onDisconnect(): any;

Returns​

Return type: any

processCore​

Derived classes must override this to do custom processing on a remote message.

Signature​

protected abstract processCore(message: ISequencedDocumentMessage, local: boolean, localOpMetadata: unknown): any;

Parameters​

Parameter Type Description
message ISequencedDocumentMessage The message to process
local boolean True if the shared object is local
localOpMetadata unknown For local client messages, this is the metadata that was submitted with the message. For messages from a remote client, this will be undefined.

Returns​

Return type: any

reSubmitCore​

Called when a message has to be resubmitted. This typically happens after a reconnection for unacked messages. The default implementation here is to resubmit the same message. The client can override if different behavior is required. It can choose to resubmit the same message, submit different / multiple messages or not submit anything at all.

Signature​

protected reSubmitCore(content: any, localOpMetadata: unknown): void;

Parameters​

Parameter Type Description
content any The content of the original message.
localOpMetadata unknown The local metadata associated with the original message.

rollback​

Revert an op

Signature​

protected rollback(content: any, localOpMetadata: unknown): void;

Parameters​

Parameter Type Description
content any
localOpMetadata unknown

submitLocalMessage​

Submits a message by the local client to the runtime.

Signature​

protected submitLocalMessage(content: any, localOpMetadata?: unknown): void;

Parameters​

Parameter Modifiers Type Description
content any Content of the message
localOpMetadata optional unknown The local metadata associated with the message. This is kept locally by the runtime and not sent to the server. This will be sent back when this message is received back from the server. This is also sent if we are asked to resubmit the message.

summarize​

Generates summary of the channel asynchronously. This should not be called where the channel can be modified while summarization is in progress.

Signature​

abstract summarize(fullTree?: boolean, trackState?: boolean, telemetryContext?: ITelemetryContext): Promise<ISummaryTreeWithStats>;

Parameters​

Parameter Modifiers Type Description
fullTree optional boolean flag indicating whether the attempt should generate a full summary tree without any handles for unchanged subtrees. It is only set to true when generating a summary from the entire container.
trackState optional boolean This tells whether we should track state from this summary.
telemetryContext optional ITelemetryContext

Returns​

A summary capturing the current state of the channel.

Return type: Promise<ISummaryTreeWithStats>