f6/c44e4eb220a6ce7ed9df2299da28a0ab63ca3a

   1 Return-Path: <amdragon@mit.edu>\r
   2 X-Original-To: notmuch@notmuchmail.org\r
   3 Delivered-To: notmuch@notmuchmail.org\r
   4 Received: from localhost (localhost [127.0.0.1])\r
   5         by olra.theworths.org (Postfix) with ESMTP id A7CA7431FCF\r
   6         for <notmuch@notmuchmail.org>; Wed, 23 Oct 2013 12:32:20 -0700 (PDT)\r
   7 X-Virus-Scanned: Debian amavisd-new at olra.theworths.org\r
   8 X-Spam-Flag: NO\r
   9 X-Spam-Score: -0.7\r
  10 X-Spam-Level: \r
  11 X-Spam-Status: No, score=-0.7 tagged_above=-999 required=5\r
  12         tests=[RCVD_IN_DNSWL_LOW=-0.7] autolearn=disabled\r
  13 Received: from olra.theworths.org ([127.0.0.1])\r
  14         by localhost (olra.theworths.org [127.0.0.1]) (amavisd-new, port 10024)\r
  15         with ESMTP id Uvyvt3ZzfiBI for <notmuch@notmuchmail.org>;\r
  16         Wed, 23 Oct 2013 12:32:15 -0700 (PDT)\r
  17 Received: from dmz-mailsec-scanner-1.mit.edu (dmz-mailsec-scanner-1.mit.edu\r
  18         [18.9.25.12])\r
  19         by olra.theworths.org (Postfix) with ESMTP id 23484431FC2\r
  20         for <notmuch@notmuchmail.org>; Wed, 23 Oct 2013 12:32:15 -0700 (PDT)\r
  21 X-AuditID: 1209190c-b7fd38e0000009aa-c9-5268243efa3b\r
  22 Received: from mailhub-auth-3.mit.edu ( [18.9.21.43])\r
  23         by dmz-mailsec-scanner-1.mit.edu (Symantec Messaging Gateway) with SMTP\r
  24         id F4.F3.02474.E3428625; Wed, 23 Oct 2013 15:32:14 -0400 (EDT)\r
  25 Received: from outgoing.mit.edu (outgoing-auth-1.mit.edu [18.9.28.11])\r
  26         by mailhub-auth-3.mit.edu (8.13.8/8.9.2) with ESMTP id r9NJWCTZ008799; \r
  27         Wed, 23 Oct 2013 15:32:13 -0400\r
  28 Received: from awakening.csail.mit.edu (awakening.csail.mit.edu [18.26.4.91])\r
  29         (authenticated bits=0)\r
  30         (User authenticated as amdragon@ATHENA.MIT.EDU)\r
  31         by outgoing.mit.edu (8.13.8/8.12.4) with ESMTP id r9NJWAfD029830\r
  32         (version=TLSv1/SSLv3 cipher=DHE-RSA-AES128-SHA bits=128 verify=NOT);\r
  33         Wed, 23 Oct 2013 15:32:11 -0400\r
  34 Received: from amthrax by awakening.csail.mit.edu with local (Exim 4.80)\r
  35         (envelope-from <amdragon@mit.edu>)\r
  36         id 1VZ4A5-0006eV-OK; Wed, 23 Oct 2013 15:32:09 -0400\r
  37 Date: Wed, 23 Oct 2013 15:32:09 -0400\r
  38 From: Austin Clements <amdragon@MIT.EDU>\r
  39 To: Tomi Ollila <tomi.ollila@iki.fi>\r
  40 Subject: Re: [PATCH 1/3] cli: add insert --must-index option\r
  41 Message-ID: <20131023193209.GF20337@mit.edu>\r
  42 References: <1374365254-13227-1-git-send-email-novalazy@gmail.com>\r
  43         <87ip048gbj.fsf@qmul.ac.uk>\r
  44         <20130727151510.GA13750@hili.localdomain>\r
  45         <87hadtxfrr.fsf@qmul.ac.uk>\r
  46         <20130912001349.GA18821@hili.localdomain>\r
  47         <87zjqhv264.fsf@zancas.localnet>\r
  48         <m238o9fguj.fsf@guru.guru-group.fi> <87bo2xtdp2.fsf@unb.ca>\r
  49         <m2eh7bu7t5.fsf@guru.guru-group.fi>\r
  50 MIME-Version: 1.0\r
  51 Content-Type: text/plain; charset=iso-8859-1\r
  52 Content-Disposition: inline\r
  53 Content-Transfer-Encoding: 8bit\r
  54 In-Reply-To: <m2eh7bu7t5.fsf@guru.guru-group.fi>\r
  55 User-Agent: Mutt/1.5.21 (2010-09-15)\r
  56 X-Brightmail-Tracker:\r
  57  H4sIAAAAAAAAA+NgFlrOKsWRmVeSWpSXmKPExsUixCmqrWunkhFkcO+DisWN1m5Gi+s3ZzJb\r
  58         vFk5j9WB2ePw14UsHs9W3WL22HLoPXMAcxSXTUpqTmZZapG+XQJXRnfXd7aCryoVn95OYG5g\r
  59         PCrTxcjJISFgIvFn8VYmCFtM4sK99WxdjFwcQgL7GCXOr3zADuFsZJS48mMnM4Rzmkmi+9Zc\r
  60         RghnCaPEtjnzwPpZBFQlDsx9xQ5iswloSGzbv5wRxBYRUJF40LaeFcRmFrCTOPK9CywuLGAj\r
  61         0T37JRuIzSugI/H0yBqoofeZJJbdaWOGSAhKnJz5hAWiWUdi59Y7QA0cQLa0xPJ/HBBheYnm\r
  62         rbPByjkFDCTeHd8Ndo8o0N4pJ7exTWAUnoVk0iwkk2YhTJqFZNICRpZVjLIpuVW6uYmZOcWp\r
  63         ybrFyYl5ealFuoZ6uZkleqkppZsYwfEhybOD8c1BpUOMAhyMSjy8Gh/Sg4RYE8uKK3MPMUpy\r
  64         MCmJ8uopZwQJ8SXlp1RmJBZnxBeV5qQWH2KU4GBWEuF98geonDclsbIqtSgfJiXNwaIkznuT\r
  65         wz5ISCA9sSQ1OzW1ILUIJivDwaEkwWsBMlSwKDU9tSItM6cEIc3EwQkynAdouBlIDW9xQWJu\r
  66         cWY6RP4Uo6KUOO9VJaCEAEgiozQPrheWvl4xigO9IszLAdLOA0x9cN2vgAYzAQ2esiQNZHBJ\r
  67         IkJKqoGxy/uv5+ojzNcuKaxx9VoxP2XersytIa330+I6k1X8Gp7sVNV+YOYdePFR2pltgv4J\r
  68         N3K0f15tYeA3d1omulPPJih8ctBE6UD+rT2Cd2MXpOf+1D7iHSL7UuNHvyBX2pRfX5eskC8p\r
  69         /mKQLfN/oq3rvZWnwr3lOzpsd63/VtuwfRVb/fmPjIuVWIozEg21mIuKEwEz2/mLOgMAAA==\r
  70 Cc: notmuch@notmuchmail.org\r
  71 X-BeenThere: notmuch@notmuchmail.org\r
  72 X-Mailman-Version: 2.1.13\r
  73 Precedence: list\r
  74 List-Id: "Use and development of the notmuch mail system."\r
  75         <notmuch.notmuchmail.org>\r
  76 List-Unsubscribe: <http://notmuchmail.org/mailman/options/notmuch>,\r
  77         <mailto:notmuch-request@notmuchmail.org?subject=unsubscribe>\r
  78 List-Archive: <http://notmuchmail.org/pipermail/notmuch>\r
  79 List-Post: <mailto:notmuch@notmuchmail.org>\r
  80 List-Help: <mailto:notmuch-request@notmuchmail.org?subject=help>\r
  81 List-Subscribe: <http://notmuchmail.org/mailman/listinfo/notmuch>,\r
  82         <mailto:notmuch-request@notmuchmail.org?subject=subscribe>\r
  83 X-List-Received-Date: Wed, 23 Oct 2013 19:32:20 -0000\r
  84 \r
  85 Quoth Tomi Ollila on Oct 23 at 10:05 pm:\r
  86 > On Thu, Oct 10 2013, David Bremner <david@tethera.net> wrote:\r
  87 > \r
  88 > > Tomi Ollila <tomi.ollila@iki.fi> writes:\r
  89 > >>> I'm not opposed to doing an SONAME bump for 0.17. Are there other ABI\r
  90 > >>> breaking changes that we have been holding back on? Can these maybe go\r
  91 > >>> through at the same time?\r
  92 > >>\r
  93 > >> Maybe something along these lines...\r
  94 > >>\r
  95 > >> (Quick draft for the API part; to start discussion before working too much\r
  96 > >> for something that is going to be dropped...)\r
  97 > >>\r
  98 > >>  notmuch_status_t\r
  99 > >> -notmuch_database_create (const char *path, notmuch_database_t **database);\r
 100 > >> +notmuch_database_create (const char *path,\r
 101 > >> +                   notmuch_loghook_t *loghook,\r
 102 > >> +                   notmuch_database_t **database);\r
 103 > >\r
 104 > > Another idea floated (by Austin?) was to pass in an options struct, to\r
 105 > > allow future options to be added without changing the function\r
 106 > > signature. I guess with some care this could be done in an upwardly\r
 107 > > compatible way.\r
 108 > \r
 109 > Maybe something like\r
 110 > \r
 111 > #define NOTMUCH_API_OPTIONS_VERSION 1\r
 112 > typedef struct {\r
 113 >         int options_version;\r
 114 >         void (*log)(void *, int level, int status, const char * format, ...);\r
 115 >         void * logdata;\r
 116 > } notmuch_options_t;        \r
 117 > \r
 118 > ...\r
 119 > \r
 120 > notmuch_status_t\r
 121 > notmuch_database_create (const char *path,\r
 122 >                        notmuch_options_t *options,\r
 123 >                        notmuch_database_t **database);\r
 124 > ...\r
 125 > \r
 126 > notmuch_status_t\r
 127 > notmuch_database_open (const char *path,\r
 128 >                        notmuch_database_mode_t mode,\r
 129 >                        notmuch_options_t *options,\r
 130 >                        notmuch_database_t **database);\r
 131 > \r
 132 > then in use:\r
 133 > \r
 134 > notmuch_options_t options = {\r
 135 >        .options_version = NOTMUCH_API_OPTIONS_VERSION,\r
 136 > \r
 137 > .. äsh, this has problem that the macro changes in header file\r
 138 > but the structure initialization is not following automatically\r
 139 > (in other fields than that). Therefore perhaps "fixing"\r
 140 > the version macros:\r
 141 > \r
 142 > #define NOTMUCH_API_OPTIONS_VERSION_1 1\r
 143 > /* #define NOTMUCH_API_OPTIONS_VERSION_2 2 // added in the future */\r
 144 > \r
 145 > notmuch_options_t options = {\r
 146 >        .options_version = NOTMUCH_API_OPTIONS_VERSION_1,\r
 147 >        .log = log_to_stderr,\r
 148 >        .logdata = NULL\r
 149 > };\r
 150 > \r
 151 > Well, this is one idea (does not sound as good as I initially\r
 152 > thought...) how does other software tackle this kind of issues...\r
 153 > \r
 154 > If something like this is finally chosen we could provide easy\r
 155 > transition path to allow NULL as options -- making notmuch CLI\r
 156 > behave as it used to be (log to stderr...).\r
 157 \r
 158 Using a version number on the options makes it tricky to maintain\r
 159 backwards compatibility, since you need code to read all past versions\r
 160 of the structure.  A similar but, I think, better way would be to take\r
 161 the size of the structure in the structure.  Something like:\r
 162 \r
 163 typedef struct {\r
 164     size_t options_length;\r
 165     ...\r
 166 } notmuch_options_t;\r
 167 \r
 168 #define NOTMUCH_OPTIONS_INIT { sizeof(notmuch_options_t) }\r
 169 // or without pre-processor, but requiring GCC attributes\r
 170 static __attribute__((__unused__))\r
 171 notmuch_options_t notmuch_options_init = { sizeof(notmuch_options_t) };\r
 172 \r
 173 NOTMUCH_OPTIONS_INIT/notmuch_options_init could also contain other\r
 174 defaults, though it's best if the defaults are simply the zero\r
 175 initializations of the various fields.\r
 176 \r
 177 \r
 178 Then, in code calling libnotmuch, you'd do something like\r
 179 \r
 180 notmuch_options_t options = NOTMUCH_OPTIONS_INIT;\r
 181 options.log = log_to_stderr;\r
 182 // ...\r
 183 \r
 184 \r
 185 And in libnotmuch, we would do something like\r
 186 \r
 187 notmuch_status_t\r
 188 notmuch_database_open (const char *path,\r
 189                        notmuch_database_mode_t mode,\r
 190                        const notmuch_options_t *options,\r
 191                        notmuch_database_t **database)\r
 192 {\r
 193     notmuch_option_t real_options = NOTMUCH_OPTIONS_INIT;\r
 194     if (real_options.options_length < options.options_length)\r
 195         return error;\r
 196     memmove(&real_options, options, options.options_length);\r
 197     // ...\r
 198 }\r
 199 \r
 200 This approach makes it free to add fields and we can always deprecate\r
 201 fields as long as we leave the space in the structure.  This is based\r
 202 roughly on how the Linux kernel deals with various structures that\r
 203 have grown over time in the syscall ABI.\r
 204 \r
 205 Another much more verbose but also more robust approach would be to\r
 206 make notmuch_options_t opaque and provide setters (and getters, if\r
 207 we're feeling benevolent).  I kind of like the simplicity of a struct.\r
 208 \r
 209 One thing to consider is what works best with bindings.  Presumably\r
 210 the opaque structure wouldn't be a problem.  I've never had to wrap\r
 211 anything like the struct approach, though, so I don't know if that's\r
 212 easy or hard.\r