Documentation
¶
Index ¶
Constants ¶
This section is empty.
Variables ¶
var ( // ErrTooManyRequests occurs when there are too many requests, // usually byproducts of infinite loops. // // Format: // "too many requests" ErrTooManyRequests error = errors.New("too many requests") // ErrIllegalAccess occurs when trying to access to an object that // has been destroyed. // // Format: // "attempt to access a destroyed object" ErrIllegalAccess error = errors.New("attempt to access a destroyed object") )
Functions ¶
func DestroySlice ¶
DestroySlice is a helper function that destroys a slice of entities in parallel.
Parameters:
- s: The slice of entities to destroy.
Returns:
- error: An error if destroying the entities fails.
Errors:
- any error: The joined error with the errors that occurred while destroying the entities.
func IsLoaded ¶
func IsLoaded(lc LoadCounter) bool
IsLoaded reports whether the object is loaded. If no load counter is provided, the call returns `false`.
Parameters:
- lc: The load counter to check.
Returns:
- bool: `true` if the object is loaded, `false` otherwise.
func LoadSlice ¶
LoadSlice is a helper function that loads a slice of entities in parallel.
Entities that are already loaded are ignored.
Parameters:
- s: The slice of entities to load.
Returns:
- error: An error if loading the entities fails.
Errors:
- any error: The joined error with the errors that occurred while loading the entities.
func UnloadSlice ¶
UnloadSlice is a helper function that unloads a slice of entities in parallel.
Parameters:
- s: The slice of entities to unload.
Returns:
- error: An error if unloading the entities fails.
Errors:
- any error: The joined error with the errors that occurred while unloading the entities.
Types ¶
type Destroyer ¶
type Destroyer interface {
// Destroy performs the necessay clean-up tasks for destroying the
// object in question; thus, making it available for garbage
// collection.
//
// For consistency reasons, `nil` receivers are considered to be
// already released and so, they will not return an error.
//
// WARNING: The destruction operation must not be used as the
// default unload mechanism as, upon a successful call, the objects
// are deemed to be unavailable for further use; thus, any attempt
// to use them might result in errors or undefined behaviors.
//
// The method returns the number of loads performed on the object
// AFTER the current destroy call. So, a value of 0 means that the
// object is not used by anyone anymore.
//
// Returns:
// - uint64: The number of remaining objects that have requested
// the object.
// - error: An error if destroying the object fails.
//
// Errors:
// - any error: Depends on the implementation.
Destroy() (uint64, error)
}
Destroyer is the interface that wraps the basic destroy method.
This is best used for when objects are not needed anymore and won't be needed ever again; especially when said objects are big.
Implementations must unload the object's memory in a safe way when destroying the object, including if the object is not in a valid state. This prevents a bunch of memory leaks and issues later on.
Furthermore, implementations should refrain from performing any I/O operations unless they are strictly necessary, for safety reasons, or for debugging purposes. This means that logging or printing inside destroy methods is generally not a good idea.
Because objects can be shared between goroutines, actual resources are destroyed only when the reference count reaches zero.
Finally, destroy methods should refrain from returning errors, ideally no error. This is due to the fact that, if destroying an object fails, it could leave is in a broken state that could cause issues down the line.
As such, it is a good practive to solve all the issues at the best of your abilities and only return an error if you have no choice but to do so.
type LoadCounter ¶
type LoadCounter interface {
// LoadCount returns the number of loads performed on the object. If
// the receiver is `nil`, it returns 0.
//
// Returns:
// - uint64: The number of loads performed on the object.
LoadCount() uint64
}
LoadCounter is the interface that wraps the basic load counter method.
type Loader ¶
type Loader interface {
// Load initializes the object's memory.
//
// Loading is done by performing the setup tasks; thus, making it
// ready for use. These operations include, but not limited to,
// gathering resources and checking preconditions.
//
// Because an object can be load multiple times, actual resources are
// loaded only at the first load call. If loading is successful, the
// object is both loaded in memory and valid for use; thus, any
// operation performed on the object afterwards should not fail
// (i.e., does not return errors that are cause by invalid states or
// missing resources).
//
// The method returns the number of loads performed on the object
// AFTER the current load call.
//
// 0: Loading failed.
// 1: Loading done for the first time.
// any other value: Loading done multiple times.
//
// Returns:
// - uint64: The number of loads performed on the object.
// - error: An error if loading the object fails.
//
// Errors:
// - ErrIllegalAccess: If the receiver is `nil` or the object has
// been destroyed.
// - ErrTooManyRequests: If the object has been loaded too many
// times.
// - any other error: Depends on the implementation.
Load() (uint64, error)
}
Loader is the interface that wraps the basic load method.
Implementations should refrain from performing any I/O operations, unless they are strictly necessary for initializing the object, for safety reasons, or for debugging. This means that logging or printing inside load methods is generally not a good idea.
type Unloader ¶
type Unloader interface {
// Unload unloads the object's memory. If the receiver is `nil` or
// not loaded, nothing happens.
//
// Unloading is done by performing any necessary cleanup tasks; thus,
// making it no longer usable. These operations include, but not
// limited to, destroying resources and checking postconditions.
//
// Because an object can be loaded multiple times, actual resources
// are unloaded only at the last unload call. If unloading is
// successful, the object is both unloaded from memory and no longer
// valid for use. Still, the object is not entirely lost and can be
// loaded again if needed with a call to load methods.
//
// The method returns the number of loads performed on the object
// AFTER the current unload call. So, a value of 0 means that the
// object is not used by anyone anymore.
//
// Returns:
// - uint64: The number of remaining objects that have requested
// the object.
// - error: An error if unloading the object fails.
//
// Errors:
// - any error: Depends on the implementation.
Unload() (uint64, error)
}
Unloader is the interface that wraps the basic unload method.
Implementations should refrain from performing any I/O operations, unless they are strictly necessary for initializing the object, for safety reasons, or for debugging. This means that logging or printing inside load methods is generally not a good idea.
Source Files