ReactOS 0.4.16-dev-297-gc569aee
Collaboration diagram for Mailboxes:

Functions

err_t sys_mbox_new (sys_mbox_t *mbox, int size)
 
void sys_mbox_post (sys_mbox_t *mbox, void *msg)
 
err_t sys_mbox_trypost (sys_mbox_t *mbox, void *msg)
 
err_t sys_mbox_trypost_fromisr (sys_mbox_t *mbox, void *msg)
 
u32_t sys_arch_mbox_fetch (sys_mbox_t *mbox, void **msg, u32_t timeout)
 
u32_t sys_arch_mbox_tryfetch (sys_mbox_t *mbox, void **msg)
 
void sys_mbox_free (sys_mbox_t *mbox)
 
int sys_mbox_valid (sys_mbox_t *mbox)
 
void sys_mbox_set_invalid (sys_mbox_t *mbox)
 

Detailed Description

Mailboxes should be implemented as a queue which allows multiple messages to be posted (implementing as a rendez-vous point where only one message can be posted at a time can have a highly negative impact on performance). A message in a mailbox is just a pointer, nothing more.

Function Documentation

◆ sys_arch_mbox_fetch()

u32_t sys_arch_mbox_fetch ( sys_mbox_t mbox,
void **  msg,
u32_t  timeout 
)

Blocks the thread until a message arrives in the mailbox, but does not block the thread longer than "timeout" milliseconds (similar to the sys_arch_sem_wait() function). If "timeout" is 0, the thread should be blocked until a message arrives. The "msg" argument is a result parameter that is set by the function (i.e., by doing "*msg = ptr"). The "msg" parameter maybe NULL to indicate that the message should be dropped. The return values are the same as for the sys_arch_sem_wait() function: SYS_ARCH_TIMEOUT if there was a timeout, any other value if a messages is received.

Note that a function with a similar name, sys_mbox_fetch(), is implemented by lwIP.

Parameters
mboxmbox to get a message from
msgpointer where the message is stored
timeoutmaximum time (in milliseconds) to wait for a message (0 = wait forever)
Returns
SYS_ARCH_TIMEOUT on timeout, any other value if a message has been received

Definition at line 177 of file sys_arch.c.

178{
179 LARGE_INTEGER LargeTimeout, PreWaitTime, PostWaitTime;
180 UINT64 TimeDiff;
183 PLWIP_MESSAGE_CONTAINER Container;
186 PVOID WaitObjects[] = {&mbox->Event, &TerminationEvent};
187
188 LargeTimeout.QuadPart = Int32x32To64(timeout, -10000);
189
190 KeQuerySystemTime(&PreWaitTime);
191
193 WaitObjects,
194 WaitAny,
195 Executive,
197 FALSE,
198 timeout != 0 ? &LargeTimeout : NULL,
199 NULL);
200
201 if (Status == STATUS_WAIT_0)
202 {
204 Entry = RemoveHeadList(&mbox->ListHead);
205 ASSERT(Entry);
206 if (IsListEmpty(&mbox->ListHead))
207 KeClearEvent(&mbox->Event);
209
210 Container = CONTAINING_RECORD(Entry, LWIP_MESSAGE_CONTAINER, ListEntry);
211 Message = Container->Message;
212 ExFreePool(Container);
213
214 if (msg)
215 *msg = Message;
216
217 KeQuerySystemTime(&PostWaitTime);
218 TimeDiff = PostWaitTime.QuadPart - PreWaitTime.QuadPart;
219 TimeDiff /= 10000;
220
221 return TimeDiff;
222 }
223 else if (Status == STATUS_WAIT_1)
224 {
225 /* DON'T remove ourselves from the thread list! */
227
228 /* We should never get here! */
229 ASSERT(FALSE);
230
231 return 0;
232 }
233
234 return SYS_ARCH_TIMEOUT;
235}
unsigned long long UINT64
#define msg(x)
Definition: auth_time.c:54
LONG NTSTATUS
Definition: precomp.h:26
#define NULL
Definition: types.h:112
#define FALSE
Definition: types.h:117
static const WCHAR Message[]
Definition: register.c:74
#define IsListEmpty(ListHead)
Definition: env_spec_w32.h:954
UCHAR KIRQL
Definition: env_spec_w32.h:591
#define KeReleaseSpinLock(sl, irql)
Definition: env_spec_w32.h:627
#define KeAcquireSpinLock(sl, irql)
Definition: env_spec_w32.h:609
#define KeQuerySystemTime(t)
Definition: env_spec_w32.h:570
#define ExFreePool(addr)
Definition: env_spec_w32.h:352
#define RemoveHeadList(ListHead)
Definition: env_spec_w32.h:964
VOID NTAPI KeClearEvent(IN PKEVENT Event)
Definition: eventobj.c:22
Status
Definition: gdiplustypes.h:25
KEVENT TerminationEvent
Definition: sys_arch.c:9
#define ASSERT(a)
Definition: mode.c:44
#define KernelMode
Definition: asm.h:34
#define Int32x32To64(a, b)
@ WaitAny
NTSTATUS NTAPI KeWaitForMultipleObjects(IN ULONG Count, IN PVOID Object[], IN WAIT_TYPE WaitType, IN KWAIT_REASON WaitReason, IN KPROCESSOR_MODE WaitMode, IN BOOLEAN Alertable, IN PLARGE_INTEGER Timeout OPTIONAL, OUT PKWAIT_BLOCK WaitBlockArray OPTIONAL)
Definition: wait.c:586
NTSTATUS NTAPI PsTerminateSystemThread(IN NTSTATUS ExitStatus)
Definition: kill.c:1145
#define STATUS_WAIT_0
Definition: ntstatus.h:237
#define STATUS_WAIT_1
Definition: ntstatus.h:71
#define STATUS_SUCCESS
Definition: shellext.h:65
base of all file and directory entries
Definition: entries.h:83
Definition: typedefs.h:120
KSPIN_LOCK Lock
Definition: sys_arch.h:12
KEVENT Event
Definition: sys_arch.h:14
LIST_ENTRY ListHead
Definition: sys_arch.h:13
Definition: dhcpd.h:245
#define SYS_ARCH_TIMEOUT
Definition: sys.h:87
#define CONTAINING_RECORD(address, type, field)
Definition: typedefs.h:260
LONGLONG QuadPart
Definition: typedefs.h:114
_Requires_lock_held_ Interrupt _Releases_lock_ Interrupt _In_ _IRQL_restores_ KIRQL OldIrql
Definition: kefuncs.h:778
@ Executive
Definition: ketypes.h:415

Referenced by sys_arch_mbox_tryfetch().

◆ sys_arch_mbox_tryfetch()

u32_t sys_arch_mbox_tryfetch ( sys_mbox_t mbox,
void **  msg 
)

This is similar to sys_arch_mbox_fetch, however if a message is not present in the mailbox, it immediately returns with the code SYS_MBOX_EMPTY. On success 0 is returned. To allow for efficient implementations, this can be defined as a function-like macro in sys_arch.h instead of a normal function. For example, a naive implementation could be: #define sys_arch_mbox_tryfetch(mbox,msg) sys_arch_mbox_fetch(mbox,msg,1) although this would introduce unnecessary delays.

Parameters
mboxmbox to get a message from
msgpointer where the message is stored
Returns
0 (milliseconds) if a message has been received or SYS_MBOX_EMPTY if the mailbox is empty

Definition at line 238 of file sys_arch.c.

239{
241 return 0;
242 else
243 return SYS_MBOX_EMPTY;
244}
u32_t sys_arch_mbox_fetch(sys_mbox_t *mbox, void **msg, u32_t timeout)
Definition: sys_arch.c:177
#define SYS_MBOX_EMPTY
Definition: sys.h:92

Referenced by sys_arch_mbox_fetch().

◆ sys_mbox_free()

void sys_mbox_free ( sys_mbox_t mbox)

Deallocates a mailbox. If there are messages still present in the mailbox when the mailbox is deallocated, it is an indication of a programming error in lwIP and the developer should be notified.

Parameters
mboxmbox to delete

Definition at line 152 of file sys_arch.c.

153{
154 ASSERT(IsListEmpty(&mbox->ListHead));
155
157}
void sys_mbox_set_invalid(sys_mbox_t *mbox)
Definition: sys_arch.c:146

◆ sys_mbox_new()

err_t sys_mbox_new ( sys_mbox_t mbox,
int  size 
)

Creates an empty mailbox for maximum "size" elements. Elements stored in mailboxes are pointers. You have to define macros "_MBOX_SIZE" in your lwipopts.h, or ignore this parameter in your implementation and use a default size. If the mailbox has been created, ERR_OK should be returned. Returning any other error will provide a hint what went wrong, but except for assertions, no real error handling is implemented.

Parameters
mboxpointer to the mbox to create
size(minimum) number of messages in this mbox
Returns
ERR_OK if successful, another err_t otherwise

Definition at line 128 of file sys_arch.c.

129{
131
133
135
136 mbox->Valid = 1;
137
138 return ERR_OK;
139}
#define KeInitializeEvent(pEvt, foo, foo2)
Definition: env_spec_w32.h:477
#define InitializeListHead(ListHead)
Definition: env_spec_w32.h:944
#define KeInitializeSpinLock(sl)
Definition: env_spec_w32.h:604
@ ERR_OK
Definition: err.h:55
@ NotificationEvent
int Valid
Definition: sys_arch.h:15

Referenced by tcpip_init().

◆ sys_mbox_post()

void sys_mbox_post ( sys_mbox_t mbox,
void msg 
)

Post a message to an mbox - may not fail -> blocks if full, only to be used from tasks NOT from ISR!

Parameters
mboxmbox to posts the message
msgmessage to post (ATTENTION: can be NULL)

Definition at line 160 of file sys_arch.c.

161{
162 PLWIP_MESSAGE_CONTAINER Container;
163
164 Container = ExAllocatePool(NonPagedPool, sizeof(*Container));
165 ASSERT(Container);
166
167 Container->Message = msg;
168
170 &Container->ListEntry,
171 &mbox->Lock);
172
174}
#define KeSetEvent(pEvt, foo, foo2)
Definition: env_spec_w32.h:476
#define NonPagedPool
Definition: env_spec_w32.h:307
#define ExAllocatePool(type, size)
Definition: fbtusb.h:44
PLIST_ENTRY NTAPI ExInterlockedInsertTailList(IN OUT PLIST_ENTRY ListHead, IN OUT PLIST_ENTRY ListEntry, IN OUT PKSPIN_LOCK Lock)
Definition: interlocked.c:140
LIST_ENTRY ListEntry
Definition: sys_arch.h:25
#define IO_NO_INCREMENT
Definition: iotypes.h:598

Referenced by sys_mbox_trypost(), tcpip_api_call(), tcpip_callback(), tcpip_callback_wait(), and tcpip_send_msg_wait_sem().

◆ sys_mbox_set_invalid()

void sys_mbox_set_invalid ( sys_mbox_t mbox)

Invalidate a mailbox so that sys_mbox_valid() returns 0. ATTENTION: This does NOT mean that the mailbox shall be deallocated: sys_mbox_free() is always called before calling this function! This may also be a define, in which case the function is not prototyped.

Definition at line 146 of file sys_arch.c.

147{
148 mbox->Valid = 0;
149}

Referenced by sys_mbox_free().

◆ sys_mbox_trypost()

err_t sys_mbox_trypost ( sys_mbox_t mbox,
void msg 
)

Try to post a message to an mbox - may fail if full. Can be used from ISR (if the sys arch layer allows this). Returns ERR_MEM if it is full, else, ERR_OK if the "msg" is posted.

Parameters
mboxmbox to posts the message
msgmessage to post (ATTENTION: can be NULL)

Definition at line 247 of file sys_arch.c.

248{
249 sys_mbox_post(mbox, msg);
250
251 return ERR_OK;
252}
void sys_mbox_post(sys_mbox_t *mbox, void *msg)
Definition: sys_arch.c:160

Referenced by sys_mbox_trypost_fromisr(), tcpip_callbackmsg_trycallback(), tcpip_inpkt(), and tcpip_try_callback().

◆ sys_mbox_trypost_fromisr()

err_t sys_mbox_trypost_fromisr ( sys_mbox_t mbox,
void msg 
)

Try to post a message to an mbox - may fail if full. To be be used from ISR. Returns ERR_MEM if it is full, else, ERR_OK if the "msg" is posted.

Parameters
mboxmbox to posts the message
msgmessage to post (ATTENTION: can be NULL)

Definition at line 287 of file sys_arch.c.

288{
289 return sys_mbox_trypost(q, msg);
290}
GLdouble GLdouble GLdouble GLdouble q
Definition: gl.h:2063
err_t sys_mbox_trypost(sys_mbox_t *q, void *msg)
Definition: sys_arch.c:270

◆ sys_mbox_valid()

int sys_mbox_valid ( sys_mbox_t mbox)

Returns 1 if the mailbox is valid, 0 if it is not valid. When using pointers, a simple way is to check the pointer for != NULL. When directly using OS structures, implementing this may be more complex. This may also be a define, in which case the function is not prototyped.

Definition at line 141 of file sys_arch.c.

142{
143 return mbox->Valid;
144}