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​

ParameterConstraintDefaultDescription
TEventISharedObjectEventsISharedObjectEvents

Constructors​

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

Properties​

PropertyTypeDescription
attributesIChannelAttributes
connectedbooleanGets the connection state
handleIFluidHandleThe handle referring to this SharedObject
idstring
IFluidLoadablethis
loggerITelemetryLoggerTelemetry logger for the shared object
runtimeIFluidDataStoreRuntime

Methods​

MethodReturn TypeDescription
applyStashedOp(content)unknownApply 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()voidBinds the given shared object to its containing data store runtime, causing it to attach once the runtime attaches.
connect(services)voidEnables the channel to send and receive ops.
didAttach()voidAllows 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()voidMarks 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)ISummaryTreeWithStatsGenerates 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)IGarbageCollectionDataReturns the GC data for this shared object. It contains a list of GC nodes that contains references to other GC nodes.
handleDecoded(decodedHandle)voidCalled 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()voidInitializes the object as a local, non-shared object. This object can become shared after it is attached to the document.
initializeLocalCore()voidAllows the distributed data type to perform custom local loading.
isAttached()booleanChecks 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()voidCalled when the object has fully connected to the delta stream Default implementation for DDS, override if different behavior is required.
onDisconnect()anyCalled when the object has disconnected from the delta stream.
processCore(message, local, localOpMetadata)anyDerived classes must override this to do custom processing on a remote message.
reSubmitCore(content, localOpMetadata)voidCalled 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)voidRevert an op
submitLocalMessage(content, localOpMetadata)voidSubmits 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​

ParameterTypeDescription
idstringThe id of the shared object
runtimeIFluidDataStoreRuntimeThe IFluidDataStoreRuntime which contains the shared object
attributesIChannelAttributesAttributes 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​

ParameterTypeDescription
contentanyContents 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​

ParameterTypeDescription
servicesIChannelServicesServices 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​

ParameterModifiersTypeDescription
fullTreeoptionalbooleanflag indicating whether the attempt should generate a full summary tree without any handles for unchanged subtrees.
trackStateoptionalbooleanoptimization 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
telemetryContextoptionalITelemetryContext

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​

ParameterModifiersTypeDescription
fullGCoptionalbooleantrue 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​

ParameterTypeDescription
decodedHandleIFluidHandleThe 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​

ParameterTypeDescription
servicesIChannelServicesServices 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​

ParameterTypeDescription
servicesIChannelStorageServiceStorage 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​
ParameterDescription
T

Parameters​

ParameterTypeDescription
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​

ParameterTypeDescription
messageISequencedDocumentMessageThe message to process
localbooleanTrue if the shared object is local
localOpMetadataunknownFor 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​

ParameterTypeDescription
contentanyThe content of the original message.
localOpMetadataunknownThe local metadata associated with the original message.

rollback​

Revert an op

Signature​

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

Parameters​

ParameterTypeDescription
contentany
localOpMetadataunknown

submitLocalMessage​

Submits a message by the local client to the runtime.

Signature​

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

Parameters​

ParameterModifiersTypeDescription
contentanyContent of the message
localOpMetadataoptionalunknownThe 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​

ParameterModifiersTypeDescription
fullTreeoptionalbooleanflag 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.
trackStateoptionalbooleanThis tells whether we should track state from this summary.
telemetryContextoptionalITelemetryContext

Returns​

A summary capturing the current state of the channel.

Return type: Promise<ISummaryTreeWithStats>