@CHIP-RTOS C Library - RTOS API
Post a tagged entry in the global data registry.
int far RTX_Publish ( const void *data, const char *nameTag );
- Pointer to global data to store
under provided name tag.
Set to NULL to remove an existing entry by this name tag.
Alternatively, the SYSTEM_PUBLIC_OBJ(size)
macro can be
used here to allocate a new global data object owned by the system (See below).
- A zero terminated ASCII string
(23 characters maximum length) to use as a unique identifier for
- Zero on success, else error code:
RTX_EC_LOW_MEMORY (-9) - Memory allocation failed.
RTX_EC_NAME_NOT_FOUND (-57) - An attempt to delete an entry
(i.e. data parameter was NULL) failed due to no entry with
this name tag was found.
RTX_EC_CALL_ILLEGAL (-58) - Illegal call made from inside an
(This API may only be called at task level.)
RTX_EC_NAME_IN_USE (-59) - Attempt to install data
failed due to that the provided name tag is already in use
by some previously published data.
- This API allows you to record a pointer that will be held inside
with an associated name tag. This pointer can then
be retrieved by name from
this registry by any program, thereby
providing a form of communication between programs.
parameter has been declared
assuming other programs treat this object as
read-only memory. However programs are free to
cast the return value from
as they please.
A named publication can later be removed by calling this API with
the name of the item to be removed and a NULL data
argument. When a task is
deleted from the system,
any global data entries which that task had installed will
automatically be removed from the registry unless that data entry
was installed using the SYSTEM_PUBLIC_OBJ
technique explained below under the heading "System Global Data".
The name tag match is done in a case sensitive manner. The maximum
name length is 23 characters, not counting the terminating zero. Any
characters after this length will be ignored.
The system makes a copy of the nameTag
string, so this string need
not persist in your program after this API returns.
The MEM console
command will list to the console the pointer, name tag
and owner for each entry in the global data registry.
System Global Data
As mentioned above, when a task is removed from the system any
global data registry entries made by that task will be automatically
removed from the system's global data registry. An exception to this
rule is when the SYSTEM_PUBLIC_OBJ
used for the data
In this case, the location of the global data object to be shared
is not specified by the data
argument. Instead, this
argument specifies the size of an object which the system should
allocate for this new shared data object. The object's size may
range up to 0xFFC0 bytes. The size is passed to this API in the
offset portion of the far data
pointer, as should be
evident by inspecting the SYSTEM_PUBLIC_OBJ
The segment portion of the data
far pointer must be zero
in order to trigger an allocation of the new shared data object
by this API.
The usage of the SYSTEM_PUBLIC_OBJ
macro would look
something like as follows:
void *shared_data = NULL ;
if (RTX_Publish( SYSTEM_PUBLIC_OBJ( sizeof(struct MyStructType)), "MyName")
shared_data = (struct MyStructType *)
RTX_GetPublication( "MyName" ) ;
This newly allocated object will be initialized to all zero bytes
by the system. A pointer to this new object will then be stored
in the registry under the specified name.
The user will need to follow a successful call to this API with
a call to RTX_GetPublication()
to discover where the new tagged object resides.
This new registry entry will be marked as owned by the system
(specifically, the MTSK task) instead of the calling task.
This will cause the registry entry and its referenced object
in the system heap memory to persists until it is explicitly
removed by some application program using this API function
with a NULL data
argument, or a system reset.
Peer to Peer Example:
When two programs want to share data and it is not clear which
will be executing first, the while loop in example code below
could be used to either install public data or retrieve the
peer's public data for read/write access.
This while loop in the example attempts to cover for race conditions
where the peer program has made an exit between the
attempt and the
call. In this case both API's
would fail on their first attempt. But note that the issue of programs
closing after clients have gained access to their public data can
still lead to problems. This would leave the client program with
a reference to system memory which no longer is allocated (or has been
reassigned to a subsequent program or system usage). Defining the
shared objects with the SYSTEM_PUBLIC_OBJ
macro, as was
discussed above is one way around this data persistence problem.
fully reentrant, so only one program will win a race to post
data under the same name.
struct SharedDataT // Only for an example
int data ;
// ... and more user defined contents can go here ...
struct SharedDataT *negotiatePublics(struct SharedDataT *myData,
const char *nameTag)
RTX_EC error = RTX_Publish(myData, nameTag) ;
if (error == 0)
break ; // We got here first.
else if (error == RTX_EC_NAME_IN_USE)
// Our peer program has already published.
struct SharedDataT *peerData = (struct SharedDataT *)
if (peerData != NULL)
myData = peerData ;
// Reach here under race condition, peer removed their data.
// Will loop for another go.
printf("RTX_Publish() unepected error %d\r\n", error) ;
myData = NULL ; // Failure.
return myData ;
- This library function invokes a RTOS software interrupt
to install a dynamic link into the RTOS.
Refer to this RTOS API function's
for more details.
- RTX API Overview
Supported since or modified in @CHIP-RTOS version
This API List
List of C Libraries
@CHIP-RTOS Main Index
End of document