Overview
C API (Component Interface)
struct EventCreateUtility { UINT32 flags; Symbol hUtility; ComponentSpec spec; const char* name; HandledEvent* handledEvent; };

Create a Utility component for the exclusive use of the caller, and prepare a HandledEvent to allow the caller to access the Utility directly.

Contract Wrappers

Utility Components should provide a contract wrapper (a class) in their header file to manage their own creation - see std/util/rng for an example.

Fields

UINT32 flags IN
None defined (must be zero).
Symbol hUtility OUT
The handle of the new Utility is returned, here. This must be S_NULL when the call is made.
ComponentSpec spec IN
The SystemML class and release that is required to be supported by the new Utility. The actual Utility object created may not be exactly that specified, but it will support the requested interface.
const char* name IN
A name to give to the new Utility, or NULL.
HandledEvent* handledEvent IN/OUT
A handled event to be filled for the utility, or NULL to not return a handled event.

Return Values

See also General Interface Return Values.

Result

  • The new Utility component is returned.
  • If a name was specified, the new component is named XXX:YYY where XXX is the name of the calling component and YYY is the specified name. If a name was not specified, the new component is named XXX:ZZZ where ZZZ is the class of the new Utility.

Example

Taken from std/util/rng.

C++ Source Code (against 1199)
void create(Symbol hComponent) { // create utility EventCreateUtility data; data.flags = 0; data.hUtility = S_NULL; data.spec.cls = "std/2009/util/rng"; data.spec.release = 0; data.name = m_utilityName.length() ? m_utilityName.c_str() : NULL; data.handledEvent = &hev; EngineEvent event; event.hCaller = hComponent; event.flags = 0; event.type = ENGINE_EVENT_CREATE_UTILITY; event.data = (void*) &data; Symbol result = brahms_engineEvent(&event); if (S_ERROR(result)) throw result; cout << "new utility is " << data.hUtility << endl; }