diff options
Diffstat (limited to 'libccnx-transport-rta/ccnx/transport/transport_rta/commands/rta_Command.h')
| -rw-r--r-- | libccnx-transport-rta/ccnx/transport/transport_rta/commands/rta_Command.h | 619 |
1 files changed, 619 insertions, 0 deletions
diff --git a/libccnx-transport-rta/ccnx/transport/transport_rta/commands/rta_Command.h b/libccnx-transport-rta/ccnx/transport/transport_rta/commands/rta_Command.h new file mode 100644 index 00000000..02973c54 --- /dev/null +++ b/libccnx-transport-rta/ccnx/transport/transport_rta/commands/rta_Command.h @@ -0,0 +1,619 @@ +/* + * 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 rta_Command.h + * @brief Wraps individual commands and is written to/from a Ring Buffer + * + * The RtaCommand is the common wrapper for all the specific command types. It also supports functions to + * write it to a PARCRingBuffer and read from a one. + * + * The ShutdownFramework command is a little different than all the other commands. There are no parameters + * to this command, so there is no separate type for it. You can create an RtaCommand of this flavor and + * check for it (rtaCommand_IsShutdownFramework), but there is no Get function. + * + */ +#ifndef Libccnx_rta_Commands_h +#define Libccnx_rta_Commands_h + +struct rta_command; +typedef struct rta_command RtaCommand; + +#include <ccnx/transport/transport_rta/commands/rta_CommandCloseConnection.h> +#include <ccnx/transport/transport_rta/commands/rta_CommandCreateProtocolStack.h> +#include <ccnx/transport/transport_rta/commands/rta_CommandDestroyProtocolStack.h> +#include <ccnx/transport/transport_rta/commands/rta_CommandOpenConnection.h> +#include <ccnx/transport/transport_rta/commands/rta_CommandTransmitStatistics.h> + +#include <parc/concurrent/parc_RingBuffer_1x1.h> + + +/** + * Writes a command to a Ring Buffer + * + * Creates a reference to the command and puts the reference on the ring buffer. + * The caller still owns their own reference to the command. + * + * This command does not involve a PARCNotifier. If using a notifier in conjunction + * with the ring buffer, the caller is reponsible for posting the notification after + * all ther writes are done. + * + * The function will not block. If the ring buffer is full, it will return false. + * + * @param [in] command The command to put (by reference) on the ring buffer. + * @param [in] commandRingBuffer The ring buffer to use + * + * @return true A reference was put on the ring buffer + * @return false Failed to put reference, likely because the ring buffer was full. + * + * Example: + * @code + * { + * RtaCommand *command = rtaCommand_CreateShutdownFramework(); + * + * bool success = rtaCommand_Write(command, ring); + * if (!success) { + * // return error to user that we're backlogged + * } + * + * rtaCommand_Release(&command); + * } + * @endcode + */ +bool rtaCommand_Write(const RtaCommand *command, PARCRingBuffer1x1 *commandRingBuffer); + +/** + * Reads a command from a ring buffer + * + * If the buffer is empty, will return NULL. + * + * @param [in] commandRingBuffer The buffer to read + * + * @return non-null A valid command object + * @return null Could not read a whole command object + * + * Example: + * @code + * { + * PARCRingBuffer1x1 *ring = parcRingBuffer1x1_Create(4, NULL); + * RtaCommand *command = rtaCommand_CreateShutdownFramework(); + * + * bool success = rtaCommand_Write(command, ring); + * assertTrue(success, "Failed to put command in to ring buffer"); + * + * // We should now have two references + * assertTrue(parcObject_GetReferenceCount(command) == 2, "Wrong refernce count, got %zu expected %zu", parcObject_GetReferenceCount(command), 2); + * + * RtaCommand *test = rtaCommand_Read(ring); + * assertTrue(test == command, "Wrong pointers, got %p expected %p", (void *) test, (void *) command); + * + * rtaCommand_Release(&command); + * rtaCommand_Release(&test); + * parcRingBuffer1x1_Release(&ring); + * } + * @endcode + */ +RtaCommand *rtaCommand_Read(PARCRingBuffer1x1 *commandRingBuffer); + +/** + * Increase the number of references to a `RtaCommand`. + * + * Note that new `RtaCommand` is not created, + * only that the given `RtaCommand` reference count is incremented. + * Discard the reference by invoking `rtaCommand_Release`. + * + * @param [in] command The RtaCommand to reference. + * + * @return non-null A reference to `command`. + * @return null An error + * + * Example: + * @code + * { + * RtaCommand *command = rtaCommand_CreateShutdownFramework(); + * RtaCommand *second = rtaCommand_Acquire(command); + * + * // release order does not matter + * rtaCommand_Release(&command); + * rtaCommand_Release(&second); + * } + * @endcode + */ +RtaCommand *rtaCommand_Acquire(const RtaCommand *command); + +/** + * Release a previously acquired reference to the specified instance, + * decrementing the reference count for the instance. + * + * The pointer to the instance is set to NULL as a side-effect of this function. + * + * If the invocation causes the last reference to the instance to be released, + * the instance is deallocated and the instance's implementation will perform + * additional cleanup and release other privately held references. + * + * @param [in,out] commandPtr A pointer to the object to release, will return NULL'd. + * + * Example: + * @code + * { + * RtaCommand *command = rtaCommand_CreateShutdownFramework(); + * RtaCommand *second = rtaCommand_Acquire(command); + * + * // release order does not matter + * rtaCommand_Release(&command); + * rtaCommand_Release(&second); + * } + * @endcode + */ +void rtaCommand_Release(RtaCommand **commandPtr); + +/** + * Print a human readable representation of the given `RtaCommand`. + * + * @param [in] command A pointer to the instance to display. + * @param [in] indentation The level of indentation to use to pretty-print the output. + * + * Example: + * @code + * { + * RtaCommand *command = rtaCommand_CreateShutdownFramework(); + * rtaCommand_Display(command, 0); + * rtaCommand_Release(&command); + * } + * @endcode + * + */ +void rtaCommand_Display(const RtaCommand *command, int indentation); + +// ====================== +// CLOSE CONNECTION + + +/** + * Tests if the RtaCommand is of type CloseConnection + * + * Tests if the RtaCommand is of type CloseConnection. This will also assert the + * RtaCommand invariants, so the RtaCommand object must be a properly constructed object. + * + * @param [in] command An allocated RtaCommand ojbect + * + * @return true The object is of type CloseConnection + * @return false The object is of some other type + * + * Example: + * @code + * { + * RtaCommandCloseConnection *closeConnection = rtaCommandCloseConnection_Create(77); + * RtaCommand *command = rtaCommand_CreateCloseConnection(closeConnection); + * assertTrue(rtaCommand_IsCloseConnection(command), "Command is not CloseConnection"); + * rtaCommand_Release(&command); + * rtaCommandCloseConnection_Release(&closeConnection); + * } + * @endcode + */ +bool rtaCommand_IsCloseConnection(const RtaCommand *command); + +/** + * Allocates and creates an RtaCommand object from a RtaCommandCloseConnection + * + * Allocates and creates an RtaCommand object from a RtaCommandCloseConnection + * by acquiring a reference to it and storing it in the RtaCommand. The caller + * may release their reference to `close` at any time. + * + * @param [in] close The specific command to make acquire a reference from. + * + * @return non-null A properly allocated and configured RtaCommand. + * @return null An error. + * + * Example: + * @code + * { + * RtaCommandCloseConnection *closeConnection = rtaCommandCloseConnection_Create(77); + * RtaCommand *command = rtaCommand_CreateCloseConnection(closeConnection); + * + * // release order does not matter + * rtaCommand_Release(&command); + * rtaCommandCloseConnection_Release(&closeConnection); + * } + * @endcode + */ +RtaCommand *rtaCommand_CreateCloseConnection(const RtaCommandCloseConnection *close); + +/** + * Returns the internal RtaCommandCloseConnection object + * + * Returns the internal RtaCommandCloseConnection object, the user should not release it. + * The the RtaCommand is not of type CloseConnection, it will assert in its validation. + * + * @param [in] command The RtaCommand to query for the object. + * + * @return The RtaCommandCloseConnection object that constructed the RtaCommand. + * + * Example: + * @code + * RtaCommandCloseConnection *closeConnection = rtaCommandCloseConnection_Create(77); + * RtaCommand *command = rtaCommand_CreateCloseConnection(closeConnection); + * + * const RtaCommandCloseConnection *testValue = rtaCommand_GetCloseConnection(command); + * assertTrue(testValue == closeConnection, "Wrong pointer returned"); + * + * rtaCommand_Release(&command); + * rtaCommandCloseConnection_Release(&closeConnection); + * @endcode + */ +const RtaCommandCloseConnection *rtaCommand_GetCloseConnection(const RtaCommand *command); + +// ====================== +// OPEN CONNECTION + +/** + * Tests if the RtaCommand is of type OpenConnection + * + * Tests if the RtaCommand is of type OpenConnection. This will also assert the + * RtaCommand invariants, so the RtaCommand object must be a properly constructed object. + * + * @param [in] command An allocated RtaCommand ojbect + * + * @return true The object is of type OpenConnection + * @return false The object is of some other type + * + * Example: + * @code + * { + * RtaCommandOpenConnection *openConnection = rtaCommandOpenConnection_Create(111, 2341, 2450987, NULL); + * RtaCommand *command = rtaCommand_CreateOpenConnection(openConnection); + * assertTrue(rtaCommand_IsOpenConnection(command), "Command is not OpenConnection"); + * rtaCommand_Release(&command); + * rtaCommandOpenConnection_Release(&openConnection); + * } + * @endcode + */ +bool rtaCommand_IsOpenConnection(const RtaCommand *command); + +/** + * Allocates and creates an RtaCommand object from a RtaCommandOpenConnection + * + * Allocates and creates an RtaCommand object from a RtaCommandOpenConnection + * by acquiring a reference to it and storing it in the RtaCommand. The caller + * may release their reference to `open` at any time. + * + * @param [in] open The specific command to make acquire a reference from. + * + * @return non-null A properly allocated and configured RtaCommand. + * @return null An error. + * + * Example: + * @code + * { + * RtaCommandOpenConnection *openConnection = rtaCommandOpenConnection_Create(111, 2341, 2450987, NULL); + * RtaCommand *command = rtaCommand_CreateOpenConnection(openConnection); + * + * // release order does not matter + * rtaCommand_Release(&command); + * rtaCommandOpenConnection_Release(&openConnection); + * } + * @endcode + */ +RtaCommand *rtaCommand_CreateOpenConnection(const RtaCommandOpenConnection *open); + +/** + * Returns the internal RtaCommandOpenConnection object + * + * Returns the internal RtaCommandOpenConnection object, the user should not release it. + * The the RtaCommand is not of type CloseConnection, it will assert in its validation. + * + * @param [in] command The RtaCommand to query for the object. + * + * @return The RtaCommandOpenConnection object that constructed the RtaCommand. + * + * Example: + * @code + * RtaCommandOpenConnection *openConnection = rtaCommandOpenConnection_Create(111, 2341, 2450987, NULL); + * RtaCommand *command = rtaCommand_CreateOpenConnection(openConnection); + * + * const RtaCommandOpenConnection *testValue = rtaCommand_GetOpenConnection(command); + * assertTrue(testValue == openConnection, "Wrong pointer returned"); + * + * rtaCommand_Release(&command); + * rtaCommandOpenConnection_Release(&openConnection); + * @endcode + */ +const RtaCommandOpenConnection *rtaCommand_GetOpenConnection(const RtaCommand *command); + +// ====================== +// CREATE STACK + +/** + * Tests if the RtaCommand is of type CreateProtocolStack + * + * Tests if the RtaCommand is of type CreateProtocolStack. This will also assert the + * RtaCommand invariants, so the RtaCommand object must be a properly constructed object. + * + * @param [in] command An allocated RtaCommand ojbect + * + * @return true The object is of type CreateProtocolStack + * @return false The object is of some other type + * + * Example: + * @code + * { + * CCNxStackConfig *config = ccnxStackConfig_Create(); + * RtaCommandCreateProtocolStack *createStack = rtaCommandCreateProtocolStack_Create(111, config); + * RtaCommand *command = rtaCommand_CreateCreateProtocolStack(createStack); + * assertTrue(rtaCommand_IsCreateProtocolStack(command), "Command is not CreateProtocolStack"); + * rtaCommand_Release(&command); + * rtaCommandCreateProtocolStack_Release(&createStack); + * ccnxStackConfig_Release(&config); + * } + * @endcode + */ +bool rtaCommand_IsCreateProtocolStack(const RtaCommand *command); + +/** + * Allocates and creates an RtaCommand object from a RtaCommandCreateProtocolStack + * + * Allocates and creates an RtaCommand object from a RtaCommandCreateProtocolStack + * by acquiring a reference to it and storing it in the RtaCommand. The caller + * may release their reference to `createStack` at any time. + * + * @param [in] createStack The specific command to make acquire a reference from. + * + * @return non-null A properly allocated and configured RtaCommand. + * @return null An error. + * + * Example: + * @code + * { + * CCNxStackConfig *config = ccnxStackConfig_Create(); + * RtaCommandCreateProtocolStack *createStack = rtaCommandCreateProtocolStack_Create(111, config); + * RtaCommand *command = rtaCommand_CreateCreateProtocolStack(createStack); + * + * // release order does not matter + * rtaCommand_Release(&command); + * rtaCommandCreateProtocolStack_Release(&createStack); + * ccnxStackConfig_Release(&config); + * } + * @endcode + */ +RtaCommand *rtaCommand_CreateCreateProtocolStack(const RtaCommandCreateProtocolStack *createStack); + +/** + * Returns the internal RtaCommandCreateProtocolStack object + * + * Returns the internal RtaCommandCreateProtocolStack object, the user should not release it. + * The the RtaCommand is not of type CloseConnection, it will assert in its validation. + * + * @param [in] command The RtaCommand to query for the object. + * + * @return The RtaCommandCreateProtocolStack object that constructed the RtaCommand. + * + * Example: + * @code + * { + * CCNxStackConfig *config = ccnxStackConfig_Create(); + * RtaCommandCreateProtocolStack *createStack = rtaCommandCreateProtocolStack_Create(111, config); + * RtaCommand *command = rtaCommand_CreateCreateProtocolStack(createStack); + * + * const RtaCommandOpenConnection *testValue = rtaCommand_GetOpenConnection(command); + * assertTrue(testValue == createStack, "Wrong pointer returned"); + * + * rtaCommand_Release(&command); + * rtaCommandCreateProtocolStack_Release(&createStack); + * ccnxStackConfig_Release(&config); + * } + * @endcode + */ +const RtaCommandCreateProtocolStack *rtaCommand_GetCreateProtocolStack(const RtaCommand *command); + +// ====================== +// DESTROY STACK + +/** + * Tests if the RtaCommand is of type DestroyProtocolStack + * + * Tests if the RtaCommand is of type DestroyProtocolStack. This will also assert the + * RtaCommand invariants, so the RtaCommand object must be a properly constructed object. + * + * @param [in] command An allocated RtaCommand ojbect + * + * @return true The object is of type DestroyProtocolStack + * @return false The object is of some other type + * + * Example: + * @code + * { + * RtaCommandDestroyProtocolStack *destroyStack = rtaCommandDestroyProtocolStack_Create(77); + * RtaCommand *command = rtaCommand_CreateDestroyProtocolStack(destroyStack); + * assertTrue(rtaCommand_IsDestroyProtocolStack(command), "Command is not DestroyProtocolStack"); + * rtaCommand_Release(&command); + * rtaCommandDestroyProtocolStack_Release(&destroyStack); + * } + * @endcode + */ +bool rtaCommand_IsDestroyProtocolStack(const RtaCommand *command); + +/** + * Allocates and creates an RtaCommand object from a RtaCommandDestroyProtocolStack + * + * Allocates and creates an RtaCommand object from a RtaCommandDestroyProtocolStack + * by acquiring a reference to it and storing it in the RtaCommand. The caller + * may release their reference to `destroyStack` at any time. + * + * @param [in] destroyStack The specific command to make acquire a reference from. + * + * @return non-null A properly allocated and configured RtaCommand. + * @return null An error. + * + * Example: + * @code + * { + * RtaCommandDestroyProtocolStack *destroyStack = rtaCommandDestroyProtocolStack_Create(77); + * RtaCommand *command = rtaCommand_CreateDestroyProtocolStack(destroyStack); + * + * // release order does not matter + * rtaCommand_Release(&command); + * rtaCommandDestroyProtocolStack_Release(&destroyStack); + * } + * @endcode + */ +RtaCommand *rtaCommand_CreateDestroyProtocolStack(const RtaCommandDestroyProtocolStack *destroyStack); + +/** + * Returns the internal RtaCommandDestroyProtocolStack object + * + * Returns the internal RtaCommandDestroyProtocolStack object, the user should not release it. + * The the RtaCommand is not of type CloseConnection, it will assert in its validation. + * + * @param [in] command The RtaCommand to query for the object. + * + * @return The RtaCommandDestroyProtocolStack object that constructed the RtaCommand. + * + * Example: + * @code + * RtaCommandDestroyProtocolStack *destroyStack = rtaCommandDestroyProtocolStack_Create(77); + * RtaCommand *command = rtaCommand_CreateDestroyProtocolStack(destroyStack); + * + * const RtaCommandDestroyProtocolStack *testValue = rtaCommand_GetOpenConnection(command); + * assertTrue(testValue == destroyStack, "Wrong pointer returned"); + * + * rtaCommand_Release(&command); + * rtaCommandDestroyProtocolStack_Release(&destroyStack); + * @endcode + */ +const RtaCommandDestroyProtocolStack *rtaCommand_GetDestroyProtocolStack(const RtaCommand *command); + +// ====================== +// SHUTDOWN FRAMEWORK + +/** + * Tests if the RtaCommand is of type ShutdownFramework + * + * Tests if the RtaCommand is of type ShutdownFramework. This will also assert the + * RtaCommand invariants, so the RtaCommand object must be a properly constructed object. + * + * The ShutdownFramework command has no parameters, so there is no rtaCommand_GetShutdownFramework() function. + * + * @param [in] command An allocated RtaCommand ojbect + * + * @return true The object is of type ShutdownFramework + * @return false The object is of some other type + * + * Example: + * @code + * { + * RtaCommand *command = rtaCommand_CreateShutdownFramework(); + * assertTrue(rtaCommand_IsShutdownFramework(command), "Command is not shutdown framework"); + * rtaCommand_Release(&command); + * } + * @endcode + */ +bool rtaCommand_IsShutdownFramework(const RtaCommand *command); + +/** + * Allocates and creates an RtaCommand object of type ShutdownFramework. + * + * Allocates and creates an RtaCommand object of type ShutdownFramework. + * There are no parameters to ShutdownFramework, so there is no underlying type. + * + * @return non-null A properly allocated and configured RtaCommand. + * @return null An error. + * + * Example: + * @code + * { + * RtaCommand *command = rtaCommand_CreateShutdownFramework(); + * rtaCommand_Release(&command); + * } + * @endcode + */ +RtaCommand *rtaCommand_CreateShutdownFramework(void); + +// ====================== +// TRANSMIT STATS + +/** + * Tests if the RtaCommand is of type TransmitStatistics + * + * Tests if the RtaCommand is of type TransmitStatistics. This will also assert the + * RtaCommand invariants, so the RtaCommand object must be a properly constructed object. + * + * @param [in] command An allocated RtaCommand ojbect + * + * @return true The object is of type TransmitStatistics + * @return false The object is of some other type + * + * Example: + * @code + * { + * RtaCommandTransmitStatistics *transmitStats = rtaCommandTransmitStatistics_Create((struct timeval) { 1, 2 }, "filename"); + * RtaCommand *command = rtaCommand_CreateTransmitStatistics(transmitStats); + * assertTrue(rtaCommand_IsTransmitStatistics(command), "Command is not TransmitStatistics"); + * rtaCommand_Release(&command); + * rtaCommandTransmitStatistics_Release(&transmitStats); + * } + * @endcode + */ +bool rtaCommand_IsTransmitStatistics(const RtaCommand *command); + +/** + * Allocates and creates an RtaCommand object from a RtaCommandTransmitStatistics + * + * Allocates and creates an RtaCommand object from a RtaCommandTransmitStatistics + * by acquiring a reference to it and storing it in the RtaCommand. The caller + * may release their reference to `transmitStats` at any time. + * + * @param [in] transmitStats The specific command to make acquire a reference from. + * + * @return non-null A properly allocated and configured RtaCommand. + * @return null An error. + * + * Example: + * @code + * { + * RtaCommandTransmitStatistics *transmitStats = rtaCommandTransmitStatistics_Create((struct timeval) { 1, 2 }, "filename"); + * RtaCommand *command = rtaCommand_CreateTransmitStatistics(transmitStats); + * + * // release order does not matter + * rtaCommand_Release(&command); + * rtaCommandTransmitStatistics_Release(&transmitStats); + * } + * @endcode + */ +RtaCommand *rtaCommand_CreateTransmitStatistics(const RtaCommandTransmitStatistics *transmitStats); + +/** + * Returns the internal RtaCommandTransmitStatistics object + * + * Returns the internal RtaCommandTransmitStatistics object, the user should not release it. + * The the RtaCommand is not of type CloseConnection, it will assert in its validation. + * + * @param [in] command The RtaCommand to query for the object. + * + * @return The RtaCommandTransmitStatistics object that constructed the RtaCommand. + * + * Example: + * @code + * RtaCommandTransmitStatistics *transmitStats = rtaCommandTransmitStatistics_Create((struct timeval) { 1, 2 }, "filename"); + * RtaCommand *command = rtaCommand_CreateTransmitStatistics(transmitStats); + * + * const RtaCommandDestroyProtocolStack *testValue = rtaCommand_GetOpenConnection(command); + * assertTrue(testValue == destroyStack, "Wrong pointer returned"); + * + * rtaCommand_Release(&command); + * rtaCommandTransmitStatistics_Release(&transmitStats); + * @endcode + */ +const RtaCommandTransmitStatistics *rtaCommand_GetTransmitStatistics(const RtaCommand *command); +#endif // Libccnx_rta_Commands_h |