Adding OrtcFactory, and changing UdpTransport to match current plan.

webrtc/api/ortcfactory.h

+/*
+ *  Copyright 2017 The WebRTC project authors. All Rights Reserved.
+ *
+ *  Use of this source code is governed by a BSD-style license
+ *  that can be found in the LICENSE file in the root of the source
+ *  tree. An additional intellectual property rights grant can be found
+ *  in the file PATENTS.  All contributing project authors may
+ *  be found in the AUTHORS file in the root of the source tree.
+ */
+
+#ifndef WEBRTC_API_ORTCFACTORY_H_
+#define WEBRTC_API_ORTCFACTORY_H_
+
+#include <memory>
+
+#include "webrtc/api/udptransportinterface.h"
+#include "webrtc/base/network.h"
+#include "webrtc/base/thread.h"
+#include "webrtc/p2p/base/packetsocketfactory.h"

[pthatcher1, 2017/01/17 20:04:36]

Should we have a TODO to move this into the api/ directory?

[Taylor Brandstetter, 2017/01/18 02:31:38]

It should move, but I don't think a TODO helps; there are hundreds of similar
includes that don't have TODOs.

+
+namespace webrtc {
+
+// WARNING: This is experimental/under development, so use at your own risk; no
+// guarantee about API stability is guaranteed here yet.
+//
+// This class is the ORTC analog of PeerConnectionFactory. It acts as a factory
+// for ORTC objects that can be connected to each other.
+//
+// Some of these objects may not be represented by the ORTC specification, but
+// follow the same general principles.
+//
+// On object lifetimes: The factory must not be destroyed before destroying the
+// objects it created, and the objects passed into the factory must not be
+// destroyed before destroying the factory.
+class OrtcFactory {
+ public:
+  // |network_thread| is the thread on which packets are sent and received.
+  // If null, a new rtc::Thread with a default socket server is created.
+  //
+  // |worker_thread| is used for CPU-intensive operations.

[pthatcher1, 2017/01/17 20:04:36]

This kind of misleading.  If the worker thread is blocked by CPU-intensive
operations, lots of stuff won't work.  Maybe we should call this the
media_thread and say that media operations happen on the media_thread or child
threads.  

[Taylor Brandstetter, 2017/01/18 02:31:37]

Technically that's just a limitation of our implementation, not the API, but I
should call it out in a comment.

+  // If null, a new rtc::Thread is created.
+  //
+  // |signaling_thread| is used for callbacks to the consumer of the API. If
+  // null, the current thread will be used, which assumes that the API consumer
+  // is running a message loop on this thread (either using an existing
+  // rtc::Thread, or by calling rtc::Thread::Current()->ProcessMessages).

[pthatcher1, 2017/01/17 20:04:36]

Is it also the case that all methods call on the API must be called on the
signaling_thread?  If not, then would callback_thread be a better name?  If so,
would api_thread be a better name?

[Taylor Brandstetter, 2017/01/18 02:31:38]

Yes, but a proxy object should handle that for the application. That's something
I was still missing; see most recent patchset.

+  //
+  // |network_manager| is used to determine which network interfaces are
+  // available. This is used for ICE, for example. If null, a default
+  // implementation will be used. Only accessed on |network_thread|.
+  //
+  // |socket_factory| is used (on the network thread) for creating sockets. If
+  // it's null, a default implementation will be used, which assumes
+  // |network_thread| is a normal rtc::Thread.
+  //
+  // Note that the OrtcFactory does not take ownership of any of the objects
+  // passed in.

[pthatcher1, 2017/01/17 20:04:36]

You might want to repeat that none of these can be destroyed before the factory
is destroyed.

[Taylor Brandstetter, 2017/01/18 02:31:38]

Done

+  OrtcFactory(rtc::Thread* network_thread,
+              rtc::Thread* worker_thread,
+              rtc::Thread* signaling_thread,
+              rtc::NetworkManager* network_manager,
+              rtc::PacketSocketFactory* socket_factory);
+  // Constructor for convenience which uses default implementations of
+  // everything (though does still require that the current thread runs a
+  // message loop; see above).
+  OrtcFactory() : OrtcFactory(nullptr, nullptr, nullptr, nullptr, nullptr) {}
+  ~OrtcFactory();
+
+  // Create a UDP transport with IP address family |family|, using a port
+  // within the specified range.
+  //
+  // |family| must be AF_INET or AF_INET6.
+  //
+  // |min_port|/|max_port| values of 0 indicate no range restriction.
+  //
+  // Returns nullptr if the transport wasn't successfully created.
+  std::unique_ptr<UdpTransportInterface> CreateUdpTransport(int family,
+                                                            uint16_t min_port,
+                                                            uint16_t max_port);
+  // Method for convenience that has no port range restrictions.
+  std::unique_ptr<UdpTransportInterface> CreateUdpTransport(int family) {
+    return CreateUdpTransport(family, 0, 0);
+  }
+
+ private:
+  rtc::Thread* network_thread_;
+  rtc::Thread* worker_thread_;
+  rtc::Thread* signaling_thread_;
+  rtc::NetworkManager* network_manager_;
+  rtc::PacketSocketFactory* socket_factory_;
+  // Which of these objects do we own (we constructed a default implementation)
+  // vs. were passed in?
+  bool owns_network_thread_ = false;
+  bool owns_worker_thread_ = false;
+  bool wraps_signaling_thread_ = false;
+  bool owns_network_manager_ = false;
+  bool owns_socket_factory_ = false;

[pthatcher1, 2017/01/17 20:04:36]

The alternative approach which many places in our code uses is this:

rtc::Thread* network_thread_;
std::unique_ptr<rtc::Thread> owned_network_thread_;

That way you get destruction for free.  Just make owned_network_thread_ ==
network_thread_ when it's owned and null when it's not.  

+};
+
+}  // namespace webrtc
+
+#endif  // WEBRTC_API_ORTCFACTORY_H_