Event Service APIs

Detailed Description

The NvSciEventService library provides the ability to build portable event-driven applications. An event is any significant occurrence or change in the state for system hardware or software. An event notification is a message or notification sent by one software part to another to convey that an event has taken place. An event-driven model consists of an event producer and event consumers. Once an event producer detects an event, it represents the event as a message (or notification). An event is transmitted from an event producer to event consumers through an OS-specific event channel. Event consumers must be informed when an event has occurred. NvSciEventService will execute the correct response (or callback) to an event.

NvSciEventService provides a mandatory abstract interface between other SCI technologies (especially NvSciIpc and NvSciStreams) and the application-provided event loop that services them.

The following common object type(s) are implemented:

• User-visible object types (for application use)
  • NvSciEventService: An object that subsumes all state that commonly would have been maintained in global variables.
  • NvSciEventNotifier: An object that a library creates using an NvSciEventService and then provides to the user, and with which the user registers an event handler that is invoked whenever the library generates an event.

Typical call flow with NvSciIpc library

1) Init mode

• NvSciEventLoopServiceCreate()
• NvSciIpcInit()
• NvSciIpcOpenEndpointWithEventService()
• NvSciIpcGetEventNotifier()
• NvSciIpcGetEndpointInfo()
• NvSciIpcResetEndpoint()
• Ensure a channel is established

  loop {
      NvSciIpcGetEvent()
      if (event & NV_SCI_IPC_EVENT_CONN_EST_ALL) break
      else {
          NvSciEventLoopService::WaitForEvent()
          or
          NvSciEventLoopService::WaitForMultipleEvents()
      }
  }

2) Runtime mode (loop)

• NvSciIpcGetEvent()
• If an event is not desired, NvSciEventLoopService::WaitForEvent() or NvSciEventLoopService::WaitForMultipleEvents()
• NvSciIpcRead() or NvSciIpcWrite()

3) Deinit mode

• If an eventNotifier is not required any more, NvSciEventNotifier::Delete()
• NvSciIpcCloseEndpoint()
• NvSciIpcDeinit()
• NvSciEventService::Delete()

Data Structures
struct	NvSciEventService
	An abstract interface for a program's event handling infrastructure. More...
struct	NvSciEventNotifier
	An abstract interface to notify event to event consumer and to register event handler of the event consumer client process. More...
struct	NvSciEventLoopService
	An abstract interface that event consumer can wait for events using event notifier in event loop. More...

Macros
#define	NV_SCI_EVENT_INFINITE_WAIT   -1
	Infinite timeout for NvSciEventLoopService::WaitForEvent() or NvSciEventLoopService::WaitForMultipleEvents(). More...
#define	NV_SCI_EVENT_PRIORITIES   4

Typedefs
typedef struct NvSciEventService	NvSciEventService
typedef struct NvSciEventNotifier	NvSciEventNotifier
typedef struct NvSciEventLoopService	NvSciEventLoopService

Functions
NvSciError	NvSciEventLoopServiceCreate (size_t maxEventLoops, NvSciEventLoopService **newEventLoopService)
	Creates a new event loop service. More...

Macro Definition Documentation

NV_SCI_EVENT_INFINITE_WAIT

#define NV_SCI_EVENT_INFINITE_WAIT   -1

Infinite timeout for NvSciEventLoopService::WaitForEvent() or NvSciEventLoopService::WaitForMultipleEvents().

Definition at line 122 of file nvscievent.h.

NV_SCI_EVENT_PRIORITIES

#define NV_SCI_EVENT_PRIORITIES   4

Definition at line 123 of file nvscievent.h.

Typedef Documentation

NvSciEventLoopService

typedef struct NvSciEventLoopService NvSciEventLoopService

Definition at line 127 of file nvscievent.h.

NvSciEventNotifier

typedef struct NvSciEventNotifier NvSciEventNotifier

Definition at line 126 of file nvscievent.h.

NvSciEventService

typedef struct NvSciEventService NvSciEventService

Definition at line 125 of file nvscievent.h.

Function Documentation

NvSciEventLoopServiceCreate()

NvSciError NvSciEventLoopServiceCreate	(	size_t	maxEventLoops,
		NvSciEventLoopService **	newEventLoopService
	)

Creates a new event loop service.

The number of event loops that can be created in the new event loop service will be limited to at most maxEventLoops.

This function creates a new event loop service newEventLoopService which is a primary instance of event service. An application must call event service functions along with newEventLoopService. The number of event loops that can be created in the new event loop service will be limited to at most maxEventLoops.

Parameters

[in]	maxEventLoops	The number of event loops, it must be 1.
[out]	newEventLoopService	NvSciEventNotifier object double pointer.

Returns

NvSciError, the completion code of operations:

• NvSciError_Success Indicates a successful operation.
• NvSciError_InsufficientMemory Indicates memory is not sufficient.
• NvSciError_NotSupported Indicates a condition is unsupported.
• NvSciError_InvalidState Indicates an invalid operation state.
• NvSciError_BadParameter Indicates an invalid or NULL argument.
• NvSciError_ResourceError Indicates not enough system resources.

Usage considerations

• Allowed context for the API call
  • Interrupt: No
  • Signal handler(QNX): No
  • Thread: Yes
• Is thread safe: Yes
• Required Privileges(QNX): None
• API Group
  • Initialization: Yes
  • Runtime: No
  • De-initialization: No