Implements a thread safe "mail" delivery system. More...
#include <mailbox.h>
Public Types | |
| enum | apply_outcomes { OKAY = basis::common::OKAY , DEFINE_OUTCOME =(APPLY_STOP, -46, "Halt the apply process") , DEFINE_OUTCOME =(APPLY_STOP, -46, "Halt the apply process") , DEFINE_OUTCOME =(APPLY_STOP, -46, "Halt the apply process") } |
| typedef basis::outcome | apply_function(letter ¤t, int uid, void *data_link) |
| the "apply_function" is what a user of apply() must provide. More... | |
Public Member Functions | |
| mailbox () | |
| virtual | ~mailbox () |
| void | drop_off (const structures::unique_int &id, letter *package) |
| drops a "package" in the mailbox for "id". More... | |
| bool | pick_up (const structures::unique_int &id, letter *&package) |
| returns true if the mailbox for "id" had a "package" to be delivered. More... | |
| int | waiting (const structures::unique_int &id) const |
| returns the number of items waiting for the "id" specified, if any. More... | |
| void | get_ids (structures::int_set &to_fill) |
| stuffs the set "to_fill" with the ids of all mailboxes present. More... | |
| bool | close_out (const structures::unique_int &id) |
| dumps all packages stored for the "id" and shuts down its mailbox. More... | |
| void | show (basis::astring &to_fill) |
| provides a picture of what's waiting in the mailbox. More... | |
| void | clean_up () |
| removes any empty mailboxes from our list. More... | |
| void | limit_boxes (int max_letters) |
| establishes a limit on the number of letters. More... | |
| void | apply (apply_function *to_apply, void *data_link) |
| calls the "to_apply" function on possibly every letter in the mailbox. More... | |
Detailed Description
Implements a thread safe "mail" delivery system.
Senders can drop packages off into the mailbox and the receivers can get those packages back out of it. The base class for all mail items is also provided in this library (letter.h). The name of this object is slightly misleading; this object is really more of a post office. Each unique id has its own mailbox slot for receiving mail.
Member Typedef Documentation
◆ apply_function
| typedef basis::outcome processes::mailbox::apply_function(letter ¤t, int uid, void *data_link) |
the "apply_function" is what a user of apply() must provide.
the function will be called on every letter in the mailbox unless one of the invocations returns APPLY_STOP or APPLY_WHACK_STOP; this causes the apply process to stop (and zap the node for APPLY_WHACK). the "uid" is the target for the "current" letter. the "data_link" provides a way for the function to refer back to a parent class or data package of some sort. note that all sorts of deadlocks will occur if your apply function tries to do anything on the mailbox, even transitively. keep those functions as simple as possible.
Member Enumeration Documentation
◆ apply_outcomes
Constructor & Destructor Documentation
◆ mailbox()
| processes::mailbox::mailbox | ( | ) |
Definition at line 148 of file mailbox.cpp.
◆ ~mailbox()
|
virtual |
Definition at line 154 of file mailbox.cpp.
References basis::WHACK().
Member Function Documentation
◆ apply()
| void processes::mailbox::apply | ( | apply_function * | to_apply, |
| void * | data_link | ||
| ) |
calls the "to_apply" function on possibly every letter in the mailbox.
this iterates until the function returns a 'STOP' outcome. the "data_link" pointer is passed to the apply function. NOTE: it is NOT safe to rearrange or manipulate the mailbox in any way from your "to_apply" function; the only changes allowed are those caused by the return value from "to_apply".
Definition at line 237 of file mailbox.cpp.
References structures::set< contents >::elements().
◆ clean_up()
| void processes::mailbox::clean_up | ( | ) |
removes any empty mailboxes from our list.
Definition at line 172 of file mailbox.cpp.
Referenced by processes::post_office::deliver_mail_on_route().
◆ close_out()
| bool processes::mailbox::close_out | ( | const structures::unique_int & | id | ) |
dumps all packages stored for the "id" and shuts down its mailbox.
the destructors for those packages should never try to do anything with the mailbox system or a deadlock could result. true is returned if the "id" had a registered mailbox; false just indicates there was no box to clear up.
Definition at line 196 of file mailbox.cpp.
◆ drop_off()
| void processes::mailbox::drop_off | ( | const structures::unique_int & | id, |
| letter * | package | ||
| ) |
drops a "package" in the mailbox for "id".
note that when you send a package to someone, you give up all authority and control over that package. hopefully the end recipient will eventually pick it up and then delete it. if the package is never received, then this object will delete it.
Definition at line 166 of file mailbox.cpp.
Referenced by processes::post_office::drop_off().
◆ get_ids()
| void processes::mailbox::get_ids | ( | structures::int_set & | to_fill | ) |
stuffs the set "to_fill" with the ids of all mailboxes present.
if you want only those mailboxes holding one or more letters, then call the clean_up() method prior to this method.
Definition at line 160 of file mailbox.cpp.
◆ limit_boxes()
| void processes::mailbox::limit_boxes | ( | int | max_letters | ) |
establishes a limit on the number of letters.
this is a helper function for a very special mailbox; it has a limited maximum size and any letters above the "max_letters" count will be deleted. don't use this function on any mailbox where all letters are important; your mailbox must have a notion of unreliability before this would ever be appropriate.
Definition at line 223 of file mailbox.cpp.
References structures::set< contents >::elements().
◆ pick_up()
| bool processes::mailbox::pick_up | ( | const structures::unique_int & | id, |
| letter *& | package | ||
| ) |
returns true if the mailbox for "id" had a "package" to be delivered.
don't forget to check multiple times on a true outcome, since there could be more than one package waiting. false is returned when no more mail is waiting. be careful; "package" could be a bomb. dynamic casts seem appropriate as a method for ensuring that you get the type of object you expect. note that once the invoker receives a package, it is their responsibility to carefully manage it and then delete the package after handling. not deleting the "package" pointer is grounds for memory leaks.
Definition at line 189 of file mailbox.cpp.
Referenced by processes::post_office::deliver_mail_on_route(), and processes::post_office::pick_up().
◆ show()
| void processes::mailbox::show | ( | basis::astring & | to_fill | ) |
provides a picture of what's waiting in the mailbox.
this relies on the derived letter's required text_form() function.
Definition at line 203 of file mailbox.cpp.
References structures::set< contents >::elements(), and processes::letter::text_form().
Referenced by processes::post_office::show_mail().
◆ waiting()
| int processes::mailbox::waiting | ( | const structures::unique_int & | id | ) | const |
returns the number of items waiting for the "id" specified, if any.
Definition at line 178 of file mailbox.cpp.
The documentation for this class was generated from the following files:
- /opt/feistymeow.org/feisty_meow/nucleus/library/processes/mailbox.h
- /opt/feistymeow.org/feisty_meow/nucleus/library/processes/mailbox.cpp
