From ec688b4723a041044226358bcd4dd6e2da39da49 Mon Sep 17 00:00:00 2001 From: Luca Muscariello Date: Thu, 23 Feb 2017 17:01:02 +0100 Subject: Initial commit: cframework. Longbow and Libparc Change-Id: I90378dbd30da6033b20fb1f829b3b822cf366c59 Signed-off-by: Luca Muscariello --- libparc/parc/algol/parc_Event.h | 211 ++++++++++++++++++++++++++++++++++++++++ 1 file changed, 211 insertions(+) create mode 100644 libparc/parc/algol/parc_Event.h (limited to 'libparc/parc/algol/parc_Event.h') diff --git a/libparc/parc/algol/parc_Event.h b/libparc/parc/algol/parc_Event.h new file mode 100644 index 00000000..3f2fde98 --- /dev/null +++ b/libparc/parc/algol/parc_Event.h @@ -0,0 +1,211 @@ +/* + * Copyright (c) 2017 Cisco and/or its affiliates. + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at: + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ + +/** + * @file parc_Event.h + * @ingroup events + * @brief Event management + * + * Provides a facade implementing many regularly available event functions. + * This is an interface that software implementors may use to substitute + * different kinds of underlying implementations of these event management functions. + * Notable examples are libevent and libev. + * + */ +#ifndef libparc_parc_Event_h +#define libparc_parc_Event_h + +/** + * Current implementation based on top of libevent2 + */ + +#include + +/** + * @typedef PARCEventType + * @brief An enumeration of event types, with an additional persist flag + */ +typedef enum { + PARCEventType_None = 0x00, + PARCEventType_Timeout = 0x01, + PARCEventType_Read = 0x02, + PARCEventType_Write = 0x04, + PARCEventType_Signal = 0x08, + PARCEventType_Persist = 0x10, + PARCEventType_EdgeTriggered = 0x20 +} PARCEventType; + +/** + * @typedef PARCEventPriority + * @brief Priority flags for queue scheduling, these currently match the RTA_*_PRIORITY + * this will eventually be replaced. + */ +typedef enum { + PARCEventPriority_Maximum = 0, + PARCEventPriority_Normal = 1, + PARCEventPriority_Minimum = 2, + PARCEventPriority_NumberOfPriorities = 3 +} PARCEventPriority; + +/** + * @typedef PARCEvent_Callback + * @brief Event callback definition + */ +typedef void (PARCEvent_Callback)(int fileDescriptor, PARCEventType type, void *user_data); + +/** + * @typedef PARCEvent + * @brief A structure containing private libevent state data variables + */ +typedef struct PARCEvent PARCEvent; + +/** + * Create a new PARCEvent instance. + * + * A new PARCEvent instance is returned. + * + * @param [in] parcEventScheduler base instance + * @param [in] fileDescriptor file descriptor to monitor + * @param [in] events to catch + * @param [in] callback function + * @param [in] callbackArgs function private arguments + * @returns A pointer to the a PARCEvent instance. + * + * Example: + * @code + * static void + * _read_callback(int fileDescriptor, PARCEventType type, void *args) + * { + * } + * + * { + * PARCEventScheduler *eventScheduler = parcEventScheduer_Create(); + * PARCEvent *event = parcEvent_Create(eventScheduler, fileDescriptor, PARCEvent_ReadEvent, _read_callback, _read_callback_args); + * } + * @endcode + * + */ +PARCEvent *parcEvent_Create(PARCEventScheduler *parcEventScheduler, int fileDescriptor, PARCEventType events, PARCEvent_Callback *callback, void *callbackArgs); + +/** + * Start an event instance. + * + * @param [in] parcEvent instance to start + * @returns -1 on error, 0 on success if nothing changed in the parcEvent backend, and 1 on success if something did. + * + * Example: + * @code + * startEvent(PARCEvent *parcEvent) + * { + * return parcEvent_Start(parcEvent); + * } + * @endcode + * + */ +int parcEvent_Start(PARCEvent *parcEvent); + +/** + * Stop a parcEvent instance. + * + * @param [in] parcEvent instance to stop + * @returns -1 on error, 0 on success. + * + * Example: + * @code + * removeEvent(PARCEvent *parcEvent) + * { + * return parcEvent_Stop(parcEvent); + * } + * @endcode + * + */ +int parcEvent_Stop(PARCEvent *parcEvent); + +/** + * Poll if an event is available to process + * + * @param [in] parcEvent instance to stop + * @param [in] event type to poll for + * @returns -1 on error, 0 on success. + * + * Example: + * @code + * pollReadEvent(PARCEvent *parcEvent) + * { + * return parcEvent_Poll(parcEvent, PARCEvent_ReadEvent); + * } + * @endcode + * + */ +int parcEvent_Poll(PARCEvent *parcEvent, PARCEventType event); + +/** + * Destroy a parcEvent instance. + * + * @param [in] parcEvent address of instance to destroy. + * + * Example: + * @code + * { + * parcEvent_Destroy(&parcEvent); + * } + * @endcode + * + */ +void parcEvent_Destroy(PARCEvent **parcEvent); + +/** + * Set a parcEvent instances priority. + * + * @param [in] parcEvent instance to modify + * @param [in] priority to set to + * @returns -1 on error, 0 on success. + * + * Example: + * @code + * { + * return parcEvent_SetPriority(parcEvent, priority); + * } + * @endcode + * + */ +int parcEvent_SetPriority(PARCEvent *parcEvent, PARCEventPriority priority); + +/** + * Turn on debugging flags and messages + * + * Example: + * @code + * { + * parcEvent_EnableDebug(); + * } + * @endcode + * + */ +void parcEvent_EnableDebug(void); + +/** + * Turn off debugging flags and messages + * + * Example: + * @code + * { + * parcEvent_DisableDebug(); + * } + * @endcode + * + */ +void parcEvent_DisableDebug(void); +#endif // libparc_parc_Event_h -- cgit 1.2.3-korg