Skip to content

Commit

Permalink
Fixup for PR.
Browse files Browse the repository at this point in the history
  • Loading branch information
@nburek
nburek committed Jan 7, 2019
1 parent 6eec102 commit e981a92
Show file tree
Hide file tree
Showing 6 changed files with 247 additions and 122 deletions.
118 changes: 98 additions & 20 deletions include/rcutils/types/array_list.h
View file
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
// Copyright 2017 Open Source Robotics Foundation, Inc.
// Copyright 2018-2019 Open Source Robotics Foundation, Inc.
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
Expand Down Expand Up @@ -34,6 +34,19 @@ typedef struct RCUTILS_PUBLIC_TYPE rcutils_array_list_t
struct rcutils_array_list_impl_t * impl;
} rcutils_array_list_t;

/**
* Validates that an rcutils_array_list_t* points to a valid array list.
* \param array_list A pointer to an rcutils_array_list_t
* \return RCUTILS_RET_INVALID_ARGUMENT if array_list is null
* \return RCUTILS_RET_NOT_INITIALIZED if array_list is not initialized
*/
#define ARRAY_LIST_VALIDATE_ARRAY_LIST(array_list) \
RCUTILS_CHECK_ARGUMENT_FOR_NULL(array_list, RCUTILS_RET_INVALID_ARGUMENT); \
if (NULL == array_list->impl) { \
RCUTILS_SET_ERROR_MSG("array_list is not initialized"); \
return RCUTILS_RET_NOT_INITIALIZED; \
}

/// Return an empty array_list struct.
/**
* This function returns an empty and zero initialized array_list struct.
Expand All @@ -42,6 +55,14 @@ typedef struct RCUTILS_PUBLIC_TYPE rcutils_array_list_t
* Every instance of array_list_t has to either be zero_initialized with this
* function or manually allocated.
*
* <hr>
* Attribute | Adherence
* ------------------ | -------------
* Allocates Memory | No
* Thread-Safe | Yes
* Uses Atomics | No
* Lock-Free | Yes
*
* Example:
*
* ```c
Expand All @@ -56,25 +77,36 @@ RCUTILS_PUBLIC
rcutils_array_list_t
rcutils_get_zero_initialized_array_list(void);

/// Initialize an array liast with a given initial capacity.
/// Initialize an array list with a given initial capacity.
/**
* This function will initialize a given, zero initialized, string array to
* This function will initialize a given, zero initialized, array_list to
* a given size.
*
* Note that putting a string into the array gives owenship to the array.
* <hr>
* Attribute | Adherence
* ------------------ | -------------
* Allocates Memory | Yes
* Thread-Safe | No
* Uses Atomics | No
* Lock-Free | Yes
*
* Example:
*
* ```c
* rcutils_allocator_t allocator = rcutils_get_default_allocator();
* rcutils_array_list_t array_list = rcutils_get_zero_initialized_array_list();
* rcutils_ret_t ret = rcutils_array_list_init(&array_list, 2, &allocator);
* rcutils_ret_t ret = rcutils_array_list_init(&array_list, 2, sizeof(int), &allocator);
* if (ret != RCUTILS_RET_OK) {
* // ... error handling
* }
* array_list.data[0] = rcutils_strdup("Hello", &allocator);
* array_list.data[1] = rcutils_strdup("World", &allocator);
* int data = 42;
* int out_data = 0;
* ret = rcutils_array_list_add(&array_list, &data);
* data++;
* ret = rcutils_array_list_get(&array_list, 0, &out_data);
* assert(42 == out_data);
* ret = rcutils_array_list_fini(&array_list);
* ```
*
* \param[inout] array_list object to be initialized
* \param[in] initial_capacity the initial capacity to allocate in the list
Expand All @@ -84,7 +116,6 @@ rcutils_get_zero_initialized_array_list(void);
* \return `RCUTILS_RET_INVALID_ARGUMENT` for invalid arguments, or
* \return `RCUTILS_RET_BAD_ALLOC` if memory allocation fails, or
* \return `RCUTILS_RET_ERROR` if an unknown error occurs
* ```
*/
RCUTILS_PUBLIC
rcutils_ret_t
Expand All @@ -94,13 +125,20 @@ rcutils_array_list_init(
size_t data_size,
const rcutils_allocator_t * allocator);

/// Finalize a string array, reclaiming all resources.
/// Finalize an array list, reclaiming all resources.
/**
* This function reclaims any memory owned by the string array, including the
* strings it references.
* This function reclaims any memory owned by the array list.
*
* The allocator used to initialize the string array is used to deallocate each
* string in the array and the array of strings itself.
* The allocator used to initialize the array list is used to deallocate each
* entry in the list and the list itself.
*
* <hr>
* Attribute | Adherence
* ------------------ | -------------
* Allocates Memory | No
* Thread-Safe | No
* Uses Atomics | No
* Lock-Free | Yes
*
* \param[inout] array_list object to be finalized
* \return `RCUTILS_RET_OK` if successful, or
Expand All @@ -114,10 +152,17 @@ rcutils_array_list_fini(rcutils_array_list_t * array_list);

/// Adds an entry to the list
/**
* This functions adds the provided data to the end of the list. A copy of
* This function adds the provided data to the end of the list. A shallow copy of
* the provided data is made to store in the list instead of just storing
* the pointer to the provided data.
*
* <hr>
* Attribute | Adherence
* ------------------ | -------------
* Allocates Memory | Yes
* Thread-Safe | No
* Uses Atomics | No
* Lock-Free | Yes
*
* \param[in] array_list to add the data to
* \param[in] data a pointer to the data to add to the list
Expand All @@ -133,16 +178,24 @@ rcutils_array_list_add(rcutils_array_list_t * array_list, const void * data);

/// Sets an entry in the list to the provided data
/**
* This functions sets the provided data at the specified index in the list. A copy of
* the provided data is made to store in the list instead of just storing
* the pointer to the provided data.
* This function sets the provided data at the specified index in the list.
* A shallow copy of the provided data is made to store in the list instead
* of just storing the pointer to the provided data.
*
* <hr>
* Attribute | Adherence
* ------------------ | -------------
* Allocates Memory | No
* Thread-Safe | No
* Uses Atomics | No
* Lock-Free | Yes
*
* \param[in] array_list to add the data to
* \param[in] index the position in the list to set the data
* \param[in] data a pointer to the data that will be set in the list
* \return `RCUTILS_RET_OK` if successful, or
* \return `RCUTILS_RET_INVALID_ARGUMENT` for invalid arguments, or
* \return `RCUTILS_RET_INVALID_ARGUMENT` if index out of bounds, or
* \return `RCUTILS_RET_BAD_ALLOC` if memory allocation fails, or
* \return `RCUTILS_RET_ERROR` if an unknown error occurs
*/
Expand All @@ -153,12 +206,21 @@ rcutils_array_list_set(rcutils_array_list_t * array_list, size_t index, const vo

/// Removes an entry in the list at the provided index
/**
* This functions removes data from the list at the specified index.
* This function removes data from the list at the specified index. The capacity
* of the list will never decrease when entries are removed.
*
* <hr>
* Attribute | Adherence
* ------------------ | -------------
* Allocates Memory | No
* Thread-Safe | No
* Uses Atomics | No
* Lock-Free | Yes
*
* \param[in] array_list to add the data to
* \return `RCUTILS_RET_OK` if successful, or
* \return `RCUTILS_RET_INVALID_ARGUMENT` for invalid arguments, or
* \return `RCUTILS_RET_INVALID_ARGUMENT` if index out of bounds, or
* \return `RCUTILS_RET_BAD_ALLOC` if memory allocation fails, or
* \return `RCUTILS_RET_ERROR` if an unknown error occurs
*/
Expand All @@ -169,7 +231,15 @@ rcutils_array_list_remove(rcutils_array_list_t * array_list, size_t index);

/// Retrieves an entry in the list at the provided index
/**
* This functions retrieves a copy of the data stored in the list.
* This function retrieves a copy of the data stored in the list at the provided index.
*
* <hr>
* Attribute | Adherence
* ------------------ | -------------
* Allocates Memory | No
* Thread-Safe | No
* Uses Atomics | No
* Lock-Free | Yes
*
*
* \param[in] array_list to add the data to
Expand All @@ -187,7 +257,15 @@ rcutils_array_list_get(const rcutils_array_list_t * array_list, size_t index, vo

/// Retrieves the size of the provided array_list
/**
* This functions retrieves the size of the provided array list
* This function retrieves the number of items in the provided array list
*
* <hr>
* Attribute | Adherence
* ------------------ | -------------
* Allocates Memory | No
* Thread-Safe | No
* Uses Atomics | No
* Lock-Free | Yes
*
*
* \param[in] array_list list to get the size of
Expand Down
Loading

0 comments on commit e981a92

Please sign in to comment.