ext/misc/carray.c

   1 /*
   2 ** 2016-06-29
   3 **
   4 ** The author disclaims copyright to this source code.  In place of
   5 ** a legal notice, here is a blessing:
   6 **
   7 **    May you do good and not evil.
   8 **    May you find forgiveness for yourself and forgive others.
   9 **    May you share freely, never taking more than you give.
  10 **
  11 *************************************************************************
  12 **
  13 ** This file demonstrates how to create a table-valued-function that
  14 ** returns the values in a C-language array.
  15 ** Examples:
  16 **
  17 **      SELECT * FROM carray($ptr,5)
  18 **
  19 ** The query above returns 5 integers contained in a C-language array
  20 ** at the address $ptr.  $ptr is a pointer to the array of integers.
  21 ** The pointer value must be assigned to $ptr using the
  22 ** sqlite3_bind_pointer() interface with a pointer type of "carray".
  23 ** For example:
  24 **
  25 **    static int aX[] = { 53, 9, 17, 2231, 4, 99 };
  26 **    int i = sqlite3_bind_parameter_index(pStmt, "$ptr");
  27 **    sqlite3_bind_pointer(pStmt, i, aX, "carray", 0);
  28 **
  29 ** There is an optional third parameter to determine the datatype of
  30 ** the C-language array.  Allowed values of the third parameter are
  31 ** 'int32', 'int64', 'double', 'char*', 'struct iovec'.  Example:
  32 **
  33 **      SELECT * FROM carray($ptr,10,'char*');
  34 **
  35 ** The default value of the third parameter is 'int32'.
  36 **
  37 ** HOW IT WORKS
  38 **
  39 ** The carray "function" is really a virtual table with the
  40 ** following schema:
  41 **
  42 **     CREATE TABLE carray(
  43 **       value,
  44 **       pointer HIDDEN,
  45 **       count HIDDEN,
  46 **       ctype TEXT HIDDEN
  47 **     );
  48 **
  49 ** If the hidden columns "pointer" and "count" are unconstrained, then
  50 ** the virtual table has no rows.  Otherwise, the virtual table interprets
  51 ** the integer value of "pointer" as a pointer to the array and "count"
  52 ** as the number of elements in the array.  The virtual table steps through
  53 ** the array, element by element.
  54 */
  55 #include "sqlite3ext.h"
  56 SQLITE_EXTENSION_INIT1
  57 #include <assert.h>
  58 #include <string.h>
  59 #ifdef _WIN32
  60   struct iovec {
  61     void *iov_base;
  62     size_t iov_len;
  63   };
  64 #else
  65 # include <sys/uio.h>
  66 #endif
  67
  68 /* Allowed values for the mFlags parameter to sqlite3_carray_bind().
  69 ** Must exactly match the definitions in carray.h.
  70 */
  71 #ifndef CARRAY_INT32
  72 # define CARRAY_INT32     0      /* Data is 32-bit signed integers */
  73 # define CARRAY_INT64     1      /* Data is 64-bit signed integers */
  74 # define CARRAY_DOUBLE    2      /* Data is doubles */
  75 # define CARRAY_TEXT      3      /* Data is char* */
  76 # define CARRAY_BLOB      4      /* Data is struct iovec* */
  77 #endif
  78
  79 #ifndef SQLITE_API
  80 # ifdef _WIN32
  81 #  define SQLITE_API __declspec(dllexport)
  82 # else
  83 #  define SQLITE_API
  84 # endif
  85 #endif
  86
  87 #ifndef SQLITE_OMIT_VIRTUALTABLE
  88
  89 /*
  90 ** Names of allowed datatypes
  91 */
  92 static const char *azType[] = { "int32", "int64", "double", "char*",
  93                                 "struct iovec" };
  94
  95 /*
  96 ** Structure used to hold the sqlite3_carray_bind() information
  97 */
  98 typedef struct carray_bind carray_bind;
  99 struct carray_bind {
 100   void *aData;                /* The data */
 101   int nData;                  /* Number of elements */
 102   int mFlags;                 /* Control flags */
 103   void (*xDel)(void*);        /* Destructor for aData */
 104 };
 105
 106
 107 /* carray_cursor is a subclass of sqlite3_vtab_cursor which will
 108 ** serve as the underlying representation of a cursor that scans
 109 ** over rows of the result
 110 */
 111 typedef struct carray_cursor carray_cursor;
 112 struct carray_cursor {
 113   sqlite3_vtab_cursor base;  /* Base class - must be first */
 114   sqlite3_int64 iRowid;      /* The rowid */
 115   void *pPtr;                /* Pointer to the array of values */
 116   sqlite3_int64 iCnt;        /* Number of integers in the array */
 117   unsigned char eType;       /* One of the CARRAY_type values */
 118 };
 119
 120 /*
 121 ** The carrayConnect() method is invoked to create a new
 122 ** carray_vtab that describes the carray virtual table.
 123 **
 124 ** Think of this routine as the constructor for carray_vtab objects.
 125 **
 126 ** All this routine needs to do is:
 127 **
 128 **    (1) Allocate the carray_vtab object and initialize all fields.
 129 **
 130 **    (2) Tell SQLite (via the sqlite3_declare_vtab() interface) what the
 131 **        result set of queries against carray will look like.
 132 */
 133 static int carrayConnect(
 134   sqlite3 *db,
 135   void *pAux,
 136   int argc, const char *const*argv,
 137   sqlite3_vtab **ppVtab,
 138   char **pzErr
 139 ){
 140   sqlite3_vtab *pNew;
 141   int rc;
 142
 143 /* Column numbers */
 144 #define CARRAY_COLUMN_VALUE   0
 145 #define CARRAY_COLUMN_POINTER 1
 146 #define CARRAY_COLUMN_COUNT   2
 147 #define CARRAY_COLUMN_CTYPE   3
 148
 149   rc = sqlite3_declare_vtab(db,
 150      "CREATE TABLE x(value,pointer hidden,count hidden,ctype hidden)");
 151   if( rc==SQLITE_OK ){
 152     pNew = *ppVtab = sqlite3_malloc( sizeof(*pNew) );
 153     if( pNew==0 ) return SQLITE_NOMEM;
 154     memset(pNew, 0, sizeof(*pNew));
 155   }
 156   return rc;
 157 }
 158
 159 /*
 160 ** This method is the destructor for carray_cursor objects.
 161 */
 162 static int carrayDisconnect(sqlite3_vtab *pVtab){
 163   sqlite3_free(pVtab);
 164   return SQLITE_OK;
 165 }
 166
 167 /*
 168 ** Constructor for a new carray_cursor object.
 169 */
 170 static int carrayOpen(sqlite3_vtab *p, sqlite3_vtab_cursor **ppCursor){
 171   carray_cursor *pCur;
 172   pCur = sqlite3_malloc( sizeof(*pCur) );
 173   if( pCur==0 ) return SQLITE_NOMEM;
 174   memset(pCur, 0, sizeof(*pCur));
 175   *ppCursor = &pCur->base;
 176   return SQLITE_OK;
 177 }
 178
 179 /*
 180 ** Destructor for a carray_cursor.
 181 */
 182 static int carrayClose(sqlite3_vtab_cursor *cur){
 183   sqlite3_free(cur);
 184   return SQLITE_OK;
 185 }
 186
 187
 188 /*
 189 ** Advance a carray_cursor to its next row of output.
 190 */
 191 static int carrayNext(sqlite3_vtab_cursor *cur){
 192   carray_cursor *pCur = (carray_cursor*)cur;
 193   pCur->iRowid++;
 194   return SQLITE_OK;
 195 }
 196
 197 /*
 198 ** Return values of columns for the row at which the carray_cursor
 199 ** is currently pointing.
 200 */
 201 static int carrayColumn(
 202   sqlite3_vtab_cursor *cur,   /* The cursor */
 203   sqlite3_context *ctx,       /* First argument to sqlite3_result_...() */
 204   int i                       /* Which column to return */
 205 ){
 206   carray_cursor *pCur = (carray_cursor*)cur;
 207   sqlite3_int64 x = 0;
 208   switch( i ){
 209     case CARRAY_COLUMN_POINTER:   return SQLITE_OK;
 210     case CARRAY_COLUMN_COUNT:     x = pCur->iCnt;   break;
 211     case CARRAY_COLUMN_CTYPE: {
 212       sqlite3_result_text(ctx, azType[pCur->eType], -1, SQLITE_STATIC);
 213       return SQLITE_OK;
 214     }
 215     default: {
 216       switch( pCur->eType ){
 217         case CARRAY_INT32: {
 218           int *p = (int*)pCur->pPtr;
 219           sqlite3_result_int(ctx, p[pCur->iRowid-1]);
 220           return SQLITE_OK;
 221         }
 222         case CARRAY_INT64: {
 223           sqlite3_int64 *p = (sqlite3_int64*)pCur->pPtr;
 224           sqlite3_result_int64(ctx, p[pCur->iRowid-1]);
 225           return SQLITE_OK;
 226         }
 227         case CARRAY_DOUBLE: {
 228           double *p = (double*)pCur->pPtr;
 229           sqlite3_result_double(ctx, p[pCur->iRowid-1]);
 230           return SQLITE_OK;
 231         }
 232         case CARRAY_TEXT: {
 233           const char **p = (const char**)pCur->pPtr;
 234           sqlite3_result_text(ctx, p[pCur->iRowid-1], -1, SQLITE_TRANSIENT);
 235           return SQLITE_OK;
 236         }
 237         case CARRAY_BLOB: {
 238           const struct iovec *p = (struct iovec*)pCur->pPtr;
 239           sqlite3_result_blob(ctx, p[pCur->iRowid-1].iov_base,
 240                                (int)p[pCur->iRowid-1].iov_len, SQLITE_TRANSIENT);
 241           return SQLITE_OK;
 242         }
 243       }
 244     }
 245   }
 246   sqlite3_result_int64(ctx, x);
 247   return SQLITE_OK;
 248 }
 249
 250 /*
 251 ** Return the rowid for the current row.  In this implementation, the
 252 ** rowid is the same as the output value.
 253 */
 254 static int carrayRowid(sqlite3_vtab_cursor *cur, sqlite_int64 *pRowid){
 255   carray_cursor *pCur = (carray_cursor*)cur;
 256   *pRowid = pCur->iRowid;
 257   return SQLITE_OK;
 258 }
 259
 260 /*
 261 ** Return TRUE if the cursor has been moved off of the last
 262 ** row of output.
 263 */
 264 static int carrayEof(sqlite3_vtab_cursor *cur){
 265   carray_cursor *pCur = (carray_cursor*)cur;
 266   return pCur->iRowid>pCur->iCnt;
 267 }
 268
 269 /*
 270 ** This method is called to "rewind" the carray_cursor object back
 271 ** to the first row of output.
 272 */
 273 static int carrayFilter(
 274   sqlite3_vtab_cursor *pVtabCursor,
 275   int idxNum, const char *idxStr,
 276   int argc, sqlite3_value **argv
 277 ){
 278   carray_cursor *pCur = (carray_cursor *)pVtabCursor;
 279   pCur->pPtr = 0;
 280   pCur->iCnt = 0;
 281   switch( idxNum ){
 282     case 1: {
 283       carray_bind *pBind = sqlite3_value_pointer(argv[0], "carray-bind");
 284       if( pBind==0 ) break;
 285       pCur->pPtr = pBind->aData;
 286       pCur->iCnt = pBind->nData;
 287       pCur->eType = pBind->mFlags & 0x07;
 288       break;
 289     }
 290     case 2:
 291     case 3: {
 292       pCur->pPtr = sqlite3_value_pointer(argv[0], "carray");
 293       pCur->iCnt = pCur->pPtr ? sqlite3_value_int64(argv[1]) : 0;
 294       if( idxNum<3 ){
 295         pCur->eType = CARRAY_INT32;
 296       }else{
 297         unsigned char i;
 298         const char *zType = (const char*)sqlite3_value_text(argv[2]);
 299         for(i=0; i<sizeof(azType)/sizeof(azType[0]); i++){
 300           if( sqlite3_stricmp(zType, azType[i])==0 ) break;
 301         }
 302         if( i>=sizeof(azType)/sizeof(azType[0]) ){
 303           pVtabCursor->pVtab->zErrMsg = sqlite3_mprintf(
 304             "unknown datatype: %Q", zType);
 305           return SQLITE_ERROR;
 306         }else{
 307           pCur->eType = i;
 308         }
 309       }
 310       break;
 311     }
 312   }
 313   pCur->iRowid = 1;
 314   return SQLITE_OK;
 315 }
 316
 317 /*
 318 ** SQLite will invoke this method one or more times while planning a query
 319 ** that uses the carray virtual table.  This routine needs to create
 320 ** a query plan for each invocation and compute an estimated cost for that
 321 ** plan.
 322 **
 323 ** In this implementation idxNum is used to represent the
 324 ** query plan.  idxStr is unused.
 325 **
 326 ** idxNum is:
 327 **
 328 **    1    If only the pointer= constraint exists.  In this case, the
 329 **         parameter must be bound using sqlite3_carray_bind().
 330 **
 331 **    2    if the pointer= and count= constraints exist.
 332 **
 333 **    3    if the ctype= constraint also exists.
 334 **
 335 ** idxNum is 0 otherwise and carray becomes an empty table.
 336 */
 337 static int carrayBestIndex(
 338   sqlite3_vtab *tab,
 339   sqlite3_index_info *pIdxInfo
 340 ){
 341   int i;                 /* Loop over constraints */
 342   int ptrIdx = -1;       /* Index of the pointer= constraint, or -1 if none */
 343   int cntIdx = -1;       /* Index of the count= constraint, or -1 if none */
 344   int ctypeIdx = -1;     /* Index of the ctype= constraint, or -1 if none */
 345
 346   const struct sqlite3_index_constraint *pConstraint;
 347   pConstraint = pIdxInfo->aConstraint;
 348   for(i=0; i<pIdxInfo->nConstraint; i++, pConstraint++){
 349     if( pConstraint->usable==0 ) continue;
 350     if( pConstraint->op!=SQLITE_INDEX_CONSTRAINT_EQ ) continue;
 351     switch( pConstraint->iColumn ){
 352       case CARRAY_COLUMN_POINTER:
 353         ptrIdx = i;
 354         break;
 355       case CARRAY_COLUMN_COUNT:
 356         cntIdx = i;
 357         break;
 358       case CARRAY_COLUMN_CTYPE:
 359         ctypeIdx = i;
 360         break;
 361     }
 362   }
 363   if( ptrIdx>=0 ){
 364     pIdxInfo->aConstraintUsage[ptrIdx].argvIndex = 1;
 365     pIdxInfo->aConstraintUsage[ptrIdx].omit = 1;
 366     pIdxInfo->estimatedCost = (double)1;
 367     pIdxInfo->estimatedRows = 100;
 368     pIdxInfo->idxNum = 1;
 369     if( cntIdx>=0 ){
 370       pIdxInfo->aConstraintUsage[cntIdx].argvIndex = 2;
 371       pIdxInfo->aConstraintUsage[cntIdx].omit = 1;
 372       pIdxInfo->idxNum = 2;
 373       if( ctypeIdx>=0 ){
 374         pIdxInfo->aConstraintUsage[ctypeIdx].argvIndex = 3;
 375         pIdxInfo->aConstraintUsage[ctypeIdx].omit = 1;
 376         pIdxInfo->idxNum = 3;
 377       }
 378     }
 379   }else{
 380     pIdxInfo->estimatedCost = (double)2147483647;
 381     pIdxInfo->estimatedRows = 2147483647;
 382     pIdxInfo->idxNum = 0;
 383   }
 384   return SQLITE_OK;
 385 }
 386
 387 /*
 388 ** This following structure defines all the methods for the
 389 ** carray virtual table.
 390 */
 391 static sqlite3_module carrayModule = {
 392   0,                         /* iVersion */
 393   0,                         /* xCreate */
 394   carrayConnect,             /* xConnect */
 395   carrayBestIndex,           /* xBestIndex */
 396   carrayDisconnect,          /* xDisconnect */
 397   0,                         /* xDestroy */
 398   carrayOpen,                /* xOpen - open a cursor */
 399   carrayClose,               /* xClose - close a cursor */
 400   carrayFilter,              /* xFilter - configure scan constraints */
 401   carrayNext,                /* xNext - advance a cursor */
 402   carrayEof,                 /* xEof - check for end of scan */
 403   carrayColumn,              /* xColumn - read data */
 404   carrayRowid,               /* xRowid - read data */
 405   0,                         /* xUpdate */
 406   0,                         /* xBegin */
 407   0,                         /* xSync */
 408   0,                         /* xCommit */
 409   0,                         /* xRollback */
 410   0,                         /* xFindMethod */
 411   0,                         /* xRename */
 412   0,                         /* xSavepoint */
 413   0,                         /* xRelease */
 414   0,                         /* xRollbackTo */
 415   0,                         /* xShadow */
 416   0                          /* xIntegrity */
 417 };
 418
 419 /*
 420 ** Destructor for the carray_bind object
 421 */
 422 static void carrayBindDel(void *pPtr){
 423   carray_bind *p = (carray_bind*)pPtr;
 424   if( p->xDel!=SQLITE_STATIC ){
 425      p->xDel(p->aData);
 426   }
 427   sqlite3_free(p);
 428 }
 429
 430 /*
 431 ** Invoke this interface in order to bind to the single-argument
 432 ** version of CARRAY().
 433 */
 434 SQLITE_API int sqlite3_carray_bind(
 435   sqlite3_stmt *pStmt,
 436   int idx,
 437   void *aData,
 438   int nData,
 439   int mFlags,
 440   void (*xDestroy)(void*)
 441 ){
 442   carray_bind *pNew;
 443   int i;
 444   pNew = sqlite3_malloc64(sizeof(*pNew));
 445   if( pNew==0 ){
 446     if( xDestroy!=SQLITE_STATIC && xDestroy!=SQLITE_TRANSIENT ){
 447       xDestroy(aData);
 448     }
 449     return SQLITE_NOMEM;
 450   }
 451   pNew->nData = nData;
 452   pNew->mFlags = mFlags;
 453   if( xDestroy==SQLITE_TRANSIENT ){
 454     sqlite3_int64 sz = nData;
 455     switch( mFlags & 0x07 ){
 456       case CARRAY_INT32:   sz *= 4;                     break;
 457       case CARRAY_INT64:   sz *= 8;                     break;
 458       case CARRAY_DOUBLE:  sz *= 8;                     break;
 459       case CARRAY_TEXT:    sz *= sizeof(char*);         break;
 460       case CARRAY_BLOB:    sz *= sizeof(struct iovec);  break;
 461     }
 462     if( (mFlags & 0x07)==CARRAY_TEXT ){
 463       for(i=0; i<nData; i++){
 464         const char *z = ((char**)aData)[i];
 465         if( z ) sz += strlen(z) + 1;
 466       }
 467     }else if( (mFlags & 0x07)==CARRAY_BLOB ){
 468       for(i=0; i<nData; i++){
 469         sz += ((struct iovec*)aData)[i].iov_len;
 470       }
 471     }
 472     pNew->aData = sqlite3_malloc64( sz );
 473     if( pNew->aData==0 ){
 474       sqlite3_free(pNew);
 475       return SQLITE_NOMEM;
 476     }
 477     if( (mFlags & 0x07)==CARRAY_TEXT ){
 478       char **az = (char**)pNew->aData;
 479       char *z = (char*)&az[nData];
 480       for(i=0; i<nData; i++){
 481         const char *zData = ((char**)aData)[i];
 482         sqlite3_int64 n;
 483         if( zData==0 ){
 484           az[i] = 0;
 485           continue;
 486         }
 487         az[i] = z;
 488         n = strlen(zData);
 489         memcpy(z, zData, n+1);
 490         z += n+1;
 491       }
 492     }else if( (mFlags & 0x07)==CARRAY_BLOB ){
 493       struct iovec *p = (struct iovec*)pNew->aData;
 494       unsigned char *z = (unsigned char*)&p[nData];
 495       for(i=0; i<nData; i++){
 496         size_t n = ((struct iovec*)aData)[i].iov_len;
 497         p[i].iov_len = n;
 498         p[i].iov_base = z;
 499         z += n;
 500         memcpy(p[i].iov_base, ((struct iovec*)aData)[i].iov_base, n);
 501       }
 502     }else{
 503       memcpy(pNew->aData, aData, sz);
 504     }
 505     pNew->xDel = sqlite3_free;
 506   }else{
 507     pNew->aData = aData;
 508     pNew->xDel = xDestroy;
 509   }
 510   return sqlite3_bind_pointer(pStmt, idx, pNew, "carray-bind", carrayBindDel);
 511 }
 512
 513
 514 /*
 515 ** For testing purpose in the TCL test harness, we need a method for
 516 ** setting the pointer value.  The inttoptr(X) SQL function accomplishes
 517 ** this.  Tcl script will bind an integer to X and the inttoptr() SQL
 518 ** function will use sqlite3_result_pointer() to convert that integer into
 519 ** a pointer.
 520 **
 521 ** This is for testing on TCL only.
 522 */
 523 #ifdef SQLITE_TEST
 524 static void inttoptrFunc(
 525   sqlite3_context *context,
 526   int argc,
 527   sqlite3_value **argv
 528 ){
 529   void *p;
 530   sqlite3_int64 i64;
 531   i64 = sqlite3_value_int64(argv[0]);
 532   if( sizeof(i64)==sizeof(p) ){
 533     memcpy(&p, &i64, sizeof(p));
 534   }else{
 535     int i32 = i64 & 0xffffffff;
 536     memcpy(&p, &i32, sizeof(p));
 537   }
 538   sqlite3_result_pointer(context, p, "carray", 0);
 539 }
 540 #endif /* SQLITE_TEST */
 541
 542 #endif /* SQLITE_OMIT_VIRTUALTABLE */
 543
 544 SQLITE_API int sqlite3_carray_init(
 545   sqlite3 *db,
 546   char **pzErrMsg,
 547   const sqlite3_api_routines *pApi
 548 ){
 549   int rc = SQLITE_OK;
 550   SQLITE_EXTENSION_INIT2(pApi);
 551 #ifndef SQLITE_OMIT_VIRTUALTABLE
 552   rc = sqlite3_create_module(db, "carray", &carrayModule, 0);
 553 #ifdef SQLITE_TEST
 554   if( rc==SQLITE_OK ){
 555     rc = sqlite3_create_function(db, "inttoptr", 1, SQLITE_UTF8, 0,
 556                                  inttoptrFunc, 0, 0);
 557   }
 558 #endif /* SQLITE_TEST */
 559 #endif /* SQLITE_OMIT_VIRTUALTABLE */
 560   return rc;
 561 }