| … | |
… | |
| 969 | If you feel the need to monitor or query a single subkey, try giving it |
969 | If you feel the need to monitor or query a single subkey, try giving it |
| 970 | it's own family. |
970 | it's own family. |
| 971 | |
971 | |
| 972 | =over |
972 | =over |
| 973 | |
973 | |
| 974 | =item db_set $family => $subkey [=> $value] |
974 | =item $guard = db_set $family => $subkey [=> $value] |
| 975 | |
975 | |
| 976 | Sets (or replaces) a key to the database - if C<$value> is omitted, |
976 | Sets (or replaces) a key to the database - if C<$value> is omitted, |
| 977 | C<undef> is used instead. |
977 | C<undef> is used instead. |
| 978 | |
978 | |
|
|
979 | When called in non-void context, C<db_set> returns a guard that |
|
|
980 | automatically calls C<db_del> when it is destroyed. |
|
|
981 | |
| 979 | =item db_del $family => $subkey... |
982 | =item db_del $family => $subkey... |
| 980 | |
983 | |
| 981 | Deletes one or more subkeys from the database family. |
984 | Deletes one or more subkeys from the database family. |
| 982 | |
985 | |
| 983 | =item $guard = db_reg $family => $subkey [=> $value] |
986 | =item $guard = db_reg $family => $port => $value |
| 984 | |
987 | |
| 985 | Sets the key on the database and returns a guard. When the guard is |
988 | =item $guard = db_reg $family => $port |
| 986 | destroyed, the key is deleted from the database. If C<$value> is missing, |
989 | |
| 987 | then C<undef> is used. |
990 | =item $guard = db_reg $family |
|
|
991 | |
|
|
992 | Registers a port in the given family and optionally returns a guard to |
|
|
993 | remove it. |
|
|
994 | |
|
|
995 | This function basically does the same as: |
|
|
996 | |
|
|
997 | db_set $family => $port => $value |
|
|
998 | |
|
|
999 | Except that the port is monitored and automatically removed from the |
|
|
1000 | database family when it is kil'ed. |
|
|
1001 | |
|
|
1002 | If C<$value> is missing, C<undef> is used. If C<$port> is missing, then |
|
|
1003 | C<$SELF> is used. |
|
|
1004 | |
|
|
1005 | This function is most useful to register a port in some port group (which |
|
|
1006 | is just another name for a database family), and have it removed when the |
|
|
1007 | port is gone. This works best when the port is a local port. |
|
|
1008 | |
|
|
1009 | =cut |
|
|
1010 | |
|
|
1011 | sub db_reg($$;$) { |
|
|
1012 | my $family = shift; |
|
|
1013 | my $port = @_ ? shift : $SELF; |
|
|
1014 | |
|
|
1015 | my $clr = sub { db_del $family => $port }; |
|
|
1016 | mon $port, $clr; |
|
|
1017 | |
|
|
1018 | db_set $family => $port => $_[0]; |
|
|
1019 | |
|
|
1020 | defined wantarray |
|
|
1021 | and &Guard::guard ($clr) |
|
|
1022 | } |
| 988 | |
1023 | |
| 989 | =item db_family $family => $cb->(\%familyhash) |
1024 | =item db_family $family => $cb->(\%familyhash) |
| 990 | |
1025 | |
| 991 | Queries the named database C<$family> and call the callback with the |
1026 | Queries the named database C<$family> and call the callback with the |
| 992 | family represented as a hash. You can keep and freely modify the hash. |
1027 | family represented as a hash. You can keep and freely modify the hash. |
| … | |
… | |
| 1217 | Keeping your messages simple, concentrating on data structures rather than |
1252 | Keeping your messages simple, concentrating on data structures rather than |
| 1218 | objects, will keep your messages clean, tidy and efficient. |
1253 | objects, will keep your messages clean, tidy and efficient. |
| 1219 | |
1254 | |
| 1220 | =back |
1255 | =back |
| 1221 | |
1256 | |
|
|
1257 | =head1 PORTING FROM AnyEvent::MP VERSION 1.X |
|
|
1258 | |
|
|
1259 | AEMP version 2 has three major incompatible changes compared to version 1: |
|
|
1260 | |
|
|
1261 | =over 4 |
|
|
1262 | |
|
|
1263 | =item AnyEvent::MP::Global no longer has group management functions. |
|
|
1264 | |
|
|
1265 | AnyEvent::MP now comes with a distributed database that is more |
|
|
1266 | powerful. It's database families map closely to ports, but the API has |
|
|
1267 | minor differences: |
|
|
1268 | |
|
|
1269 | grp_reg $group, $port # old |
|
|
1270 | db_reg $group, $port # new |
|
|
1271 | |
|
|
1272 | $list = grp_get $group # old |
|
|
1273 | db_keys $group, sub { my $list = shift } # new |
|
|
1274 | |
|
|
1275 | grp_mon $group, $cb->(\@ports, $add, $del) # old |
|
|
1276 | db_mon $group, $cb->(\%ports, $add, $change, $del) # new |
|
|
1277 | |
|
|
1278 | C<grp_reg> is a no-brainer (just replace by C<db_reg>), but C<grp_get> |
|
|
1279 | is no longer instant, because the local node might not have a copy of |
|
|
1280 | the group. This can be partially remedied by using C<db_mon> to keep an |
|
|
1281 | updated copy of the group: |
|
|
1282 | |
|
|
1283 | my $local_group_copy; |
|
|
1284 | db_mon $group => sub { $local_group_copy = shift }; |
|
|
1285 | |
|
|
1286 | # no keys %$local_group_copy always returns the most up-to-date |
|
|
1287 | # list of ports in the group. |
|
|
1288 | |
|
|
1289 | C<grp_mon> can almost be replaced by C<db_mon>: |
|
|
1290 | |
|
|
1291 | db_mon $group => sub { |
|
|
1292 | my ($ports, $add, $chg, $lde) = @_; |
|
|
1293 | $ports = [keys %$ports]; |
|
|
1294 | |
|
|
1295 | # now $ports, $add and $del are the same as |
|
|
1296 | # were originally passed by grp_mon. |
|
|
1297 | ... |
|
|
1298 | }; |
|
|
1299 | |
|
|
1300 | =item Nodes not longer connect to all other nodes. |
|
|
1301 | |
|
|
1302 | In AEMP 1.x, every node automatically loads the L<AnyEvent::MP::Global> |
|
|
1303 | module, which in turn would create connections to all other nodes in the |
|
|
1304 | network (helped by the seed nodes). |
|
|
1305 | |
|
|
1306 | In version 2.x, global nodes still connect to all other global nodes, but |
|
|
1307 | other nodes don't - now every node either is a global node itself, or |
|
|
1308 | attaches itself to another global node. |
|
|
1309 | |
|
|
1310 | If a node isn't a global node itself, then it attaches itself to one |
|
|
1311 | of its seed nodes. If that seed node isn't a global node yet, it will |
|
|
1312 | automatically be upgraded to a global node. |
|
|
1313 | |
|
|
1314 | So in many cases, nothing needs to be changed - one just has to make sure |
|
|
1315 | that all seed nodes are meshed together with the other seed nodes (as with |
|
|
1316 | AEMP 1.x), and other nodes specify them as seed nodes. |
|
|
1317 | |
|
|
1318 | Not opening a connection to every other node is usually an advantage, |
|
|
1319 | except when you need the lower latency of an already established |
|
|
1320 | connection. To ensure a node establishes a connection to another node, |
|
|
1321 | you can monitor the node port (C<mon $node, ...>), which will attempt to |
|
|
1322 | create the connection (And notify you when the connection fails). |
|
|
1323 | |
|
|
1324 | =item Listener-less nodes are gone. |
|
|
1325 | |
|
|
1326 | And are not coming back, at least not in their old form. |
|
|
1327 | |
|
|
1328 | There are vague plans to implement some form of routing domains, which |
|
|
1329 | might or might not bring back listener-less nodes, but don't count on it. |
|
|
1330 | |
|
|
1331 | The fact that most connections are now optional somewhat mitigates this, |
|
|
1332 | as a node can be effectively unreachable from the outside without any |
|
|
1333 | problems, as long as it isn't a global node and only reaches out to other |
|
|
1334 | nodes (as opposed to being contacted from other nodes). |
|
|
1335 | |
|
|
1336 | =back |
|
|
1337 | |
| 1222 | =head1 SEE ALSO |
1338 | =head1 SEE ALSO |
| 1223 | |
1339 | |
| 1224 | L<AnyEvent::MP::Intro> - a gentle introduction. |
1340 | L<AnyEvent::MP::Intro> - a gentle introduction. |
| 1225 | |
1341 | |
| 1226 | L<AnyEvent::MP::Kernel> - more, lower-level, stuff. |
1342 | L<AnyEvent::MP::Kernel> - more, lower-level, stuff. |
