Petr Machata | a24021c | 2012-09-25 14:46:44 +0200 | [diff] [blame] | 1 | /* |
| 2 | * This file is part of ltrace. |
Petr Machata | 4e293f9 | 2013-10-14 20:02:38 +0200 | [diff] [blame] | 3 | * Copyright (C) 2011,2012,2013 Petr Machata, Red Hat Inc. |
Petr Machata | a24021c | 2012-09-25 14:46:44 +0200 | [diff] [blame] | 4 | * |
| 5 | * This program is free software; you can redistribute it and/or |
| 6 | * modify it under the terms of the GNU General Public License as |
| 7 | * published by the Free Software Foundation; either version 2 of the |
| 8 | * License, or (at your option) any later version. |
| 9 | * |
| 10 | * This program is distributed in the hope that it will be useful, but |
| 11 | * WITHOUT ANY WARRANTY; without even the implied warranty of |
| 12 | * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU |
| 13 | * General Public License for more details. |
| 14 | * |
| 15 | * You should have received a copy of the GNU General Public License |
| 16 | * along with this program; if not, write to the Free Software |
| 17 | * Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA |
| 18 | * 02110-1301 USA |
| 19 | */ |
| 20 | |
| 21 | #ifndef _CALLBACK_H_ |
| 22 | #define _CALLBACK_H_ |
| 23 | |
| 24 | /* Notes on the iteration interface used across ltrace. Typically the |
| 25 | * iteration function looks something like this: |
| 26 | * |
| 27 | * foo *each_foo(foo *start_after, |
| 28 | * enum callback_status (*cb)(foo *f, void *data), |
| 29 | * void *data); |
| 30 | * |
| 31 | * The iteration starts after the element designated by START_AFTER, |
| 32 | * or at the first element if START_AFTER is NULL. CB is then called |
| 33 | * for each element of the collection. DATA is passed verbatim to CB. |
| 34 | * If CB returns CBS_STOP, the iteration stops and the current element |
| 35 | * is returned. That element can then be passed as START_AFTER to |
| 36 | * restart the iteration. NULL is returned when iteration ends. |
| 37 | * |
| 38 | * CBS_FAIL is not currently handled, and essentially means the same |
| 39 | * thing as CBS_STOP. There's no provision for returning error |
| 40 | * states. Errors need to be signaled to the caller via DATA, |
| 41 | * together with any other data that the callback needs. |
Petr Machata | 4e293f9 | 2013-10-14 20:02:38 +0200 | [diff] [blame] | 42 | * |
| 43 | * A richer iteration interface looks like this: |
| 44 | * |
| 45 | * struct each_foo_t { |
| 46 | * foo *restart; |
| 47 | * int status; |
| 48 | * } each_foo(foo *start_after, |
| 49 | * enum callback_status (*cb)(foo *f, void *data), |
| 50 | * void *data); |
| 51 | * |
| 52 | * These provide error handling. The two-part structure encodes both |
| 53 | * the restart cookie and status. Status of 0 means success, negative |
| 54 | * values signify failures. Status of -1 is dedicated to failures in |
| 55 | * user callback (such that the callback returns CBS_FAIL). Other |
| 56 | * negative values signal failures in the iteration mechanism itself. |
Petr Machata | a24021c | 2012-09-25 14:46:44 +0200 | [diff] [blame] | 57 | */ |
| 58 | enum callback_status { |
| 59 | CBS_STOP, /* The iteration should stop. */ |
| 60 | CBS_CONT, /* The iteration should continue. */ |
| 61 | CBS_FAIL, /* There was an error. The iteration should stop |
| 62 | * and return error. */ |
| 63 | }; |
| 64 | |
Petr Machata | 567399a | 2012-12-05 21:36:00 +0100 | [diff] [blame] | 65 | #define CBS_STOP_IF(X) ((X) ? CBS_STOP : CBS_CONT) |
| 66 | #define CBS_CONT_IF(X) ((X) ? CBS_CONT : CBS_STOP) |
| 67 | |
Petr Machata | a24021c | 2012-09-25 14:46:44 +0200 | [diff] [blame] | 68 | #endif /* _CALLBACK_H_ */ |