src/backend/utils/cache/syscache.c

   1 /*-------------------------------------------------------------------------
   2  *
   3  * syscache.c
   4  *        System cache management routines
   5  *
   6  * Portions Copyright (c) 1996-2009, PostgreSQL Global Development Group
   7  * Portions Copyright (c) 1994, Regents of the University of California
   8  *
   9  *
  10  * IDENTIFICATION
  11  *        $PostgreSQL$
  12  *
  13  * NOTES
  14  *        These routines allow the parser/planner/executor to perform
  15  *        rapid lookups on the contents of the system catalogs.
  16  *
  17  *        see catalog/syscache.h for a list of the cache id's
  18  *
  19  *-------------------------------------------------------------------------
  20  */
  21 #include "postgres.h"
  22
  23 #include "access/sysattr.h"
  24 #include "catalog/indexing.h"
  25 #include "catalog/pg_aggregate.h"
  26 #include "catalog/pg_amop.h"
  27 #include "catalog/pg_amproc.h"
  28 #include "catalog/pg_auth_members.h"
  29 #include "catalog/pg_authid.h"
  30 #include "catalog/pg_cast.h"
  31 #include "catalog/pg_constraint.h"
  32 #include "catalog/pg_conversion.h"
  33 #include "catalog/pg_database.h"
  34 #include "catalog/pg_enum.h"
  35 #include "catalog/pg_foreign_data_wrapper.h"
  36 #include "catalog/pg_foreign_server.h"
  37 #include "catalog/pg_language.h"
  38 #include "catalog/pg_namespace.h"
  39 #include "catalog/pg_opclass.h"
  40 #include "catalog/pg_operator.h"
  41 #include "catalog/pg_opfamily.h"
  42 #include "catalog/pg_proc.h"
  43 #include "catalog/pg_rewrite.h"
  44 #include "catalog/pg_statistic.h"
  45 #include "catalog/pg_ts_config.h"
  46 #include "catalog/pg_ts_config_map.h"
  47 #include "catalog/pg_ts_dict.h"
  48 #include "catalog/pg_ts_parser.h"
  49 #include "catalog/pg_ts_template.h"
  50 #include "catalog/pg_type.h"
  51 #include "catalog/pg_user_mapping.h"
  52 #include "utils/rel.h"
  53 #include "utils/syscache.h"
  54
  55
  56 /*---------------------------------------------------------------------------
  57
  58         Adding system caches:
  59
  60         Add your new cache to the list in include/utils/syscache.h.
  61         Keep the list sorted alphabetically.
  62
  63         Add your entry to the cacheinfo[] array below. All cache lists are
  64         alphabetical, so add it in the proper place.  Specify the relation OID,
  65         index OID, number of keys, key attribute numbers, and number of hash
  66         buckets.  If the relation contains tuples that are associated with a
  67         particular relation (for example, its attributes, rules, triggers, etc)
  68         then specify the attribute number that contains the OID of the associated
  69         relation.  This is used by CatalogCacheFlushRelation() to remove the
  70         correct tuples during a table drop or relcache invalidation event.
  71
  72         The number of hash buckets must be a power of 2.  It's reasonable to
  73         set this to the number of entries that might be in the particular cache
  74         in a medium-size database.
  75
  76         There must be a unique index underlying each syscache (ie, an index
  77         whose key is the same as that of the cache).  If there is not one
  78         already, add definitions for it to include/catalog/indexing.h: you need
  79         to add a DECLARE_UNIQUE_INDEX macro and a #define for the index OID.
  80         (Adding an index requires a catversion.h update, while simply
  81         adding/deleting caches only requires a recompile.)
  82
  83         Finally, any place your relation gets heap_insert() or
  84         heap_update() calls, make sure there is a CatalogUpdateIndexes() or
  85         similar call.  The heap_* calls do not update indexes.
  86
  87         bjm 1999/11/22
  88
  89 *---------------------------------------------------------------------------
  90 */
  91
  92 /*
  93  *              struct cachedesc: information defining a single syscache
  94  */
  95 struct cachedesc
  96 {
  97         Oid                     reloid;                 /* OID of the relation being cached */
  98         Oid                     indoid;                 /* OID of index relation for this cache */
  99         int                     reloidattr;             /* attr number of rel OID reference, or 0 */
 100         int                     nkeys;                  /* # of keys needed for cache lookup */
 101         int                     key[4];                 /* attribute numbers of key attrs */
 102         int                     nbuckets;               /* number of hash buckets for this cache */
 103 };
 104
 105 static const struct cachedesc cacheinfo[] = {
 106         {AggregateRelationId,           /* AGGFNOID */
 107                 AggregateFnoidIndexId,
 108                 0,
 109                 1,
 110                 {
 111                         Anum_pg_aggregate_aggfnoid,
 112                         0,
 113                         0,
 114                         0
 115                 },
 116                 32
 117         },
 118         {AccessMethodRelationId,        /* AMNAME */
 119                 AmNameIndexId,
 120                 0,
 121                 1,
 122                 {
 123                         Anum_pg_am_amname,
 124                         0,
 125                         0,
 126                         0
 127                 },
 128                 4
 129         },
 130         {AccessMethodRelationId,        /* AMOID */
 131                 AmOidIndexId,
 132                 0,
 133                 1,
 134                 {
 135                         ObjectIdAttributeNumber,
 136                         0,
 137                         0,
 138                         0
 139                 },
 140                 4
 141         },
 142         {AccessMethodOperatorRelationId,        /* AMOPOPID */
 143                 AccessMethodOperatorIndexId,
 144                 0,
 145                 2,
 146                 {
 147                         Anum_pg_amop_amopopr,
 148                         Anum_pg_amop_amopfamily,
 149                         0,
 150                         0
 151                 },
 152                 64
 153         },
 154         {AccessMethodOperatorRelationId,        /* AMOPSTRATEGY */
 155                 AccessMethodStrategyIndexId,
 156                 0,
 157                 4,
 158                 {
 159                         Anum_pg_amop_amopfamily,
 160                         Anum_pg_amop_amoplefttype,
 161                         Anum_pg_amop_amoprighttype,
 162                         Anum_pg_amop_amopstrategy
 163                 },
 164                 64
 165         },
 166         {AccessMethodProcedureRelationId,       /* AMPROCNUM */
 167                 AccessMethodProcedureIndexId,
 168                 0,
 169                 4,
 170                 {
 171                         Anum_pg_amproc_amprocfamily,
 172                         Anum_pg_amproc_amproclefttype,
 173                         Anum_pg_amproc_amprocrighttype,
 174                         Anum_pg_amproc_amprocnum
 175                 },
 176                 64
 177         },
 178         {AttributeRelationId,           /* ATTNAME */
 179                 AttributeRelidNameIndexId,
 180                 Anum_pg_attribute_attrelid,
 181                 2,
 182                 {
 183                         Anum_pg_attribute_attrelid,
 184                         Anum_pg_attribute_attname,
 185                         0,
 186                         0
 187                 },
 188                 2048
 189         },
 190         {AttributeRelationId,           /* ATTNUM */
 191                 AttributeRelidNumIndexId,
 192                 Anum_pg_attribute_attrelid,
 193                 2,
 194                 {
 195                         Anum_pg_attribute_attrelid,
 196                         Anum_pg_attribute_attnum,
 197                         0,
 198                         0
 199                 },
 200                 2048
 201         },
 202         {AuthMemRelationId,                     /* AUTHMEMMEMROLE */
 203                 AuthMemMemRoleIndexId,
 204                 0,
 205                 2,
 206                 {
 207                         Anum_pg_auth_members_member,
 208                         Anum_pg_auth_members_roleid,
 209                         0,
 210                         0
 211                 },
 212                 128
 213         },
 214         {AuthMemRelationId,                     /* AUTHMEMROLEMEM */
 215                 AuthMemRoleMemIndexId,
 216                 0,
 217                 2,
 218                 {
 219                         Anum_pg_auth_members_roleid,
 220                         Anum_pg_auth_members_member,
 221                         0,
 222                         0
 223                 },
 224                 128
 225         },
 226         {AuthIdRelationId,                      /* AUTHNAME */
 227                 AuthIdRolnameIndexId,
 228                 0,
 229                 1,
 230                 {
 231                         Anum_pg_authid_rolname,
 232                         0,
 233                         0,
 234                         0
 235                 },
 236                 128
 237         },
 238         {AuthIdRelationId,                      /* AUTHOID */
 239                 AuthIdOidIndexId,
 240                 0,
 241                 1,
 242                 {
 243                         ObjectIdAttributeNumber,
 244                         0,
 245                         0,
 246                         0
 247                 },
 248                 128
 249         },
 250         {
 251                 CastRelationId,                 /* CASTSOURCETARGET */
 252                 CastSourceTargetIndexId,
 253                 0,
 254                 2,
 255                 {
 256                         Anum_pg_cast_castsource,
 257                         Anum_pg_cast_casttarget,
 258                         0,
 259                         0
 260                 },
 261                 256
 262         },
 263         {OperatorClassRelationId,       /* CLAAMNAMENSP */
 264                 OpclassAmNameNspIndexId,
 265                 0,
 266                 3,
 267                 {
 268                         Anum_pg_opclass_opcmethod,
 269                         Anum_pg_opclass_opcname,
 270                         Anum_pg_opclass_opcnamespace,
 271                         0
 272                 },
 273                 64
 274         },
 275         {OperatorClassRelationId,       /* CLAOID */
 276                 OpclassOidIndexId,
 277                 0,
 278                 1,
 279                 {
 280                         ObjectIdAttributeNumber,
 281                         0,
 282                         0,
 283                         0
 284                 },
 285                 64
 286         },
 287         {ConversionRelationId,          /* CONDEFAULT */
 288                 ConversionDefaultIndexId,
 289                 0,
 290                 4,
 291                 {
 292                         Anum_pg_conversion_connamespace,
 293                         Anum_pg_conversion_conforencoding,
 294                         Anum_pg_conversion_contoencoding,
 295                         ObjectIdAttributeNumber,
 296                 },
 297                 128
 298         },
 299         {ConversionRelationId,          /* CONNAMENSP */
 300                 ConversionNameNspIndexId,
 301                 0,
 302                 2,
 303                 {
 304                         Anum_pg_conversion_conname,
 305                         Anum_pg_conversion_connamespace,
 306                         0,
 307                         0
 308                 },
 309                 128
 310         },
 311         {ConstraintRelationId,          /* CONSTROID */
 312                 ConstraintOidIndexId,
 313                 Anum_pg_constraint_conrelid,
 314                 1,
 315                 {
 316                         ObjectIdAttributeNumber,
 317                         0,
 318                         0,
 319                         0
 320                 },
 321                 1024
 322         },
 323         {ConversionRelationId,          /* CONVOID */
 324                 ConversionOidIndexId,
 325                 0,
 326                 1,
 327                 {
 328                         ObjectIdAttributeNumber,
 329                         0,
 330                         0,
 331                         0
 332                 },
 333                 128
 334         },
 335         {DatabaseRelationId,            /* DATABASEOID */
 336                 DatabaseOidIndexId,
 337                 0,
 338                 1,
 339                 {
 340                         ObjectIdAttributeNumber,
 341                         0,
 342                         0,
 343                         0
 344                 },
 345                 4
 346         },
 347         {EnumRelationId,                        /* ENUMOID */
 348                 EnumOidIndexId,
 349                 0,
 350                 1,
 351                 {
 352                         ObjectIdAttributeNumber,
 353                         0,
 354                         0,
 355                         0
 356                 },
 357                 256
 358         },
 359         {EnumRelationId,                        /* ENUMTYPOIDNAME */
 360                 EnumTypIdLabelIndexId,
 361                 0,
 362                 2,
 363                 {
 364                         Anum_pg_enum_enumtypid,
 365                         Anum_pg_enum_enumlabel,
 366                         0,
 367                         0
 368                 },
 369                 256
 370         },
 371         {ForeignDataWrapperRelationId,          /* FOREIGNDATAWRAPPERNAME */
 372                 ForeignDataWrapperNameIndexId,
 373                 0,
 374                 1,
 375                 {
 376                         Anum_pg_foreign_data_wrapper_fdwname,
 377                         0,
 378                         0,
 379                         0
 380                 },
 381                 8
 382         },
 383         {ForeignDataWrapperRelationId,          /* FOREIGNDATAWRAPPEROID */
 384                 ForeignDataWrapperOidIndexId,
 385                 0,
 386                 1,
 387                 {
 388                         ObjectIdAttributeNumber,
 389                         0,
 390                         0,
 391                         0
 392                 },
 393                 8
 394         },
 395         {ForeignServerRelationId,       /* FOREIGNSERVERNAME */
 396                 ForeignServerNameIndexId,
 397                 0,
 398                 1,
 399                 {
 400                         Anum_pg_foreign_server_srvname,
 401                         0,
 402                         0,
 403                         0
 404                 },
 405                 32
 406         },
 407         {ForeignServerRelationId,       /* FOREIGNSERVEROID */
 408                 ForeignServerOidIndexId,
 409                 0,
 410                 1,
 411                 {
 412                         ObjectIdAttributeNumber,
 413                         0,
 414                         0,
 415                         0
 416                 },
 417                 32
 418         },
 419         {IndexRelationId,                       /* INDEXRELID */
 420                 IndexRelidIndexId,
 421                 Anum_pg_index_indrelid,
 422                 1,
 423                 {
 424                         Anum_pg_index_indexrelid,
 425                         0,
 426                         0,
 427                         0
 428                 },
 429                 1024
 430         },
 431         {LanguageRelationId,            /* LANGNAME */
 432                 LanguageNameIndexId,
 433                 0,
 434                 1,
 435                 {
 436                         Anum_pg_language_lanname,
 437                         0,
 438                         0,
 439                         0
 440                 },
 441                 4
 442         },
 443         {LanguageRelationId,            /* LANGOID */
 444                 LanguageOidIndexId,
 445                 0,
 446                 1,
 447                 {
 448                         ObjectIdAttributeNumber,
 449                         0,
 450                         0,
 451                         0
 452                 },
 453                 4
 454         },
 455         {NamespaceRelationId,           /* NAMESPACENAME */
 456                 NamespaceNameIndexId,
 457                 0,
 458                 1,
 459                 {
 460                         Anum_pg_namespace_nspname,
 461                         0,
 462                         0,
 463                         0
 464                 },
 465                 256
 466         },
 467         {NamespaceRelationId,           /* NAMESPACEOID */
 468                 NamespaceOidIndexId,
 469                 0,
 470                 1,
 471                 {
 472                         ObjectIdAttributeNumber,
 473                         0,
 474                         0,
 475                         0
 476                 },
 477                 256
 478         },
 479         {OperatorRelationId,            /* OPERNAMENSP */
 480                 OperatorNameNspIndexId,
 481                 0,
 482                 4,
 483                 {
 484                         Anum_pg_operator_oprname,
 485                         Anum_pg_operator_oprleft,
 486                         Anum_pg_operator_oprright,
 487                         Anum_pg_operator_oprnamespace
 488                 },
 489                 1024
 490         },
 491         {OperatorRelationId,            /* OPEROID */
 492                 OperatorOidIndexId,
 493                 0,
 494                 1,
 495                 {
 496                         ObjectIdAttributeNumber,
 497                         0,
 498                         0,
 499                         0
 500                 },
 501                 1024
 502         },
 503         {OperatorFamilyRelationId,      /* OPFAMILYAMNAMENSP */
 504                 OpfamilyAmNameNspIndexId,
 505                 0,
 506                 3,
 507                 {
 508                         Anum_pg_opfamily_opfmethod,
 509                         Anum_pg_opfamily_opfname,
 510                         Anum_pg_opfamily_opfnamespace,
 511                         0
 512                 },
 513                 64
 514         },
 515         {OperatorFamilyRelationId,      /* OPFAMILYOID */
 516                 OpfamilyOidIndexId,
 517                 0,
 518                 1,
 519                 {
 520                         ObjectIdAttributeNumber,
 521                         0,
 522                         0,
 523                         0
 524                 },
 525                 64
 526         },
 527         {ProcedureRelationId,           /* PROCNAMEARGSNSP */
 528                 ProcedureNameArgsNspIndexId,
 529                 0,
 530                 3,
 531                 {
 532                         Anum_pg_proc_proname,
 533                         Anum_pg_proc_proargtypes,
 534                         Anum_pg_proc_pronamespace,
 535                         0
 536                 },
 537                 2048
 538         },
 539         {ProcedureRelationId,           /* PROCOID */
 540                 ProcedureOidIndexId,
 541                 0,
 542                 1,
 543                 {
 544                         ObjectIdAttributeNumber,
 545                         0,
 546                         0,
 547                         0
 548                 },
 549                 2048
 550         },
 551         {RelationRelationId,            /* RELNAMENSP */
 552                 ClassNameNspIndexId,
 553                 ObjectIdAttributeNumber,
 554                 2,
 555                 {
 556                         Anum_pg_class_relname,
 557                         Anum_pg_class_relnamespace,
 558                         0,
 559                         0
 560                 },
 561                 1024
 562         },
 563         {RelationRelationId,            /* RELOID */
 564                 ClassOidIndexId,
 565                 ObjectIdAttributeNumber,
 566                 1,
 567                 {
 568                         ObjectIdAttributeNumber,
 569                         0,
 570                         0,
 571                         0
 572                 },
 573                 1024
 574         },
 575         {RewriteRelationId,                     /* RULERELNAME */
 576                 RewriteRelRulenameIndexId,
 577                 Anum_pg_rewrite_ev_class,
 578                 2,
 579                 {
 580                         Anum_pg_rewrite_ev_class,
 581                         Anum_pg_rewrite_rulename,
 582                         0,
 583                         0
 584                 },
 585                 1024
 586         },
 587         {StatisticRelationId,           /* STATRELATT */
 588                 StatisticRelidAttnumIndexId,
 589                 Anum_pg_statistic_starelid,
 590                 2,
 591                 {
 592                         Anum_pg_statistic_starelid,
 593                         Anum_pg_statistic_staattnum,
 594                         0,
 595                         0
 596                 },
 597                 1024
 598         },
 599         {TSConfigMapRelationId,         /* TSCONFIGMAP */
 600                 TSConfigMapIndexId,
 601                 0,
 602                 3,
 603                 {
 604                         Anum_pg_ts_config_map_mapcfg,
 605                         Anum_pg_ts_config_map_maptokentype,
 606                         Anum_pg_ts_config_map_mapseqno,
 607                         0
 608                 },
 609                 4
 610         },
 611         {TSConfigRelationId,            /* TSCONFIGNAMENSP */
 612                 TSConfigNameNspIndexId,
 613                 0,
 614                 2,
 615                 {
 616                         Anum_pg_ts_config_cfgname,
 617                         Anum_pg_ts_config_cfgnamespace,
 618                         0,
 619                         0
 620                 },
 621                 16
 622         },
 623         {TSConfigRelationId,            /* TSCONFIGOID */
 624                 TSConfigOidIndexId,
 625                 0,
 626                 1,
 627                 {
 628                         ObjectIdAttributeNumber,
 629                         0,
 630                         0,
 631                         0
 632                 },
 633                 16
 634         },
 635         {TSDictionaryRelationId,        /* TSDICTNAMENSP */
 636                 TSDictionaryNameNspIndexId,
 637                 0,
 638                 2,
 639                 {
 640                         Anum_pg_ts_dict_dictname,
 641                         Anum_pg_ts_dict_dictnamespace,
 642                         0,
 643                         0
 644                 },
 645                 16
 646         },
 647         {TSDictionaryRelationId,        /* TSDICTOID */
 648                 TSDictionaryOidIndexId,
 649                 0,
 650                 1,
 651                 {
 652                         ObjectIdAttributeNumber,
 653                         0,
 654                         0,
 655                         0
 656                 },
 657                 16
 658         },
 659         {TSParserRelationId,            /* TSPARSERNAMENSP */
 660                 TSParserNameNspIndexId,
 661                 0,
 662                 2,
 663                 {
 664                         Anum_pg_ts_parser_prsname,
 665                         Anum_pg_ts_parser_prsnamespace,
 666                         0,
 667                         0
 668                 },
 669                 4
 670         },
 671         {TSParserRelationId,            /* TSPARSEROID */
 672                 TSParserOidIndexId,
 673                 0,
 674                 1,
 675                 {
 676                         ObjectIdAttributeNumber,
 677                         0,
 678                         0,
 679                         0
 680                 },
 681                 4
 682         },
 683         {TSTemplateRelationId,          /* TSTEMPLATENAMENSP */
 684                 TSTemplateNameNspIndexId,
 685                 0,
 686                 2,
 687                 {
 688                         Anum_pg_ts_template_tmplname,
 689                         Anum_pg_ts_template_tmplnamespace,
 690                         0,
 691                         0
 692                 },
 693                 16
 694         },
 695         {TSTemplateRelationId,          /* TSTEMPLATEOID */
 696                 TSTemplateOidIndexId,
 697                 0,
 698                 1,
 699                 {
 700                         ObjectIdAttributeNumber,
 701                         0,
 702                         0,
 703                         0
 704                 },
 705                 16
 706         },
 707         {TypeRelationId,                        /* TYPENAMENSP */
 708                 TypeNameNspIndexId,
 709                 Anum_pg_type_typrelid,
 710                 2,
 711                 {
 712                         Anum_pg_type_typname,
 713                         Anum_pg_type_typnamespace,
 714                         0,
 715                         0
 716                 },
 717                 1024
 718         },
 719         {TypeRelationId,                        /* TYPEOID */
 720                 TypeOidIndexId,
 721                 Anum_pg_type_typrelid,
 722                 1,
 723                 {
 724                         ObjectIdAttributeNumber,
 725                         0,
 726                         0,
 727                         0
 728                 },
 729                 1024
 730         },
 731         {UserMappingRelationId,         /* USERMAPPINGOID */
 732                 UserMappingOidIndexId,
 733                 0,
 734                 1,
 735                 {
 736                         ObjectIdAttributeNumber,
 737                         0,
 738                         0,
 739                         0
 740                 },
 741                 128
 742         },
 743         {UserMappingRelationId,         /* USERMAPPINGUSERSERVER */
 744                 UserMappingUserServerIndexId,
 745                 0,
 746                 2,
 747                 {
 748                         Anum_pg_user_mapping_umuser,
 749                         Anum_pg_user_mapping_umserver,
 750                         0,
 751                         0
 752                 },
 753                 128
 754         }
 755 };
 756
 757 static CatCache *SysCache[
 758                                                   lengthof(cacheinfo)];
 759 static int      SysCacheSize = lengthof(cacheinfo);
 760 static bool CacheInitialized = false;
 761
 762
 763 /*
 764  * InitCatalogCache - initialize the caches
 765  *
 766  * Note that no database access is done here; we only allocate memory
 767  * and initialize the cache structure.  Interrogation of the database
 768  * to complete initialization of a cache happens upon first use
 769  * of that cache.
 770  */
 771 void
 772 InitCatalogCache(void)
 773 {
 774         int                     cacheId;
 775
 776         Assert(!CacheInitialized);
 777
 778         MemSet(SysCache, 0, sizeof(SysCache));
 779
 780         for (cacheId = 0; cacheId < SysCacheSize; cacheId++)
 781         {
 782                 SysCache[cacheId] = InitCatCache(cacheId,
 783                                                                                  cacheinfo[cacheId].reloid,
 784                                                                                  cacheinfo[cacheId].indoid,
 785                                                                                  cacheinfo[cacheId].reloidattr,
 786                                                                                  cacheinfo[cacheId].nkeys,
 787                                                                                  cacheinfo[cacheId].key,
 788                                                                                  cacheinfo[cacheId].nbuckets);
 789                 if (!PointerIsValid(SysCache[cacheId]))
 790                         elog(ERROR, "could not initialize cache %u (%d)",
 791                                  cacheinfo[cacheId].reloid, cacheId);
 792         }
 793         CacheInitialized = true;
 794 }
 795
 796
 797 /*
 798  * InitCatalogCachePhase2 - finish initializing the caches
 799  *
 800  * Finish initializing all the caches, including necessary database
 801  * access.
 802  *
 803  * This is *not* essential; normally we allow syscaches to be initialized
 804  * on first use.  However, it is useful as a mechanism to preload the
 805  * relcache with entries for the most-commonly-used system catalogs.
 806  * Therefore, we invoke this routine when we need to write a new relcache
 807  * init file.
 808  */
 809 void
 810 InitCatalogCachePhase2(void)
 811 {
 812         int                     cacheId;
 813
 814         Assert(CacheInitialized);
 815
 816         for (cacheId = 0; cacheId < SysCacheSize; cacheId++)
 817                 InitCatCachePhase2(SysCache[cacheId], true);
 818 }
 819
 820
 821 /*
 822  * SearchSysCache
 823  *
 824  *      A layer on top of SearchCatCache that does the initialization and
 825  *      key-setting for you.
 826  *
 827  *      Returns the cache copy of the tuple if one is found, NULL if not.
 828  *      The tuple is the 'cache' copy and must NOT be modified!
 829  *
 830  *      When the caller is done using the tuple, call ReleaseSysCache()
 831  *      to release the reference count grabbed by SearchSysCache().  If this
 832  *      is not done, the tuple will remain locked in cache until end of
 833  *      transaction, which is tolerable but not desirable.
 834  *
 835  *      CAUTION: The tuple that is returned must NOT be freed by the caller!
 836  */
 837 HeapTuple
 838 SearchSysCache(int cacheId,
 839                            Datum key1,
 840                            Datum key2,
 841                            Datum key3,
 842                            Datum key4)
 843 {
 844         if (cacheId < 0 || cacheId >= SysCacheSize ||
 845                 !PointerIsValid(SysCache[cacheId]))
 846                 elog(ERROR, "invalid cache id: %d", cacheId);
 847
 848         return SearchCatCache(SysCache[cacheId], key1, key2, key3, key4);
 849 }
 850
 851 /*
 852  * ReleaseSysCache
 853  *              Release previously grabbed reference count on a tuple
 854  */
 855 void
 856 ReleaseSysCache(HeapTuple tuple)
 857 {
 858         ReleaseCatCache(tuple);
 859 }
 860
 861 /*
 862  * SearchSysCacheCopy
 863  *
 864  * A convenience routine that does SearchSysCache and (if successful)
 865  * returns a modifiable copy of the syscache entry.  The original
 866  * syscache entry is released before returning.  The caller should
 867  * heap_freetuple() the result when done with it.
 868  */
 869 HeapTuple
 870 SearchSysCacheCopy(int cacheId,
 871                                    Datum key1,
 872                                    Datum key2,
 873                                    Datum key3,
 874                                    Datum key4)
 875 {
 876         HeapTuple       tuple,
 877                                 newtuple;
 878
 879         tuple = SearchSysCache(cacheId, key1, key2, key3, key4);
 880         if (!HeapTupleIsValid(tuple))
 881                 return tuple;
 882         newtuple = heap_copytuple(tuple);
 883         ReleaseSysCache(tuple);
 884         return newtuple;
 885 }
 886
 887 /*
 888  * SearchSysCacheExists
 889  *
 890  * A convenience routine that just probes to see if a tuple can be found.
 891  * No lock is retained on the syscache entry.
 892  */
 893 bool
 894 SearchSysCacheExists(int cacheId,
 895                                          Datum key1,
 896                                          Datum key2,
 897                                          Datum key3,
 898                                          Datum key4)
 899 {
 900         HeapTuple       tuple;
 901
 902         tuple = SearchSysCache(cacheId, key1, key2, key3, key4);
 903         if (!HeapTupleIsValid(tuple))
 904                 return false;
 905         ReleaseSysCache(tuple);
 906         return true;
 907 }
 908
 909 /*
 910  * GetSysCacheOid
 911  *
 912  * A convenience routine that does SearchSysCache and returns the OID
 913  * of the found tuple, or InvalidOid if no tuple could be found.
 914  * No lock is retained on the syscache entry.
 915  */
 916 Oid
 917 GetSysCacheOid(int cacheId,
 918                            Datum key1,
 919                            Datum key2,
 920                            Datum key3,
 921                            Datum key4)
 922 {
 923         HeapTuple       tuple;
 924         Oid                     result;
 925
 926         tuple = SearchSysCache(cacheId, key1, key2, key3, key4);
 927         if (!HeapTupleIsValid(tuple))
 928                 return InvalidOid;
 929         result = HeapTupleGetOid(tuple);
 930         ReleaseSysCache(tuple);
 931         return result;
 932 }
 933
 934
 935 /*
 936  * SearchSysCacheAttName
 937  *
 938  * This routine is equivalent to SearchSysCache on the ATTNAME cache,
 939  * except that it will return NULL if the found attribute is marked
 940  * attisdropped.  This is convenient for callers that want to act as
 941  * though dropped attributes don't exist.
 942  */
 943 HeapTuple
 944 SearchSysCacheAttName(Oid relid, const char *attname)
 945 {
 946         HeapTuple       tuple;
 947
 948         tuple = SearchSysCache(ATTNAME,
 949                                                    ObjectIdGetDatum(relid),
 950                                                    CStringGetDatum(attname),
 951                                                    0, 0);
 952         if (!HeapTupleIsValid(tuple))
 953                 return NULL;
 954         if (((Form_pg_attribute) GETSTRUCT(tuple))->attisdropped)
 955         {
 956                 ReleaseSysCache(tuple);
 957                 return NULL;
 958         }
 959         return tuple;
 960 }
 961
 962 /*
 963  * SearchSysCacheCopyAttName
 964  *
 965  * As above, an attisdropped-aware version of SearchSysCacheCopy.
 966  */
 967 HeapTuple
 968 SearchSysCacheCopyAttName(Oid relid, const char *attname)
 969 {
 970         HeapTuple       tuple,
 971                                 newtuple;
 972
 973         tuple = SearchSysCacheAttName(relid, attname);
 974         if (!HeapTupleIsValid(tuple))
 975                 return tuple;
 976         newtuple = heap_copytuple(tuple);
 977         ReleaseSysCache(tuple);
 978         return newtuple;
 979 }
 980
 981 /*
 982  * SearchSysCacheExistsAttName
 983  *
 984  * As above, an attisdropped-aware version of SearchSysCacheExists.
 985  */
 986 bool
 987 SearchSysCacheExistsAttName(Oid relid, const char *attname)
 988 {
 989         HeapTuple       tuple;
 990
 991         tuple = SearchSysCacheAttName(relid, attname);
 992         if (!HeapTupleIsValid(tuple))
 993                 return false;
 994         ReleaseSysCache(tuple);
 995         return true;
 996 }
 997
 998
 999 /*
1000  * SysCacheGetAttr
1001  *
1002  *              Given a tuple previously fetched by SearchSysCache(),
1003  *              extract a specific attribute.
1004  *
1005  * This is equivalent to using heap_getattr() on a tuple fetched
1006  * from a non-cached relation.  Usually, this is only used for attributes
1007  * that could be NULL or variable length; the fixed-size attributes in
1008  * a system table are accessed just by mapping the tuple onto the C struct
1009  * declarations from include/catalog/.
1010  *
1011  * As with heap_getattr(), if the attribute is of a pass-by-reference type
1012  * then a pointer into the tuple data area is returned --- the caller must
1013  * not modify or pfree the datum!
1014  *
1015  * Note: it is legal to use SysCacheGetAttr() with a cacheId referencing
1016  * a different cache for the same catalog the tuple was fetched from.
1017  */
1018 Datum
1019 SysCacheGetAttr(int cacheId, HeapTuple tup,
1020                                 AttrNumber attributeNumber,
1021                                 bool *isNull)
1022 {
1023         /*
1024          * We just need to get the TupleDesc out of the cache entry, and then we
1025          * can apply heap_getattr().  Normally the cache control data is already
1026          * valid (because the caller recently fetched the tuple via this same
1027          * cache), but there are cases where we have to initialize the cache here.
1028          */
1029         if (cacheId < 0 || cacheId >= SysCacheSize ||
1030                 !PointerIsValid(SysCache[cacheId]))
1031                 elog(ERROR, "invalid cache id: %d", cacheId);
1032         if (!PointerIsValid(SysCache[cacheId]->cc_tupdesc))
1033         {
1034                 InitCatCachePhase2(SysCache[cacheId], false);
1035                 Assert(PointerIsValid(SysCache[cacheId]->cc_tupdesc));
1036         }
1037
1038         return heap_getattr(tup, attributeNumber,
1039                                                 SysCache[cacheId]->cc_tupdesc,
1040                                                 isNull);
1041 }
1042
1043 /*
1044  * List-search interface
1045  */
1046 struct catclist *
1047 SearchSysCacheList(int cacheId, int nkeys,
1048                                    Datum key1, Datum key2, Datum key3, Datum key4)
1049 {
1050         if (cacheId < 0 || cacheId >= SysCacheSize ||
1051                 !PointerIsValid(SysCache[cacheId]))
1052                 elog(ERROR, "invalid cache id: %d", cacheId);
1053
1054         return SearchCatCacheList(SysCache[cacheId], nkeys,
1055                                                           key1, key2, key3, key4);
1056 }