1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353 354 355 356 357 358 359 360 361 362 363 364 365 366 367 368 369 370 371 372 373 374 375 376 377 378 379 380 381 382 383 384 385 386 387 388 389 390 391 392 393 394 395 396 397 398 399 400 401 402 403 404 405 406 407 408 409 410 411 412 413 414 415 416 417 418 419 420 421 422 423 424 425 426 427 428 429 430 431 432 433 434 435 436 437 438 439 440 441 442 443 444 445 446 447 448 449 450 451 452 453 454 455 456 457 458 459 460 461 462 463 464 465 466 467 468 469 470 471 472 473 474 475 476 477 478 479 480 481 482 483 484 485 486 487 488 489 490 491 492 493 494 495 496 497 498 499 500 501 502 503 504 505 506 507 508 509 510 511 512 513 514 515 516 517 518 519 520 521 522 523 524 525 526 527 528 529 530 531 532 533 534 535 536 537 538 539 540 541 542 543 544 545 546 547 548 549 550 551 552 553 554 555 556 557 558 559 560 561 562 563 564 565 566 567 568 569 570 571 572 573 574 575 576 577 578 579 580 581 582 583 584 585 586 587 588 589 590 591 592 593 594 595 596 597 598 599 600 601 602 603 604 605 606 607 608 609 610 611 612 613 614 615 616 617 618 619 620 621 622 623 624 625 626 627 628 629 630 631 632 633 634 635 636 637 638 639 640 641 642 643 644 645 646 647 648 649 650 651 652 653 654 655 656 657 658 659 660 661 662 663 664 665 666 667 668 669 670 671 672 673 674 675 676 677 678 679 680 681 682 683 684 685 686 687 688 689 690 691 692 693 694 695 696 697 698 699 700 701 702 703 704 705 706 707 708 709 710 711 712 713 714 715 716 717 718 719 720 721 722 723 724 725 726 727 728 729 730 731 732 733 734 735 736 737 738 739 740 741 742 743 744 745 746 747 748 749 750 751 752 753 754 755 756 757 758 759 760 761 762 763 764 765 766 767 768 769 770 771 772 773 774 775 776 777 778 779 780 781 782 783 784 785 786 787 788 789 790 791 792 793 794 795 796 797 798 799 800 801 802 803 804 805 806 807 808 809 810 811 812 813 814 815 816 817 818 819 820 821 822 823 824 825 826 827 828 829 830 831 832 833 834 835 836 837 838 839 840 841 842 843 844 845 846 847 848 849 850 851 852 853 854 855 856 857 858 859 860 861 862 863 864 865 866 867 868 869 870 871 872 873 874 875 876 877 878 879 880 881 882 883 884 885 886 887 888 889 890 891 892 893 894 895 896 897 898 899 900 901 902 903 904 905 906 907 908 909 910 911 912 913 914 915 916 917 918 919 920 921 922 923 924 925 926 927 928 929 930 931 932 933 934 935 936 937 938 939 940 941 942 943 944 945 946 947 948 949 950 951 952 953 954 955 956 957 958 959 960 961 962 963 964 965 966 967 968 969 970 971 972 973 974 975 976 977 978 979 980 981 982 983 984 985 986 987 988 989 990 991 992 993 994 995 996 997 998 999 1000 1001 1002 1003 1004
//! Actor based asynchronous runtime //! //! # Table of Contents //! 1. [Introduction](#introduction) //! 2. [Perspective features](#perspective-features) //! 3. [Architecture elements](#architecture-elements) //! 4. [Basic operations](#basic-operations) //! 5. [Lifetime hooks](#lifetime-hooks) //! 6. [Stopping actors](#stopping-actors) //! 7. [Actor communications](#actor-communications) //! 8. [ActorRef sharing](#actorref-sharing) //! 9. [More about DeadLetters](#more-about-deadletters) //! 10. [More about dispatchers](#more-about-dispatchers) //! 11. [Timers](#timers) //! 12. [Stash](#stash) //! 13. [Watching](#watching) //! 14. [Ask](#ask) //! 15. [FSM](#fsm) //! 16. [Supervision](#supervision) //! 17. [Remoting](#remoting) //! //! //! # Introduction //! This runtime is realize the classical actor paradigm actively used in the actor based languages, //! such as Erlang and actors framework, such as Akka. To be frank, this module is heavily relies on //! the last and actively use principles and abstractions submitted in this framework. //! //! At this moment, module presents next features: //! * Untyped actors with exchanged the messages derived from Any trait //! * Actor lifetime management //! * DeadLetters //! * TestKit //! * Timers //! * Watching //! * Various dispatchers realizations //! * FSM //! //! # Perspective features: //! Under this features already exists architectural basis, and their implementation is a question //! of my free time. //! //! * Mailboxes with user defined functional //! * Supervising //! * Distributed actor systems //! //! //! # Architecture elements //! //! Before we go to the concrete examples of usage, you mast understand the internal architecture of //! the actors runtime. Without this, you will do not understand many of errors which may cause at //! work with the library and it will be seems for you as bags, but it's doesn't. //! //! Actor runtime contains three big elements: //! * Runtime - contains objects used of actor at execution //! * System - environment of actors representation . Controls actors lifetime (start, stop, and //! etc.). Contains default and other system elements. //! * Actor - objects providing actor execution in the runtime //! //! Runtime consists two object: //! * Mailbox - queue protected from race condition. This is an interface, which presents set of //! some basic methods for work with the internal queue. In this queue drops all messages passed //! to the actor before his actual processing. In the library exists few standard realization of //! this interface: //! //! * UnboundedMailbox - mailbox without any queue size restrictions. This mailbox is used by //! default at the time of actor creation, if other mailbox type, does not specified explicitly. //! //! * Dispatcher - entity which process the messages. Message processing may be planned in it, and //! after that, dispatcher decides himself, how and when run his processing. Message processing is //! the operation, when receive method of actor is called with processed message and prepared //! context. Dispatcher is an interface, and him concrete behavior base on it's implementation. In //! the library exists few standard realization of this interface: //! //! * DefaultDispatcher - dispatcher based on on ThradPinnedDispatcher with thread pinning //! stratagy. This executor contants set of threads, which distributes between actors. He is used //! for main purpose and non blocking tasks, with medium loading for the system. //! * PinnedDispatcher - dispatcher which contain only one thread and service work of only one //! actor. Stops at the same time with serviced actor. Used for situations when actor needs to //! perform some heavy synchronous tasks such as working with a files or using a network. Blocking //! of message processing in this dispatcher have nothing impact to other actors in the system. //! //! Runtime consists five object: //! * Actor - user defined structure implemented with the Actor trait. This object contains //! application logic of program constructed in the actors style. Him has one mandatory function for //! realization (receive) and few optional (preStart, postStop an others). //! * ActorRef - representation of the actor link. This is an interface, through which users code //! may interact with underlayed actor. This interface is an encapsulate of interaction with the //! underlying ActorCell (described below). ActorRef may be cloned as many time as you want, safe //! shared between actors and other thread. This feature ensured by the fact, that all instances of //! the cloned ref, will link to the single protected ActorCell object. //! * ActorCell - system actor representation. Coordinates all interaction with actor from the //! outside. This object contains the current lifetime state of an actor. In him stored mailbox and //! link to the dispatcher, in which will be processed messages from the mailbox. Functional it //! performs, start, stop and suspend actor. Interacts with dispatcher for planning messages //! processing and etc. Need make a comment about the mailbox and dispatcher instances. ActorCell //! has always it's own instance if the mailbox, which will created with the other elements of the //! actor at the creation stage of him. Unique of the dispatcher depends on it's type. Some //! dispatchers has a shared nature. They may be user with few actors at the same time. Others is //! unique for each actor instance. Example of the first type dispatcher is DefaultDispatcher. //! Second is PinnedDispatcher (in developing stage, used in the strategy - os thread per actor). //! * ActorPath - representation of the actor path in the actors system. This object is used for //! comparing actor references, paths printing in the debug messages and other internal needs. //! * ActorContext - actor environment at processing message. This struct conatins message sender //! reference, self actor reference, link to the system on witch actor is executed and other useful //! values and methods. //! //! System consists two object: //! * ActorSystem - object represents the actor system. It used for creating, stopping actors and //! some other service operations performing. //! * Dead Letter - special sort of the mailbox in which all enqueued messages is logged and after //! that destroyed. Never is planned. Used to dispose of undelivered messages for various reasons. //! //! # Basic operations //! //! Now, after we will learn set of the basis framework elements, let's try to write some practical //! code. First, we need some implementation of an actor. Let's create actor to which we may send //! message with some text, and actor will print it. As side-effect, actor will be count of //! printed characters. //! //! ``` //! use crate::actors::prelude::*; //! use std::any::Any; //! use std::sync::{Mutex, Arc}; //! use match_downcast::*; //! //! pub fn props() -> Props { //! Props::new(tsafe!(BasicActor::new())) //! } //! //! pub struct Print { //! pub text: String, //! } //! //! pub struct BasicActor { //! printed_chars: usize //! } //! //! impl BasicActor { //! pub fn new() -> BasicActor { //! BasicActor { //! printed_chars: 0 //! } //! } //! } //! //! impl Actor for BasicActor { //! //! fn receive(self: &mut Self, msg: Message, _ctx: ActorContext) -> HandleResult { //! let msg = msg.get(); //! match_downcast_ref!(msg, { //! m: Print => { //! self.printed_chars = self.printed_chars + m.text.len(); //! println!("{}", m.text); //! }, //! _ => return Ok(false) //! }); //! //! Ok(true) //! } //! } //! ``` //! //! Next we write the code which use this actor: //! //! ``` //! let mut system = LocalActorSystem::new(); //! //! let mut printer = system //! .actor_of(basic_actor::props(), Some("printer")); //! //! let msg = msg!(basic_actor::Print { text: String::from("Hello world!") }); //! printer.tell(msg, None); //! ``` //! //! At first line, we create new actor system. Internally, this operation creates default dispatcher //! and DeadLetter synthetic actor. At next line, we create the early defined actor. actor_of //! functions is receive Pops object as //! first argument, and actor name as second. Actor name is optional, and it may be set to None. //! In this case, name will be generated automatically. Props object is indicates the system, which //! actor to create, and with which params. We will come across this structure more than once as //! the material is presented. For now, we simple creates new actor instance and put it's to the //! Props object. As a result of the actor_off call, we will receive actor link object - ActorRef. //! Internally this call, besides the ActorRef, will create next objects: ActorCell, Mailbox and //! Dispatcher if it was specified and has unique nature. After performs all internal operations, //! library code will call preStart function, which will be described later in this doc. //! //! And at last stage, we may send the Print message to the actor.We create the new Print structure, //! uses for it the msg! macro and then send her to the actor through tell function. The 'msg!' //! macros is creates the special wrapper for messages, which may contain any data type and he may //! be safely shared between threads. Tell function receive message as first //! argument and sender actor reference as second. Last is optional, because if we send message //! outside of the actor system we do not someone whom may be represents as sender. If you perform //! this operation from the actor, you should be set ctx.self_ to this value. But about this we //! say later. When you call tell function, ActorCell get passed message to the mailbox and //! indicates dispatcher schedule this message for processing. //! //! Ok, message in the mailbox, what happens with him further? Next, the dispatcher, when he //! will be ready for it, extract message from the mailbox and message processing stage is starts. //! First, the message is heading to the internal receive function. His task, determine service message //! (such as PoisonPill, witch stops the actor). If it is, it will be processed, some service //! actions will be performed and message will dropped. He will does not reach the receive function //! of the target actor. If this message is not a service message, actor.receive function will be //! called. This function must return a HandleResult value, which indicates fact, was handled message or //! not (or some error occurs). If the message was handled, message processing logic is end, else the message will be dropped //! to the DeadLetter. //! //! Now consider the the function of messages receive of our actor. It have three args. First arg //! is the link to self object which state is fully mutable. Second args is the received message. //! Last arg is the message processing context. Message represents as boxed Any type and may be //! matched be any comfortable way for you. I use for this the crate 'match-downcast' which allows //! keep code clear at downcast operations. From the context, for now, only one object is //! interesting - sender. What does he point to? At DeadLetter, because at tell operation, we was //! specify None as sender reference. //! //! # Lifetime hooks //! Actor has few lifetime hooks which may be used for various operations: //! * pre_start - called after full actor initialization and before allowing reception of //! messages. At this stage already exists actor context, which may be used for creating new actors //! or sending message for himself. Also is available actor's internal state for mutating. //! * post_stop - called after full stop of actor. This means, that all message passed to the actor //! was processed or dropped and it will not receive any new messages further. This is the last //! point of interaction with internal actor's state. At this stage actor context also exists and //! may be user to perform various operations. //! * pre_fail - Called before some supervising operation will be started. Read more about what it //! in the special chapter. //! * post_restart - Called after actor was restarted. This may occurs if some supervision action //! occurs. Read more about what it in the special chapter. //! //! For example let's add this hooks to our basic actor: //! //! ``` //! ... //! //! fn pre_start(self: &mut Self, ctx: ActorContext) { //! println!("BasicActor is started") //! } //! //! fn post_stop(self: &mut Self, ctx: ActorContext) { //! println!("BasicActor is stopped") //! } //! //! ... //! ``` //! //! After you run this modified example, before printing the passed message, in the stdout you will //! see 'BasicActor is started'. postTop will triggered after actor will be stopped. This operation //! we will learn below. //! //! # Stopping actors //! Actor can be stopped in two way: //! * Send PoisonPill - this is a special service message, located in the actor submodule. //! If you send this message to an actor, it will be enqueued as an any regular message. But when //! dispatcher will face with him, he will drop all messages in the mailbox after it, and starts //! actor stopping procedure. //! //! ``` //! bench.tell(msg!(actor::PoisonPill { }), None); //! ``` //! //! * ActorSystem::stop(ActorRef) - this call immediately stops the specified actor. He lead to block mailbox //! of the actor, flush all it's messages and mark him as stopped. If this call happens from a //! message handler, current message will be processed, but all subsequent does not. Internally this //! call does the following. He suspends the actor, clean his mailbox and prepend to it ths single //! PoisonPill message. This will lead to that after processing the current message dispatcher will //! immediately come across a message PoisonPill and stops the actor. Similar situation will be //! happened and if this call occurs outside of actor system. In this case, if target actor is in //! process of some message, it will be processed and after that actor will be stopped. //! //! ``` //! system.stop(bench); //! ``` //! //! # Actor communications //! For consideration of this topic, we need some more complicated example. In the 'example' //! submodule located module named logger. This is more complex program then basic example, but this //! much more real world example of actors usage. Here contains three actors which realize logger, //! in which we may indicate logging target. Log target may be StdOut or File. Logger actor contains //! links to the writers, whom directly realize logging logic to him target. Task of the logger //! actor is receive Log message, determine target writer actor and send Write message to him. //! Writer actor receive this message, performs write and respond to the sender with Ok message. //! Logger actor receive this message, increment internal counter of write chars and print info //! text about this action to console. Below are given 'receive' functions of this actors. //! Surrounding code is redundant for this doc, and you may see him in in the source files. //! //! ``` //!// Logger //!fn receive(self: &mut Self, msg: Message, ctx: ActorContext) -> HandleResult { //! let msg = msg.get(); //! match_downcast_ref!(msg, { //! m: Log => { //! match m.target { //! LogTarget::File => { //! let msg = msg!(file_writer::Write { text: m.text.to_string() }); //! self.file_writer.tell(msg , Some(&ctx.self_)) //! }, //! LogTarget::StdOut => { //! let msg = msg!(stdout_writer::Write { text: m.text.to_string() }); //! self.stdout_writer.tell(msg, Some(&ctx.self_)) //! } //! }; //! }, //! m: file_writer::Ok => { //! println!("File logger write '{}' chars", m.chars_count); //! self.chars_counter = self.chars_counter + m.chars_count; //! }, //! m: stdout_writer::Ok => { //! println!("Stout logger write '{}' chars", m.chars_count); //! self.chars_counter = self.chars_counter + m.chars_count; //! }, //! _ => return Ok(false) //! }); //! //! Ok(true) //!} //! //! //!//StdoutWriter //!fn receive(self: &mut Self, msg: Message, mut ctx: ActorContext) -> HandleResult { //! let msg = msg.get(); //! match_downcast_ref!(msg, { //! m: Write => { //! println!("{}", m.text); //! let resp = msg!(Ok { chars_count: m.text.len() }); //! ctx.sender.tell(resp, Some(&ctx.self_)); //! }, //! _ => return Ok(false) //! }); //! //! Ok(true) //!} //! //! //! //FileWriter //!fn receive(self: &mut Self, msg: Message, mut ctx: ActorContext) -> HandleResult { //! let msg = msg.get(); //! match_downcast_ref!(msg, { //! m: Write => { //! fs::write(&self.file, m.text.as_bytes()); //! let resp = msg!(Ok { chars_count: m.text.len() }); //! ctx.sender.tell(resp, Some(&ctx.self_)); //! }, //! _ => return Ok(false) //! }); //! //! Ok(true) //!} //! ``` //! //! And code which use this actors: //! //! ``` //! let mut system = LocalActorSystem::new(); //! //! let mut logger = { //! let mut system = system; //! let file_writer = system.actor_of(file_writer::props("/tmp/log"), Some("file_writer")); //! let stdout_writer = system.actor_of(stdout_writer::props(), Some("stdout_writer")); //! system.actor_of(logger::props(file_writer, stdout_writer), Some("logger")) //! }; //! //! logger.tell(msg!(logger::Log { text: String::from("To file log"), target: logger::LogTarget::File }), None); //! logger.tell(msg!(logger::Log { text: String::from("To stdout log"), target: logger::LogTarget::StdOut }), None); //! ``` //! //! This code demonstrate two patterns and operation as part of this library: //! * Dependency Injection - at deploying stage of the system, we create two actors (writers) and //! inject it to the logger actor through him constructor (which is hidden by the props function). //! * Context using - demonstrated actor context usage for sending messages to another actor and //! respond to messages. //! //! # ActorRef sharing //! In the previous example we was moved created references to the logging writers to the //! constructor of logger actor. But what about if you want to use this references later in your //! code? For this, ActorRef's may by simply cloned. //! //! ``` //!let (mut logger, mut file_writer, mut stdout_writer) = { //! let mut system = system; //! let file_writer = system.actor_of(file_writer::props("/tmp/log"), Some("file_writer")); //! let stdout_writer = system.actor_of(stdout_writer::props(), Some("stdout_writer")); //! let logger = system.actor_of(logger::props(file_writer.clone(), stdout_writer.clone()), Some("logger")); //! (logger, file_writer, stdout_writer) //! }; //! ``` //! # More about DeadLetters //! In the previous text will be described what is the DeadLetters. Now will be described why it //! exists and how it use. Basic idea of the actors message passing, consists in that all message //! must be delivered to the target actor and consumed. If this is not happens, and message not //! consumed be the receiver, this is an semantic error in the your program. Main task of the //! DeadLetters, is quite aggressive indicates to you, that this error type was occurs in your //! program. For this, DeadLetter log each received by him message to the stdout. //! //! ```text //! DeadLetter receive some message ... from 'ActorRef (/stdout_writer)' to 'ActorRef (/logger)' //! ``` //! //! This feature is unable to disable be the ideological reasons. Because not processed messages is //! an error! In practical, this prints is very useful for actor system debug , when something goes //! wrong and work improperly. 90% of errors in actor-based programs linked to the problem of not //! delivered messages and DeadLetters allows to you fastly determine bags. //! //! Also, you may encounter with situation, when you may want to interact with DeadLetters directly. //! This is may be performed by obtaining the DeadLetter actor reference. This reference stored in //! the ActorSystem and may by cloned from it by the special function: //! //! ``` //! let mut deadLetters = system.dead_letters(); //! ``` //! //! This is a regular actor reference, but all messages passed through it, will be dropped directly //! to the DeadLetter. //! //! # More about dispatchers //! //! Messages dispatch is more complex topic for describe him in one paragraph. Next text //! completes this omission. //! //! ## Specifying the dispatcher via props //! //! You may specify dispatcher for actor by presents her name to the Props object. By default, //! exists two dispatchers type - default and pinned. Default used alwasy as default if you don't //! set another type explicitly. You may specify other dispatcher by calling with_dispatcher //! function. //! //! ``` //! let some_actor = Props::new(tsafe!(SomeActor::new())) //! .with_dispatcher("pinned"); //! ``` //! //! ## Adding new dispatchers //! //! You can add external dispatchers to the actor system through add_ dispatcher method. This method //! receive name of created dispatcher and his object. Should notice that if dispatcher with the //! same name exists, it will be replaced. Old dispatcher will be immediately stoppd and dropped. //! After adding dispatcher, he may be used with Props object through with_dispatcher method. //! Replacing feature, permits you to replace default dispatcher of the actor system. //! //! ``` //! //! // Replace default dispatcher with custom count of threads //! system.add_dispatcher("default", tsafe!(DefaultDispatcher::new(16))); //! //! ``` //! //! ## Implementing custom dispatcher //! You can implement your own dispatcher type with some specific functionality. This is not magic //! action, because actor system dispatcher is a simple struct which implements the two traits - //! Dispatcher and Executor. You may implement this struct and pass it with add_dispatcher method to //! the actor system. This action is contain too many code for describe him in this doc. You may see //! to the example of custom dispatcher implementing in the 'example/actors/custom_dispatcher'. //! //! ## Using dispatchers with futures //! //! Fact that dispatcher implements Executor trait, allows to you use him as execution context of //! AsyncPromise. You can do this in such way: //! //! ``` //! //! ``` //! //! # Timers //! //! Timers is the separate module which is uses for scheduling automatic message sending with a //! specified time-params. Main his purpose is sending messages from an actor to himself for //! determine timeout of various asynchronous operations. Next example demonstrates contrived actor, //! uses this features. Realization details was dropped for more clear understanding of the concept //! ( you may found full code in the examples module ). //! //! ``` //! impl Actor for Ticker { //! //! fn pre_start(self: &mut Self, ctx: ActorContext) { //! let mut timers = RealTimers::new(ctx.system.clone()); //! //! timers.start_single( //! 0, //! &ctx.self_, //! &ctx.self_, //! Duration::from_secs(1), //! msg!(SingleTick {})); //! //! timers.start_periodic( //! 1, //! &ctx.self_, //! &ctx.self_, //! Duration::from_secs(2), //! Box::new(|| msg!(PeriodicTick {}))); //! //! self.timers = Some(tsafe!(timers)); //! } //! //! fn post_stop(&mut self, _ctx: ActorContext) { //! self.timers.cancel_all(); //! } //! //! //! fn receive(self: &mut Self, msg: Message, ctx: ActorContext) -> HandleResult { //! let msg = msg.get(); //! match_downcast_ref!(msg, { //! m: SingleTick => { //! println!("SingleTick"); //! }, //! m: PeriodicTick => { //! if (self.ticks == 3) { //! self.timers.cancel(1); //! println!("PeriodicTick cancelled"); //! } else { //! println!("PeriodicTick"); //! self.ticks = self.ticks + 1; //! } //! }, //! _ => return Ok(false) //! }); //! //! Ok(true) //! } //! } //! ``` //! //! Here in the pre_start hook, creates two timers. All timers has practically identical set of //! arguments. You must specify key, on which timer may be cancelled, sender and receiver refs, time //! parameter and message for sending. First timer is the single timer, it is send message only once //! with one second delay. Message are sent from self to self. As message specified SingleTick //! structure. Second timer is the periodic timer. He will send message to the actor each two //! second, until he will be explicitly cancelled. Message argument contains some trick. It's accept not //! struct itself, but closure which produce this struct. It is due to than for each timer iteration, //! schedulers needs the new message. If you send to this arg a structure, it will be fully consumed at //! first iteration, and timer will does not have what to send. Closure used here as factory of a //! single message. //! //! After all timers was configured, timer object stored in the actor state. Through one second //! after start, the actor will receive the SingleTick message. After two, the actor will start //! receive the periodic message - PeriodicTick. After receive three such messages, it will cancel //! this timer specify the timer key in the cancel method. //! //! In post_stop hook, all timers must be canceled. If this is don't do, you risk encounter with //! situation, when timer will send message to dead actor and it will be dropped to DeadLetters. //! This situation may be more dangerous, if intervals timers exists. If don't cancel it after actor //! was stopped, memory leaks occurs, because actor doesn't may be dropped because of him. //! //! # Stash //! //! If an actor have several lines of behavior, exists one serious problem. What to do with messages //! not from current behavior? For this situation, exists special pattern named stashing. He //! expressed as simple struct which works as user side mailbox. You can put messages into it and when //! need you may initiate resend of stored messages. Normally stash created in pre_start hook: //! //! ``` //! self.stash = RealStash::new(&ctx); //! ``` //! //! And after that you can use it: //! //! ``` //! self.stash.stash(&msg, &ctx); //! //! // In other message handler ... //! //! self.stash.unstash_all(); //! ``` //! Need to pay strongly attention, that stash stores 'self' actor reference. This fact points to //! that you must always explicitly stop all stashes. If you don't do this, actor will does not be //! dropped, because ring dependency will be exist between stash and actor. You can destroy stash //! for example in the post_stop method: //! //! ``` //! self.stash.stop(); //! ``` //! # Watching //! //! Each actor have special set of internal events. When event from this set occurs, it's passed //! to the internal event bus. Watching allows one actor to subscribe to another actor's events. //! Most significant usege of this technique is tracking of terminating of watched actors. You may //! subscribe actor for events of another actor in the following way: //! //! ``` //! ctx.system().watch(&ctx.self_, &self.target); //! ``` //! //! First argument of the watch function is the reference to actor which will be subscribed for //! events of the actor specified in the second argument. After that subscriber, will be receive //! special messages always when some events occurs with the target actor. For now exists next event //! types: //! //! * Terminated - occurs when watched actor is fully stopped (event occurs right after post_stop //! hook was called). //! //! Actor may unsubscribes from actor events in similar way, using function unwatch: //! //! ``` //! ctx.system().unwatch(&ctx.self_, &self.target); //! ``` //! //! Caution about unwatching. You must always explicitly call unwatch method, before actor (which is //! watch to another actors) will be stopped. This is non critical, but if you don't do it, this //! cause to full walk of event bus tree for search and remove stopped actor from subscribers of //! events. It may be extremely expensive operation if on the event bus exists many observed actors. //! //! You may see full example usage of watching in the 'examples/actors/watch' submodule. //! //! # Ask //! //! Ask call doing the same thing that tell call, but expects, that target actor respond back with //! some message. This expectation represents as Future, which will be completed with received //! message or with AskTimeoutError if target actor does not respond with some timeout. This //! operation may be used in three way: //! //! * Interact with actor system from synchronous world. The essence of this patterns consists in //! that you Ask target, and block your thread on the Future, which returned be the function. This //! operation will permits to you interact with actors as if they would be a some synchronous //! function. This operation must be never used from the actor system, because it will cause to block //! of the dispatcher, that will very fast leads to dead lock of the entire system. //! //! ``` //! let req = actor.ask(&mut (system), msg!(SomeRequest {})); //! let result = req.result(Duration::from_secs(5)); //! //! // Do some actions with received message or handle error //! ``` //! * Connection of actor's world with future's world. This situation is very often occurs in the //! web development. Most count of modern server libraries, more or less supports future paradigm. //! This features consists in than when server receives a request, you do not process him in the //! handler but pass this work to the future. With Ask pattern you may represents interaction //! with actor system through such future. Basic example of this interactions may be expressed //! in this way: //! //! ``` //! actor.ask(&mut (system), msg!(SomeRequest {})) //! .map(|v| { //! // Do some with received message //! }) //! .recover(|e| { //! // Do some with timeout error //! }); //! ``` //! * Intercommunication layer between actors without mutation of state . Imagine the next station. //! You have three actors A, B and C. A requests B for some data. But B for respond to A, need //! firstly request C and based on him response, he may create response for A. Without futures this //! may be realized only as state machine. After receives request from A, B sends request to C and //! change it's behavior for handle responses from C. When response from C will be received, //! B create response to A, send him, and switch her behavior to the normal. Details about what do //! with messages addressed to B when it's not in the normal state is omitted. If in this situation //! state of actor B does not mutates, state machine may be converted to actor with linear behavior, //! which uses for this operation futures. Such code Ask actor C and does not wait anything, all //! logic now live in the future combinators, which will be processed fully separate from the actor B. //! Situation of this sort, often have a place to be in DDD paradigm in parts of CQRS interactions //! logic. For example you ask to root aggregate for get some view object of some entity, he will //! calls read side of entity, read side in turn asks repository. Repository return raw view object //! to the read side. Read side transforms this object to the natural view object, and root //! aggregate removes some system fields from it and returns it to the requester. All stages in this //! chain is immutable for state of the participants. And all this operation may be performed with //! futures. On practice it may work follows: //! //! ``` //! fn receive(&mut self, msg: Message, mut ctx: ActorContext) -> HandlerResult { //! let msg = msg.get(); //! match_downcast_ref!(msg, { //! m: commands::RequestFromA => { //! let inter_data = m.data + 100; //! //! let mut sender = ctx.sender.clone(); //! let mut self_ = ctx.self_.clone(); //! //! self.c_actor.ask(&mut (*ctx.system()), msg!(RequestFromB { data: inter_data }) ) //! .on_complete(move |v| { //! if v.is_ok() { //! let resp = v.as_ref().ok().unwrap(); //! let resp = resp.get(); //! if let Some(m) = resp.downcast_ref::<ResponseFromC>() { //! let inter = m.data; //! sender.tell(msg!(ResponseFromB {data: inter }), Some(&self_)); //! } //! } else { //! println!("Oops! C does not respond!") //! } //! }); //! }, //! _ => return Ok(false) //! }); //! //! Ok(true) //! } //! ``` //! //! You may see full example of Ask usage in the 'examples/actors/ask' submodule. //! //! # FSM //! //! FSM is transcripted as Finite State Machine. This conceptions is very powerful used with //! actors, because permits you to create fully asynchronous state machines with full control //! around them behavior. //! //! Actor may be presented as FSM if it her logic satisfies few things: //! * He uses few lines of behavior with various data //! * Some behaviours needs a timeouts //! * Lifetime of an actor is finite (this is partial demand, because may exist fsm with lifetime //! equals to lifetime of entire program). //! //! All this aspects may be realized with conditional operators and timers, but in this case, your //! code will be is very dirty. For eliminate this difficulties, in the library exists special //! module, which contains abstraction layer for creating of FSM. //! //! ### State and Data //! //! State is the main executable unit of any FSM. Each state accompanied by a some Data. In any //! piece of time, FSM always be in one of some State and have one of some Data. States and Data //! on the language level describes as enum. Separate State handlers describes as function with the next //! signature: //! //! ``` //! pub fn state0(&mut self, msg: &Message, ctx: &ActorContext, data: &Data) -> StateResult<Self, State, Data> { //! //Make a some actions with a message based on a presented Data //! } //! ``` //! You may perceive this handler as special variant of the standard receive function of actor. //! There you may do similar actions as in the receive functions, buf instead HandleResult, you //! must return StateResult. Last type is the alias for the very complex type, so for prevent you from //! creating a trash code, library presents few functions for produce this result. This result //! indicates to the upper library code, what to do next - switch state or data, stop actor or //! some other things. //! //! * Fsm::goto(state) - indicates to change current state to some other. //! * Fsm::goto_using(state, data) - indicates to change current state and data to some others //! * Fsm::stay() - indicates to stay in current state and with current data //! * Fsm::stay_using(data) - indicates to stay in current state but with some other data //! * Fsm::stop() - indicates that work of FSM is completed (stops the actor) //! * Fsm::unhandled() - indicates that current message was doest not be handled (unknown type //! of message or some other reasons) //! //! Each state handlers must be explicitly registered in the fsm object: //! //! ``` //! fsm.register_handler(State::StateA, Self::state_a, Duration::from_secs(5)); //! ``` //! //! In this call you must specify the state on which attached handler, handler function and state //! timeout. //! //! ### States timeouts //! //! Each separate state have it's own idle timeout. If fsm will does not receive any messages in //! this timeout, library automatically send special message SendTimeout, which will be indicates //! to the user code, that state timeout was reached. What to do next in this situation is youre //! decision. //! //! ### Unhandled messages //! //! You may register special handler of unhandled messages. This function will be called always, //! when some state completes with Fsm::unhandled(). Handler is useful when you need detect //! unhandled message in state independent manner. Handler presented as next function: //! //! ``` //! fn unhandled(&mut self, msg: &Message, ctx: &ActorContext, state: &State, data: &Data) -> HandleResult //! ``` //! //! Signature is analogous for default receive function of an actor, but contains additional //! information about state and data, under which fsm was missed a message. Handler may be //! registered through this method: //! //! ``` //! fsm.register_unhandled(Self::unhandled); //! ``` //! //! ### State transitions //! //! You may execute some code in the moment when fsm will be change status. Handler of this //! situation have the next view: //! //! ``` //! fn transition(&mut self, from: &State, to: &State) //! ``` //! //! He contains in arguments link to the state from which fsm passes and a link to the state to //! which fsm goes. This handler may be registered with the next call: //! //! ``` //! fsm.register_transition(Self::transition); //! ``` //! //! ### Full example //! //! You can see the full example of how to use fsm in 'examples/actor/fsm' //! //! ### When you need to use FSM and when Futures? //! //! When you start a real world work with fsm, you may encounter with the strange question - why //! I need to use the fsm, if i may instead I use combined futures? I suffered from this issue //! many cont of times, but in the end, I was create some conception of when user fsm and when use //! futures. Here she is. //! //! Future - used when operation contains only lenear logic, less than three stage and it does not //! need information about states. Example - you need checks user permissions and based on this //! check, to request data from repository or not. All simple, two stage, no data between them and //! no branching. //! //! Fsm - used when operation shares data between states or she contains more than three stages or //! operation logic is non linear. Example. At first stage you request of authorisation data from the //! local caсhe. If he contains data about user, you go to stage three. If not, you start stage two - //! checking user permissions on a remote server. At stage thee you have user permissions check //! result. If it is privileged user, you requests to repository for getting version of data for //! privileged user. If not, you requests to repository for getting version of data for non-privileged //! user. At stage four, based on this data from the repository, you respond to the originator with //! some final result. Four stages, shared data between them and several scenarios. //! //! # Supervision //! //! All actors in the system grouped to tree, in which each actor have one parent and zero or more //! children's. Supervision in the actor system relies on the two simple ideas. First idea consists //! is that lifetime of all child actors directly depends on lifetime of his parents. Second idea //! is that actor may be failed when process some message, and after that, system will take some //! actions for restore broken actor from this situation. //! //! ### Hierarchy //! //! As was said before, each actor have one parent and may have childs. At the top of all hierarchy //! placed Root Guardian - synthetic actor whose only task is to be parents for all actors which will //! be created through system.actor_of method. You may create an actor through another way: //! //! ``` //! ctx.actor_of(some_actor::props(), Some("name")); //! ``` //! //! In this code as ActorRef provider ActorContext is used. Actor from called this action, becomes //! as parent for created actor and his lifetime is fully depended on lifetime of his parent. How it //! work on practice. For example you have the next actors hierarchy - /root/A/B/C. If you will stop //! the A actor, it will cause to recursive stopping of actors B and C. What about root? Yes, he also //! may be stopped. This action occurs when you call system.terminate method. Before the handler will //! stops the dispatchers, he will stop the Root Guardian, what cause to stops of all actors in the //! hierarchy. //! //! ### actor_select //! //! Hierarchy of actors gives us some useful feature. You may obtain ActorRef's of actors placed //! in some leaf of the tree if you know them path. //! //! ``` //! let selection = system.actor_select("/root/a/b"); //! let b_ref = &mut selection[0]; //! ``` //! //! Call of acotor_select return the vector with found ActorRef's. This is the regular refs which will //! may be used as refs created through actor_of call. //! //! Need make a note, that actor_of is the some cost operation, because with searching of actor, //! code goes through all hierarchy of cells, what cause to locks. Based on that, what then //! deeper the target actor, than more expensive the search. //! //! ### Error recovery //! //! Message handler may completes with some error: //! //! ``` //! fn receive(self: &mut Self, msg: Message, _ctx: ActorContext) -> HandleResult { //! let msg = msg.get(); //! match_downcast_ref!(msg, { //! m: HelloToC => { //! println!("Hello to some from the outside world!") //! }, //! m: FailMe => { //! println!("CActor receive FailMe"); //! return Err(err!("some err")) //! }, //! _ => return Ok(false) //! }); //! //! Ok(true) //! } //! ``` //! //! This situation treated be system as signal that processed actor was faced with an insoluble //! error, and system must take some actions. This actions is called supervision operation and //! determined with supervision strategy. Exist four strategies: //! //! * Resume - do nothing, ignore occurred error //! * Stop - stop the actor //! * Restart - restart the actor (stop and start) //! * Escalate - lift this error to the parent of the actor //! //! All created actors has Restart strategy by default. Root Guardian and DeadLetters has Resume //! strategy. Strategy of a separate actor may be set up through Props object: //! //! ``` //! let props = Props::new(tsafe!(SomeActor::new())) //! .with_supervision_strategy(SupervisionStrategy::Escalate) //! ``` //! //! Before starts of the supervision operation, pre_fail hook of the failed actor will be called. //! This hook contains the actor context, occurred error and current supervision strategy. //! //! # Remoting //! //! Remoting is the feature which concludes in opportunity of interaction between two actor systems //! through network. This systems may be placed in one application, in separate applications on one //! or different physical machines. For now, realized the next interaction features: //! //! * actor_select of actors on a remote actor system //! * message sending between actor systems //! //! Remoting is concluded in few concepts, described below. //! //! ## RemoteActorRef //! //! When you work with ordinary actor system, you will always interact with LocalActorRef. This //! type of refs works with internal actor representation in the system (actor cell). Whenever //! you will work with some type of remote systems, together with LocalActorRef you will be //! interact with RemoteActorRef. RemoteActorRef instead of linked to cell, referenced //! to network connection in the system network controller. Practical work with this type of //! refs, no different from work with LocalActorRef, excluding some moments. You may read about //! them in the Delivery Guarantee paragraph. //! //! ## NetworkActorSystem //! //! This is a complete of LocalActorSystem clone with one small exception - she have controller //! of network connections which allow for other actor systems establish connection with her //! through network. Constructor of the system, receives the two additional arguments - bind //! address and link to a messages serializer. Bind address is a string which may be converted //! to the SocketAddr object. About a messages serializer you may read below. //! //! ## RemoteActorSystem //! //! This is the thin wrapper over network controller which allows you to interact with a remote //! actor system. You may think about her as domain oriented socket. She contains the same methods //! like her big sisters (Network/Test/LocalActorSystem), but actions which do this methods will be //! addressed to a remote system behind network connection. Constructor of this type of system //! receives three additional arguments - connection address of a remote system, messages //! serializer and host actor system. This system is always relies on a big actor system - local, //! remote or test actor system. //! //! ## MessageSerializer //! //! Since Rust, unlike platforms such as JVM, does not contain developed means of language //! reflection, you should explain to the library how to convert various messages into a //! byte representation and back. For this target, library present the special trait - //! MessageSerializer. Before moving on to further descriptions, should make the following //! remark. Library does not determine how you will be serialize finite message. You may use //! any type of serialization which will you like (json, protobuf, you own and etc). //! MessageSerializer is the trait with two mandatory methods - to_binary and from_binary. //! First method is receives a Message and must return result with SerializationResult //! or SerializationError struct. SerializationResult have two fields - marker and blob. Field //! 'marker' is an unique number which can uniquely indicate this type of message. Field 'blob' //! must contain binary representation of an original message. How you transform original message //! to binary array is your choice. SerializationError represents set of the standard failure //! situations, which may be occurs at this operation. //! //! The method from_binary is a mirror for the to_binary method. He receives marker number and //! blob and must return result with the Message or SerializationResult struct. //! //! ## Delivery guaranty //! //! When you work with local system, exists guarantee that a message passed to an actor will //! reach the recipient (of course if he was not accidentally stopped ). When working with remote //! system, this rule is does not work. It doesn't work, because many of thing may goes wrong - //! connection may be lost, may occurs routing error, low quality level of transmission on physical //! level and many other bad things. In other words, passed message may does not reach the target //! and you should always keep this in mind. You must constructs remote services in the way that //! requests always have a reply message, which allows for you fixed the fact that message was //! really delivered to the target. //! //! Also need pay attention to that fact, that actor behind RemoteActorRef may be stopped, and you //! never know about it if you doesn't explicitly watch him. //! //! ## Blocking operations //! //! All method calls on RemoteActorRef and RemoteActorSystem have blocking IO //! operation nature. In other words, this calls may lock dispatcher thread if you will be call's //! them directly from an actor messages handler. As a consequence of this, exist only three places //! where you may invoke them safely - outside of the actor system space, in async future and in //! actor with pinned dispatcher. //! //! ## Practical usage //! //! How this technique may be used in practice you may see in 'examples/actor/remote'. First see to //! the mod.rs for to understand how this example is work. //! #[macro_use] pub mod message; #[macro_use] pub mod error; pub mod prelude; pub mod dispatcher; pub mod default_dispatcher; pub mod pinned_dispatcher; pub mod actor_cell; pub mod envelope; pub mod mailbox; pub mod unbound_mailbox; pub mod actor; pub mod local_actor_system; pub mod abstract_actor_ref; pub mod props; pub mod actor_path; pub mod actor_context; pub mod dead_letters; pub mod synthetic_actor; pub mod actor_ref_factory; pub mod abstract_actor_system; pub mod local_actor_ref; pub mod scheduler; pub mod timers; pub mod watcher; pub mod ask_actor; pub mod wrapped_dispatcher; pub mod stash; pub mod fsm; pub mod supervision; pub mod remoting;