Module catalog
A general purpose Catalog.
The catalog is used to give objects well known names for sharing purposes.
It also allows synchronization, by blocking the requester until the object
is made available. Catalogs themselves are made available under a Well Known
Name. Typical catalogs are "tasks", "events", "mutexes" and "pipes".
A name is associated to a single object, and an object has a single name.
Catalogs can be strong or weak, ie, they can keep objects from being garbage collected, or not.
Usage:
local tasks = require 'lumen.catalog'.get_catalog('tasks')
..
asks:register('a task', sched.running_task)
..
ocal a_task=tasks:waitfor('a task')
Functions
| register (catalogd, name, object, force) | Give a name to an object. |
| unregister (catalogd, name) | Removes an entry from the catalog. |
| waitfor (catalogd, name, timeout) | Retrieve a object with a given name. |
| namefor (catalogd, object) | Find the name of a given object. |
| get_catalog (name, strong) | Retrieve a catalog. |
| iterator (catalogd) | Iterator for registered objects. |
Functions
- register (catalogd, name, object, force)
-
Give a name to an object.
Parameters:
- catalogd the catalog to use.
- name a name for the object.
- object the object to name.
- force forces the renaming of the object if already present.
Returns:
-
true is successful; nil, 'used' if the name is already used by another object; nil, 'present' if the object
is already in the catalog under a different name, and forcing is not enabled.
- unregister (catalogd, name)
-
Removes an entry from the catalog.
Parameters:
- catalogd the catalog to use.
- name a name for the object.
Returns:
-
true on success, or nil, 'missing' if the name was not registered previously.
- waitfor (catalogd, name, timeout)
-
Retrieve a object with a given name.
Can wait up to timeout until it appears.
Parameters:
- catalogd the catalog to use.
- name name of the object
- timeout time to wait. nil or negative waits for ever.
Returns:
-
the object if successful; on timeout expiration returns nil, 'timeout'.
- namefor (catalogd, object)
-
Find the name of a given object.
Parameters:
- catalogd the catalog to use.
- object the object to lookup.
Returns:
-
the object if successful; If the object has not been given a name, returns nil.
- get_catalog (name, strong)
-
Retrieve a catalog.
Catalogs are created on demand.
Parameters:
- name the name of the catalog.
- strong if true catalog will hold a reference to the object and avoid it from being garbage collected.
Returns:
-
a catalog object.
- iterator (catalogd)
-
Iterator for registered objects.
Parameters:
- catalogd the catalog to use.
Returns:
-
Iterator function
Usage:
local tasks = require 'lumen.catalog'.get_catalog('tasks') or name, task in tasks:iterator() do print(name, task) nd