All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Modules Pages
as_error.h
Go to the documentation of this file.
1 /*
2  * Copyright 2008-2014 Aerospike, Inc.
3  *
4  * Portions may be licensed to Aerospike, Inc. under one or more contributor
5  * license agreements.
6  *
7  * Licensed under the Apache License, Version 2.0 (the "License"); you may not
8  * use this file except in compliance with the License. You may obtain a copy of
9  * the License at http://www.apache.org/licenses/LICENSE-2.0
10  *
11  * Unless required by applicable law or agreed to in writing, software
12  * distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
13  * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
14  * License for the specific language governing permissions and limitations under
15  * the License.
16  */
17 #pragma once
18 
19 #include <aerospike/as_status.h>
20 
21 #include <stdarg.h>
22 #include <stdint.h>
23 #include <stdio.h>
24 #include <string.h>
25 
26 /******************************************************************************
27  * MACROS
28  *****************************************************************************/
29 
30 /**
31  * The size of as_error.message
32  *
33  * @ingroup as_error_object
34  */
35 #define AS_ERROR_MESSAGE_MAX_SIZE 1024
36 
37 /**
38  * The maximum string length of as_error.message
39  *
40  * @ingroup as_error_object
41  */
42 #define AS_ERROR_MESSAGE_MAX_LEN (AS_ERROR_MESSAGE_MAX_SIZE - 1)
43 
44 /******************************************************************************
45  * TYPES
46  *****************************************************************************/
47 
48 /**
49  * All operations that interact with the Aerospike cluster accept an as_error
50  * argument and return an as_status value. The as_error argument is populated
51  * with information about the error that occurred. The as_status return value
52  * is the as_error.code value.
53  *
54  * When an operation succeeds, the as_error.code value is usually set to
55  * `AEROSPIKE_OK`. There are some operations which may have other success
56  * status codes, so please review each operation for information on status
57  * codes.
58  *
59  * When as_error.code is not a success value (`AEROSPIKE_OK`), then you can
60  * expect the other fields of as_error.code to be populated.
61  *
62  * Example usage:
63  * ~~~~~~~~~~{.c}
64  * as_error err;
65  *
66  * if ( aerospike_key_get(&as, &err, NULL, &key, &rec) != AEROSPIKE_OK ) {
67  * fprintf(stderr, "(%d) %s at %s[%s:%d]\n", error.code, err.message, err.func, err.file. err.line);
68  * }
69  * ~~~~~~~~~~
70  *
71  * You can reuse an as_error with multiple operations. Each operation
72  * internally resets the error. So, if an error occurred in one operation,
73  * and you did not check it, then the error will be lost with subsequent
74  * operations.
75  *
76  * Example usage:
77  *
78  * ~~~~~~~~~~{.c}
79  * as_error err;
80  *
81  * if ( aerospike_key_put(&as, &err, NULL, &key, rec) != AEROSPIKE_OK ) {
82  * fprintf(stderr, "(%d) %s at %s[%s:%d]\n", error.code, err.message, err.func, err.file. err.line);
83  * }
84  *
85  * if ( aerospike_key_get(&as, &err, NULL, &key, &rec) != AEROSPIKE_OK ) {
86  * fprintf(stderr, "(%d) %s at %s[%s:%d]\n", error.code, err.message, err.func, err.file. err.line);
87  * }
88  * ~~~~~~~~~~
89  *
90  * @ingroup client_objects
91  */
92 typedef struct as_error_s {
93 
94  /**
95  * Numeric error code
96  */
98 
99  /**
100  * NULL-terminated error message
101  */
103 
104  /**
105  * Name of the function where the error occurred.
106  */
107  const char * func;
108 
109  /**
110  * Name of the file where the error occurred.
111  */
112  const char * file;
113 
114  /**
115  * Line in the file where the error occurred.
116  */
117  uint32_t line;
118 
119 } as_error;
120 
121 /******************************************************************************
122  * MACROS
123  *****************************************************************************/
124 
125 /**
126  * as_error_update(&as->error, AEROSPIKE_OK, "%s %d", "a", 1);
127  *
128  * @ingroup as_error_object
129  */
130 #define as_error_update(__err, __code, __fmt, ...) \
131  as_error_setallv( __err, __code, __func__, __FILE__, __LINE__, __fmt, ##__VA_ARGS__ );
132 
133 /**
134  * as_error_set_message(&as->error, AEROSPIKE_ERR, "error message");
135  *
136  * @ingroup as_error_object
137  */
138 #define as_error_set_message(__err, __code, __msg) \
139  as_error_setall( __err, __code, __msg, __func__, __FILE__, __LINE__ );
140 
141 /******************************************************************************
142  * FUNCTIONS
143  *****************************************************************************/
144 
145 /**
146  * Initialize the error to default (empty) values, returning the error.
147  *
148  * @param err The error to initialize.
149  *
150  * @returns The initialized err.
151  *
152  * @relates as_error
153  * @ingroup as_error_object
154  */
155 static inline as_error * as_error_init(as_error * err) {
156  err->code = AEROSPIKE_OK;
157  err->message[0] = '\0';
158  err->func = NULL;
159  err->file = NULL;
160  err->line = 0;
161  return err;
162 }
163 
164 /**
165  * Resets the error to default (empty) values, returning the status code.
166  *
167  * @param err The error to reset.
168  *
169  * @returns AEROSPIKE_OK.
170  *
171  * @relates as_error
172  * @ingroup as_error_object
173  */
174 static inline as_status as_error_reset(as_error * err) {
175  err->code = AEROSPIKE_OK;
176  err->message[0] = '\0';
177  err->func = NULL;
178  err->file = NULL;
179  err->line = 0;
180  return err->code;
181 }
182 
183 /**
184  * Sets the error.
185  *
186  * @return The status code set for the error.
187  *
188  * @relates as_error
189  */
190 static inline as_status as_error_setall(as_error * err, as_status code, const char * message, const char * func, const char * file, uint32_t line) {
191  err->code = code;
192  strncpy(err->message, message, AS_ERROR_MESSAGE_MAX_LEN);
193  err->message[AS_ERROR_MESSAGE_MAX_LEN] = '\0';
194  err->func = func;
195  err->file = file;
196  err->line = line;
197  return err->code;
198 }
199 
200 /**
201  * Sets the error.
202  *
203  * @return The status code set for the error.
204  *
205  * @relates as_error
206  */
207 static inline as_status as_error_setallv(as_error * err, as_status code, const char * func, const char * file, uint32_t line, const char * fmt, ...) {
208  if ( fmt != NULL ) {
209  va_list ap;
210  va_start(ap, fmt);
211  vsnprintf(err->message, AS_ERROR_MESSAGE_MAX_LEN, fmt, ap);
212  err->message[AS_ERROR_MESSAGE_MAX_LEN] = '\0';
213  va_end(ap);
214  }
215  err->code = code;
216  err->func = func;
217  err->file = file;
218  err->line = line;
219  return err->code;
220 }
221 
222 /**
223  * Sets the error message
224  *
225  * @relates as_error
226  */
227 static inline as_status as_error_set(as_error * err, as_status code, const char * fmt, ...) {
228  if ( fmt != NULL ) {
229  va_list ap;
230  va_start(ap, fmt);
231  vsnprintf(err->message, AS_ERROR_MESSAGE_MAX_LEN, fmt, ap);
232  err->message[AS_ERROR_MESSAGE_MAX_LEN] = '\0';
233  va_end(ap);
234  }
235  err->code = code;
236  return err->code;
237 }
#define AS_ERROR_MESSAGE_MAX_LEN
Definition: as_error.h:42
as_status
Definition: as_status.h:26
char message[AS_ERROR_MESSAGE_MAX_SIZE]
Definition: as_error.h:102
const char * file
Definition: as_error.h:112
static as_error * as_error_init(as_error *err)
Definition: as_error.h:155
const char * func
Definition: as_error.h:107
static as_status as_error_set(as_error *err, as_status code, const char *fmt,...)
Definition: as_error.h:227
#define AS_ERROR_MESSAGE_MAX_SIZE
Definition: as_error.h:35
static as_status as_error_reset(as_error *err)
Definition: as_error.h:174
uint32_t line
Definition: as_error.h:117
as_status code
Definition: as_error.h:97
static as_status as_error_setallv(as_error *err, as_status code, const char *func, const char *file, uint32_t line, const char *fmt,...)
Definition: as_error.h:207
static as_status as_error_setall(as_error *err, as_status code, const char *message, const char *func, const char *file, uint32_t line)
Definition: as_error.h:190