syseventAllocate(3EXT)

NAME | SYNOPSIS | API RESTRICTIONS | PARAMETERS | DESCRIPTION | RETURN VALUE | ERRORS | ATTRIBUTES | SEE ALSO

NAME

syseventAllocate- allocate a free sysevent buffer

SYNOPSIS

$(NUCLEUS_DIR)/lib/sysevent/sysevent.a
#include <sysevent/chSysevent.h>

int syseventAllocate(int spaceId, int queueId, int evSize, KnTimeVal *waitLimit, Knsysevent **sysevent);

API RESTRICTIONS

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.

PARAMETERS

spaceId

Handle pointing to the event space

queueId

Identifier of the event queue to which the buffer should belong

evSize

Requested size of the event

waitLimit

Timeout, if there is no free event buffer immediately available

sysevent

Address of a pointer where the event buffer address is stored

DESCRIPTION

The syseventAllocate() function returns a free system event buffer from the pool associated with the event queue named by queueId. If the pool is not empty, this call immediately sets the address of the event buffer into sysevent and returns. Otherwise, syseventAllocate() waits for a free buffer, according to the value of waitLimit If waitLimit is set to K_NOBLOCK, syseventAllocate() immediately returns with a K_ETIMEOUT error code. Otherwise, the caller is blocked until an event of the pool is freed by syseventFree(), or until the timeout expires.

Upon successful completion of this call, the caller's data can be copied at the address pointed by sysevent->evPayload.

This system event buffer contains a KnSyseventHead object used by the core sysevent library for its own private management. The caller's data are abutted on KnSyseventHead. Thus, the caller's data are also accessible at sizeof (KnSyseventHead) bytes offset from the address returned in sysevent, which points to the beginning of the event buffer. If the content of the KnSyseventHead structure is removed by mistake, the core sysevent API can behave unpredictably or return unexpected errors.

RETURN VALUE

K_OK is returned on successful completion. Otherwise, a negative error code is returned.

ERRORS

[K_EINVAL]

Some of the supplied parameters are not valid

[K_ESIZE]

evSize is greater than the event size specified at the time the event space is allocated

[K_ETIMEOUT]

The maximum waiting time expired

[K_ADDR]

The sysevent has a null value. Note that if this pointer is a non-accessible address, the caller actor crashes itself into the PRM or VM memory models. Otherwise, the FLM memory model can behave unpredictably

[K_EABORT]

The invoking thread was aborted while waiting for an event

ATTRIBUTES

See attributes(5) for descriptions of the following attributes:

ATTRIBUTE TYPE	ATTRIBUTE VALUE
Interface Stability	Evolving

SEE ALSO

syseventFree(3EXT), syseventGet(3EXT), syseventGetAny(3EXT), syseventPut(3EXT)

ChorusOS 5.0  Last Revised December 2001

NAME | SYNOPSIS | API RESTRICTIONS | PARAMETERS | DESCRIPTION | RETURN VALUE | ERRORS | ATTRIBUTES | SEE ALSO