This is an automated email from the ASF dual-hosted git repository.
kou pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/arrow.git
The following commit(s) were added to refs/heads/main by this push:
new 5e1c112e93 MINOR: [FlightRPC][C++][Python][Docs] Minor tweaks to
docstrings (#36900)
5e1c112e93 is described below
commit 5e1c112e93092bcbf62c45b51fd6629463332c4d
Author: Bryce Mecum <[email protected]>
AuthorDate: Wed Jul 26 18:13:43 2023 -0800
MINOR: [FlightRPC][C++][Python][Docs] Minor tweaks to docstrings (#36900)
### Rationale for this change
Improves language surrounding Flight Shutdown/Wait/Serve.
### What changes are included in this PR?
Just docstring tweaks.
### Are these changes tested?
No tests, just docstrings.
### Are there any user-facing changes?
n/a
Authored-by: Bryce Mecum <[email protected]>
Signed-off-by: Sutou Kouhei <[email protected]>
---
cpp/src/arrow/flight/server.h | 20 +++++++++++++-------
python/pyarrow/_flight.pyx | 4 +++-
2 files changed, 16 insertions(+), 8 deletions(-)
diff --git a/cpp/src/arrow/flight/server.h b/cpp/src/arrow/flight/server.h
index 5c15d8d564..76f1a31706 100644
--- a/cpp/src/arrow/flight/server.h
+++ b/cpp/src/arrow/flight/server.h
@@ -202,8 +202,10 @@ class ARROW_FLIGHT_EXPORT FlightServerBase {
Status SetShutdownOnSignals(const std::vector<int> sigs);
/// \brief Start serving.
- /// This method blocks until either Shutdown() is called or one of the
signals
- /// registered in SetShutdownOnSignals() is received.
+ /// This method blocks until the server shuts down.
+ ///
+ /// The server will start to shut down when either Shutdown() is called
+ /// or one of the signals registered in SetShutdownOnSignals() is received.
Status Serve();
/// \brief Query whether Serve() was interrupted by a signal.
@@ -212,14 +214,18 @@ class ARROW_FLIGHT_EXPORT FlightServerBase {
/// \return int the signal number that interrupted Serve(), if any,
otherwise 0
int GotSignal() const;
- /// \brief Shut down the server. Can be called from signal handler or another
- /// thread while Serve() blocks. Optionally a deadline can be set. Once the
- /// the deadline expires server will wait until remaining running calls
- /// complete.
+ /// \brief Shut down the server, blocking until current requests finish.
+ ///
+ /// Can be called from a signal handler or another thread while Serve()
+ /// blocks. Optionally a deadline can be set. Once the the deadline expires
+ /// server will wait until remaining running calls complete.
///
+ /// Should only be called once.
Status Shutdown(const std::chrono::system_clock::time_point* deadline =
NULLPTR);
- /// \brief Block until server is terminated with Shutdown.
+ /// \brief Block until server shuts down with Shutdown.
+ ///
+ /// Does not respond to signals like Serve().
Status Wait();
// Implement these methods to create your own server. The default
diff --git a/python/pyarrow/_flight.pyx b/python/pyarrow/_flight.pyx
index 6f5cd03cd5..c9f5526754 100644
--- a/python/pyarrow/_flight.pyx
+++ b/python/pyarrow/_flight.pyx
@@ -3016,7 +3016,7 @@ cdef class FlightServerBase(_Weakrefable):
def serve(self):
"""Block until the server shuts down.
- This method only returns if shutdown() is called or a signal a
+ This method only returns if shutdown() is called or a signal is
received.
"""
if self.server.get() == nullptr:
@@ -3041,6 +3041,8 @@ cdef class FlightServerBase(_Weakrefable):
method, as then the server will block forever waiting for that
request to finish. Instead, call this method from a background
thread.
+
+ This method should only be called once.
"""
# Must not hold the GIL: shutdown waits for pending RPCs to
# complete. Holding the GIL means Python-implemented Flight
