PADDLE_ENFORCE Rewriting Specification

PADDLE_ENFORCE 改写规范

---

规范概要：

• 第1节，本规范的背景，即为什么要改写PADDLE_ENFORCE。
• 第2节，如何改写不合规的PADDLE_ENFORCE表达式（共9类），已加入CI监控
• 第3节，当前不需要修改的PADDLE_ENFORCE表达式（共3类），届时请找 chenwhql(陈威行)或luotao1(骆涛) approve

补充说明：

1. 规范在执行过程中，可能会发现现有规范未考虑到的方面，需要在实施过程中不断补充与完善，也请大家积极反馈意见
2. 后续会进一步对PADDLE_THROW表达式进行完善和监控

1. 背景说明

• 为什么不推荐 PADDLE_ENFORCE 表达式？
  • PADDLE_ENFORCE(COND, ...)表达式接收的是bool型表达式，只能判断true和false，不能给出具体错误提示。。
  • PADDLE_ENFORCE_GT(__VAL0, __VAL1, ...) 等表达式接收具体参数，并对应着具体比较条件，易于给出精准的错误信息。
  • 如PADDLE_ENFORCE(A>B)只能报true和false，但改成PADDLE_ENFORCE_GT(A, B)，会报出A和B的具体值是什么。
• 为什么不靠加强报错信息来解决，非要改接口呢？
  • 添加的详细报错信息是具体个人写的，写的好坏参差不齐，全凭自觉。每个审核人的标准也是不一样的，而且比较难注意到是否加详细的报错信息了。机器自动化报错要优先人工添加报错信息，会更加客观标准，因此优先改进。
  • 如果靠几个特定审核人来Review的话，审核人会成为瓶颈。目前存量不合规代码有2700条。

2. 如何改写

注意：为了描述更加简单，以下示例只针对表达式进行修改，报错信息文案修改请参考Paddle报错信息文案书写规范。

2.1 使用PADDLE_ENFORCE_EQ/NE/GT/GE/LT/LE表达式

// 判断是否true
PADDLE_ENFORCE(ctx->HasInput("X")); // 修改前
PADDLE_ENFORCE_EQ(ctx->HasInput("X"), true); //修改后

// 判断是否相等
PADDLE_ENFORCE(input_num == 1); //修改前
PADDLE_ENFORCE_EQ(input_num, 1UL); //修改后

// 判断是否不相等
PADDLE_ENFORCE(output_name_map.count(name) != 0); //修改前
PADDLE_ENFORCE_NE(output_name_map.count(name), 0UL); //修改后

// 判断是否大于
PADDLE_ENFORCE(h_inter_ctxs_.size() > 0); //修改前
PADDLE_ENFORCE_GT(h_inter_ctxs_.size(), 0UL); //修改后

// 判断是否大于等于
PADDLE_ENFORCE(run_order_ >= 0); //修改前
PADDLE_ENFORCE_GE(run_order_, 0UL); //修改后

// 判断是否小于
PADDLE_ENFORCE(cur_loc < 64); //修改前
PADDLE_ENFORCE_LT(cur_loc, 64UL); //修改后

// 判断是否小于等于
PADDLE_ENFORCE(part_height <= trans_dims[2]); //修改前
PADDLE_ENFORCE_LE(part_height, trans_dims[2]); //修改后

2.2 使用PADDLE_ENFORCE_NOT_NULL表达式

// 判断是否空指针
PADDLE_ENFORCE(scope_ptr); //修改前
PADDLE_ENFORCE_NOT_NULL(scope_ptr); //修改后

2.3 CUDA相关接口请使用PADDLE_ENFORCE_CUDA_SUCCESS表达式

PADDLE_ENFORCE(dynload::cublasCreate(&handle_)); //修改前
PADDLE_ENFORCE_CUDA_SUCCESS(dynload::cublasCreate(&handle_)); // 修改后

2.4 不允许含有&&，即对子表达式需要分别进行报错

// 简单&&表达式
PADDLE_ENFORCE(bit_length >= 1 && bit_length <= 16); //修改前
PADDLE_ENFORCE_GE(bit_length, 1UL); //修改后
PADDLE_ENFORCE_LE(bit_length, 16UL);

// 复杂&&表达式
PADDLE_ENFORCE(((start < end) && (step > 0)) || ((start > end) && (step < 0))); //修改前
// 修改后
if(step > 0) PADDLE_ENFORCE_LT(start, end);
elseif(step < 0) PADDLE_ENFORCE_GT(start, end);

3. 当前不需要修改的表达式

3.1 表达式中含有||，如

PADDLE_ENFORCE(input->dims().size() == 4 || input->dims().size() == 5); 
PADDLE_ENFORCE(is_train || !is_backward);
PADDLE_ENFORCE(v < 0 || v >= 1);
PADDLE_ENFORCE((lbl >= 0 && lbl < axis_dim) || lbl == ignore_index);
PADDLE_ENFORCE(!fuse_residual_conn || !force_fp32_output);
PADDLE_ENFORCE(op_desc.type() != kFeedOpType || expect_feed);

3.2 特殊处理的cuda error，如paddle/fluid/memory/detail/system_allocator.cc中

// Purposefully allow cudaErrorCudartUnloading, because
// that is returned if you ever call cudaFreeHost after the
// driver has already shutdown. This happens only if the
// process is terminating, in which case we don't care if
// cudaFreeHost succeeds.
if (err != cudaErrorCudartUnloading) {
  PADDLE_ENFORCE(err, "cudaFreeHost failed in GPUPinnedAllocator::Free.");
}

3.3 GPU内核函数中的报错

注意：

• GPU内核函数在.cu文件中，但并不是所有.cu文件中的都是GPU内核函数。只有使用__global__，HOSTDEVICE等关键字装饰的函数才是。
• 如下的paddle/fluid/operators/center_loss_op.cu例子，只说明PADDLE_ENFORCE表达式不需要修改，但文案修改请参考Paddle报错信息文案书写规范

__global__ void ComputeDifferent(T *centers_diff, const T *X, const T *centers,
                                 const int64_t *ids, const int64_t N,
                                 const int64_t K, const int64_t D) {
  int idx = threadIdx.x;
  int idy = blockIdx.x + threadIdx.y * GridDimX;

  while (idy < K) {
    int64_t id = ids[idy];
    PADDLE_ENFORCE(id >= 0, "received id:", id);
    PADDLE_ENFORCE(id < N, "received id:", id);
    T *out = centers_diff + idy * D;
    const T *x = X + idy * D;
    const T *cent = centers + id * D;
    for (int i = idx; i < D; i += BlockDimX) {
      out[i] = x[i] - cent[i];
    }
    idy += BlockDimY * GridDimX;
  }
}