Loader

Description

sealed class Tinman.Engine.Scenes.Util.Loader

Derived from

Disposable abstract

A helper class for loading objects asynchronously using background tasks.

To set up a Loader object, performs the following steps:

  1. Choose a base path to use for resolving relative paths (see BasePath) and create a Loader object.

  2. Call Begin to start submitting load jobs, using the specified LoaderDelegate. The static Load* methods of this class perform loading of various built-in objects. With the Wrap method, IHeightmapProvider object can be used directly.

  3. Use Load1, Load2, PushLoad1 and PushLoad2 to start loading objects asynchronously.

  4. Call End once for each call to Begin.

  5. Use Wait and IsIdle to query the status of the pending load jobs. The Get, GetNull and PopLoad method can be used to fetch the loaded objects.

The Loader uses canonical Path values to identify objects and their associated load jobs. To obtain that value up-front without loading any object, use the Normalize method.

See also

TaskPool

Public / Constructors

Loader

public constructor Loader → (1)

basePath opt : Path = null

The base path to use for resolving relative paths or null to use the canonical form of Path.Current.

Creates a new instance of Loader.

Public / Methods

Begin

public method Begin → (1)

loader in : LoaderDelegate

[not-null]
The loader delegate to use.

returns → Loader

this

Begins a loader cycle.

For each call to Begin, the End method must be called once.

End

public method End → ()

returns → Loader

this

Ends the current loader cycle.

See also

Loader.Begin

Get

[OwnerReturn]
public method Get → (1) → <TObject ref>

path in : Path

Normalized path to an object being loaded, see Normalize.

returns → TObject

The loaded object.

Fetches the result of the given load job, waiting for it to finish if necessary.

If an object has been loaded but the requested type does not match, DisposableUtil.DisposeOrDelete is used to dispose the loaded object.

IOException

If the load job has failed, in which case the result is considered having been fetched, or if GetNull would have returned null, indicated by IOError.BadPath.

See also

Loader.Load1
Loader.Load2

Get​Null

[OwnerReturn]
public method GetNull → (1) → <TObject ref>

path in : Path

Normalized path to an object being loaded, see Normalize.

returns → TObject

The loaded object or null if path in is null, if the requested type does not match or if the result has already been fetched.

Fetches the result of the given load job, waiting for it to finish if necessary.

If an object has been loaded but the requested type does not match, DisposableUtil.DisposeOrDelete is used to dispose the loaded object.

IOException

If the load job has failed, in which case the result is considered having been fetched.

See also

Loader.Load1
Loader.Load2

Load

2 overloads

[BeginEnd]
public method Load1 → (1)

path in : string

[not-null]
Path to the object to load, which will be normalized.

returns → Path

The normalized path that identifies the load job.

Submits a load job for the given object.

See also

Loader.Normalize

[BeginEnd]
public method Load2 → (1)

path in : Path

[not-null]
Path to the object to load, which will be normalized.

returns → Path

The normalized path that identifies the load job.

Submits a load job for the given object.

See also

Loader.Normalize

Load​Heightmap

[OwnerReturn] [ThrowAny]
public static method LoadHeightmap → (1)

path in : Path

Path to the heightmap dataset to load.

returns → object

The loaded heightmap dataset.

A LoaderDelegate that uses DatasetCollection.Open4 of Heightmap.Datasets.

Load​Shape

[ThrowAny]
public static method LoadShape → (1)

path in : Path

Path to the shape to load.

returns → object

The loaded shape.

A LoaderDelegate that uses IShapeReader.ReadAll of ShapeFormat.ReadShapes1 of ShapeFormat.Any.

TinmanException

If loading has failed.

Normalize

[Pure]
public method Normalize → (1)

path in : Path

Path to an object or null.

returns → Path

The canonical form of path in, resolved against BasePath if necessary. Will be null or Path.Unknown iff path in has the respective value.

Normalizes the given object path.

See also

Loader.Load1
Loader.Load2
Loader.PushLoad1
Loader.PushLoad2

Pop​Load

[OwnerReturn]
public method PopLoad → (1) → <TObject ref>

fetch opt : bool = true

If false, the method does nothing and just returns null.

returns → TObject

The loaded object or null iff the queue is empty.

Fetches the result of the oldest load job in the internal queue, waiting for it to finish if necessary.

If an object has been loaded but the requested type does not match, DisposableUtil.DisposeOrDelete is used to dispose the loaded object.

IOException

If the load job has failed, in which case the result is considered having been fetched, or if GetNull would have returned null, indicated by IOError.BadPath.

See also

Loader.PushLoad1
Loader.PushLoad2

Push​Load

2 overloads

[BeginEnd]
public method PushLoad1 → (1)

path in : string

[not-null]
Path to the object to load, which will be normalized.

returns → Loader

this

Calls Load1 and queues the resulting load job in an internal list.

See also

Loader.PopLoad

[BeginEnd]
public method PushLoad2 → (1)

path in : Path

[not-null]
Path to the object to load, which will be normalized.

returns → Loader

this

Calls Load2 and queues the resulting load job in an internal list.

See also

Loader.PopLoad

Wait

public method Wait → (2)

path opt : Path = null

Normalized path to an object being loaded, see Normalize. If null, the methods waits for all jobs to finish.

timeout opt : int32 = 0

[>=0]
Optional timeout in milliseconds. If 0, this method only checks that status of the load job.

returns → int32

-1 : if there are no load jobs,
0 : if at least one object is being loaded,
+1 : if loading is complete and the objects may be fetched.

Waits for load jobs to finish.

Wrap

public static method Wrap → (2)

provider in : IHeightmapProvider

[not-null]
The provider to wrap.

readOnly opt : bool = true

The argument to pass to IHeightmapProvider.OpenHeightmapDataset.

returns → LoaderDelegate

The wrapping delegate.

Wraps the given IHeightmapProvider in aLoaderDelegate.

Public / Attributes

Base​Path

[Constant]
public attribute BasePath → (get)

value : Path

[not-null]
The base path, in canonical form.

Returns the base path of this loader.

The base path is used by Normalize to resolve relative paths.

See also

Path.Canonical

Is​Idle

public attribute IsIdle → (get)

value : bool

true if one or more object are being loaded,
false if there are no pending load jobs.

Checks if there are any background tasks that are loading an object.