GH-43209: [C++] Add lint for DCHECK in public headers

[zanmato1984]

Rationale for this change

I raised my question in #43209 about which I have always been curious. The top answer makes a good sense and after some searching in the code base, I found more evidence like:

arrow/cpp/src/arrow/public_api_test.cc

Lines 67 to 71 in 0372617

	TEST(InternalHeaders, DCheckExposed) {
	#ifdef DCHECK
	FAIL() << "DCHECK should not be visible from Arrow public headers.";
	#endif
	}

So I'm making the following changes to DCHECK macro family.

What changes are included in this PR?

1. Add lint rule for DCHECK usage in public headers;
2. Cleanup exisiting DCHECK usages in public (probably non-public, but at least not named with internal) headers;
3. Add ifdef protection for DCHECK definition like we did for ASSIGN_OR_RAISE (

   arrow/cpp/src/arrow/result_internal.h

   Lines 20 to 22 in 0372617

   	#ifndef ASSIGN_OR_RAISE
   	#define ASSIGN_OR_RAISE(lhs, rhs) ARROW_ASSIGN_OR_RAISE(lhs, rhs)
   	#endif

   ) and RETURN_NOT_OK (

   arrow/cpp/src/arrow/status.h

   Lines 80 to 82 in 0372617

   	#ifndef RETURN_NOT_OK
   	#define RETURN_NOT_OK(s) ARROW_RETURN_NOT_OK(s)
   	#endif

   ), to not mess up user code that directly includes arrow/util/logging.h.
4. Add comments as guideline.

Are these changes tested?

No test needed.

Are there any user-facing changes?

Probably not?

• GitHub Issue: [C++] Are ARROW_DCHECK* and DCHECK* interchangeable? #43209

[github-actions]

Thanks for opening a pull request!

If this is not a minor PR. Could you open an issue for this pull request on GitHub? https://github.com/apache/arrow/issues/new/choose

Opening GitHub issues ahead of time contributes to the Openness of the Apache Arrow project.

Then could you also rename the pull request title in the following format?

GH-${GITHUB_ISSUE_ID}: [${COMPONENT}] ${SUMMARY}

or

MINOR: [${COMPONENT}] ${SUMMARY}

In the case of PARQUET issues on JIRA the title also supports:

PARQUET-${JIRA_ISSUE_ID}: [${COMPONENT}] ${SUMMARY}

See also:

• Other pull requests
• Contribution Guidelines - Contributing Overview

[zanmato1984]

File whose path containing test and internal will be excluded universally in lint_files.

hash.h is already gone.

[github-actions]

⚠️ GitHub issue #43209 has been automatically assigned in GitHub to PR creator.

[zanmato1984]

A small cleanup. @pitrou would you like to take a look? Thanks.

[wgtmac]

@github-actions crossbow submit -g cpp

[zanmato1984]

@github-actions crossbow submit -g cpp

[mapleFU]

Thanks for your good catch!

[pitrou]

@github-actions crossbow submit -g cpp

[github-actions]

Revision: cb0e3b1

Submitted crossbow builds: ursacomputing/crossbow @ actions-84164aa0b0

Task	Status
test-alpine-linux-cpp
test-build-cpp-fuzz
test-conda-cpp
test-conda-cpp-valgrind
test-cuda-cpp
test-debian-12-cpp-amd64
test-debian-12-cpp-i386
test-fedora-39-cpp
test-ubuntu-20.04-cpp
test-ubuntu-20.04-cpp-bundled
test-ubuntu-20.04-cpp-minimal-with-formats
test-ubuntu-20.04-cpp-thread-sanitizer
test-ubuntu-22.04-cpp
test-ubuntu-22.04-cpp-20
test-ubuntu-22.04-cpp-emscripten
test-ubuntu-22.04-cpp-no-threading
test-ubuntu-24.04-cpp
test-ubuntu-24.04-cpp-gcc-14

[pitrou]

@zanmato1984 I think we should avoid @ing usernames in PR descriptions, because they end up in the final commit message and then can generate notification spam when people update their forks.

[zanmato1984]

@zanmato1984 I think we should avoid @ing usernames in PR descriptions, because they end up in the final commit message and then can generate notification spam when people update their forks.

Thanks for reminding. That's very thoughtful and I have updated the PR description. Appreciate that!

[pitrou]

Thanks a lot @zanmato1984 !

[conbench-apache-arrow]

After merging your PR, Conbench analyzed the 4 benchmarking runs that have been run so far on merge-commit 12f68fc.

There were no benchmark performance regressions. 🎉

The full Conbench report has more details. It also includes information about 2 possible false positives for unstable benchmarks that are known to sometimes produce them.