allocTrans(3)

NAME
allocTrans, freeTrans, getTransByAddr, getTransByName, readTrans, writeTrans, getTransName -- RCCL transform maintenance primitives.

USAGE
#include <rccl.h>

TRSF *allocTrans (name, pool)
   const char *name;
   int pool;

freeTrans (tr)
   TRSF *tr;

TRSF *getTransByName (name)
   const char *name;

TRSF *getTransByAddr (tp)
   TRSF *tp;

TRSF *readTrans (tr, tbuf)
   TRSF *tr;
   TRSF *tbuf;

TRSF *writeTrans (tr, tbuf)
   TRSF *tr;
   TRSF *tbuf;

char *getTransName(tr)
   TRSF *tr;

ARGUMENTS

name --
    Name of the transform (optional; can be specified as NULL if not required).

pool --
    Memory area from which to allocate the transform. Under the current implementation, there is one memory area on each CPU, so pool is actually a CPU number. The idea is to allocate the transform on the CPU where it will be accessed the most. If you don't care what memory pool is used to allocate the transform, give this argument as UNDEF.

tr --
    Pointer to the transform.

tp --
    Pointer to the transform which is valid in the planning task context.

tbuf --
    Buffer to copy the transform into or read it from.

RESTRICTIONS
At the moment, allocTrans() and freeTrans() must be called from the planning level.

DESCRIPTION
These routines provide an RCCL program with the ability to create transformation objects which can be accessed globally from any part of an RCCL program. These routines are implemented using the RCI allocMem() package, which can also be used to create global data objects other than transforms (see allocMem(3)). The primitives described in this manual page are analogous to the allocMem() primitives. The reason for having separate routines is that the transform objects are associated with additional data fields (hidden from the programmer) that are used to provide special functionality. In particular, transforms created with allocTrans() may be bound to real-time functions that update their values from the trajectory level (see setTransConst(3)).

allocTrans() creates a transform with the given "name". The argument pool identifies a memory pool from which to allocate the transform; under the current implementation, this is simply a CPU number; i.e., giving pool a value of N will cause the transform to be allocated from memory on CPU N. If pool is given as UNDEF, then the memory pool is chosen by the system. It is possible to specifiy a NULL name, by setting name to be either NULL, or a pointer to an empty string. This can be useful for allocating internal transforms without the risk of causing name-space collisions. Under the current implementation, allocTrans() must be called from the planning task.

freeTrans() frees the allocated transform. This routine must also be called from the planning task.

getTransByName() locates a transform, using its name as a key, and returns a pointer to it. It is necessary to use such a routine when accessing a transform from the control level (e.g., from within a monitor or transform function). This is because the control level memory context may be different from the planning level memory context (particularly if the control level is executing on a different CPU) and so a transform pointer which is valid in the planning level context may not be valid at the control level. (Remember that different virtual addresses can point to the same physical address.)

getTransByAddr() is similar to getTransByName(), except that it locates a transform using its planning level address as a key. This is useful in cases where it is desirable to not name a transform (in order to avoid name-space collisions, as described above). The routine is also faster than getTransByName().

A couple of routines are also provided for accessing the value of a transform atomically:

readTrans() copies the contents of a transform into a buffer. The operation is atomic, in that it will lock out other readTrans() or writeTrans() operations on the same transform. The routine returns the pointer tr.

writeTrans() copies the contents of a buffer into the indicated transform. The operation is atomic, in that it will lock out other readTrans() or writeTrans() operations on the same transform. The routine returns the pointer tr.

 NOTE: only the transform itself, i.e., the leftmost argument, is accessed atomically by readTrans() and writeTrans(). The righthand argument is not accessed atomically.

getTransName() returns the name of a transform.

DIAGNOSTICS
allocTrans() returns NULL in the event of an error. It will automatically abort the program if the option RCCL_ERROR_EXIT is set (see rcclSetOptions(3)). Error codes and messages are placed on the errorStack (q.v.). The following error codes may be set:

EMemory --
    Not enough memory left in the shared memory pool.

EDuplicate --
    Attempt was made to create a transform with the same name as one already allocated.

getTransByName() and getTransByAddr() return NULL if they cannot find the indicated transform.

allocTrans() and freeTrans() will abort the program if called from the control level.

SEE ALSO
allocMem(3), setTransVarb(3), errorStack(3).