Skip to content

Commit 05d05bc

Browse files
teh-cmcteh-cmc
authored
rr.serve -> rr.serve_web, rr.connect -> rr.connect_tcp (#7906)
1 parent 558ff44 commit 05d05bc

File tree

35 files changed

+298
-47
lines changed

35 files changed

+298
-47
lines changed

‎crates/top/re_sdk/src/recording_stream.rs

+91-3
Original file line numberDiff line numberDiff line change
@@ -310,8 +310,24 @@ impl RecordingStreamBuilder {
310310
/// let rec = re_sdk::RecordingStreamBuilder::new("rerun_example_app").connect()?;
311311
/// # Ok::<(), Box<dyn std::error::Error>>(())
312312
/// ```
313+
#[deprecated(since = "0.20.0", note = "use connect_tcp() instead")]
313314
pub fn connect(self) -> RecordingStreamResult<RecordingStream> {
314-
self.connect_opts(crate::default_server_addr(), crate::default_flush_timeout())
315+
self.connect_tcp()
316+
}
317+
318+
/// Creates a new [`RecordingStream`] that is pre-configured to stream the data through to a
319+
/// remote Rerun instance.
320+
///
321+
/// See also [`Self::connect_opts`] if you wish to configure the TCP connection.
322+
///
323+
/// ## Example
324+
///
325+
/// ```no_run
326+
/// let rec = re_sdk::RecordingStreamBuilder::new("rerun_example_app").connect_tcp()?;
327+
/// # Ok::<(), Box<dyn std::error::Error>>(())
328+
/// ```
329+
pub fn connect_tcp(self) -> RecordingStreamResult<RecordingStream> {
330+
self.connect_tcp_opts(crate::default_server_addr(), crate::default_flush_timeout())
315331
}
316332

317333
/// Creates a new [`RecordingStream`] that is pre-configured to stream the data through to a
@@ -328,10 +344,33 @@ impl RecordingStreamBuilder {
328344
/// .connect_opts(re_sdk::default_server_addr(), re_sdk::default_flush_timeout())?;
329345
/// # Ok::<(), Box<dyn std::error::Error>>(())
330346
/// ```
347+
#[deprecated(since = "0.20.0", note = "use connect_tcp_opts() instead")]
331348
pub fn connect_opts(
332349
self,
333350
addr: std::net::SocketAddr,
334351
flush_timeout: Option<std::time::Duration>,
352+
) -> RecordingStreamResult<RecordingStream> {
353+
self.connect_tcp_opts(addr, flush_timeout)
354+
}
355+
356+
/// Creates a new [`RecordingStream`] that is pre-configured to stream the data through to a
357+
/// remote Rerun instance.
358+
///
359+
/// `flush_timeout` is the minimum time the [`TcpSink`][`crate::log_sink::TcpSink`] will
360+
/// wait during a flush before potentially dropping data. Note: Passing `None` here can cause a
361+
/// call to `flush` to block indefinitely if a connection cannot be established.
362+
///
363+
/// ## Example
364+
///
365+
/// ```no_run
366+
/// let rec = re_sdk::RecordingStreamBuilder::new("rerun_example_app")
367+
/// .connect_opts(re_sdk::default_server_addr(), re_sdk::default_flush_timeout())?;
368+
/// # Ok::<(), Box<dyn std::error::Error>>(())
369+
/// ```
370+
pub fn connect_tcp_opts(
371+
self,
372+
addr: std::net::SocketAddr,
373+
flush_timeout: Option<std::time::Duration>,
335374
) -> RecordingStreamResult<RecordingStream> {
336375
let (enabled, store_info, batcher_config) = self.into_args();
337376
if enabled {
@@ -464,12 +503,12 @@ impl RecordingStreamBuilder {
464503
// NOTE: If `_RERUN_TEST_FORCE_SAVE` is set, all recording streams will write to disk no matter
465504
// what, thus spawning a viewer is pointless (and probably not intended).
466505
if forced_sink_path().is_some() {
467-
return self.connect_opts(connect_addr, flush_timeout);
506+
return self.connect_tcp_opts(connect_addr, flush_timeout);
468507
}
469508

470509
crate::spawn(opts)?;
471510

472-
self.connect_opts(connect_addr, flush_timeout)
511+
self.connect_tcp_opts(connect_addr, flush_timeout)
473512
}
474513

475514
/// Creates a new [`RecordingStream`] that is pre-configured to stream the data through to a
@@ -503,13 +542,62 @@ impl RecordingStreamBuilder {
503542
//
504543
// # TODO(#5531): keep static data around.
505544
#[cfg(feature = "web_viewer")]
545+
#[deprecated(since = "0.20.0", note = "use serve_web() instead")]
506546
pub fn serve(
507547
self,
508548
bind_ip: &str,
509549
web_port: WebViewerServerPort,
510550
ws_port: RerunServerPort,
511551
server_memory_limit: re_memory::MemoryLimit,
512552
open_browser: bool,
553+
) -> RecordingStreamResult<RecordingStream> {
554+
self.serve_web(
555+
bind_ip,
556+
web_port,
557+
ws_port,
558+
server_memory_limit,
559+
open_browser,
560+
)
561+
}
562+
563+
/// Creates a new [`RecordingStream`] that is pre-configured to stream the data through to a
564+
/// web-based Rerun viewer via WebSockets.
565+
///
566+
/// If the `open_browser` argument is `true`, your default browser will be opened with a
567+
/// connected web-viewer.
568+
///
569+
/// If not, you can connect to this server using the `rerun` binary (`cargo install rerun-cli --locked`).
570+
///
571+
/// ## Details
572+
/// This method will spawn two servers: one HTTPS server serving the Rerun Web Viewer `.html` and `.wasm` files,
573+
/// and then one WebSocket server that streams the log data to the web viewer (or to a native viewer, or to multiple viewers).
574+
///
575+
/// The WebSocket server will buffer all log data in memory so that late connecting viewers will get all the data.
576+
/// You can limit the amount of data buffered by the WebSocket server with the `server_memory_limit` argument.
577+
/// Once reached, the earliest logged data will be dropped.
578+
/// Note that this means that static data may be dropped if logged early (see <https://github.com/rerun-io/rerun/issues/5531>).
579+
///
580+
/// ## Example
581+
///
582+
/// ```ignore
583+
/// let rec = re_sdk::RecordingStreamBuilder::new("rerun_example_app")
584+
/// .serve_web("0.0.0.0",
585+
/// Default::default(),
586+
/// Default::default(),
587+
/// re_sdk::MemoryLimit::from_fraction_of_total(0.25),
588+
/// true)?;
589+
/// # Ok::<(), Box<dyn std::error::Error>>(())
590+
/// ```
591+
//
592+
// # TODO(#5531): keep static data around.
593+
#[cfg(feature = "web_viewer")]
594+
pub fn serve_web(
595+
self,
596+
bind_ip: &str,
597+
web_port: WebViewerServerPort,
598+
ws_port: RerunServerPort,
599+
server_memory_limit: re_memory::MemoryLimit,
600+
open_browser: bool,
513601
) -> RecordingStreamResult<RecordingStream> {
514602
let (enabled, store_info, batcher_config) = self.into_args();
515603
if enabled {

‎crates/top/rerun/src/clap.rs

+2-2
Original file line numberDiff line numberDiff line change
@@ -112,7 +112,7 @@ impl RerunArgs {
112112

113113
RerunBehavior::Connect(addr) => Ok((
114114
RecordingStreamBuilder::new(application_id)
115-
.connect_opts(addr, crate::default_flush_timeout())?,
115+
.connect_tcp_opts(addr, crate::default_flush_timeout())?,
116116
Default::default(),
117117
)),
118118

@@ -132,7 +132,7 @@ impl RerunArgs {
132132
.map_err(|err| anyhow::format_err!("Bad --server-memory-limit: {err}"))?;
133133

134134
let open_browser = true;
135-
let rec = RecordingStreamBuilder::new(application_id).serve(
135+
let rec = RecordingStreamBuilder::new(application_id).serve_web(
136136
&self.bind,
137137
Default::default(),
138138
Default::default(),

‎crates/viewer/re_viewer/data/quick_start_guides/quick_start_connect.cpp

+1-1
Original file line numberDiff line numberDiff line change
@@ -6,7 +6,7 @@ using namespace rerun::demo;
66
int main() {
77
// Create a new `RecordingStream` which sends data over TCP to the viewer process.
88
const auto rec = rerun::RecordingStream("rerun_example_quick_start_connect");
9-
rec.connect().exit_on_failure();
9+
rec.connect_tcp().exit_on_failure();
1010

1111
// Create some data using the `grid` utility function.
1212
std::vector<rerun::Position3D> points = grid3d<rerun::Position3D, float>(-10.f, 10.f, 10);

‎crates/viewer/re_viewer/data/quick_start_guides/quick_start_connect.py

+1-1
Original file line numberDiff line numberDiff line change
@@ -7,7 +7,7 @@
77
rr.init("rerun_example_quick_start_connect")
88

99
# Connect to a local viewer using the default port
10-
rr.connect()
10+
rr.connect_tcp()
1111

1212

1313
# Create some data

‎crates/viewer/re_viewer/data/quick_start_guides/quick_start_connect.rs

+2-1
Original file line numberDiff line numberDiff line change
@@ -4,7 +4,8 @@ use rerun::{demo_util::grid, external::glam};
44

55
fn main() -> Result<(), Box<dyn std::error::Error>> {
66
// Create a new `RecordingStream` which sends data over TCP to the viewer process.
7-
let rec = rerun::RecordingStreamBuilder::new("rerun_example_quick_start_connect").connect()?;
7+
let rec =
8+
rerun::RecordingStreamBuilder::new("rerun_example_quick_start_connect").connect_tcp()?;
89

910
// Create some data using the `grid` utility function.
1011
let points = grid(glam::Vec3::splat(-10.0), glam::Vec3::splat(10.0), 10);

‎docs/content/reference/migration/migration-0-13.md

+1-1
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
---
22
title: Migrating from 0.12 to 0.13
3-
order: 130
3+
order: 996
44
---
55

66
## `TimeSeriesScalar` deprecated in favor of [Scalar](../types/archetypes/scalar.md) & [SeriesLine](../types/archetypes/series_line.md)/[SeriesPoint](../types/archetypes/series_point.md)

‎docs/content/reference/migration/migration-0-15.md

+1-1
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
---
22
title: Migrating from 0.14 to 0.15
3-
order: 150
3+
order: 995
44
---
55

66
## `InstanceKey` removed from our logging APIs

‎docs/content/reference/migration/migration-0-16.md

+1-1
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
---
22
title: Migrating from 0.15 to 0.16
3-
order: 160
3+
order: 994
44
---
55

66

‎docs/content/reference/migration/migration-0-17.md

+1-1
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
---
22
title: Migrating from 0.16 to 0.17
3-
order: 170
3+
order: 993
44
---
55

66

‎docs/content/reference/migration/migration-0-18.md

+1-1
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
---
22
title: Migrating from 0.17 to 0.18
3-
order: 180
3+
order: 992
44
---
55

66
## ⚠️ Breaking changes

‎docs/content/reference/migration/migration-0-19.md

+1-1
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
---
22
title: Migrating from 0.18 to 0.19
3-
order: 190
3+
order: 991
44
---
55

66
Blueprint files (.rbl) from previous Rerun versions will no longer load _automatically_.

‎docs/content/reference/migration/migration-0-20.md

+20
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,20 @@
1+
---
2+
title: Migrating from 0.19 to 0.20
3+
order: 990
4+
---
5+
6+
7+
## ⚠️ Breaking changes
8+
9+
10+
### `connect` -> `connect_tcp` & `serve` -> `serve_web`
11+
12+
In all SDKs:
13+
* `connect()` is now deprecated in favor `connect_tcp()`
14+
* `serve()` is now deprecated in favor `serve_web()`
15+
16+
The rationale behind this change is that it was common for users (see https://github.com/rerun-io/rerun/issues/7766).
17+
18+
We frequently had reports from users that were understandably expecting a serving process (`rr.serve()`) to be ready to accept connections from other processes (`rr.connect()`), when in reality the two things are completely unrelated: one is hosting a websocket server to be polled by the web-viewer, while the other is trying to connect to the TCP SDK comms pipeline.
19+
20+
You can learn more about Rerun's application model and the different servers and ports by reading our [new documentation page on the matter](../../concepts/app-model.md).

‎docs/content/reference/migration/migration-0-9.md

+1-1
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
---
22
title: Migrating from 0.8 to 0.9
3-
order: 90
3+
order: 1000
44
---
55

66
Rerun-0.9 introduces a new set of type-oriented logging APIs built on top of an updated, more concrete,

‎docs/snippets/all/concepts/app-model/native-sync.cpp

+1-1
Original file line numberDiff line numberDiff line change
@@ -4,7 +4,7 @@ int main() {
44
// Connect to the Rerun TCP server using the default address and
55
// port: localhost:9876
66
const auto rec = rerun::RecordingStream("rerun_example_native_sync");
7-
rec.connect().exit_on_failure();
7+
rec.connect_tcp().exit_on_failure();
88

99
// Log data as usual, thereby pushing it into the TCP socket.
1010
while (true) {

‎docs/snippets/all/concepts/app-model/native-sync.py

+1-1
Original file line numberDiff line numberDiff line change
@@ -6,7 +6,7 @@
66

77
# Connect to the Rerun TCP server using the default address and
88
# port: localhost:9876
9-
rr.connect()
9+
rr.connect_tcp()
1010

1111
# Log data as usual, thereby pushing it into the TCP socket.
1212
while True:

‎docs/snippets/all/concepts/app-model/native-sync.rs

+1-1
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
fn main() -> Result<(), Box<dyn std::error::Error>> {
22
// Connect to the Rerun TCP server using the default address and
33
// port: localhost:9876
4-
let rec = rerun::RecordingStreamBuilder::new("rerun_example_native_sync").connect()?;
4+
let rec = rerun::RecordingStreamBuilder::new("rerun_example_native_sync").connect_tcp()?;
55

66
// Log data as usual, thereby pushing it into the TCP socket.
77
loop {

‎docs/snippets/all/quick_start/quick_start_connect.cpp

+1-1
Original file line numberDiff line numberDiff line change
@@ -6,7 +6,7 @@ using namespace rerun::demo;
66
int main() {
77
// Create a new `RecordingStream` which sends data over TCP to the viewer process.
88
const auto rec = rerun::RecordingStream("rerun_example_quick_start_connect");
9-
rec.connect().exit_on_failure();
9+
rec.connect_tcp().exit_on_failure();
1010

1111
// Create some data using the `grid` utility function.
1212
std::vector<rerun::Position3D> points = grid3d<rerun::Position3D, float>(-10.f, 10.f, 10);

‎docs/snippets/all/quick_start/quick_start_connect.py

+1-1
Original file line numberDiff line numberDiff line change
@@ -7,7 +7,7 @@
77
rr.init("rerun_example_quick_start_connect")
88

99
# Connect to a local viewer using the default port
10-
rr.connect()
10+
rr.connect_tcp()
1111

1212

1313
# Create some data

‎docs/snippets/all/quick_start/quick_start_connect.rs

+2-1
Original file line numberDiff line numberDiff line change
@@ -4,7 +4,8 @@ use rerun::{demo_util::grid, external::glam};
44

55
fn main() -> Result<(), Box<dyn std::error::Error>> {
66
// Create a new `RecordingStream` which sends data over TCP to the viewer process.
7-
let rec = rerun::RecordingStreamBuilder::new("rerun_example_quick_start_connect").connect()?;
7+
let rec =
8+
rerun::RecordingStreamBuilder::new("rerun_example_quick_start_connect").connect_tcp()?;
89

910
// Create some data using the `grid` utility function.
1011
let points = grid(glam::Vec3::splat(-10.0), glam::Vec3::splat(10.0), 10);

‎docs/snippets/all/tutorials/data_out.py

+1-1
Original file line numberDiff line numberDiff line change
@@ -27,7 +27,7 @@
2727

2828
# Connect to the viewer
2929
rr.init(recording.application_id(), recording_id=recording.recording_id())
30-
rr.connect()
30+
rr.connect_tcp()
3131

3232
# log the jaw open state signal as a scalar
3333
rr.send_columns(

‎examples/cpp/log_file/main.cpp

+1-1
Original file line numberDiff line numberDiff line change
@@ -43,7 +43,7 @@ int main(int argc, char** argv) {
4343
if (args["spawn"].as<bool>()) {
4444
rec.spawn().exit_on_failure();
4545
} else if (args["connect"].as<bool>()) {
46-
rec.connect().exit_on_failure();
46+
rec.connect_tcp().exit_on_failure();
4747
} else if (args["stdout"].as<bool>()) {
4848
rec.to_stdout().exit_on_failure();
4949
} else if (args.count("save")) {

‎examples/python/multiprocess_logging/README.md

+1-1
Original file line numberDiff line numberDiff line change
@@ -29,7 +29,7 @@ The function `task` is decorated with `@rr.shutdown_at_exit`. This decorator ens
2929
def task(child_index: int) -> None:
3030
rr.init("rerun_example_multiprocessing")
3131

32-
rr.connect()
32+
rr.connect_tcp()
3333

3434
title = f"task_{child_index}"
3535
rr.log(

‎examples/python/multiprocess_logging/multiprocess_logging.py

+1-1
Original file line numberDiff line numberDiff line change
@@ -24,7 +24,7 @@ def task(child_index: int) -> None:
2424
rr.init("rerun_example_multiprocessing")
2525

2626
# We then have to connect to the viewer instance.
27-
rr.connect()
27+
rr.connect_tcp()
2828

2929
title = f"task_{child_index}"
3030
rr.log(

‎examples/rust/chess_robby_fischer/README.md

+2-2
Original file line numberDiff line numberDiff line change
@@ -30,7 +30,7 @@ let app_id = "RobbyFischer";
3030
let rec_id = uuid::Uuid::new_v4().to_string();
3131
let rec = rerun::RecordingStreamBuilder::new(app_id)
3232
.recording_id(&rec_id)
33-
.connect()
33+
.connect_tcp()
3434
.unwrap();
3535

3636
// …
@@ -323,7 +323,7 @@ parser.add_argument("--application-id", type=str)
323323

324324
args = parser.parse_args()
325325
rr.init(args.application_id, recording_id=args.recording_id)
326-
rr.connect()
326+
rr.connect_tcp()
327327
rr.send_blueprint(blueprint)
328328
```
329329

‎examples/rust/minimal_serve/src/main.rs

+1-1
Original file line numberDiff line numberDiff line change
@@ -4,7 +4,7 @@ use rerun::{demo_util::grid, external::glam};
44

55
fn main() -> Result<(), Box<dyn std::error::Error>> {
66
let open_browser = true;
7-
let rec = rerun::RecordingStreamBuilder::new("rerun_example_minimal_serve").serve(
7+
let rec = rerun::RecordingStreamBuilder::new("rerun_example_minimal_serve").serve_web(
88
"0.0.0.0",
99
Default::default(),
1010
Default::default(),

‎rerun_cpp/docs/readme_snippets.cpp

+1-1
Original file line numberDiff line numberDiff line change
@@ -45,7 +45,7 @@ static std::vector<uint8_t> create_image() {
4545
[[maybe_unused]] static void connecting() {
4646
/// [Connecting]
4747
rerun::RecordingStream rec("rerun_example_app");
48-
auto result = rec.connect(); // Connect to local host with default port.
48+
auto result = rec.connect_tcp(); // Connect to local host with default port.
4949
if (result.is_err()) {
5050
// Handle error.
5151
}

‎rerun_cpp/src/rerun/recording_stream.cpp

+4
Original file line numberDiff line numberDiff line change
@@ -101,6 +101,10 @@ namespace rerun {
101101
}
102102

103103
Error RecordingStream::connect(std::string_view tcp_addr, float flush_timeout_sec) const {
104+
return RecordingStream::connect_tcp(tcp_addr, flush_timeout_sec);
105+
}
106+
107+
Error RecordingStream::connect_tcp(std::string_view tcp_addr, float flush_timeout_sec) const {
104108
rr_error status = {};
105109
rr_recording_stream_connect(
106110
_id,

0 commit comments

Comments
 (0)