20.1.9 ead_put_all() (stores keys and values by using a batch operation)

(1) Description

Using a batch operation, this function stores multiple keys and values in cache.

An array of the ead_key_value_pair structure is specified in the argument and each key is associated with a value and then is stored in cache.

If the same key is specified multiple times, it is processed multiple times in the order specified.

To Page Top

(2) Format

#include <eads.h>
ead_put_all_results ead_put_all
(
  const EAD_CACHE              *cp,                 /* In */
  size_t                       array_length,        /* In */
  const ead_key_value_pair     *key_value_array,    /* In */
  int                          *error_code          /* Out */
);

To Page Top

(3) Arguments

cp

Specifies the handle (pointer) to the cache where the keys and values are to be stored.

Specify the handle (pointer) obtained from ead_start_cache() when access to the cache was started.

array_length

Specifies the number of array elements of the ead_key_value_pair structure to be stored.

For details about the ead_key_value_pair structure and its format, see 20.1.40 ead_key_value_pair structure (key-value pairs).

key_value_array

Specifies the pointer to the top of the array of the ead_key_value_pair structure to be stored.

For details about the ead_key_value_pair structure and its format, see 20.1.40 ead_key_value_pair structure (key-value pairs).

error_code

Specifies the pointer from which to retrieve the error code.

For details about error codes, see 20.2 Error codes in the client library (C).

To Page Top

(4) Return value

Using a batch operation, this function returns the results (ead_put_all_results structure) of storing keys and values.

• If the batch storage processing was successful

  The success_operation_number member contains the same number of keys as in the list of keys specified in the argument, and the failure_info member contains NULL.

• If the batch storage processing failed partially or entirely

  The failure_info member contains as many sets of information about the failed processing as indicated in the failure_operation_number member.

• If an error occurred during non-key processing (such as an invalid argument or a shortage of memory area)

  A numeric-type member of the ead_put_all_results structure contains 0, and a pointer-type member contains NULL.

For details about the ead_put_all_results structure and its format, see 20.1.43 ead_put_all_results structure (execution results of ead_put_all()).

To Page Top

(5) Notes

• If the batch storage processing fails, this function returns the following error codes:

  • If the batch storage processing failed entirely

    EAD_ERROR_BATCH_FAILED_ALL

  • If the batch storage processing failed partially

    EAD_ERROR_BATCH_FAILED_PART

• The memory area for storing the results of batch storage of keys and values that is returned as the return value is not freed automatically. You must free it in the application program. For details, see 19.1.1(10) Freeing a memory area returned as a return value.

• A value of zero cannot be specified in array_length. If an invalid value is specified, valid operation is not guaranteed.

• Make sure that you allocate a contiguous memory area for the array of the ead_key_value_pair structure that is large enough for the elements.

• If the cache operation fails partially, identify which operations have failed from the return value, and then re-execute this function, if necessary.

• Because caches are not locked while operations are ongoing, a target value might be changed by another cache operation during batch operation.

• When batch operations are performed on a large amount of data, a large amount of memory might be required by EADS clients and EADS servers.

• When batch operations are performed on a large amount of data, it might take a long time to complete the processing. To ensure proper operation, make sure that you design a timeout value that is appropriate for the processing time.

To Page Top