// Licensed to the Apache Software Foundation (ASF) under one

// or more contributor license agreements.  See the NOTICE file

// distributed with this work for additional information

// regarding copyright ownership.  The ASF licenses this file

// to you 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.

#pragma once

#include <arrow/status.h>

#include "udf/python/python_client.h"

namespace doris {

class PythonUDTFClient;

using PythonUDTFClientPtr = std::shared_ptr<PythonUDTFClient>;

/**

 * Python UDTF Client

 * 

 * Implements simplified UDTF (User-Defined Table Function):

 * 

 * Handler Function:

 * - evaluate_func(*args): Process input arguments and yield output rows

 * 

 * UDTF Characteristics:

 * - Takes scalar or table inputs

 * - Returns table (multiple rows)

 * - Simple yield pattern

 * 

 * Example:

 * ```python

 * def evaluate_func(text, delimiter):

 *     # Split string by delimiter and return multiple results

 *     for item in text.split(delimiter):

 *         # or yield (item, )

 *         yield item 

 * ```

 * 

 * Communication protocol with Python server:

 * 1. Send input row batch to Python

 * 2. Python calls evaluate_func() for each input row

 * 3. Collect all output rows and return

 */

class PythonUDTFClient : public PythonClient {

public:

    PythonUDTFClient() = default;

    ~PythonUDTFClient() override = default;

    static Status create(const PythonUDFMeta& func_meta, ProcessPtr process,

                         PythonUDTFClientPtr* client);

    /**

     * Evaluate UDTF on input rows

     * 

     * Protocol (ListArray-based):

     * Python server returns a RecordBatch with 1 column:

     * - Column 0: ListArray where each list element corresponds to one input row's outputs

     * 

     * Example:

     *   Input: 3 rows

     *   Output ListArray:

     *     [0]: [val1, val2, val3]      (3 elements for input row 0)

     *     [1]: []                       (0 elements for input row 1)

     *     [2]: [val4, val5, val6, val7] (4 elements for input row 2)

     * 

     * @param input Input row batch (columns = UDTF function parameters)

     * @param list_array Output ListArray (length = num_input_rows)

     * @return Status

     */

    Status evaluate(const arrow::RecordBatch& input, std::shared_ptr<arrow::ListArray>* list_array);

private:

    DISALLOW_COPY_AND_ASSIGN(PythonUDTFClient);

};

} // namespace doris