Providers

A provider is an exchangeable backend of a Pulse plugin: where save games are kept, who a player is, where definitions come from. Every plugin ships a default provider that works without setup. A game that needs something else (a cloud, a database of the studio, a console’s own storage) derives its own provider in C++ or Blueprint and picks it in the plugin’s settings or at runtime. The plugin talks to every provider the same way, so nothing else changes.

All providers derive from UPulseProvider (Providers/PulseProvider.h). The base keeps the open requests of a provider and guarantees:

  • Exactly one answer per request. An operation may answer at once (inside the call) or later (from a task, a web request, a timer). A second or late answer is ignored with a warning in the log.
  • Timeouts. A request that waits longer than its timeout answers Pulse.Result.Failure.Timeout (real time, 30 seconds unless the provider or the operation says otherwise; 0 waits forever).
  • Cancel and end. CancelRequest and the end of the provider answer Pulse.Result.Failure.Cancelled (unlike Cancel Pulse Request of the request subsystem, which forgets a request without an answer). A request made after the end is answered Cancelled on the next tick.
  • The game thread. Callbacks always run on the game thread. A provider chooses when: Inline (the default: inside Finish Request, so an answer given inside the operation reaches the caller before the operation returns) or Next Tick (a caller never gets its answer inside its own call).
  • Tasks. Disk and network work never block the game thread: a provider starts it on a task, and the task posts its answer to the provider’s inbox (GetInbox(), a thread-safe shared pointer). The task never touches the provider object, so it may outlive it.
  • Debugging. Request ids are unique in the process. Each request is a bar in the debug timeline (one lane per provider class), and the snapshot of a provider (category Providers, a plugin may override GetDebugCategory) lists its open requests with their age.

Answers are an FPulseResult (a reason tag on failure; leave its message empty, the reason has a text) and an optional struct with the data of the answer.

How a plugin defines a provider

The plugin derives an abstract provider class with its operations. Each operation is a BlueprintNativeEvent that receives the request id; a typed Finish function answers it. A C++ entry for the callers opens the request and calls the operation:

UCLASS(Abstract, Blueprintable)
class UMyScoreProvider : public UPulseProvider
{
	GENERATED_BODY()

public:

	/** C++ entry: asks for the best score of a player. */
	void ReadBestScore(const FString& InPlayerKey, TFunction<void(const FPulseResult&, const FMyScore&)> InDone)
	{
		const FPulseRequestId id = BeginProviderRequest(TEXT("ReadBestScore"), Pulse::Providers::MakeCallback<FMyScore>(MoveTemp(InDone)));

		// An ended provider answers Cancelled by itself
		if (CanStartRequests())
			ReadBest(id, InPlayerKey);
	}

protected:

	/** The operation: a provider answers with Finish Read Best. */
	UFUNCTION(BlueprintNativeEvent, Category = "My Game|Scores")
	void ReadBest(FPulseRequestId RequestId, const FString& PlayerKey);

	/** Answers Read Best. */
	UFUNCTION(BlueprintCallable, Category = "My Game|Scores", meta = (BlueprintProtected))
	void FinishReadBest(FPulseRequestId RequestId, const FPulseResult& Result, int32 Score)
	{
		FMyScore score;
		score.Value = Score;

		FinishRequest(RequestId, Result, FInstancedStruct::Make(score));
	}
};

Pulse::Providers::MakeCallback<T> turns a typed function into the callback of a request: a successful answer without a T becomes a failure with Pulse.Result.Failure.Invalid (logged), a failure keeps its reason. Pulse::Providers::MakeResultCallback is the same for operations without data (a write, a delete). Callbacks capture objects weakly: a request may be answered after the caller is gone.

How a game writes its own provider

Blueprint: create a Blueprint class of the plugin’s provider class (the plugin lists it under Create in the Pulse window), override its operations and call the Finish function, at once or later, for example after an HTTP request finished. On Initialize and On Deinitialize run when the plugin starts and ends the provider; Get Default Timeout sets the timeout of its requests. Pick the class in the plugin’s settings.

An event of the event graph keeps only its last parameters: when a second request arrives while the first one waits (for an HTTP answer, a delay), the Request Id pin already shows the second one. Keep the id with the thing you wait for (a map from the HTTP request to the id, or a variable per request) and answer with that id.

C++: derive from the plugin’s provider class, override the _Implementation of each operation and call the Finish function. Long work goes on a task that keeps the inbox, never the provider:

void UMyScoreProvider_Backend::ReadBest_Implementation(FPulseRequestId RequestId, const FString& PlayerKey)
{
	// The task posts to the inbox; the provider takes the answer on the game thread (also while it ends)
	TSharedRef<FPulseProviderInbox, ESPMode::ThreadSafe> inbox = GetInbox();

	UE::Tasks::Launch(UE_SOURCE_LOCATION, [inbox, RequestId, PlayerKey]()
	{
		FMyScore score;
		const bool bOk = MyBackend::ReadBest(PlayerKey, score.Value);

		inbox->Post(RequestId, bOk ? FPulseResult::Success() : FPulseResult::Failure(TAG_MyReason_BackendDown), FInstancedStruct::Make(score));
	});
}

A provider whose tasks must land before it ends (writes) waits for them in On Deinitialize; the answers they posted are taken before the open requests are cancelled.

How a plugin holds its provider

TPulseProviderSlot<T> is the active provider of one purpose. The plugin keeps one in the object that uses the provider (a subsystem), points it at its settings and offers Get and Set functions to the game:

// Initialize of the subsystem: the class in the settings is read when the provider is first needed
Scores.Init(this, []() { return GetDefault<UMyScoreSettings>()->ProviderClass; });

// Use
if (UMyScoreProvider* provider = Scores.Get())
	provider->ReadBestScore(Key, ...);

// The game sets another one at runtime; Set(nullptr) turns the purpose off, Reset goes back to the settings
Scores.Set(MyProvider);

// Deinitialize of the subsystem: the provider ends, Get answers null from now on
Scores.Shutdown();

The slot makes the provider in the transient package (it finds its world through the owner, so Blueprint providers can use world context nodes), initializes it and keeps it alive. A provider the slot lets go is deinitialized after the slot took its new state, so the callbacks of the cancelled requests already see the new provider. A provider works for one owner: the slot refuses one that another owner uses or that ended (CanSet tells it before). A settings class that does not load or is abstract is logged once and the purpose stays off until a class is set again. OnChanged tells when the provider changed.

Providers of Pulse Foundation

A provider that answers a quick question the same way on every machine needs no request: its operation is a BlueprintNativeEvent that returns the answer.

Purpose Provider class Held by Setting
Who a player is UPulsePlayerIdentityProvider (answers at once) UPulsePlayerIdentitySubsystem (game instance) Player Identity Provider
Where definitions come from UPulseDefinitionCatalog (Find and Get answer at once, Load Definition is a request) UPulseDefinitionSubsystem (game instance), one catalog per kind Default Definition Catalog, Definition Catalogs
Which phase the game is in UPulseGamePhaseSource (hears the level changes, sets the phase) UPulseGamePhaseSubsystem (game instance) Game Phase Source
Where player settings are kept UPulsePlayerSettingsStorage (Load Settings and Save Settings are requests; the default answers at once) UPulseSettingsSubsystem (local player) Player Settings Storage

Rules

  • A provider keeps no state per player outside its own maps by owner or player key.
  • A provider never blocks the game thread.
  • The plugin that defines a provider registers its reasons (Pulse::Results::RegisterReason).
  • Every plugin ships a default provider that works like the plugin did before, so a project needs no new step.

Spec: PulseFoundation.Providers.


PulseFoundation plugin documentation.

This site uses Just the Docs, a documentation theme for Jekyll.