#include <pd/chPd.h>int padKeyCreate(PdKey *pkey, KnPdHdl destructor);
The function or functions documented here may not be used safely in all application contexts with all APIs provided in the ChorusOS 5.0 product.
See API(5FEA) for details.
The padKeyCreate function creates an actor-specific data key visible to all actors on a site.
The key created is returned in *pkey.
You can only call padKeyCreate from a supervisor actor.
The keys provided by padKeyCreate are opaque indices used to locate actor-specific data. Although the same key may be used by different actors, the values bound to the key by padSet (2K) are maintained on a per-actor basis and persist for the life of the designated actor.
Upon key creation, the value NULL is associated with the new key in all active actors. Upon actor creation, the value NULL is associated with all keys defined in the new actor.
An optional destructor function may be associated with each key. At actor exit, if a key has a non-NULL destructor pointer, and the actor has a non-NULL value associated with that key, the function destructor() is called with the current value as its sole argument.
By default, the Private Data Manager invokes the destructor function through the LAP invocation mechanism (see IsvLapCreate(2K)) to ensure that the destructor function has the same execution actor than the thread which called padKeyCreate() originally. However, when an actor associates a destructor function to itself, the destructor function cannot be invoked by LAP (as the actor is being deleted) and is executed in the context of the Private Data Manager. As a consequence, an actor self deletion handler should not use any API which assumes that the current execution actor is the actor being deleted.
The order of destructor calls is unspecified if there is more than one destructor for an actor when it exits.
Destructor calls are repeated for a maximum of PD_DESTRUCTOR_ITERATIONS (as defined in pd/chPd.h) times as necessary to reclaim all actor-specific data in the case that a destructor causes more actor-specific data to be created.
Upon successful completion, the newly created key is stored in *pkey and a value of 0 is returned. Otherwise, a positive error code is returned.
The system-imposed limit on the total number of keys has been exceeded (see PAD_KEYS_MAX in pd/chPd.h).
There is insufficient memory to create the key.
The Private Data Manager is unreachable.
This call is reserved for supervisor actors.
See attributes(5) for descriptions of the following attributes:
|ATTRIBUTE TYPE||ATTRIBUTE VALUE|