1// Copyright 2013 The Flutter Authors. All rights reserved. 2// Use of this source code is governed by a BSD-style license that can be 3// found in the LICENSE file. 4 5part of dart.ui; 6 7/// Static methods to allow for simple sharing of [SendPort]s across [Isolate]s. 8/// 9/// All isolates share a global mapping of names to ports. An isolate can 10/// register a [SendPort] with a given name using [registerPortWithName]; 11/// another isolate can then look up that port using [lookupPortByName]. 12/// 13/// To create a [SendPort], first create a [ReceivePort], then use 14/// [ReceivePort.sendPort]. 15/// 16/// Since multiple isolates can each obtain the same [SendPort] associated with 17/// a particular [ReceivePort], the protocol built on top of this mechanism 18/// should typically consist of a single message. If more elaborate two-way 19/// communication or multiple-message communication is necessary, it is 20/// recommended to establish a separate communication channel in that first 21/// message (e.g. by passing a dedicated [SendPort]). 22class IsolateNameServer { 23 // This class is only a namespace, and should not be instantiated or 24 // extended directly. 25 factory IsolateNameServer._() => null; 26 27 /// Looks up the [SendPort] associated with a given name. 28 /// 29 /// Returns null if the name does not exist. To register the name in the first 30 /// place, consider [registerPortWithName]. 31 /// 32 /// The `name` argument must not be null. 33 static SendPort lookupPortByName(String name) { 34 assert(name != null, "'name' cannot be null."); 35 return _lookupPortByName(name); 36 } 37 38 /// Registers a [SendPort] with a given name. 39 /// 40 /// Returns true if registration is successful, and false if the name entry 41 /// already existed (in which case the earlier registration is left 42 /// unchanged). To remove a registration, consider [removePortNameMapping]. 43 /// 44 /// Once a port has been registered with a name, it can be obtained from any 45 /// [Isolate] using [lookupPortByName]. 46 /// 47 /// Multiple isolates should avoid attempting to register ports with the same 48 /// name, as there is an inherent race condition in doing so. 49 /// 50 /// The `port` and `name` arguments must not be null. 51 static bool registerPortWithName(SendPort port, String name) { 52 assert(port != null, "'port' cannot be null."); 53 assert(name != null, "'name' cannot be null."); 54 return _registerPortWithName(port, name); 55 } 56 57 /// Removes a name-to-[SendPort] mapping given its name. 58 /// 59 /// Returns true if the mapping was successfully removed, false if the mapping 60 /// did not exist. To add a registration, consider [registerPortWithName]. 61 /// 62 /// Generally, removing a port name mapping is an inherently racy operation 63 /// (another isolate could have obtained the name just prior to the name being 64 /// removed, and thus would still be able to communicate over the port even 65 /// after it has been removed). 66 /// 67 /// The `name` argument must not be null. 68 static bool removePortNameMapping(String name) { 69 assert(name != null, "'name' cannot be null."); 70 return _removePortNameMapping(name); 71 } 72 73 static SendPort _lookupPortByName(String name) 74 native 'IsolateNameServerNatives_LookupPortByName'; 75 static bool _registerPortWithName(SendPort port, String name) 76 native 'IsolateNameServerNatives_RegisterPortWithName'; 77 static bool _removePortNameMapping(String name) 78 native 'IsolateNameServerNatives_RemovePortNameMapping'; 79} 80