YugabyteDB (2.13.0.0-b42, bfc6a6643e7399ac8a0e81d06a3ee6d6571b33ab)

//--------------------------------------------------------------------------------------------------

// Copyright (c) YugaByte, Inc.

//

// Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except

// in compliance with the License.  You may obtain a copy of the License at

//

// http://www.apache.org/licenses/LICENSE-2.0

//

// Unless required by applicable law or agreed to in writing, software distributed under the License

// is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express

// or implied.  See the License for the specific language governing permissions and limitations

// under the License.

//

//

// This module defines the entries to the builtin library functions.

//   FindPgsqlOpcode() - Compiling builtin call into opcode.

//   ExecPgsqlOpcode() - Execute builtin call using opcode.

//

// NOTES ON BUILTIN DEFINITIONS

// ----------------------------

// Here's how new builtin functions are implemented or added to this library.

// * Define C++ function (e.g. Token) in this library or any C++ library (yb_bfpg).

//   If the function is defined in a different library, link it to this library.

// * Define associated PGSQL function ("token") by adding it to PGSQL parser.

// * In file "directory.cc", add an entry at the end of the kBFDirectory table.

//     { C++ func_name , PGSQL func_name , return_type, { formal_parameter_types } }

//     Example:

//     { "Token", "token", STRING, {TYPEARGS} }

// * The rest of the code would be auto-generated.

//

// NOTES ON PROCESSING BUILTIN CALLS

// ---------------------------------

// Here's how builtin calls can be processed using this library.

// - Getting the opcode from a process (such as client or proxy server).

//     FindPgsqlOpcode(function_name,              // Input:         Such as "+"

//                     actual_parameter_types,     // Input:         Types of arguments.

//                     opcode,                     // Output:        Found associated opcode.

//                     formal_parameter_types,     // Output:        Types of formal parameters.

//                     return_type)                // Input/Output:  Return type.

// - Send the opcode & parameter values to any processes (such as tablet server).

// - The receiving process can then execute it.

//     ExecPgsqlOpcode(opcode,                     // Input:         Opcode from compilation.

//                     param_values,               // Input:         Arguments.

//                     return_value)               // Output:        Computed result.

//

// NOTES ON COMPILING BUILTIN CALLS

// --------------------------------

// FindPgsqlOpcode() should be called to type check a builtin calls.

// * FindPgsqlOpcode() does type checking for the parameters (function signature).

// * FindPgsqlOpcode() outputs a BFOpcode to be used at execution time.

// * FindPgsqlOpcode() outputs the formal parameter types.

//   - This is the signature of the function.

//   - The arguments to a builtin call must be converted to these exact formal types.

// * FindPgsqlOpcode() inputs / outputs the return type.

//   - If return type is not given (UNKNOWN_DATA), it returns the expected return type to caller.

//   - If return type is given, it checks if the type is compatible with the function's return type.

//

// NOTES ON EXECUTING BUILTIN CALLS

// --------------------------------

// Call ExecPgsqlFunc(opcode, args, result)

// * Input arguments must be of exact datatypes as the formal parameter types. Operator "cast"

//   should have been used to convert these arguments when needed.

//

// * The return result must also be of expected type. The return value of expected type would be

//   written to this result.

//

// EXAMPPLE

// --------

// The test "/yb/bfpg/bfpg-test.cc" would be a good example on builtin-call usage.

// The file "/yb/yql/cql/ql/ptree/pt_bfunc.cc" can be used as example at the moment.

//--------------------------------------------------------------------------------------------------

#ifndef YB_BFPG_BFPG_H

#define YB_BFPG_BFPG_H

#include <vector>

#include <list>

#include "yb/util/logging.h"

#include "yb/bfpg/bfpg_template.h"

#include "yb/bfpg/tserver_opcodes.h"

namespace yb {

namespace bfpg {

const char *const kCastFuncName = "cast";

//--------------------------------------------------------------------------------------------------

// class BFCompileApi<PType, RType> has one main entry function - FindPgsqlOpcode().

//

// FindPgsqlOpcode() finds the builtin opcode, signature, and return type using the function name.

// - This function is a template function which accept with any parameter and result classes that

//   implement the following functions.

//     DataType ql_type_id();

//     void set_ql_type_id(DataType);

//

// - Example

//   . PGSQL expression treenode can be used for both PType and RType because it has the two

//     required functions for set & get ql_type_ids.

//   . Pseudo code.

//     using BFCompileQL = BFCompileApi<std::shared_ptr<QLValue>, QLValue>.

//

// - Example for a class that can be used as PType and Rtype for this template.

//     class YourArg {

//       DataType ql_type_id() { return ql_type_id_; }

//       void set_ql_type_id(DataType t) { ql_type_id_ = t; }

//     };

//

//   Builtin library provides interface for both raw and shared pointers.

//     vector<YourArgPointer> params = { ... };

//     BFCompileApi<YourArg, YourArg>::FindPgsqlOpcode(name, params, opcode, decl, result_ptr);

template<typename PType, typename RType>

class BFCompileApi {

 public:

  //------------------------------------------------------------------------------------------------

  // Because we using Arena allocator, our compiler don't use standard collection types such as

  // std::vector. The following templates allow the compiler to resolve builtin calls with with

  // various collection types.

  // Interface for any collections of shared_ptrs.

  template<template<typename, typename> class CType, typename AType>

  static Status FindPgsqlOpcodeImpl(const string& ql_name,

                                    const CType<std::shared_ptr<PType>, AType>& param_types,

                                    BFOpcode *opcode,

                                    const BFDecl **bfdecl,

                                    const std::shared_ptr<RType>& result) {

    Status s = FindOpcode<CType<std::shared_ptr<PType>, AType>, const std::shared_ptr<RType>&>(

                   ql_name, param_types, opcode, bfdecl, result);

    VLOG(3) << "Compiled function call " << ql_name << ". Status: " << s.ToString();

    return s;

  }

  // Interface for any collections of raw pointers.

  template<template<typename, typename> class CType, typename AType>

  static Status FindPgsqlOpcodeImpl(const string& ql_name,

                                    const CType<PType*, AType>& param_types,

                                    BFOpcode *opcode,

                                    const BFDecl **bfdecl,

                                    const std::shared_ptr<RType>& result) {

    Status s = FindOpcode<CType<PType*, AType>, const std::shared_ptr<RType>&>(

                   ql_name, param_types, opcode, bfdecl, result);

    VLOG(3) << "Compiled function call " << ql_name << ". Status: " << s.ToString();

    return s;

  }

  //------------------------------------------------------------------------------------------------

  // Seeks builtin opcode using the given the std::vector of shared pointers.

  static Status FindPgsqlOpcode(const string& ql_name,

                                const std::vector<std::shared_ptr<PType>>& param_types,

                                BFOpcode *opcode,

                                const BFDecl **bfdecl,

                                const std::shared_ptr<RType>& result) {

    return FindPgsqlOpcodeImpl<std::vector>(ql_name, param_types, opcode, bfdecl, result);

  }

  // Seeks builtin opcode using the given the std::vector of raw pointers.

  static Status FindPgsqlOpcode(const string& ql_name,

                                const std::vector<PType*>& param_types,

                                BFOpcode *opcode,

                                const BFDecl **bfdecl,

                                const std::shared_ptr<RType>& result) {

    return FindPgsqlOpcodeImpl<std::vector>(ql_name, param_types, opcode, bfdecl, result);

  }

  // Seeks builtin opcode using the given the std::vector of Datatypes.

  static Status FindPgsqlOpcode(const string& ql_name,

                                const std::vector<DataType>& actual_types,

                                BFOpcode *opcode,

                                const BFDecl **bfdecl,

                                DataType *return_type) {

    Status s = FindOpcodeByType(ql_name, actual_types, opcode, bfdecl, return_type);

    VLOG(3) << "Compiled function call " << ql_name << ". Status: " << s.ToString();

    return s;

  }

  // Seeks CAST opcode from one type to another.

  static Status FindCastOpcode(DataType source, DataType target, BFOpcode *opcode) {

    if (source == target ||

        source == DataType::NULL_VALUE_TYPE ||

        target == DataType::NULL_VALUE_TYPE) {

      *opcode = yb::bfpg::BFOPCODE_NOOP;

      return Status::OK();

    }

    // Find conversion opcode.

    const BFDecl *found_decl = nullptr;

    std::vector<DataType> actual_types = { source, target };

    DataType return_type = DataType::UNKNOWN_DATA;

    return FindPgsqlOpcode(bfpg::kCastFuncName, actual_types, opcode, &found_decl,

                           &return_type);

  }

};

//--------------------------------------------------------------------------------------------------

// class BFExecApi<PType, RType> has one main entry function - ExecPgsqlOpcode().

// ExecPgsqlOpcode() executes builtin calls with the given opcode and arguments and writes result

// to the output parameter result. It reports error by returning Status.

//

// NOTES:

// The API are using templates which have the following requirements.

//

// - The datatype of parameters must have the following member functions.

//     bool IsNull() const;

//     InternalType type() const;

//     int8_t int8_value() const;

//     int16_t int16_value() const;

//     int32_t int32_value() const;

//     int64_t int64_value() const;

//     float float_value() const;

//     double double_value() const;

//     bool bool_value() const;

//     const std::string& string_value() const;

//     Timestamp timestamp_value() const;

//     const std::string& binary_value() const;

//     InetAddress inetaddress_value() const;

//

// - The datatype of return-results must have the following member functions.

//     void SetNull();

//     InternalType type() const;

//     void set_int8_value(int8_t val);

//     void set_int16_value(int16_t val);

//     void set_int32_value(int32_t val);

//     void set_int64_value(int64_t val);

//     void set_float_value(float val);

//     void set_double_value(double val);

//     void set_bool_value(bool val);

//     void set_string_value(const std::string& val);

//     void set_string_value(const char* val);

//     void set_string_value(const char* val, size_t size);

//     void set_timestamp_value(const Timestamp& val);

//     void set_timestamp_value(int64_t val);

//     void set_binary_value(const std::string& val);

//     void set_binary_value(const void* val, size_t size);

//     void set_inetaddress_value(const InetAddress& val);

//

// - Builtin-calls don't do implicit data conversion. They expect parameters to have the expected

//   type, and they always return data of the expected type. Arguments must be converted to correct

//   types before passing by using "cast" operator.

template<typename PType,

         typename RType,

         template<typename, typename> class CType = std::vector,

         template<typename> class AType = std::allocator>

class BFExecApi {

 public:

  // Declare table of function pointers that take shared_ptr as arguments and returned-result.

  static const vector<std::function<Status(const std::vector<std::shared_ptr<PType>>&,

                                           const std::shared_ptr<RType>&)>>

      kBFExecFuncs;

  // Declare table of function pointers that take raw pointers as arguments and returned-result.

  static const vector<std::function<Status(const std::vector<PType*>&, RType*)>>

      kBFExecFuncsRaw;

  // Declare table of function pointers that take ref as arguments and raw pointers as result

  static const vector<std::function<Status(std::vector<PType>*, RType*)>>

      kBFExecFuncsRefAndRaw;

  //------------------------------------------------------------------------------------------------

  // Runs the associated entry in the table of function pointers on the given shared_ptrs.

  //   kBFExecFuncs[opcode](args)

  static Status ExecPgsqlOpcode(BFOpcode opcode,

                                const std::vector<std::shared_ptr<PType>>& params,

                                const std::shared_ptr<RType>& result) {

    // TODO(neil) There has to be some sanity error check here.

    RETURN_NOT_OK(CheckError(opcode, params, result));

    Status s = kBFExecFuncs[static_cast<int>(opcode)](params, result);

    VLOG(3) << "Executed builtin call(" << int(opcode) << "). Status: " << s.ToString();

    return s;

  }

_ZN2yb4bfpg9BFExecApiINS0_11BFTestValueES2_NSt3__16vectorENS3_9allocatorEE15ExecPgsqlOpcodeENS0_8BFOpcodeERKNS4_INS3_10shared_ptrIS2_EENS5_IS9_EEEERKS9_

Line

Count

Source

264

13

                                const std::shared_ptr<RType>& result) {

265

    // TODO(neil) There has to be some sanity error check here.

266

13

    RETURN_NOT_OK(CheckError(opcode, params, result));

267

13

    Status s = kBFExecFuncs[static_cast<int>(opcode)](params, result);

268

0

    VLOG(3) << "Executed builtin call(" << int(opcode) << "). Status: " << s.ToString();

269

13

    return s;

270

13

  }

Unexecuted instantiation: _ZN2yb4bfpg9BFExecApiINS_7QLValueES2_NSt3__16vectorENS3_9allocatorEE15ExecPgsqlOpcodeENS0_8BFOpcodeERKNS4_INS3_10shared_ptrIS2_EENS5_IS9_EEEERKS9_

  // TODO(neil) Because opcodes are created and executed by different processes, some sanity error

  // checking must be done at run time in logging mode.

  static Status CheckError(BFOpcode opcode,

                           const std::vector<std::shared_ptr<PType>>& params,

                           const std::shared_ptr<RType>& result) {

    // TODO(neil) Currently, the execution phase is not yet implemented, so it'd be immature to

    // code for error-check here. Once it is implemented, we'll know what to check.

    if (VLOG_IS_ON(3)) {

      LOG(INFO) << "Executing opcode " << int(opcode);

    }

    return Status::OK();

  }

_ZN2yb4bfpg9BFExecApiINS0_11BFTestValueES2_NSt3__16vectorENS3_9allocatorEE10CheckErrorENS0_8BFOpcodeERKNS4_INS3_10shared_ptrIS2_EENS5_IS9_EEEERKS9_

Line

Count

Source

276

13

                           const std::shared_ptr<RType>& result) {

277

    // TODO(neil) Currently, the execution phase is not yet implemented, so it'd be immature to

278

    // code for error-check here. Once it is implemented, we'll know what to check.

279

0

    if (VLOG_IS_ON(3)) {

280

0

      LOG(INFO) << "Executing opcode " << int(opcode);

281

0

    }

282

13

    return Status::OK();

283

13

  }

Unexecuted instantiation: _ZN2yb4bfpg9BFExecApiINS_7QLValueES2_NSt3__16vectorENS3_9allocatorEE10CheckErrorENS0_8BFOpcodeERKNS4_INS3_10shared_ptrIS2_EENS5_IS9_EEEERKS9_

  //------------------------------------------------------------------------------------------------

  // Runs the associated entry in the table of function pointers on the given raw pointers.

  //   kBFExecFuncsRaw[opcode](args)

  static Status ExecPgsqlOpcode(BFOpcode opcode,

                                const std::vector<PType*>& params,

                                RType *result) {

    // TODO(neil) There has to be some sanity error check here.

    RETURN_NOT_OK(CheckError(opcode, params, result));

    Status s = kBFExecFuncsRaw[static_cast<int>(opcode)](params, result);

    VLOG(3) << "Executed builtin call(" << int(opcode) << "). Status: " << s.ToString();

    return s;

  }

  static Status CheckError(BFOpcode opcode,

                           const std::vector<PType*>& params,

                           RType *result) {

    // TODO(neil) Currently, the execution phase is not yet implemented, so it'd be immature to

    // code for error-check here. Once it is implemented, we'll know what to check.

    if (VLOG_IS_ON(3)) {

      LOG(INFO) << "Executing opcode " << int(opcode);

    }

    return Status::OK();

  }

  //------------------------------------------------------------------------------------------------

  // Runs the associated entry in the table of function pointers on the given raw pointers.

  //   kBFExecFuncsRefAndRaw[opcode](args)

  static Status ExecPgsqlOpcode(BFOpcode opcode,

                                std::vector<PType> *params,

                                RType *result) {

    // TODO(neil) There has to be some sanity error check here.

    RETURN_NOT_OK(CheckError(opcode, params, result));

    Status s = kBFExecFuncsRefAndRaw[static_cast<int>(opcode)](params, result);

    VLOG(3) << "Executed builtin call(" << int(opcode) << "). Status: " << s.ToString();

    return s;

  }

  static Status CheckError(BFOpcode opcode,

                           std::vector<PType> *params,

                           RType *result) {

    // TODO(neil) Currently, the execution phase is not yet implemented, so it'd be immature to

    // code for error-check here. Once it is implemented, we'll know what to check.

    if (VLOG_IS_ON(3)) {

      LOG(INFO) << "Executing opcode " << int(opcode);

    }

    return Status::OK();

  }

};

//--------------------------------------------------------------------------------------------------

// This class is conveniently and ONLY for testing purpose. It executes builtin calls by names

// instead of opcode.

template<typename PType,

         typename RType,

         template<typename, typename> class CType = std::vector,

         template<typename> class AType = std::allocator>

class BFExecImmediateApi : public BFExecApi<PType, RType, CType, AType> {

 public:

  // Interface for shared_ptr.

  static Status ExecPgsqlFunc(const string& ql_name,

                              const std::vector<std::shared_ptr<PType>>& params,

                              const std::shared_ptr<RType>& result) {

    BFOpcode opcode;

    const BFDecl *bfdecl;

    RETURN_NOT_OK((FindOpcode<std::vector<std::shared_ptr<PType>>, const std::shared_ptr<RType>&>(

        ql_name, params, &opcode, &bfdecl, result)));

    return BFExecApi<PType, RType>::ExecPgsqlOpcode(opcode, params, result);

  }

  // Interface for raw pointer.

  static Status ExecPgsqlFunc(const string& ql_name,

                              const std::vector<PType*>& params,

                              RType *result) {

    BFOpcode opcode;

    const BFDecl *bfdecl;

    RETURN_NOT_OK(

        (FindOpcode<std::vector<PType*>, RType*>(ql_name, params, &opcode, &bfdecl, result)));

    return BFExecApi<PType, RType>::ExecPgsqlOpcode(opcode, params, result);

  }

};

} // namespace bfpg

} // namespace yb

//--------------------------------------------------------------------------------------------------

// Generated tables "kBFExecFuncs" and "kBFExecFuncsRaw".

// Because the tables must be initialized after the specification for "class BFExecApi", we have to

// include header file "gen_bfunc_table.h" at the end of this file.

#include "yb/bfpg/gen_bfunc_table.h"

#endif  // YB_BFPG_BFPG_H