diff options
Diffstat (limited to 'libparc/parc/algol/parc_EventBuffer.h')
-rwxr-xr-x | libparc/parc/algol/parc_EventBuffer.h | 387 |
1 files changed, 0 insertions, 387 deletions
diff --git a/libparc/parc/algol/parc_EventBuffer.h b/libparc/parc/algol/parc_EventBuffer.h deleted file mode 100755 index 8e82a5e6..00000000 --- a/libparc/parc/algol/parc_EventBuffer.h +++ /dev/null @@ -1,387 +0,0 @@ -/* - * 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_EventBuffer.h - * @ingroup events - * @brief Buffered 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_EventBuffer_h -#define libparc_parc_EventBuffer_h - -#include <parc/algol/parc_EventQueue.h> - -#ifdef PARCLibrary_DISABLE_VALIDATION -# define parcEventBuffer_OptionalAssertValid(_instance_) -#else -# define parcEventBuffer_OptionalAssertValid(_instance_) parcEventBuffer_AssertValid(_instance_) -#endif - -/** - * @typedef PARCEventBuffer - * @brief A structure containing private libevent state data variables - */ -typedef struct PARCEventBuffer PARCEventBuffer; - -/** - * Create an event buffer instance. - * - * @returns A pointer to a new PARCEventBuffer instance. - * - * Example: - * @code - * { - * PARCEventBuffer *parcEventBuffer = parcEventBuffer_Create(); - * } - * @endcode - * - */ -PARCEventBuffer *parcEventBuffer_Create(void); - -/** - * Destroy a network parcEventBuffer instance. - * - * The address of the event instance is passed in. - * - * @param [in] parcEventBuffer - The address of the instance to destroy. - * - * Example: - * @code - * { - * parcEventBuffer_Destroy(&parcEventBuffer) - * } - * @endcode - * - */ -void parcEventBuffer_Destroy(PARCEventBuffer **parcEventBuffer); - -/** - * Determine if an instance of `PARCEventBuffer` is valid. - * - * Valid means the internal state of the type is consistent with its required current or future behaviour. - * This may include the validation of internal instances of types. - * - * @param [in] eventBuffer A pointer to a `PARCEventBuffer` instance. - * - * @return true The instance is valid. - * @return false The instance is not valid. - * - * Example: - * @code - * { - * PARCEventBuffer *instance = parcEventBuffer_Create(); - * - * if (parcEventBuffer_IsValid(instance)) { - * printf("Instance is valid.\n"); - * } - * } - * @endcode - */ -bool parcEventBuffer_IsValid(const PARCEventBuffer *eventBuffer); - -/** - * Assert that the given `PARCEventBuffer` instance is valid. - * - * @param [in] eventBuffer A pointer to a valid PARCEventBuffer instance. - * - * Example: - * @code - * { - * PARCEventBuffer *a = parcEventBuffer_Create(); - * - * parcEventBuffer_AssertValid(a); - * - * printf("Instance is valid.\n"); - * - * parcEventBuffer_Release(&b); - * } - * @endcode - */ -void parcEventBuffer_AssertValid(const PARCEventBuffer *eventBuffer); - -/** - * Get the input parcEventBuffer instance from the Queue - * - * @param [in] parcEventQueue - The queue to obtain the input parcEventBuffer from - * @returns A pointer to the a PARCEventBuffer instance. - * - * Example: - * @code - * { - * PARCEventBuffer *parcEventBuffer = parcEventBuffer_GetQueueBufferInput(eventQueue); - * } - * @endcode - * - */ -PARCEventBuffer *parcEventBuffer_GetQueueBufferInput(PARCEventQueue *parcEventQueue); - -/** - * Get the output parcEventBuffer instance from the Queue - * - * @param [in] parcEventQueue - The queue to obtain the output parcEventBuffer from - * @returns A pointer to the a PARCEventBuffer instance. - * - * Example: - * @code - * { - * PARCEventBuffer *parcEventBuffer = parcEventBuffer_GetQueueBufferOutput(parcEventQueue); - * } - * @endcode - * - */ -PARCEventBuffer *parcEventBuffer_GetQueueBufferOutput(PARCEventQueue *parcEventQueue); - -/** - * Get the data length of the associated buffer - * - * @param [in] parcEventBuffer - The buffer to obtain the length from - * @returns The length of data within the buffer, 0 if the internal buffer has been freed - * - * Example: - * @code - * { - * int length = parcEventBuffer_GetLength(parcEventBuffer); - * } - * @endcode - * - */ -size_t parcEventBuffer_GetLength(PARCEventBuffer *parcEventBuffer); - -/** - * Consolidate data in the associated parcEventBuffer - * - * @param [in] parcEventBuffer - The buffer to consolidate - * @param [in] size - The length of data to consolidate, -1 linearizes the entire buffer - * @returns A pointer to the first byte in the buffer. - * - * Example: - * @code - * { - * unsigned char *ptr = parcEventBuffer_Pullup(parcEventBuffer, size); - * } - * @endcode - * - */ -uint8_t *parcEventBuffer_Pullup(PARCEventBuffer *parcEventBuffer, ssize_t size); - -/** - * Read data from the associated parcEventBuffer - * - * @param [in] parcEventBuffer - The parcEventBuffer to read from - * @param [in] data - The memory to read into, NULL to discard data - * @param [in] length - The number of bytes of data to be read - * @returns Number of bytes read, -1 on failure. - * - * Example: - * @code - * { - * int bytesRead = parcEventBuffer_Read(parcEventBuffer, destination, bytesToRead); - * } - * @endcode - * - */ -int parcEventBuffer_Read(PARCEventBuffer *parcEventBuffer, void *data, size_t length); - -/** - * Read data from the associated parcEventBuffer without delete them from the buffer. - * Data can not be NULL - * - * @param [in] parcEventBuffer - The parcEventBuffer to read from - * @param [in] data - The memory to read into - * @param [in] length - The number of bytes of data to be read - * @returns Number of bytes read, -1 on failure. - * - */ -int parcEventBuffer_copyOut(PARCEventBuffer *readBuffer, void *data_out, size_t length); - - -/** - * Read from a file descriptor into the end of a buffer - * - * @param [in] parcEventBuffer - The buffer to read from - * @param [in] fd - The file descriptor to read from - * @param [in] length - The number of bytes of data to be read - * @returns The number of bytes read, 0 on EOF and -1 on error. - * - * Example: - * @code - * { - * int bytesTransfered = parcEventBuffer_ReadFromFileDescriptor(parcEventBuffer, fd, length); - * } - * @endcode - * - */ -int parcEventBuffer_ReadFromFileDescriptor(PARCEventBuffer *parcEventBuffer, int fd, size_t length); - -/** - * Write to a file descriptor from a buffer - * - * @param [in] parcEventBuffer - The buffer to read from - * @param [in] fd - The file descriptor to write to - * @param [in] length - The number of bytes of data to be read (-1 for all). - * @returns The number of bytes read, 0 on EOF and -1 on error. - * - * Example: - * @code - * { - * int bytesTransfered = parcEventBuffer_WriteToFileDescriptor(parcEventBuffer, fd, length); - * } - * @endcode - * - */ -int parcEventBuffer_WriteToFileDescriptor(PARCEventBuffer *parcEventBuffer, int fd, ssize_t length); - -/** - * Append one PARCEventBuffer to another - * - * @param [in] source - The buffer to append - * @param [in] destination - The buffer to append to - * @returns 0 on success, -1 on failure - * - * Example: - * @code - * { - * int result = parcEventBuffer_AppendBuffer(source, destination); - * } - * @endcode - * - */ -int parcEventBuffer_AppendBuffer(PARCEventBuffer *source, PARCEventBuffer *destination); - -/** - * Append bytes to a parcEventBuffer - * - * @param [in] parcEventBuffer - The buffer to write into - * @param [in] sourceData - The data to append - * @param [in] length - The number of bytes of data to be added - * @returns 0 on success, -1 on failure - * - * Example: - * @code - * { - * int result = parcEventBuffer_Append(parcEventBuffer, sourceData, length); - * } - * @endcode - * - */ -int parcEventBuffer_Append(PARCEventBuffer *parcEventBuffer, void *sourceData, size_t length); - -/** - * Prepend data to the associated parcEventBuffer - * - * @param [in] parcEventBuffer - The parcEventBuffer to prepend to - * @param [in] sourceData - The data to prepend - * @param [in] length - The number of bytes of data to be added - * @returns 0 on success, -1 on failure - * - * Example: - * @code - * { - * int result = parcEventBuffer_Read(parcEventBuffer, sourceData, length); - * } - * @endcode - * - */ -int parcEventBuffer_Prepend(PARCEventBuffer *parcEventBuffer, void *sourceData, size_t length); - -/** - * Move data from one buffer to another - * - * @param [in] sourceEventBuffer - The buffer to read from - * @param [in] destinationEventBuffer - The buffer to move into - * @param [in] length - The number of bytes of data to be moved - * @returns The number of bytes moved on success, -1 on failure - * - * Example: - * @code - * { - * int bytesMoved = parcEventBuffer_Create(sourceEventBuffer, destinationEventBuffer, length); - * } - * @endcode - * - */ -int parcEventBuffer_ReadIntoBuffer(PARCEventBuffer *sourceEventBuffer, PARCEventBuffer *destinationEventBuffer, size_t length); - -/** - * Read a text line terminated by an optional carriage return, followed by a single linefeed - * - * @param [in] parcEventBuffer - The buffer to read from - * @param [in] length - The number of bytes of data to be moved - * @returns A newly allocated null terminated string, which must be freed by the caller - * - * Example: - * @code - * { - * char *text = parcEventBuffer_ReadLine(parcEventBuffer, length); - * ... - * parcMemory_Deallocate((void *)&text); - * } - * @endcode - * - */ -char *parcEventBuffer_ReadLine(PARCEventBuffer *parcEventBuffer, size_t *length); - -/** - * Free a text line returned from parcEventBuffer_ReadLine - * - * @param [in] parcEventBuffer - The buffer to read from - * @param [in] line address of returned value from previous call to parcEventBuffer_ReadLine - * - * Example: - * @code - * { - * char *text = parcEventBuffer_ReadLine(parcEventBuffer, length); - * ... - * parcEventBuffer_FreeLine(parcEventBuffer, &text); - * } - * @endcode - * - */ -void parcEventBuffer_FreeLine(PARCEventBuffer *parcEventBuffer, char **line); - -/** - * Turn on debugging flags and messages - * - * @param [in] logger - the log to write debug messages to - * - * Example: - * @code - * { - * parcEventBuffer_EnableDebug(logger); - * } - * @endcode - * - */ -void parcEventBuffer_EnableDebug(PARCLog *logger); - -/** - * Turn off debugging flags and messages - * - * Example: - * @code - * { - * parcEventBuffer_DisableDebug(); - * } - * @endcode - * - */ -void parcEventBuffer_DisableDebug(void); -#endif // libparc_parc_EventBuffer_h |